问题

我们遇到了一个关于OpenClaw网关服务的问题，具体表现为在AutoClaw更新后出现连接错误，提示“云端设备未连接，请先启动设备”。通过检查网关状态，发现错误信息为“gateway token mismatch”，即网关的认证令牌不匹配。

AutoClaw报错如下（没写错，AutoClaw 是智谱的产品）

Error invoking remote method 'agent:send': Error: 云端设备未连接，请先启动设备

OpenClaw检查gateway状态报错如下

gateway connect failed: Error: unauthorized: gateway token mismatch (set gateway.remote.token to match gateway.auth.token)

报错比较明显，问题在于配置文件（openclaw.json）中的两个令牌（gateway.auth.token和gateway.remote.token）不一致，以下是解决步骤：

1. 修改配置文件：确保openclaw.json中的gateway.auth.token和gateway.remote.token的值相同。
2. 强制重新安装网关服务，以同步新的令牌到Windows计划任务。
3. 重启网关服务。
4. 如果问题仍然存在，重启计算机。

现在，我们将这些步骤具体化：

解决步骤

🔑 1. 统一配置文件中的 token

打开配置文件 

C:\Users\Administrator\.openclaw\openclaw.json，确保以下值完全相同：

{  "gateway": {    "auth": {      "token": "your_shared_token_value"  // 替换为实际值    },    "remote": {      "token": "your_shared_token_value"  // 必须与上方相同    }  }}

⚙️ 2. 强制更新服务配置（关键步骤）

openclaw gateway install --force

此命令会：

• 更新 Windows 计划任务中的环境变量
• 将新 token 同步到系统服务
• 解除旧服务的绑定

🔄 3. 重启网关服务

openclaw gateway restart

🧹 4. 解决端口冲突（如仍存在）

# 查找占用 18789 端口的进程netstat -ano | findstr :18789# 强制终止占用进程（示例 PID 12932）taskkill /F /PID 12932

💻 5. 最终验证

openclaw gateway status

检查输出应包含：

• RPC probe: success
  
  （而非 failed）
• 无 token mismatch 错误
• 端口使用正常

上面一套组合拳还是报错，重启大法走起，包治百病。

OpenClaw Gateway Token 详解

Gateway Token 是 OpenClaw Gateway 的核心鉴权机制，本质上是一个共享密钥（shared secret），用于在客户端（CLI、浏览器 Control UI、远程节点等）与 Gateway 服务之间建立安全的 WebSocket 连接。

一、为什么要引进 Gateway Token

OpenClaw Gateway 作为一个可能暴露在网络中的服务，不只是监听本地回环地址。当以下场景出现时，任何能访问该端口的机器都可以连接到 Gateway：

• 绑定到局域网地址（bind: "lan"）
• 通过 Tailscale Serve/Funnel 对外暴露
• 在 Docker 容器中做端口映射
• 服务器上部署供团队使用

如果没有鉴权，这些场景下 Gateway 就是裸奔的——任何人都可以直接连上来发送指令、调用模型、触发工具。Gateway Token 就是解决这个问题的第一道防线。

同时，OpenClaw 的控制面板（Control UI）运行在浏览器中，通过 WebSocket 与 Gateway 通信。Token 被浏览器保存在 localStorage 中，每次连接时自动携带，对用户来说几乎是透明的——输一次就永久生效，不会牺牲使用体验。

二、Token 的工作机制

服务端（Gateway）

在 openclaw.json 中配置 gateway.auth.token：

{  "gateway": {    "auth": {      "mode": "token",      "token": "你的密钥字符串"    }  }}

• Gateway 启动时读取该值，所有接入的 WebSocket 连接都必须在握手阶段提供匹配的 token
• 如果配置文件中未设置 token，首次启动时 Gateway 会自动生成一个随机字符串并将其写入配置文件
• 非 loopback 绑定（如 LAN、Tailnet）时强制要求设置 auth，否则 Gateway 拒绝启动

客户端（CLI / Control UI / 远程连接）

客户端需要提供 gateway.remote.token，它必须与 gateway.auth.token 完全一致：

{  "gateway": {    "remote": {      "url": "ws://gateway.tailnet:18789",      "token": "与gateway.auth.token相同的值"    }  }}

验证通过后，WebSocket 连接建立，双向通信开始。如果 token 不匹配，会收到：

gateway connect failed: Error: unauthorized: gateway token mismatch(set gateway.remote.token to match gateway.auth.token)

三、Token 的配置要求

四、其他鉴权模式对比

Gateway Token 不是唯一选项。OpenClaw 提供了四种 gateway.auth.mode：

五、Token 生命周期与安全实践

• Token 泄露后的处理
  
  ：如果曾在聊天记录或日志中泄露过 token，需要立即更换——修改 openclaw.json 中的 gateway.auth.token，然后执行 openclaw gateway install --force（Windows 服务模式）或 openclaw gateway restart 使新 token 生效。旧链接和旧书签中携带的 #token=... 会全部失效。CSDN
• 浏览器存储
  
  ：Control UI 将 token 存储在浏览器的 localStorage 中，只需在首次访问 Dashboard 时粘贴一次。更换浏览器或清除站点数据后，需要重新输入。
• Tailscale 场景的特殊处理
  
  ：当 tailscale.mode = "serve" 时，Gateway 还可通过 tailscale whois 验证 Tailscale 身份头，实现无 token 的控制面板访问（gateway.auth.allowTailscale 默认为 true）。
• 失败限流保护
  
  ：gateway.auth.rateLimit 支持对失败鉴权尝试进行限流（默认允许 10 次/分钟，超限后锁定 5 分钟），loopback 默认豁免，防止暴力破解。