The "device token mismatch" error means the token stored on your device doesn't match what OpenClaw's gateway expects. This typically happens after a gateway restart, container rebuild, or when connecting from a new browser.

Error Messages You Might See

All of these point to the same issue:

connect failed: device token mismatch

disconnected (4008): connect failed — device token mismatch

openclaw gateway device token mismatch

Quick Fix: `openclaw doctor`

The fastest solution:

openclaw doctor --fix

This detects the token mismatch and regenerates matching tokens. Restart after:

openclaw restart

Manual Fix: Reset the Device Token

If doctor doesn't resolve it, manually reset the device identity:

Step 1: List Registered Devices

openclaw devices list

This shows all approved devices and their token status.

Step 2: Remove the Mismatched Device

openclaw devices remove DEVICE_ID

Step 3: Reconnect

Open your browser or Telegram bot and reconnect. You'll see a new pairing request:

openclaw devices list
# Look for the pending device
openclaw devices approve DEVICE_ID

Why Does This Happen?

Cause 1: Gateway Token Changed on Restart

OpenClaw regenerates the gateway token on every restart unless you pin it. This invalidates all existing device connections.

Permanent fix — set a stable token:

openclaw config set gateway.token "your-stable-token-here"

Or via environment variable:

export OPENCLAW_GATEWAY_TOKEN="your-stable-token-here"

Cause 2: Container Was Rebuilt

If you're running OpenClaw in Docker, rebuilding the container creates a fresh gateway identity. All previously paired devices become invalid.

Prevention — mount the data directory:

docker run -v openclaw-data:/app/data openclaw-stack

Cause 3: Multiple Instances

Running two OpenClaw instances on the same machine can cause token collisions. Each instance needs its own data directory and port.

Cause 4: Browser Cache

Sometimes the browser holds an old token in localStorage.

Fix: Clear site data for your OpenClaw URL, then reconnect.

Docker-Specific Fix

If you're running OpenClaw in Docker:

# Enter the container
docker exec -it YOUR_CONTAINER_ID bash

# Run doctor inside the container
openclaw doctor --fix

# Or manually set a stable token
openclaw config set gateway.token "your-stable-token"

# Exit and restart the container
exit
docker restart YOUR_CONTAINER_ID

Prevention Checklist

To avoid future token mismatches:

Pin your gateway token with OPENCLAW_GATEWAY_TOKEN env var or gateway.token config
Persist your data directory when using Docker volumes
Use one instance per machine unless you've configured separate ports and data dirs
Run openclaw doctor after upgrades to catch mismatches early

Verify the Fix

After resolving the mismatch:

# Check gateway status
openclaw status

# Verify device is connected
openclaw devices list

All devices should show connected status.

Avoid Token Issues Entirely

ClawTank handles gateway tokens, device pairing, and container persistence automatically. No manual token management — just deploy and connect.