$cd ../troubleshooting/
⚠ High Impact#gateway#auth
device token mismatch — 升级后网关认证失效
升级 OpenClaw（尤其是 2026.2.14 之后）后，CLI、Control UI 和子 Agent 可能全部报 device token mismatch，但配置看起来完全正确。最常见根因是：systemd（或 launchd / Windows 计划任务）服务文件里写死了旧的 OPENCLAW_GATEWAY_TOKEN，环境变量覆盖了 openclaw.json。本文是非官方社区排错指南，覆盖 Ubuntu 24.04 与 Mac Mini 上的常见修复。
作者 Jason Guo · 非官方社区指南 · 基于 Ubuntu systemd 与 Mac Mini 常见环境 · 与 OpenClaw 官方项目无关联
一句话结论
- 1.症状：openclaw gateway status → device token mismatch；Control UI / CLI 认证失败。
- 2.原因：服务单元（或 .env）里的 OPENCLAW_GATEWAY_TOKEN 与 ~/.openclaw/openclaw.json 中的 gateway.auth.token 不一致。
- 3.快修：删掉 systemd 单元里过期的 Environment= 行，daemon-reload，重启 gateway。
- 4.然后用 openclaw gateway status 和新的 Control UI 登录验证。
symptom.log
🔍 症状
$ openclaw gateway status
[ERROR] device token mismatch — rejecting client
[WARN] Control UI / CLI auth failed after upgrade
示例日志 / 状态输出
✓ 日志或 CLI 出现：device token mismatch
✓ 进程在跑，但 openclaw gateway status 认证失败
✓ 升级或 doctor --fix 之后 Control UI 连不上
✓ 子 Agent / 远程客户端断开，但 Telegram/WhatsApp 通道看起来还在
✓ 发生在 gateway install、轮换 token，或从旧版 Clawdbot 迁移之后
root_cause.md
🧪 根本原因（对号入座）
#A
systemd 用户服务里残留旧 OPENCLAW_GATEWAY_TOKEN
// openclaw gateway install 会把 Environment=OPENCLAW_GATEWAY_TOKEN=... 写入 ~/.config/systemd/user/openclaw-gateway.service。之后轮换 token（doctor --fix、改配置、升级）只更新了 openclaw.json，没更新 unit。环境变量优先 → 不一致。
→ 修复 A
#B
.env 与 openclaw.json 不一致
// ~/.openclaw/.env（或 shell profile）里仍是旧 OPENCLAW_GATEWAY_TOKEN，而 openclaw.json 已重新生成。环境变量覆盖配置。
→ 修复 B
#C
2026.2.14+ 校验变严
// 旧版本对 token 不一致更宽松；新版本会正确拒绝。问题本来就存在，只是以前被静默容忍。
→ 修复 A 或 B
#D
macOS launchd / Windows 计划任务写死了旧 token
// 与 systemd 同类问题：守护进程定义仍导出旧 token。
→ 修复 C
fix.sh
✅ 修复方法
修复 A — 清除 systemd 中的过期 token（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
修复 B — 同步 .env 与 openclaw.json（或删除 env 覆盖）
# 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
修复 C — macOS / Windows：轮换 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
修复 D — 重新生成全新 gateway token
$ openclaw doctor --generate-gateway-token
# Then apply Fix A/B so no stale Environment= remains
$ systemctl --user restart openclaw-gateway
✔ 验证
$ openclaw gateway status
$ openclaw doctor
# Control UI should connect without device token mismatch
🛡️ 预防清单
- ✓任何 token 轮换后，重跑 openclaw gateway install（或编辑 unit），避免残留旧 Environment=
- ✓token 只放在 ~/.openclaw/.env 或 openclaw.json 其中一处，避免两处不同值
- ✓不要把 OPENCLAW_GATEWAY_TOKEN 提交到 git 或贴到公开 Issue
- ✓非 loopback 绑定务必保持 token/password 认证，不要在公网接口用 mode: none
- ✓升级后先跑 openclaw doctor 与 openclaw gateway status，再假设机器人健康
❓ 常见问题
Q1. device token mismatch 是什么意思？
客户端（CLI、Control UI 或子 Agent）出示的凭证与网关进程实际使用的密钥不一致。最常见情况是：网关从 systemd 继承了旧的 OPENCLAW_GATEWAY_TOKEN，而客户端读取的是 openclaw.json 里更新后的 gateway.auth.token。
Q2. 为什么升级后才出现？
约 2026.2.14 起 OpenClaw 收紧了 token 校验。以前 systemd 里过期 env 可能被静默容忍；升级后会显式报错。应修复过期 env，而不是降级掩盖问题。
Q3. 从 systemd 删除 OPENCLAW_GATEWAY_TOKEN 安全吗？
可以，前提是 gateway.auth.token（或与配置正确同步的 .env）仍然存在。删除写死的 Environment= 后，网关会在运行时读取当前密钥。daemon-reload 并重启后，使用当前配置密钥的客户端应能重新认证。
Q4. 需要重新扫 WhatsApp / Telegram 二维码吗？
通常不需要。这是网关控制面认证，不是消息通道会话认证。只要 ~/.openclaw/ 下的通道数据没被清掉，会话一般会保留。若网关认证修好后通道仍失败，再按通道会话问题单独排查。
Q5. 如何安全地重新生成 gateway token？
生成并持久化新 token（openclaw doctor --generate-gateway-token 或你版本的等价命令），确保 openclaw.json / .env 一致，删掉服务文件里过期的 Environment=，然后重启网关并用新密钥重连 Control UI。
Q6. Docker 部署也会中招吗？
会。如果你在 compose 的 environment: 里传了 OPENCLAW_GATEWAY_TOKEN，后来只改了挂载的配置文件，就会不一致。保持单一事实来源——要么只用 compose env，要么只用配置文件——轮换后 recreate 容器。