lark-cli enters Hermes context when HERMES_HOME is inherited, then bind ignores HERMES_HOME path

[GuGuLiuSandao]

Summary

After installing Hermes, unrelated CLI/automation processes that happen to inherit HERMES_HOME start failing when running lark-cli.

lark-cli detects a Hermes context and refuses to use the existing local lark-cli config, returning:

{
  "ok": false,
  "error": {
    "type": "config",
    "subtype": "not_configured",
    "message": "hermes context detected but lark-cli is not bound to it",
    "hint": "read `lark-cli config bind --help`, then ask the user to confirm intent and identity preset..."
  }
}

However, when trying to bind Hermes explicitly, lark-cli does not appear to use the HERMES_HOME path that triggered Hermes detection. Instead, it looks for a different default path:

{
  "ok": false,
  "error": {
    "type": "config",
    "subtype": "invalid_config",
    "message": "failed to read Hermes config: open C:\\Users\\example\\.hermes\\.env: The system cannot find the path specified.",
    "hint": "verify Hermes is installed and configured at C:\\Users\\example\\.hermes\\.env"
  }
}

In this environment, HERMES_HOME points somewhere else, for example:

HERMES_HOME=C:\Users\example\AppData\Local\hermes

Expected behavior

If lark-cli detects Hermes because HERMES_HOME is present, then one of the following should happen:

1. config bind --source hermes should read Hermes config from HERMES_HOME, or
2. lark-cli should not enter Hermes context unless Hermes config can actually be resolved, or
3. there should be a documented way to force normal local config mode, e.g. an env var or flag like --ignore-agent-context.

Actual behavior

Any unrelated process that inherits HERMES_HOME is treated as Hermes context.

This breaks existing lark-cli usage in non-Hermes automation tasks. Commands such as:

lark-cli auth status
lark-cli config show
lark-cli im +chat-messages-list --as user ...

fail before using the existing local config.

If HERMES_HOME is removed from the current shell, the same commands work again and use the normal local config:

Remove-Item Env:HERMES_HOME -ErrorAction SilentlyContinue
lark-cli auth status

Reproduction

1. Have a working local lark-cli config.
2. Install Hermes or otherwise set HERMES_HOME to a Hermes data directory.
3. In a non-Hermes shell or automation process that inherits HERMES_HOME, run:

lark-cli auth status

4. Observe hermes context detected but lark-cli is not bound to it.
5. Try:

lark-cli config bind --source hermes --identity user-default

6. Observe that bind looks for C:\Users\example\.hermes\.env instead of the path from HERMES_HOME.

Impact

This causes unrelated automation jobs that use lark-cli to fail after Hermes is installed, even though those jobs are not Hermes jobs and already have a valid local lark-cli config.

Version

lark-cli version 1.0.51

[nguyenngothuong]

Opened #1445 to address this.

What the PR does (option 3 from the issue): adds a documented escape hatch LARKSUITE_CLI_FORCE_LOCAL=1. When set, DetectWorkspaceFromEnv returns the local workspace and overrides every Agent signal, so automation that merely inherits HERMES_HOME (or OPENCLAW_HOME) can keep using its valid local lark-cli config without unsetting the inherited variable:

# inherited HERMES_HOME → hijacked into hermes context (the bug)
HERMES_HOME=/some/path lark-cli config show
#   → "hermes context detected but lark-cli is not bound to it"

# escape hatch → back to the normal local config
HERMES_HOME=/some/path LARKSUITE_CLI_FORCE_LOCAL=1 lark-cli config show

The "not bound" error hint now mentions the escape hatch so operators who hit the wall can discover it.

On the second symptom — bind looking at ~/.hermes/.env instead of HERMES_HOME: this looks like it may already be fixed on main. resolveHermesEnvPath() in cmd/config/binder.go reads HERMES_HOME first and only falls back to ~/.hermes/.env when it's empty, and config bind resolves the source path through that function. Could you confirm whether you still see the wrong path on a current build from main? If it still reproduces there, it'd be worth splitting out as a separate bug.

Root-cause note for maintainers: the PR intentionally keeps scope minimal (the escape hatch). The deeper cause is that HERMES_HOME is a user-facing path variable that leaks into shell profiles, unlike the subprocess-scoped HERMES_GATEWAY_TOKEN / HERMES_SESSION_KEY. OpenClaw detection already has a precise subprocess marker (OPENCLAW_CLI == "1"); Hermes has no equivalent. If you'd prefer, I'm happy to follow up by adding a Hermes subprocess marker and downgrading HERMES_HOME to a secondary signal — but that changes detection semantics, so I left it out of this PR pending your call.

[evandance]

Thanks for the detailed report. A couple of clarifications on the intended behavior.

"hermes context detected but not bound" isn't a failure — it's the designed state. config bind isolates each Agent's credentials into its own workspace, so when a Hermes signal is present the CLI intentionally does not use your personal local config. That local config is untouched; it's just deliberately not used inside an Agent context.

lark-cli treats HERMES_HOME being set as the signal that it's running under Hermes. In a standard setup you don't set this variable yourself — Hermes manages it for its own processes and falls back to its default location when it's unset, so it isn't meant to live in a global shell profile or a system/user environment entry. If an unrelated job sees it, it's been set globally somewhere in your environment and other processes are inheriting it. The correct state is to leave it unset at that global level; removing it there won't affect Hermes, which resolves the same default path on its own. (If you intentionally run Hermes against a non-default data directory, set HERMES_HOME the way Hermes documents for your deployment — scoped to how Hermes is launched — rather than as a global environment variable.)

On the second point: config bind resolves the Hermes config path from HERMES_HOME too, so it follows the same variable. Once HERMES_HOME is only set in a real Hermes context, the detection and the bind path will line up. If you still see the path pointing somewhere unexpected while HERMES_HOME is set, paste its value and the full config bind output from the same shell and we'll take a look.