From 5f75f703266d097623f2b969deef6c84f2322cab Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Sat, 25 Apr 2026 22:26:18 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@e640c0a95fcbd06a1311f18fc635518d011d45da --- .openclaw-sync/source.json | 4 ++-- docs/gateway/protocol.md | 8 ++++++++ docs/gateway/security/index.md | 5 +++++ docs/gateway/troubleshooting.md | 6 ++++++ 4 files changed, 21 insertions(+), 2 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index c0dedb51a..244f8157b 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "8d08e86f42acbe23db32d689e4b2805a5a76e52f", - "syncedAt": "2026-04-25T22:04:11.303Z" + "sha": "e640c0a95fcbd06a1311f18fc635518d011d45da", + "syncedAt": "2026-04-25T22:24:51.504Z" } diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md index 46cce9d0a..6d0b4d106 100644 --- a/docs/gateway/protocol.md +++ b/docs/gateway/protocol.md @@ -110,6 +110,14 @@ permissions: } ``` +Trusted same-process backend clients (`client.id: "gateway-client"`, +`client.mode: "backend"`) may omit `device` on direct loopback connections when +they authenticate with the shared gateway token/password. This path is reserved +for internal control-plane RPCs and keeps stale CLI/device pairing baselines from +blocking local backend work such as subagent session updates. Remote clients, +browser-origin clients, node clients, and explicit device-token/device-identity +clients still use the normal pairing and scope-upgrade checks. + When a device token is issued, `hello-ok` also includes: ```json diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index 74b8eb3a3..55ac84121 100644 --- a/docs/gateway/security/index.md +++ b/docs/gateway/security/index.md @@ -92,6 +92,11 @@ Treat Gateway and node as one operator trust domain, with different roles: - **Gateway** is the control plane and policy surface (`gateway.auth`, tool policy, routing). - **Node** is remote execution surface paired to that Gateway (commands, device actions, host-local capabilities). - A caller authenticated to the Gateway is trusted at Gateway scope. After pairing, node actions are trusted operator actions on that node. +- Direct loopback backend clients authenticated with the shared gateway + token/password can make internal control-plane RPCs without presenting a user + device identity. This is not a remote or browser pairing bypass: network + clients, node clients, device-token clients, and explicit device identities + still go through pairing and scope-upgrade enforcement. - `sessionKey` is routing/context selection, not per-user auth. - Exec approvals (allowlist + ask) are guardrails for operator intent, not hostile multi-tenant isolation. - OpenClaw's product default for trusted single-operator setups is that host exec on `gateway`/`node` is allowed without approval prompts (`security="full"`, `ask="off"` unless you tighten it). That default is intentional UX, not a vulnerability by itself. diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md index eced49a8f..eb549bcba 100644 --- a/docs/gateway/troubleshooting.md +++ b/docs/gateway/troubleshooting.md @@ -200,6 +200,12 @@ Use `error.details.code` from the failed `connect` response to pick the next act | `AUTH_DEVICE_TOKEN_MISMATCH` | Cached per-device token is stale or revoked. | Rotate/re-approve device token using [devices CLI](/cli/devices), then reconnect. | | `PAIRING_REQUIRED` | Device identity needs approval. Check `error.details.reason` for `not-paired`, `scope-upgrade`, `role-upgrade`, or `metadata-upgrade`, and use `requestId` / `remediationHint` when present. | Approve pending request: `openclaw devices list` then `openclaw devices approve `. Scope/role upgrades use the same flow after you review the requested access. | +Direct loopback backend RPCs authenticated with the shared gateway +token/password should not depend on the CLI's paired-device scope baseline. If +subagents or other internal calls still fail with `scope-upgrade`, verify the +caller is using `client.id: "gateway-client"` and `client.mode: "backend"` and +is not forcing an explicit `deviceIdentity` or device token. + Device auth v2 migration check: ```bash