OpenClaw 启动报错 disconnected (1008): 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、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 错误，它们的修复方式完全不同：

常用命令速查表

总结

disconnected (1008): gateway token mismatch 错误的本质是客户端与服务端持有的 Token 不一致。绝大多数情况下，通过以下三步即可快速解决：

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

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