OpenClaw 网关 token mismatch 问题解决文档

问题现象

执行 openclaw devices list 或其他 CLI 命令时，报错：


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

同时网关日志显示 reason=token_mismatch。

环境信息

OpenClaw 版本：2026.4.8
安装方式：全局 npm 安装
配置文件路径：~/.openclaw/openclaw.json
网关绑定模式：loopback 或 lan

根本原因

配置缺少 gateway.remote.token 字段
OpenClaw 网关在 bind: loopback 或 lan 模式下，强制要求 CLI 连接时提供 remote.token，且必须与 auth.token 相同。即使只有本地回环连接也不例外。
token 中含有特殊字符
原 token 为 @&4gEgw6@DEWTT，其中的 @ 和 & 可能在 WebSocket 握手或 CLI 参数传递时被错误解析/编码，导致服务端收到的 token 与预期不符。
CLI 未自动读取 remote.token
即使配置文件正确添加了 remote.token，CLI 命令（如 devices list）默认仍不发送该 token，需要显式传递或通过环境变量指定。
旧网关进程未完全停止
修改配置后未重启网关，或 systemd 服务仍在后台运行，导致新配置未生效。

解决步骤

1. 修改配置文件，添加 `remote.token`

编辑 ~/.openclaw/openclaw.json，在 gateway 对象中增加 remote 块：

json
"gateway": {
  "auth": {
    "token": "你的token",
    "mode": "token"
  },
  "remote": {
    "token": "你的token"      // 必须与 auth.token 完全相同
  },
  "bind": "loopback",         // 或 "lan"
  "port": 18789
}

注意 JSON 逗号位置：auth 块后要有逗号，remote 块后也要有逗号（除非是最后一个属性）。

2. 将 token 改为纯数字或简单字符串（避免特殊字符）

推荐使用仅包含字母数字的 token，例如 3283261937 或 mySecret123。
修改后同步更新 auth.token 和 remote.token。

3. 完全停止旧网关进程

bash
openclaw gateway stop
pkill -9 -f openclaw
rm -f ~/.openclaw/gateway.pid          # 删除可能残留的锁文件
# 如果存在 systemd 用户服务，也停止它
systemctl --user stop openclaw-gateway.service

4. 验证配置文件格式与内容

bash
# 检查 token 是否已正确写入
grep '"token"' ~/.openclaw/openclaw.json

# 验证 JSON 格式
python3 -c "import json; json.load(open('/home/aigc/.openclaw/openclaw.json'))" && echo "OK"

5. 重新启动网关（前台运行，便于观察）

bash
openclaw gateway --verbose

等待输出 [gateway] ready 和 Gateway listening...。保持此终端运行。

6. 测试 CLI 命令

在另一个终端中执行：

bash
# 方法一：显式传递 token（最可靠）
openclaw devices list --token "你的token"

# 方法二：使用环境变量（变量名可能因版本而异）
export OPENCLAW_GATEWAY_TOKEN="你的token"
export OPENCLAW_REMOTE_GATEWAY_TOKEN="你的token"
openclaw devices list

# 方法三：若 token 为纯数字且配置正确，有时可直接运行
openclaw devices list

成功时输出设备列表（可能为空），不再报 token mismatch。

7. （可选）将 token 写入环境变量以简化后续使用

将以下两行添加到 ~/.bashrc 或 ~/.zshrc：

bash
export OPENCLAW_GATEWAY_TOKEN="你的token"
export OPENCLAW_REMOTE_GATEWAY_TOKEN="你的token"

之后重新登录或执行 source ~/.bashrc，即可直接运行 openclaw devices list 而无需每次指定 --token。

验证成功的标志

openclaw devices list 正常返回设备列表（可能为空）。
openclaw dashboard 能正常打开 Web 界面。
网关日志中不再出现 unauthorized 或 token_mismatch。

常见误区与注意事项

误区	正确做法
只设置 `auth.token`，忽略 `remote.token`	无论 `bind` 值如何，都同时设置两者且保持一致
修改配置后不重启网关	必须完全停止旧进程（包括 systemd 服务）再启动
token 中包含 `@`、`&`、`#` 等特殊字符	尽量使用字母数字，或确保在 CLI 中用双引号包裹并正确转义
依赖 CLI 自动读取 `remote.token`	当前版本 CLI 不会自动读取，需用 `--token` 或环境变量
使用 `CLAW_GATEWAY_TOKEN` 环境变量	官方文档推荐 `OPENCLAW_GATEWAY_TOKEN`（注意前缀）

附录：最小可用配置示例

json
{
  "gateway": {
    "auth": { "token": "3283261937", "mode": "token" },
    "remote": { "token": "3283261937" },
    "bind": "loopback",
    "port": 18789
  }
}

参考链接

文档版本：1.0
最后更新：2026-04-08
适用 OpenClaw 版本：2026.4.8 及以上

目录