Fix "Gateway Token Mismatch" Error

Not the same as Device Token Mismatch — check your exact error

THIS PAGE

unauthorized: gateway token mismatch (set gateway.remote.token…)

Shared secret config mismatch — common in Docker where the gateway regenerates a random token on each restart. Fix: align gateway.auth.token ↔ gateway.remote.token.

OTHER PAGE →

unauthorized: device token mismatch

Per-device credential expired after Gateway restart or update. Fix: openclaw gateway token rotate.

Next Step

Fix now, then reduce repeat incidents

If this issue keeps coming back, validate your setup in Doctor first, then harden your config.

Open Doctor Harden Config

Need proactive alerts? Join Monitor early access.

You see this error when a client (CLI, remote node, or Control UI) connects to the gateway but sends a token that doesn't match gateway.auth.token. The gateway rejects the WebSocket handshake immediately.

Jump to Fix

Quick Fix (60 Seconds) Docker / Docker Compose Environment Variable Override Remote CLI / Node Mode How Gateway Auth Works Still Not Working

What the Error Looks Like

disconnected (1008): unauthorized: gateway token mismatch (set gateway.remote.token to match gateway.auth.token)

gateway connect failed: error: unauthorized: gateway token mismatch (provide gateway auth token)

unauthorized: gateway token missing (open the dashboard url and paste the token in control ui settings)

gateway closed (1008): unauthorized: gateway token mismatch

The key indicator is gateway token mismatch (not "device token mismatch"). This means the shared secret between client and gateway doesn't match.

Quick Fix (60 Seconds)

Align the Tokens

Both sides must use the same token value. Check your config file:

// ~/.openclaw/openclaw.json
{
  "gateway": {
    "auth": {
      "token": "my-secret-token"    // <-- gateway uses this
    },
    "remote": {
      "url": "ws://localhost:18789",
      "token": "my-secret-token"    // <-- client uses this (MUST match)
    }
  }
}

If gateway.auth.token and gateway.remote.token differ, you get this error.

View current config

openclaw config get gateway

Compare the auth.token and remote.token values. If they differ, update one to match the other:

Set matching tokens

# Set the remote token to match the gateway's auth token
openclaw config set gateway.remote.token "YOUR_AUTH_TOKEN_HERE"

# Restart to apply
openclaw gateway restart

Docker / Docker Compose

This is the most common scenario for this error. In Docker, the gateway container and the CLI container are separate processes that need the same token.

Common Docker Trap

The gateway generates a random token on first start if none is configured. On each container rebuild/redeploy, it generates a new random token, breaking the connection with other containers that cached the old one.

Fix: Set an explicit token as an environment variable in docker-compose.yml:

docker-compose.yml

services:
  openclaw-gateway:
    image: openclaw/gateway:latest
    environment:
      OPENCLAW_GATEWAY_TOKEN: "my-fixed-secret-token"
    ports:
      - "18789:18789"

  openclaw-cli:
    image: openclaw/cli:latest
    environment:
      OPENCLAW_GATEWAY_TOKEN: "my-fixed-secret-token"
      OPENCLAW_GATEWAY_URL: "ws://openclaw-gateway:18789"

Both containers now use the same fixed token. This survives rebuilds and redeployments.

Environment Variable Override

The OPENCLAW_GATEWAY_TOKEN environment variable silently overrides whatever is in openclaw.json. This is a common source of confusion:

BUG

Config says token = "abc", env var says token = "xyz"

Gateway uses "xyz" (env wins)

Config says token = "abc", no env var set

Gateway uses "abc" (config)

RISKY

No config token, no env var

Gateway generates random token on start

Check for env override

# Check if the env var is set
echo $OPENCLAW_GATEWAY_TOKEN

# Windows PowerShell
echo $env:OPENCLAW_GATEWAY_TOKEN

Remote CLI / Node Mode

When running a remote CLI node that connects to a gateway on another machine:

Remote node config

// On the REMOTE machine (~/.openclaw/openclaw.json)
{
  "gateway": {
    "remote": {
      "url": "ws://192.168.1.100:18789",
      "token": "MUST_MATCH_THE_GATEWAY_AUTH_TOKEN"
    }
  }
}

The gateway.remote.token on the client machine must exactly match gateway.auth.token on the gateway machine. Copy-paste to avoid typos.

How Gateway Auth Works

Client connects via WebSocket

The CLI or Control UI opens a WebSocket to ws://gateway:18789 and sends the token in the handshake.

Gateway validates token

The gateway compares the received token against gateway.auth.token (or OPENCLAW_GATEWAY_TOKEN env var).

Match = connected, mismatch = 1008

If tokens match, the connection proceeds to device pairing. If not, the gateway closes with code 1008.

Gateway token auth is the first layer. After it passes, the gateway checks device token (second layer) and then device pairing (third layer).

Still Not Working?

Full Debug Checklist

# 1. Check gateway's actual token

openclaw config get gateway.auth.token

# 2. Check client's token

openclaw config get gateway.remote.token

# 3. Check for env var override

echo $OPENCLAW_GATEWAY_TOKEN

# 4. Nuclear reset — set both to the same value

openclaw config set gateway.auth.token "my-new-token"

openclaw config set gateway.remote.token "my-new-token"

openclaw gateway restart

Or use the web-based Error Doctor to paste the full error and get matched fixes.

Seeing Other Errors Too?

Gateway token issues often come with these related problems:

Gateway Monitor detects unplanned restarts in real time and alerts you before stale tokens break your next agent run.

Get Early Access

Fix It Faster With Our Tools

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.

Did this guide solve your problem?