docs: refresh gateway auth precedence refs

docs/cli/devices.md

@@ -146,6 +146,11 @@ openclaw devices approve <requestId>
 
 5. Retry client connection with the current shared token/password.
 
+Notes:
+
+- Normal reconnect auth precedence is explicit shared token/password first, then explicit `deviceToken`, then stored device token, then bootstrap token.
+- Trusted `AUTH_TOKEN_MISMATCH` recovery can temporarily send both the shared token and the stored device token together for the one bounded retry.
+
 Related:
 
 - [Dashboard auth troubleshooting](/web/dashboard#if-you-see-unauthorized-1008)

docs/gateway/protocol.md

@@ -282,6 +282,8 @@ The Gateway treats these as **claims** and enforces server-side allowlists.
   approved scope set for that token. This preserves read/probe/status access
   that was already granted and avoids silently collapsing reconnects to a
   narrower implicit admin-only scope.
+- Normal connect auth precedence is explicit shared token/password first, then
+  explicit `deviceToken`, then stored per-device token, then bootstrap token.
 - Additional `hello-ok.auth.deviceTokens` entries are bootstrap handoff tokens.
   Persist them only when the connect used bootstrap auth on a trusted transport
   such as `wss://` or loopback/local pairing.

docs/gateway/troubleshooting.md

@@ -120,6 +120,9 @@ Common signatures:
 - That cached-token retry reuses the cached scope set stored with the paired
   device token. Explicit `deviceToken` / explicit `scopes` callers keep their
   requested scope set instead.
+- Outside that retry path, connect auth precedence is explicit shared
+  token/password first, then explicit `deviceToken`, then stored device token,
+  then bootstrap token.
 - On the async Tailscale Serve Control UI path, failed attempts for the same
   `{scope, ip}` are serialized before the limiter records the failure. Two bad
   concurrent retries from the same client can therefore surface `retry later`

docs/help/faq.md

@@ -2554,6 +2554,7 @@ Related: [/concepts/oauth](/concepts/oauth) (OAuth flows, token storage, multi-a
     - The Control UI keeps the token in `sessionStorage` for the current browser tab session and selected gateway URL, so same-tab refreshes keep working without restoring long-lived localStorage token persistence.
     - On `AUTH_TOKEN_MISMATCH`, trusted clients can attempt one bounded retry with a cached device token when the gateway returns retry hints (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`).
     - That cached-token retry now reuses the cached approved scopes stored with the device token. Explicit `deviceToken` / explicit `scopes` callers still keep their requested scope set instead of inheriting cached scopes.
+    - Outside that retry path, connect auth precedence is explicit shared token/password first, then explicit `deviceToken`, then stored device token, then bootstrap token.
 
     Fix:
 

docs/web/dashboard.md

@@ -77,6 +77,7 @@ Prefer localhost, Tailscale Serve, or an SSH tunnel.
 
 - 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. 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.
+- Outside that retry path, connect auth precedence is explicit shared token/password first, then explicit `deviceToken`, then stored device token, then bootstrap token.
 - On the async Tailscale Serve Control UI path, failed attempts for the same
   `{scope, ip}` are serialized before the failed-auth limiter records them, so
   the second concurrent bad retry can already show `retry later`.