【OpenClaw】启动报错 disconnected (1008): unauthorized: gateway token mismatch

📑 文章目录

• 一、问题现象

• 二、错误原因分析

• 三、快速修复（60 秒）

• 四、Docker 用户特别注意

• 五、彻底修复（停止 → 清除 → 重启）

• 六、易混淆错误辨析

• 七、常用命令速查表

• 八、总结

一、问题现象

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 相关环境变量
docker exec <container_name> env | grep OPENCLAW

如果输出中出现 OPENCLAW_GATEWAY_TOKEN，且其值与配置文件中的 gateway.auth.token 不一致 —— 这就是问题所在。

🛠 修复方法

在 docker-compose.yml 中更新或删除该环境变量：

# 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 → ② 清除旧 Token → ③ 启动 Gateway → ④ 重连 Agent

Step 1：停止 Gateway 并确认已停止

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

# Docker 部署
docker compose stop
docker ps | 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 不一致。

绝大多数情况下，通过以下三步即可快速解决：

1. 首先尝试 openclaw doctor --fix 自动修复；

2. 如未解决，检查配置文件中 auth.token 与 remote.token 是否一致；

3. Docker 用户额外检查环境变量 OPENCLAW_GATEWAY_TOKEN 是否存在覆盖。

如果上述方法均无效，执行完整的「停止 → 清除 → 重启」流程即可彻底解决。

本文档 OpenClaw 故障排查指南，适用于版本 2026.2.26 及以上