OpenClaw 启动报错 gateway token mismatch 解决方案

问题表现

OpenClaw 启动后，控制台通常会输出类似以下的错误信息：

disconnected (1008): unauthorized: gateway token mismatch (open the dashboard URL and paste the token in Control UI settings)

这属于 WebSocket 握手阶段的认证失败。错误码 1008 在协议层面表示策略违规，意味着服务端因配置原因主动切断了连接。

为什么会报错

当客户端（CLI、远程节点或浏览器 Dashboard）尝试连接 Gateway 时，会在握手阶段携带一个 Token。Gateway 会拿这个 Token 和自身配置里的 gateway.auth.token 做比对。一旦对不上，连接就会被直接拒绝，返回 1008。

常见导致不匹配的场景有：

• Gateway 重启后生成了新 Token，但客户端还在用旧的
• 浏览器收藏夹里存的是旧标签页的链接（URL 里不带最新 Token）
• 手动改了配置文件里的 auth.token，却没同步更新 remote.token
• Docker 环境变量静默覆盖了挂载配置文件中的值

快速修复方案

重新获取带 Token 的 Dashboard 链接

如果你是通过浏览器直接访问 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"
    },
    "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、Token Mismatch 等）：

openclaw doctor --fix

如果你不确定根因在哪，优先跑这条命令，它能覆盖大部分常见配置错误。

Docker 用户特别注意

在 Docker 环境中运行 OpenClaw 时，环境变量优先级高于挂载的配置文件。这意味着即使 ~/.openclaw/openclaw.json 里的 Token 是对的，只要有一个过时的 OPENCLAW_GATEWAY_TOKEN 环境变量存在，就会持续报错且常规排查无效。

排查方法

进入容器查看相关环境变量：

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 重置流程：停止 → 清除 → 重启。

1. 停止 Gateway

   # 原生部署
   openclaw gateway stop
   ps aux | grep openclaw
   
   # Docker 部署
   docker compose stop
   docker ps | grep openclaw
   

2. 清除旧 Token 删除每个 Agent 的 auth.json 文件中的 token 值。

   ❌ 注意：只删除 auth.json 中的 token 值，不要删除整个文件！

3. 重新启动 Gateway Gateway 启动时会自动生成新的 Token。

   openclaw gateway start
   

4. 重连 Agent Agent 首次连接时会自动获取并保存新 Token，无需手动操作。

💡 提示：日常重启推荐用 docker compose restart；仅在需要全新容器状态时才用 down && up。

易混淆错误辨析

对比项	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 不一致。绝大多数情况下，按以下顺序处理即可解决：

1. 先试 openclaw doctor --fix 自动修复；
2. 检查配置文件里 auth.token 与 remote.token 是否一致；
3. Docker 用户额外检查环境变量 OPENCLAW_GATEWAY_TOKEN 是否存在覆盖。

如果以上都无效，再执行完整的「停止 → 清除 → 重启」流程。