Fix OpenClaw Auth Errors (Decision Tree)
New keyword traffic is concentrated in one family: gateway token mismatch, gateway token missing, device identity required, and pairing required. These should be handled as one root-cause cluster, not separate thin pages.
Next Step
Fix now, then reduce repeat incidents
If this issue keeps coming back, validate your setup in Doctor first, then harden your config.
Jump to the Exact Error
A) gateway token mismatch / token missing
This means the client token does not match gateway auth token. Most common in Docker/redeploy flows where token source drifts.
# Compare token values first openclaw config get gateway # Force remote token to match auth token openclaw config set gateway.remote.token "YOUR_GATEWAY_AUTH_TOKEN" # Restart gateway openclaw gateway restart
If your query says open the dashboard url and paste the token in control ui settings, open the tokenized dashboard URL from gateway startup output, then retry. Detailed guide: Gateway Token Mismatch.
B) control ui requires device identity
Root cause is secure context: browser key generation needs localhost or https. Plain LAN HTTP typically fails.
# Prefer local access http://localhost:18789 # For remote/LAN access, use HTTPS reverse proxy or tunnel URL https://YOUR_HOST_OR_TUNNEL:18789
Detailed guide: Device Identity Required.
C) pairing required (1008)
Identity exists but device is not approved yet. Common in Docker NAT, LAN clients, and remote nodes.
# On the machine running OpenClaw gateway openclaw devices list openclaw devices approve <request-id>
Detailed guide: Pairing Required.
One-Pass Recovery (Safe Order)
# 1) restart gateway cleanly openclaw gateway restart # 2) ensure token alignment openclaw config get gateway # 3) re-open control ui on localhost/https # 4) if still 1008 pairing required: approve request openclaw devices list openclaw devices approve <request-id>
Verification Sources Used
- Official docs: Device pairing/auth and secure-context behavior.
- Official troubleshooting docs for token mismatch, identity required, pairing required.
- GitHub issue validation: openclaw/openclaw#1690 (token mismatch pattern and tokenized URL path).
Related High-Intent Fixes
If your error is startup/runtime instead of auth, jump here:
Did this guide solve your problem?