OpenClaw Gateway Token: Diagnose Auth Without Leaking It

An OpenClaw Gateway token is not healthy merely because it exists in a config file or because the dashboard HTML loads. The useful proof is a chain: the Gateway is reachable, the intended credential source resolved, the WebSocket handshake accepted it, the device has the required scopes, and the Gateway became ready enough to perform the intended operation. That distinction answers the common troubleshooting question early. If you see unauthorized , 1008 , AUTH TOKEN MISMATCH , AUTH SCOPE MISMATCH , or pairing required , do not start by disabling auth or rotating every token. Classify the failed layer first. A shared token mismatch, a recognized device with insufficient scopes, and an unapproved new device are different incidents with different repairs. The safest default is to work from the Gateway host, use openclaw dashboard for browser bootstrap, keep the Control UI on localhost, Tailscale Serve, or an SSH tunnel, and preserve only secret free evidence in tickets and health reports. Separate five layers that can fail independently OpenClaw's current documentation describes the Gateway as the WebSocket server for channels, nodes, sessions, and hooks. Its dashboard is an admin surface: it can expose chat, configuration, and execution approvals. The page shell can arrive over HTTP while the WebSocket connection is rejected. That is why a browser displaying the Control UI is not yet an authenticated session. Use five layers: Layer Question Safe evidence What it does not prove Transport Can the client reach the intended host, port, tunnel, and TLS endpoint? destination class, connect result, timestamp that auth was attempted Credential source Did the intended token, password, SecretRef, or identity mode resolve? auth mode, source type, present/absent that client and server values agree Handshake Did the Gateway accept the presented auth path? normalized result such as ok , token missing , or token mismatch that device scopes are sufficient Device authority Is the device paired and approved for the requested scopes? device id alias, requested scopes, approval state that plugins and channels are ready Readiness Can the authenticated client perform the intended operation? readiness result and one bounded operation receipt that a separate agent task completed This model prevents a familiar false green: /healthz answers liveness, while /readyz is stricter. The current Gateway CLI documentation says readiness remains red while startup plugin sidecars, channels, or configured hooks are still settling. Neither endpoint substitutes for an authenticated WebSocket handshake. The reverse also matters. A successful handshake followed by not ready is not a token incident. Rotating the shared secret in that state adds drift without repairing the blocking component. Collect evidence without collecting the token A useful incident record never needs the shared token value. It also does not need a token prefix, reversible fingerprint, Authorization header, cookie, dashboard screenshot containing a fragment, or a copy of openclaw.json . Record only: This is enough to route the case. It says the source resolved and the server was live, but a recognized device did not carry the requested authority. The correct next move is scope approval or re pairing—not shared token rotation. The current dashboard contract has several details worth preserving: auth is enforced at the WebSocket handshake; a token passed to the dashboard is kept in sessionStorage for the current browser tab and selected Gateway URL, then stripped from the URL; openclaw dashboard is the recommended local bootstrap path; a runtime token generated because no shared secret was configured is ephemeral and cannot be retrieved with openclaw config get gateway.auth.token ; a SecretRef managed token deliberately produces a non tokenized dashboard URL; the Control UI should not be exposed publicly. Those are handling rules, not an invitation to paste the token into a support ticket. If host local troubleshooting genuinely requires viewing or resolving a credential, keep that step interactive and out of captured output. Never send it through chat, a screenshot, CI log, shell trace, or article fixture. When a remote CLI command uses an explicit url , the current Gateway CLI documentation says it does not fall back to config or environment credentials. The caller must provide explicit auth. That behavior can explain a missing credential failure even when local commands succeed. It does not justify putting a real token directly into documentation or a reusable command history. Classify the failure before choosing a repair The artifact built for this article accepts the secret free fields above and rejects keys such as token , password , Authorization , cookie , secret , or even a token hash. Run it against an evidence file: For a scope mismatch, the output is deliberately narrow: The companion fixture covers eight cases: unreachable transport, missing credential, token drift, scope mismatch, pairing required, ready, authenticated but not ready, and live but unauthenticated. Several cases share httpLiveness: true . They still produce different verdicts because liveness is not the decision boundary. Use this repair table: Verdict Strongest evidence Bounded repair Verification UNREACHABLE connection to the intended destination fails repair route, tunnel, bind, TLS, listener, or DNS repeat transport check before auth CREDENTIAL MISSING auth mode requires a secret but intended source is absent, or handshake reports missing resolve the configured source on the Gateway host new handshake result; no secret in output TOKEN DRIFT AUTH TOKEN MISMATCH after any documented trusted retry identify which configured source and client path differ; rotate only with authority authenticated handshake using the intended source SCOPE REPAIR REQUIRED AUTH SCOPE MISMATCH for a recognized device approve the required scope set or re pair requested operation succeeds under approved scopes WAITING FOR PAIRING server requests device approval authorized owner approves the pending device handshake succeeds with expected scopes AUTHENTICATED NOT READY handshake succeeds but readiness remains red diagnose readiness components readiness plus one intended operation READY handshake and readiness pass no auth repair preserve timestamped receipt UNCERTAIN evidence is missing or contradictory collect the next missing layer reclassify; do not guess healthy AUTH TOKEN MISMATCH deserves care. Current dashboard guidance says a client may perform one trusted retry with a cached device token when the Gateway supplies retry hints. If the retry fails, repair token drift manually. Do not build an unbounded reconnect loop, and do not take an old gateway.remote.token workaround from a historical issue as the current contract. AUTH SCOPE MISMATCH is more specific. The device credential was recognized, but it lacks requested scopes. Rotating the shared token does not grant those scopes. Re pair or approve the new scope set through an authorized path. pairing required is a waiting state, not necessarily a broken Gateway. The owner must decide whether the device and requested authority are legitimate. Treating it as an outage encourages unsafe auto approval. Prove recovery at the intended operation Recovery needs one more step than a green connection. After transport, handshake, scope, and readiness pass, perform a bounded operation that represents the client's actual need. A read only status or health query may be enough for an observer. An administrative client needs its own authorized operation receipt. Do not expand permissions merely to make the test pass. A compact recovery receipt can contain: The receipt omits the token and any content returned by the agent. It proves that the intended layer recovered without turning the incident log into a credential store. There are three useful boundaries: 1. Do not disable auth to diagnose auth. A successful connection under none only proves that the auth check was bypassed. It also changes the threat model of an admin surface. 2. Do not rotate before identifying drift. Rotation can invalidate healthy clients and convert a local source resolution problem into fleet wide token drift. 3. Do not call pairing or scope approval automatic recovery. Both grant authority. They require an owner decision and an audit trail. The artifact has a deliberate limitation: it classifies supplied evidence but cannot retrieve, compare, or validate a real credential. That is a feature. Secret retrieval stays on the Gateway host with an authorized operator. The report remains safe to share. Sidewisp's planned health model includes availability, tool access, permission loss, waiting states, and safe recovery boundaries. A future OpenClaw adapter could collect secret free connection and readiness evidence, but it must distinguish diagnosis from authority and must not upload tokens, passwords, prompts, or raw logs. Sidewisp is currently in private preview. The production monitoring engine, OpenClaw adapter, and recovery executor are not generally shipped. The public site and article system are live; join the preview if you want an evidence first health view around agents you already operate. Sources: OpenClaw Gateway CLI, OpenClaw Dashboard authentication, OpenClaw Gateway configuration, and Sidewisp product status.