【OpenClaw】启动报错 disconnected (1008): unauthorized: gateway token mismatch
【OpenClaw】启动报错 disconnected (1008): unauthorized: 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 值
三、快速修复（60 秒）
方法一：重新打开带 Token 的 Dashboard URL
如果你是通过浏览器的旧标签页或直接访问 http://127.0.0.1:18789/ 打开的 Dashboard，那么浏览器不会携带当前有效的 Token。
修复步骤：
# 方式 1：自动打开浏览器 openclaw dashboard # 方式 2：仅输出 URL，手动复制到浏览器 openclaw dashboard --no-open ⚠️ 安全提示
请勿收藏带 Token 的 Dashboard URL！Token 应当被视为密码，每次通过命令获取即可。
方法二：对齐配置文件中的 Token
打开配置文件 ~/.openclaw/openclaw.json，重点关注以下两个字段：
{"gateway":{"auth":{"token":"my-secret-token"// ← Gateway 服务端使用},"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 相关环境变量dockerexec<container_name>env|grep OPENCLAW 如果输出中出现 OPENCLAW_GATEWAY_TOKEN，且其值与配置文件中的 gateway.auth.token 不一致 —— 这就是问题所在。
🛠️ 修复方法
在 docker-compose.yml 中更新或删除该环境变量：
# docker-compose.ymlservices: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 → ② 清除旧 Token → ③ 启动 Gateway → ④ 重连 Agent Step 1：停止 Gateway 并确认已停止
# 原生部署 openclaw gateway stop ps aux |grep openclaw # Docker 部署docker compose stop dockerps|grep openclaw Step 2：清除旧 Token
删除每个 Agent 的 auth.json 文件中的 token 值。
❌ 注意
只删除auth.json中的 token 值，不要删除整个文件！
Step 3：重新启动 Gateway
Gateway 在启动时会自动生成新的 Token。
openclaw gateway start Step 4：重新连接所有 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是否存在覆盖。
如果上述方法均无效，执行完整的「停止 → 清除 → 重启」流程即可彻底解决。
🎉 希望本文对你有帮助！
如果解决了你的问题，请点赞 👍 收藏 ⭐ 关注 🔔，你的支持是我持续输出的动力！有问题欢迎在评论区留言交流~
