OpenClaw Gateway 故障排除实录

记录时间：2026-02-27

环境：Windows 10/11 + OpenClaw 2026.2.26

---

问题概述

今天遇到了 OpenClaw Gateway 的两个主要问题：

1. 飞书通道配置错误 - accounts.default is missing
2. 网关令牌不匹配 - gateway token mismatch

本文记录了完整的排查和解决过程。

---

问题一：飞书通道配置错误

错误信息

[Fri 2026-02-27 09:36 GMT+8] - channels.feishu: accounts.default is missing 
and no valid account-scoped binding exists for configured accounts (main). 
Channel-only bindings (no accountId) match only default. 
Add bindings[].match.accountId for one of these accounts (or "*"), 
or add channels.feishu.accounts.default.

原因分析

• 配置文件中飞书账户名为 main
• 系统期望有一个 default 账户
• 绑定规则默认匹配 default，找不到就报错

解决方案

修改配置文件，将 accounts.main 改为 accounts.default：

修改前：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "accounts": {
        "main": {
          "appId": "cli_a9128b71b438dbd9",
          "appSecret": "YOUR_APP_SECRET"
        }
      }
    }
  }
}

修改后：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "accounts": {
        "default": {
          "appId": "cli_a9128b71b438dbd9",
          "appSecret": "YOUR_APP_SECRET"
        }
      }
    }
  }
}

验证结果

openclaw status

输出显示 Feishu: OK ✅，飞书通道恢复正常。

---

问题二：网关令牌不匹配

错误信息

gateway disconnected: unauthorized: gateway token mismatch 
(provide gateway auth token)

gateway connect failed: Error: unauthorized: gateway token mismatch 
(provide gateway auth token)

原因分析

• 网关服务使用的是旧 token
• 配置文件中的 gateway.auth.token 已更新
• 配置文件中缺少 gateway.remote.token（客户端连接时使用的 token）
• 两个 token 不一致导致认证失败

排查过程

1. 检查网关状态：

   openclaw gateway status
   

   输出：

   Runtime: stopped (state Ready, last run time 2026/2/27 9:39:57)
   RPC probe: ok
   

2. 查看日志：

   # 日志位置
   C:\Users\liuni\AppData\Local\Temp\openclaw\openclaw-2026-02-27.log
   

   日志显示网关实际在运行：

   listening on ws://127.0.0.1:18789 (PID 34780)
   feishu[main]: WebSocket client started
   ws client ready
   

3. 检查配置：

   openclaw config get gateway.auth --show-secrets
   openclaw config get gateway.remote --show-secrets
   

   发现 gateway.remote.token 未设置。

解决方案

方案 1：设置客户端连接 token（推荐，无需管理员权限）

openclaw config set gateway.remote.token "YOUR_TOKEN_HERE"

方案 2：重新安装网关服务（需要管理员权限）

# 以管理员身份运行
openclaw gateway install --force

最终解决步骤

# 1. 设置客户端 token
openclaw config set gateway.remote.token "YOUR_TOKEN_HERE"

# 2. 停止旧进程
openclaw gateway stop
taskkill /PID <pid> /F  # 如果进程卡住

# 3. 重启网关
openclaw gateway restart

# 4. 验证状态
openclaw gateway status

验证结果

openclaw gateway status

输出：

Runtime: running (last run time 2026/2/27 10:47:26)
RPC probe: ok
Listening: 127.0.0.1:18789

---

完整配置示例

最终的 openclaw.json 相关配置：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "accounts": {
        "default": {
          "appId": "YOUR_APP_ID",
          "appSecret": "YOUR_APP_SECRET"
        }
      }
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "YOUR_TOKEN_HERE"
    },
    "remote": {
      "token": "YOUR_TOKEN_HERE"
    }
  }
}

关键点：

• gateway.auth.token - 网关服务使用的 token
• gateway.remote.token - 客户端连接时使用的 token
• 两者必须一致

---

故障排除命令速查

命令	用途
openclaw status	查看整体状态
openclaw gateway status	查看网关详细状态
openclaw gateway stop	停止网关
openclaw gateway restart	重启网关
openclaw gateway install --force	重新安装服务（需管理员）
openclaw config get gateway.auth --show-secrets	查看网关认证配置
netstat -ano | findstr :18789	检查端口占用
taskkill /PID <pid> /F	强制结束进程

---

常见状态解读

Runtime: stopped 但 RPC probe: ok

• 含义：网关进程在运行，但不是通过 Windows 计划任务启动的
• 影响：功能正常，不影响使用
• 解决：可选，运行 openclaw gateway install --force 同步状态

Token mismatch 错误

• 原因：gateway.auth.token 和 gateway.remote.token 不一致
• 解决：设置 gateway.remote.token 为相同值

端口被占用

# 查看占用进程
netstat -ano | findstr :18789

# 结束进程
taskkill /PID <pid> /F

---

日志位置

• 文件日志：C:\Users\<用户名>\AppData\Local\Temp\openclaw\openclaw-YYYY-MM-DD.log
• 配置文件：C:\Users\<用户名>\.openclaw\openclaw.json
• 浏览器数据：C:\Users\<用户名>\.openclaw\browser\openclaw\user-data

---

总结

1. 飞书通道问题：账户名必须是 default，不能是 main
2. 网关令牌问题：需要同时设置 gateway.auth.token 和 gateway.remote.token
3. 优先使用非管理员方案：设置 gateway.remote.token 比重新安装服务更简单
4. 查看日志很重要：Runtime: stopped 不一定代表网关没在运行

---

文档版本: 1.0
创建日期: 2026-02-27
适用版本: OpenClaw 2026.2.x