Fix "Device Token Mismatch" Error
Most Common Gateway Error
This is the #1 reported error in OpenClaw communities. If you see disconnected (1008): unauthorized: device token mismatch, this guide will fix it.
Next Step
Fix now, then reduce repeat incidents
If this issue keeps coming back, validate your setup in Doctor first, then harden your config.
The device token mismatch error means your client's stored authentication token no longer matches what the Gateway expects. This usually happens after a Gateway restart, crash, update, or when a zombie process is running.
Jump to Your Situation
What the Error Looks Like
You'll see one or more of these messages:
The (1008) is a WebSocket close code meaning "policy violation" — in this case, the Gateway rejected your client's device token.
Wrong page? Check your exact error message
unauthorized: device token mismatch
Per-device credential issue — token expired/rotated after Gateway restart. Fix: rotate/reset device token.
unauthorized: gateway token mismatch (set gateway.remote.token…)
Shared secret config mismatch — common in Docker. Fix: align gateway.auth.token and gateway.remote.token.
Your Gateway restarted — and you didn't know until it broke.
Get instant alerts when your Gateway goes down. Early access to Gateway Monitor — free.
Quick Fix (Works 80% of the Time)
Restart Gateway + Clear Browser
Why Incognito? Your normal browser cached the old device token. Incognito starts clean.
If this didn't work, read on to identify the specific cause — or let the Doctor diagnose it for you:
How to Rotate / Reissue the Device Token
The error message itself tells you: rotate/reissue device token. Here's how:
Method 1: CLI Command (Recommended)
# Reissue a fresh device token openclaw gateway token rotate # Verify the new token is active openclaw gateway token status # Restart to apply openclaw gateway restart
Method 2: Full Reset
If rotation doesn't work, do a full token reset:
# Stop the Gateway openclaw gateway stop # Remove stored device tokens openclaw gateway token reset # Start fresh openclaw gateway start
After a token reset, all connected devices will need to re-authenticate. Open the Dashboard in a fresh browser window to complete the handshake.
Did the token reset fix it?
Cause: Zombie Process Holding the Port
The Hidden Killer
An old node.exe process crashed but didn't release port 18789. Your new Gateway starts, but clients connect to the dead process which has the old token — causing permanent mismatch errors.
How to Detect
# macOS / Linux lsof -i :18789 # Windows netstat -ano | findstr :18789
If you see a process listening on port 18789 while the Gateway is supposedly stopped, that's your zombie.
How to Fix
# macOS / Linux — kill the zombie kill -9 <PID> # Windows — kill the zombie (replace 9800 with your PID) taskkill /PID 9800 /F # Verify port is free # macOS/Linux: lsof -i :18789 (should return nothing) # Windows: netstat -ano | findstr :18789 (should return nothing) # Now start clean openclaw gateway start
Cause: After a Gateway Update
Updating OpenClaw can regenerate internal tokens. The client still holds the old token from before the update. Fix:
# Reinstall the service with new config openclaw gateway install --force # Restart openclaw gateway restart # Then open Dashboard in Incognito to get the new token
Cause: Break-glass Auth Settings Left On
If you previously enabled insecure auth settings for debugging (common advice in Discord), they may now be causing the mismatch instead of fixing it. Disable them:
# Revert break-glass settings openclaw config set gateway.controlUi.allowInsecureAuth false openclaw config set gateway.controlUi.dangerouslyDisableDeviceAuth false # Restart openclaw gateway restart
Security Warning
dangerouslyDisableDeviceAuth disables all device authentication. Never leave this on in production. It was designed as a temporary debugging tool only.
Auto-Fix with openclaw doctor
The built-in diagnostic tool can detect and fix token mismatch issues automatically:
Run the Doctor
The --fix flag will: kill zombie processes, rotate device tokens, restart the Gateway, and verify connectivity.
You can also use our web-based Doctor tool to run diagnostics from your browser.
Windows-Specific Issues
On Windows, the device token mismatch is especially common due to how background processes work. Key differences:
Scheduled Task conflicts
The Windows Scheduled Task (service) may run a different Gateway instance than your CLI. Run openclaw gateway install --force to sync them.
Zombie processes are harder to find
Windows doesn't always release ports after crashes. Use netstat -ano | findstr :18789 and taskkill /PID <PID> /F to clean up.
Multiple derived ports
OpenClaw uses ports 18789, 18791, and 18792. A zombie on any of these can cause token issues. Check all three.
# Kill all zombie processes on OpenClaw ports netstat -ano | findstr "18789 18791 18792" taskkill /PID <PID> /F # Force reinstall the service openclaw gateway install --force # Restart openclaw gateway restart
For a complete Windows troubleshooting walkthrough, see Fix Gateway Errors on Windows.
Decision Flowchart
If you've tried everything above, walk through this checklist:
Is a zombie process holding port 18789?
Kill it, then restart Gateway
Did you recently update OpenClaw?
Run openclaw gateway install --force
Are break-glass auth settings enabled?
Disable them and restart
Are you opening Dashboard in a normal browser?
Try Incognito/Private window instead
On Windows with Scheduled Task?
Check for task/CLI config mismatch
Multiple devices connecting?
Run openclaw gateway token reset to reissue for all
None of the above?
Run openclaw doctor --fix for automatic diagnosis
Still Stuck?
Run our diagnostic tool to catch issues automatically:
openclaw doctor --fixOr use the web-based Doctor tool for a guided walkthrough.
Seeing Other Errors Too?
Device token issues often come with these related problems:
Your token expired because the Gateway restarted — and you didn't know.
Gateway Monitor watches your instance 24/7 and sends an alert the second it goes down, so you can act before tokens expire.
Fix It Faster With Our Tools
Did this guide solve your problem?