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

确认 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。

易混淆错误辨析

常用命令速查表

总结

disconnected (1008): gateway token mismatch 的本质是客户端与服务端持有的 Token 不一致。绝大多数情况下，按以下顺序处理即可解决：

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

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