Gateway: harden custom session-store discovery (#44176)

Merged via squash.

Prepared head SHA: 52ebbf5188b47386f2a78ac4715993bc082e911b
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Reviewed-by: @gumadeiras

docs/channels/channel-routing.md

@@ -118,6 +118,11 @@ Session stores live under the state directory (default `~/.openclaw`):
 
 You can override the store path via `session.store` and `{agentId}` templating.
 
+Gateway and ACP session discovery also scans disk-backed agent stores under the
+default `agents/` root and under templated `session.store` roots. Discovered
+stores must stay inside that resolved agent root and use a regular
+`sessions.json` file. Symlinks and out-of-root paths are ignored.
+
 ## WebChat behavior
 
 WebChat attaches to the **selected agent** and defaults to the agent’s main

docs/cli/sessions.md

@@ -24,6 +24,12 @@ Scope selection:
 - `--all-agents`: aggregate all configured agent stores
 - `--store <path>`: explicit store path (cannot be combined with `--agent` or `--all-agents`)
 
+`openclaw sessions --all-agents` reads configured agent stores. Gateway and ACP
+session discovery are broader: they also include disk-only stores found under
+the default `agents/` root or a templated `session.store` root. Those
+discovered stores must resolve to regular `sessions.json` files inside the
+agent root; symlinks and out-of-root paths are skipped.
+
 JSON examples:
 
 `openclaw sessions --all-agents --json`:

docs/tools/acp-agents.md

@@ -421,6 +421,8 @@ Some controls depend on backend capabilities. If a backend does not support a co
 | `/acp doctor`        | Backend health, capabilities, actionable fixes.           | `/acp doctor`                                                  |
 | `/acp install`       | Print deterministic install and enable steps.             | `/acp install`                                                 |
 
+`/acp sessions` reads the store for the current bound or requester session. Commands that accept `session-key`, `session-id`, or `session-label` tokens resolve targets through gateway session discovery, including custom per-agent `session.store` roots.
+
 ## Runtime options mapping
 
 `/acp` has convenience commands and a generic setter.