OpenClaw 启动报错 disconnected (1008): gateway token mismatch 解决方案
问题现象
OpenClaw 启动后，控制台输出以下报错信息：
disconnected (1008): unauthorized: gateway token mismatch (open the dashboard URL and paste the token in Control UI settings)
该错误属于 WebSocket 握手阶段的认证失败，错误码 1008 是 WebSocket 协议中定义的 Policy Violation，表示服务端因策略原因主动拒绝连接。
错误原因分析
当客户端（CLI、远程节点或 Control UI 浏览器）连接到 Gateway 时，会在握手阶段携带一个 Token。Gateway 会将该 Token 与自身配置中的 gateway.auth.token 进行比对。一旦不匹配，Gateway 将立即拒绝 WebSocket 连接，返回 1008 错误。
常见导致 Token 不匹配的场景包括：
- Gateway 重启后生成了新的 Token，但客户端仍使用旧 Token
- 通过浏览器收藏夹或旧标签页访问 Dashboard（URL 中不含最新 Token）
- 手动修改了配置文件中的 auth.token，但未同步更新 remote.token
- Docker 环境变量静默覆盖了挂载配置文件中的 Token 值
快速修复方案
重新打开带 Token 的 Dashboard URL
如果你是通过浏览器的旧标签页或直接访问 http://127.0.0.1:18789/ 打开的 Dashboard，那么浏览器不会携带当前有效的 Token。
可以通过以下方式获取最新的 Dashboard 链接：
# 方式 1：自动打开浏览器
openclaw dashboard
# 方式 2：仅输出 URL，手动复制到浏览器
openclaw dashboard --no-open
⚠️ 安全提示
请勿收藏带 Token 的 Dashboard URL！Token 应当被视为密码，每次通过命令获取即可。
对齐配置文件中的 Token
打开配置文件 ~/.openclaw/openclaw.json，重点关注以下两个字段：
{
"gateway": {
"auth": {
"token": "my-secret-token"
}
},
"remote": {
"url": "ws://localhost:18789",
"token": "my-secret-token"
}
}
确认 auth.token 与 remote.token 的值完全一致。如果不同，使用以下命令同步：
# 将 remote.token 设置为与 auth.token 一致
openclaw config set gateway.remote.token "YOUR_AUTH_TOKEN_HERE"
# 重启 Gateway 使配置生效
openclaw gateway restart
使用自动诊断修复
OpenClaw 内置了诊断工具，可以自动检测并修复大多数配置问题（包括 401 Unauthorized、429 Rate Limit Exceeded、Token Mismatch 等）：
openclaw doctor --fix
如果你不确定问题根因，优先尝试 openclaw doctor --fix，它能覆盖大部分常见配置错误。
Docker 用户特别注意
在 Docker 中运行 OpenClaw 时，docker-compose.yml 或 docker run 命令中设置的环境变量会静默覆盖挂载配置文件中的值。这意味着：即使 ~/.openclaw/openclaw.json 中的 Token 是正确的，一个过时的 OPENCLAW_GATEWAY_TOKEN 环境变量也会导致持续报错，且常规排查无效。
排查方法
# 进入容器查看所有 OpenClaw 相关环境变量
docker exec <container_name> env | grep OPENCLAW
如果输出中出现 OPENCLAW_GATEWAY_TOKEN，且其值与配置文件中的 gateway.auth.token 不一致，这就是问题所在。
修复方法
在 docker-compose.yml 中更新或删除该环境变量：
services:
openclaw:
image: openclaw:latest
environment:
# 方案 A：更新为正确的 Token
- OPENCLAW_GATEWAY_TOKEN=正确的 Token 值
# 方案 B：直接删除此行，让配置文件生效
# - OPENCLAW_GATEWAY_TOKEN=xxx
修改完成后重启容器：
docker compose down && docker compose up -d
彻底修复流程
如果以上快速修复方法都不奏效，可以执行完整的 Token 重置流程：停止 → 清除 → 重启。
第一步：停止 Gateway 并确认已停止
# 原生部署
openclaw gateway stop
ps aux | grep openclaw
# Docker 部署
docker compose stop
docker ps | grep openclaw
第二步：清除旧 Token
删除每个 Agent 的 auth.json 文件中的 token 值。
❌ 注意
只删除 auth.json 中的 token 值，不要删除整个文件！
第三步：重新启动 Gateway
Gateway 在启动时会自动生成新的 Token。
openclaw gateway start
第四步：重新连接所有 Agent
Agent 首次连接时会自动获取并保存新 Token，无需手动操作。
💡 Docker 用户提示
日常重启推荐使用 docker compose restart；仅在需要全新容器状态时才使用 docker compose down && docker compose up -d。
易混淆错误辨析
请注意区分以下两种 Token Mismatch 错误，它们的修复方式完全不同：
| 对比项 | Gateway Token Mismatch | Device Token Mismatch |
|---|---|---|
| 认证对象 | Agent → Gateway 的连接 | 浏览器 / Control UI 会话 |
| 涉及配置 | gateway.auth.token | device.token |
| 典型场景 | Gateway 重启、配置不同步 | 更换浏览器、清除 Cookie |
| 修复方式 | 对齐 auth.token 和 remote.token | 重新打开 Dashboard URL |
常用命令速查表
| 场景 | 命令 |
|---|---|
| 自动诊断修复 | openclaw doctor --fix |
| 查看当前 Gateway Token | openclaw config get gateway.auth.token |
| 重新生成 Token | openclaw doctor --generate-gateway-token |
| 打开带 Token 的 Dashboard | openclaw dashboard --no-open |
| 同步 Remote Token | openclaw config set gateway.remote.token "TOKEN" |
| 重启 Gateway | openclaw gateway restart |
总结
disconnected (1008): gateway token mismatch 错误的本质是客户端与服务端持有的 Token 不一致。绝大多数情况下，通过以下三步即可快速解决：
- 首先尝试 openclaw doctor --fix 自动修复；
- 如未解决，检查配置文件中 auth.token 与 remote.token 是否一致；
- Docker 用户额外检查环境变量 OPENCLAW_GATEWAY_TOKEN 是否存在覆盖。
如果上述方法均无效，执行完整的「停止 → 清除 → 重启」流程即可彻底解决。
