From f502b023d99a0611d9cb4033ffdf7de6d074ba95 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 14:25:47 +0100 Subject: [PATCH] docs: refresh device token scope mirrors --- docs/cli/index.md | 3 +++ docs/gateway/troubleshooting.md | 12 ++++++------ docs/web/dashboard.md | 2 +- 3 files changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/cli/index.md b/docs/cli/index.md index 87fe63ea228..ea910597e05 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -824,6 +824,9 @@ Notes: - `devices list` and `devices approve` can fall back to local pairing files on local loopback when direct pairing scope is unavailable. - `devices approve` auto-selects the newest pending request when no `requestId` is passed or `--latest` is set. +- Stored-token reconnects reuse the token's cached approved scopes; explicit + `devices rotate --scope ...` updates that stored scope set for future + cached-token reconnects. - `devices rotate` and `devices revoke` return JSON payloads. ### `qr` diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md index 0d26534cdce..df51a9b5f33 100644 --- a/docs/gateway/troubleshooting.md +++ b/docs/gateway/troubleshooting.md @@ -130,12 +130,12 @@ Common signatures: Use `error.details.code` from the failed `connect` response to pick the next action: -| Detail code | Meaning | Recommended action | -| ---------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | Client did not send a required shared token. | Paste/set token in the client and retry. For dashboard paths: `openclaw config get gateway.auth.token` then paste into Control UI settings. | -| `AUTH_TOKEN_MISMATCH` | Shared token did not match gateway auth token. | If `canRetryWithDeviceToken=true`, allow one trusted retry. If still failing, run the [token drift recovery checklist](/cli/devices#token-drift-recovery-checklist). | -| `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 is known but not approved for this role. | Approve pending request: `openclaw devices list` then `openclaw devices approve `. | +| Detail code | Meaning | Recommended action | +| ---------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AUTH_TOKEN_MISSING` | Client did not send a required shared token. | Paste/set token in the client and retry. For dashboard paths: `openclaw config get gateway.auth.token` then paste into Control UI settings. | +| `AUTH_TOKEN_MISMATCH` | Shared token did not match gateway auth token. | If `canRetryWithDeviceToken=true`, allow one trusted retry. Cached-token retries reuse stored approved scopes; explicit `deviceToken` / `scopes` callers keep requested scopes. If still failing, run the [token drift recovery checklist](/cli/devices#token-drift-recovery-checklist). | +| `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 is known but not approved for this role. | Approve pending request: `openclaw devices list` then `openclaw devices approve `. | Device auth v2 migration check: diff --git a/docs/web/dashboard.md b/docs/web/dashboard.md index 77306144897..33089311e68 100644 --- a/docs/web/dashboard.md +++ b/docs/web/dashboard.md @@ -76,7 +76,7 @@ Prefer localhost, Tailscale Serve, or an SSH tunnel. ## If you see "unauthorized" / 1008 - Ensure the gateway is reachable (local: `openclaw status`; remote: SSH tunnel `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/`). -- For `AUTH_TOKEN_MISMATCH`, clients may do one trusted retry with a cached device token when the gateway returns retry hints. If auth still fails after that retry, resolve token drift manually. +- For `AUTH_TOKEN_MISMATCH`, clients may do one trusted retry with a cached device token when the gateway returns retry hints. That cached-token retry reuses the token's cached approved scopes; explicit `deviceToken` / explicit `scopes` callers keep their requested scope set. If auth still fails after that retry, resolve token drift manually. - For token drift repair steps, follow [Token drift recovery checklist](/cli/devices#token-drift-recovery-checklist). - Retrieve or supply the shared secret from the gateway host: - Token: `openclaw config get gateway.auth.token`