Gateway vs Device Token Mismatch
OpenClaw has two distinct token mismatch errors. They look similar but have different root causes and different fixes. Use your exact error message to identify which one you have, then follow the matching fix.
Next Step
Fix now, then reduce repeat incidents
If this issue keeps coming back, validate your setup in Doctor first, then harden your config.
1-Minute Execution Version
Read your error message, copy the matching command.
If you see: "device token mismatch"
openclaw gateway token rotate openclaw gateway restart
If you see: "gateway token mismatch (set gateway.remote.token…)"
# Align gateway.auth.token and gateway.remote.token in openclaw.json # Both values must be identical openclaw config set gateway.auth.token "YOUR_SHARED_SECRET" openclaw config set gateway.remote.token "YOUR_SHARED_SECRET" openclaw gateway restart
Which Error Do You Have?
Find your exact error message below. The key difference is in the suffix:
Cause: Your browser or client cached a device token that no longer matches what the Gateway knows.
When: After Gateway restart, update, crash, or clearing browser storage.
Fix: Rotate/reissue the per-device token, open Dashboard in Incognito.
Cause: The shared secret between your OpenClaw client config and the Gateway does not match.
When: After Docker redeploy, manual config edit, or env variable override.
Fix: Align gateway.auth.token and gateway.remote.token to the same value.
Fix A: Device Token Mismatch
This is a per-device credential issue. The Gateway regenerated its internal device registry (after restart or update), but your browser still has the old token.
Step 1 — Rotate the Token
openclaw gateway token rotate openclaw gateway token status openclaw gateway restart
Step 2 — Open Dashboard Fresh
Open the Dashboard in an Incognito / Private window. This forces a clean device token handshake. Your normal window cached the old token.
If rotation doesn't work, do a full reset: openclaw gateway token reset. This invalidates all connected devices — they each need to re-authenticate.
Fix B: Gateway Token Mismatch
This is a shared-secret config mismatch. gateway.auth.token (what the Gateway expects) and gateway.remote.token (what the client sends) must match exactly.
Check Current Values
openclaw config get gateway.auth.token openclaw config get gateway.remote.token
If the values differ, align them:
# Set both to the same value openclaw config set gateway.auth.token "your-shared-secret" openclaw config set gateway.remote.token "your-shared-secret" openclaw gateway restart
Docker Users
In Docker deployments, the token is usually injected via environment variable. Check your docker-compose.yml or .env:
# In docker-compose.yml — both services must use the same value environment: - OPENCLAW_GATEWAY_TOKEN=your-shared-secret # Then restart docker compose down && docker compose up -d
Both Errors at the Same Time
After a full reinstall or major config reset, you may see both errors simultaneously. Fix in this order:
Fix gateway.auth.token / gateway.remote.token mismatch first (Error B)
Establishes the shared secret the Gateway will accept
Restart the Gateway
Loads the updated config
Rotate device tokens (Error A)
Clears any stale per-device credentials
Open Dashboard in Incognito
Completes clean device handshake
Related Fixes
Other pages that can help:
Fix It Faster
Config Wizard
Generate a production-ready clawhub.json in 30 seconds.
Local Doctor
Diagnose Node.js, permissions, and config issues instantly.
Cost Simulator
Calculate your agent burn rate before you get surprised.
Gateway Monitor
Detect token spikes and gateway incidents before users complain.
Skill Finder
Describe your use case and find the right Claude Code skill instantly.
Did this guide solve your problem?