Fix "Device Token Mismatch" in OpenClaw [2026 Guide]

Getting one of these errors?

device token mismatch

connect failed: device token mismatch

disconnected (4008): connect failed

disconnected (4008): connect failed — device token mismatch

openclaw gateway device token mismatch

Error: device token mismatch — please re-pair this device

WebSocket connection failed: device token mismatch

connect failed (4008): device identity rejected

They all mean the same thing: the token stored on your device no longer matches what your OpenClaw gateway expects. This guide covers every way to fix it.

TL;DR -- Quick Fix

Run this inside your OpenClaw environment:

openclaw doctor --fix && openclaw restart

That single command detects the token mismatch, regenerates matching tokens, and restarts the gateway. If that doesn't work, keep reading for the full step-by-step.

Step-by-Step Fix for OpenClaw Device Token Mismatch

Step 1: Run the built-in diagnostic

openclaw doctor --fix

openclaw doctor --fix scans for configuration problems including device token mismatches. It will automatically regenerate tokens and update the gateway config.

Step 2: Restart the gateway

openclaw restart

The fix only takes effect after a restart. Wait until you see [gateway] listening on in the logs before trying to reconnect.

Step 3: Verify the fix

openclaw status

You should see gateway: running with no errors. If any devices show as disconnected, continue to Step 4.

Step 4: Re-approve disconnected devices

List all registered devices:

openclaw devices list

If your device shows pending or rejected, approve it:

openclaw devices approve DEVICE_ID

If the device is stuck in a broken state, remove and re-pair it:

openclaw devices remove DEVICE_ID

Then open your browser or Telegram bot and reconnect. A new pairing request will appear. Approve it with openclaw devices approve and the new device ID.

Step 5: Confirm all devices are connected

openclaw devices list

Every device should show connected status.

Why This Happens

There are four common causes for the device token mismatch error.

1. Gateway restart regenerated the token

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

This is the most common cause. Any time your server reboots, your process manager restarts, or you run openclaw restart without a pinned token, every paired device gets a mismatch.

2. Container was rebuilt (Docker users)

Rebuilding a Docker container creates a fresh gateway identity. All previously paired devices -- browsers, Telegram bots, mobile apps -- become invalid because the new container has no record of them.

This affects anyone using docker run, docker-compose up --build, or CI/CD pipelines that recreate containers on deploy.

3. Multiple OpenClaw instances running

Running two OpenClaw instances on the same machine causes token collisions. Each instance reads from the same default data directory, so they overwrite each other's tokens.

You will see intermittent mismatch errors that seem to fix themselves and then come back. If your error is inconsistent, this is likely the cause.

4. Stale browser cache

Sometimes the browser holds an old device token in localStorage. Even after fixing the server-side config, the browser sends the outdated token.

Fix: Clear site data for your OpenClaw URL in your browser settings, then reconnect and approve the new device.

Docker-Specific Fix for Device Token Mismatch

If you run OpenClaw in Docker, the fix requires entering the container:

# Enter the running container
docker exec -it YOUR_CONTAINER_NAME bash

# Run the diagnostic tool
openclaw doctor --fix

# Exit the container
exit

# Restart the container to apply changes
docker restart YOUR_CONTAINER_NAME

To reset a device token manually inside Docker:

docker exec -it YOUR_CONTAINER_NAME bash

# Set a stable gateway token
openclaw config set gateway.token "your-stable-token-here"

# Remove all stale device pairings
openclaw devices list
openclaw devices remove DEVICE_ID

exit
docker restart YOUR_CONTAINER_NAME

After the container restarts, reconnect from your browser or Telegram and approve the new device.

Docker Compose users

If you use Docker Compose, add the environment variable to your docker-compose.yml:

services:
  openclaw:
    image: openclaw-stack
    environment:
      - OPENCLAW_GATEWAY_TOKEN=your-stable-token-here
    volumes:
      - openclaw-data:/app/data

volumes:
  openclaw-data:

Then rebuild without losing your data:

docker compose down && docker compose up -d

Prevention Checklist

Stop the device token mismatch from happening again:

• Pin your gateway token. Set OPENCLAW_GATEWAY_TOKEN as an environment variable or run openclaw config set gateway.token "your-stable-token". This prevents token regeneration on restart.
• Persist your data directory. Mount a Docker volume at /app/data so container rebuilds don't wipe device pairings.
• One instance per machine. If you must run multiple instances, configure separate data directories and ports for each.
• Run openclaw doctor after upgrades. Major version upgrades can change the token format. Running openclaw doctor --fix catches problems before they reach your users.
• Clear browser cache after major changes. If you change your gateway URL, domain, or token, clear site data in every browser that connects.

Still Not Working?

If openclaw doctor --fix and manual token resets do not resolve the error:

1. Check your OpenClaw version. Run openclaw --version and make sure you are on the latest release. Older versions had token rotation bugs that have since been patched.
2. Check for port conflicts. Run openclaw status and verify the gateway port is not in use by another process.
3. Inspect the gateway logs. Run openclaw logs gateway and look for lines containing token or device. The log output will show exactly which token the gateway expects versus what the client sent.
4. Nuclear option -- full reset. If nothing else works, remove all device pairings and start fresh:

openclaw devices list
# Remove every device
openclaw devices remove DEVICE_ID_1
openclaw devices remove DEVICE_ID_2

# Set a new stable token
openclaw config set gateway.token "new-token-here"

# Restart
openclaw restart

Then reconnect and re-approve each device.

5. Ask the community. Post your openclaw doctor output and gateway logs in the OpenClaw GitHub Discussions or Discord server.

Skip Token Management Entirely

ClawTank handles gateway tokens, device pairing, container persistence, and automatic TLS out of the box. No manual token pinning, no Docker volume configuration, no openclaw doctor after every restart. Deploy once and connect from any device.