$cd ../troubleshooting/
β High Impact#gateway#auth
device token mismatch β Gateway Auth Broken After Upgrade
After upgrading OpenClaw (especially past 2026.2.14), CLI, Control UI, and sub-agents may all fail with device token mismatch even though your config looks correct. The usual root cause is a stale OPENCLAW_GATEWAY_TOKEN baked into the systemd (or launchd / Scheduled Task) service file β that env var overrides openclaw.json. This unofficial guide walks through diagnosis and permanent fixes tested on Ubuntu 24.04 and Mac Mini.
Written by Jason Guo Β· Unofficial community guide Β· Tested against common Ubuntu systemd + Mac Mini setups Β· Not affiliated with the official OpenClaw project
TL;DR
- 1.Symptom: openclaw gateway status β device token mismatch; Control UI / CLI auth fails.
- 2.Cause: OPENCLAW_GATEWAY_TOKEN in the service unit (or .env) does not match gateway.auth.token in ~/.openclaw/openclaw.json.
- 3.Fast fix: remove the stale Environment= line from the systemd unit, daemon-reload, restart gateway.
- 4.Then verify with openclaw gateway status and a fresh Control UI login.
symptom.log
π Symptoms
$ openclaw gateway status
[ERROR] device token mismatch β rejecting client
[WARN] Control UI / CLI auth failed after upgrade
Example log / status output
β Logs or CLI show: device token mismatch
β openclaw gateway status fails auth even though the process is running
β Control UI / WebUI cannot connect after an upgrade or doctor --fix
β Sub-agents and remote clients disconnect while Telegram/WhatsApp may still look 'up'
β Started after openclaw gateway install, token rotation, or migration from older Clawdbot installs
root_cause.md
π§ͺ Root causes (pick your match)
#A
Stale OPENCLAW_GATEWAY_TOKEN in systemd user service
// openclaw gateway install writes Environment=OPENCLAW_GATEWAY_TOKEN=... into ~/.config/systemd/user/openclaw-gateway.service. Later token rotation (doctor --fix, config edit, upgrade) updates openclaw.json but not the unit file. The env var wins β mismatch.
β Fix A
#B
.env and openclaw.json disagree
// You set OPENCLAW_GATEWAY_TOKEN in ~/.openclaw/.env (or shell profile) to an old value while gateway.auth.token in openclaw.json was regenerated. Env overrides config.
β Fix B
#C
Stricter auth after 2026.2.14+
// Older builds were lenient about mismatched device/gateway tokens. Newer builds correctly reject the mismatch β the bug was always there; validation got stricter.
β Fix A or B
#D
macOS launchd / Windows Scheduled Task baked the old token
// Same pattern as systemd: the daemon definition still exports an old token after you rotated secrets.
β Fix C
fix.sh
β Fixes
Fix A β Clear stale token from systemd (most common on Linux VPS)
# 1) Confirm the stale env is present
$ grep OPENCLAW_GATEWAY_TOKEN ~/.config/systemd/user/openclaw-gateway.service
# 2) Remove the Environment= line (keep a backup)
$ cp ~/.config/systemd/user/openclaw-gateway.service ~/openclaw-gateway.service.bak
$ sed -i '/OPENCLAW_GATEWAY_TOKEN=/d' ~/.config/systemd/user/openclaw-gateway.service
# 3) Reload + restart
$ systemctl --user daemon-reload
$ systemctl --user restart openclaw-gateway
$ openclaw gateway status
Fix B β Sync .env with openclaw.json (or remove the env override)
# Compare env override vs config token
$ grep OPENCLAW_GATEWAY_TOKEN ~/.openclaw/.env 2>/dev/null
$ grep -n 'auth.token\\|"token"' ~/.openclaw/openclaw.json
# Option 1: delete the env override and rely on openclaw.json
$ sed -i '/OPENCLAW_GATEWAY_TOKEN=/d' ~/.openclaw/.env
# Option 2: set .env to the exact same value as gateway.auth.token
# then restart gateway / container
Fix C β macOS launchd / Windows: reinstall daemon after rotating token
# macOS
$ openclaw service uninstall 2>/dev/null || true
$ openclaw service install
$ openclaw service restart
# Windows: recreate the Scheduled Task / service after token rotation so it no longer exports a stale OPENCLAW_GATEWAY_TOKEN
Fix D β Regenerate a fresh gateway token (when you want a clean secret)
$ openclaw doctor --generate-gateway-token
# Then apply Fix A/B so no stale Environment= remains
$ systemctl --user restart openclaw-gateway
β Verify
$ openclaw gateway status
$ openclaw doctor
# Control UI should connect without device token mismatch
π‘οΈ Prevention checklist
- βAfter any token rotation, re-run openclaw gateway install (or edit the unit) so the service file does not keep an old Environment= line
- βPrefer storing the token in ~/.openclaw/.env OR openclaw.json β not both with different values
- βNever commit OPENCLAW_GATEWAY_TOKEN to git or paste it into public issues
- βOn non-loopback binds, keep gateway.auth.mode at token/password β do not set mode: none on a public interface
- βAfter upgrades, run openclaw doctor and openclaw gateway status before assuming the bot is healthy
β FAQ
Q1. What does device token mismatch mean in OpenClaw?
The client (CLI, Control UI, or sub-agent) is presenting a device/gateway credential that does not match the secret the gateway process is actually using. Most often the gateway process inherited OPENCLAW_GATEWAY_TOKEN from systemd while clients read a newer gateway.auth.token from openclaw.json.
Q2. Why did this start after I upgraded?
Around 2026.2.14 OpenClaw tightened token validation. Previously a stale systemd env token could be silently tolerated. After the upgrade, the same mismatch surfaces as an explicit error. Fix the stale env β do not downgrade to hide it.
Q3. Is it safe to delete OPENCLAW_GATEWAY_TOKEN from the systemd unit?
Yes, if gateway.auth.token (or a correctly synced .env next to the config) is present. Removing the baked-in Environment= line lets the gateway read the current secret at runtime. After daemon-reload and restart, clients that use the current config secret should authenticate again.
Q4. Do I need to rescan WhatsApp / Telegram QR codes?
Usually no. This is gateway control-plane auth, not messaging-channel session auth. Channel sessions under ~/.openclaw/ should survive if your volumes/paths were not wiped. If a channel still fails after gateway auth is fixed, treat it as a separate session issue.
Q5. How do I regenerate a gateway token safely?
Generate and persist a new token (openclaw doctor --generate-gateway-token or your version's equivalent), ensure openclaw.json / .env match, remove any stale Environment= lines from the service file, then restart the gateway and reconnect Control UI clients with the new secret.
Q6. Does this affect Docker deployments?
Yes if you pass OPENCLAW_GATEWAY_TOKEN in compose environment: and later change only the mounted config. Keep a single source of truth β either the compose env value or the config file β and recreate the container after rotating.