Gateway 故障排除

此页面是深度运行手册。 如果您想要快速分诊流程，请从 /help/troubleshooting 开始。

命令阶梯

首先按顺序运行这些：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

预期健康信号：

• openclaw gateway status 显示 Runtime: running 和 RPC probe: ok。
• openclaw doctor 报告没有阻塞配置/服务问题。
• openclaw channels status --probe 显示已连接/就绪的渠道。

无回复

如果渠道已启动但没有回复，请在重新连接之前检查路由和策略。

openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow

查找：

• DM 发送者的配对待处理。
• 群组提及门控（requireMention、mentionPatterns）。
• 渠道/群组允许列表不匹配。

常见签名：

• drop guild message (mention required → 群组消息在提及前被忽略。
• pairing request → 发送者需要批准。
• blocked / allowlist → 发送者/渠道被策略过滤。

相关：

• /channels/troubleshooting
• /channels/pairing
• /channels/groups

仪表板控制 UI 连接

当仪表板/控制 UI 无法连接时，验证 URL、认证模式和安全上下文假设。

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

查找：

• 正确的探测 URL 和仪表板 URL。
• 客户端和 Gateway 之间的认证模式/令牌不匹配。
• 需要设备身份时使用 HTTP。

常见签名：

• device identity required → 非安全上下文或缺少设备认证。
• unauthorized / 重新连接循环 → 令牌/密码不匹配。
• gateway connect failed: → 错误的主机/端口/URL 目标。

相关：

• /web/control-ui
• /gateway/authentication
• /gateway/remote

Gateway 服务未运行

当服务已安装但进程未保持运行时使用此命令。

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep

查找：

• Runtime: stopped 带有退出提示。
• 服务配置不匹配（Config (cli) vs Config (service)）。
• 端口/监听器冲突。

常见签名：

• Gateway start blocked: set gateway.mode=local → 本地 Gateway 模式未启用。修复：在配置中设置 gateway.mode="local"（或运行 openclaw configure）。如果您通过使用专用 openclaw 用户的 Podman 运行 OpenClaw，配置位于 ~openclaw/.openclaw/openclaw.json。
• refusing to bind gateway ... without auth → 非回环绑定没有令牌/密码。
• another gateway instance is already listening / EADDRINUSE → 端口冲突。

相关：

• /gateway/background-process
• /gateway/configuration
• /gateway/doctor

渠道连接消息不流动

如果渠道状态已连接但消息流已死，关注策略、权限和渠道特定投递规则。

openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels

查找：

• DM 策略（pairing、allowlist、open、disabled）。
• 群组允许列表和提及要求。
• 缺少渠道 API 权限/范围。

常见签名：

• mention required → 消息被群组提及策略忽略。
• pairing / 待批准跟踪 → 发送者未批准。
• missing_scope、not_in_channel、Forbidden、401/403 → 渠道认证/权限问题。

相关：

• /channels/troubleshooting
• /channels/whatsapp
• /channels/telegram
• /channels/discord

Cron 和心跳投递

如果 cron 或心跳未运行或未投递，首先验证调度程序状态，然后验证投递目标。

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

查找：

• Cron 启用且下一次唤醒存在。
• 作业运行历史状态（ok、skipped、error）。
• 心跳跳过原因（quiet-hours、requests-in-flight、alerts-disabled）。

常见签名：

• cron: scheduler disabled; jobs will not run automatically → cron 已禁用。
• cron: timer tick failed → 调度程序滴答失败；检查文件/日志/运行时错误。
• heartbeat skipped 带有 reason=quiet-hours → 在活动时间窗口之外。
• heartbeat: unknown accountId → 心跳投递目标无效账户 ID。
• heartbeat skipped 带有 reason=dm-blocked → 心跳目标解析为 DM 样式目标，而 agents.defaults.heartbeat.directPolicy（或每个代理覆盖）设置为 block。

相关：

• /automation/troubleshooting
• /automation/cron-jobs
• /gateway/heartbeat

节点配对工具失败

如果节点已配对但工具失败，隔离前台、权限和批准状态。

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status

查找：

• 具有预期功能的节点在线。
• 相机/麦克风/位置/屏幕的 OS 权限授予。
• 执行批准和允许列表状态。

常见签名：

• NODE_BACKGROUND_UNAVAILABLE → 节点应用必须在前台。
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → 缺少 OS 权限。
• SYSTEM_RUN_DENIED: approval required → 执行批准待处理。
• SYSTEM_RUN_DENIED: allowlist miss → 命令被允许列表阻止。

相关：

• /nodes/troubleshooting
• /nodes/index
• /tools/exec-approvals

浏览器工具失败

当浏览器工具操作失败但 Gateway 本身健康时使用此命令。

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

查找：

• 有效的浏览器可执行路径。
• CDP 配置可达性。
• profile="chrome" 的扩展转发选项卡附加。

常见签名：

• Failed to start Chrome CDP on port → 浏览器进程启动失败。
• browser.executablePath not found → 配置路径无效。
• Chrome extension relay is running, but no tab is connected → 扩展转发未附加。
• Browser attachOnly is enabled ... not reachable → 仅附加配置没有可达目标。

相关：

• /tools/browser-linux-troubleshooting
• /tools/chrome-extension
• /tools/browser

如果您升级后突然坏了

大多数升级后损坏是配置漂移或现在强制执行更严格的默认值。

1) 认证和 URL 覆盖行为更改

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

要检查：

• 如果 gateway.mode=remote，CLI 调用可能正在针对远程，而您的本地服务正常。
• 显式 --url 调用不回退到存储的凭据。

常见签名：

• gateway connect failed: → 错误的 URL 目标。
• unauthorized → 端点可达但认证错误。

2) 绑定和认证护栏更严格

openclaw config get gateway.bind
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

要检查：

• 非回环绑定（lan、tailnet、custom）需要配置认证。
• 旧密钥如 gateway.token 不能替换 gateway.auth.token。

常见签名：

• refusing to bind gateway ... without auth → 绑定+认证不匹配。
• RPC probe: failed 而运行时正在运行 → Gateway 活着但当前认证/URL 不可访问。

3) 配对和设备身份状态更改

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

要检查：

• 配对需要重新批准（如果密钥轮换或设置更改）。
• 设备身份验证失败。
• 未知设备 ID。

常见签名：

• device identity required → 设备身份缺失或无效。
• unauthorized → 令牌不匹配。

相关：

• /gateway/pairing
• /gateway/authentication
• /gateway/doctor

Gateway 日志位置

Gateway 写入滚动日志文件（启动时打印为 gateway log file: ...）。

路径（macOS）：~/Library/Logs/openclaw/

路径（Linux）：~/.config/openclaw/logs/ 或 /tmp/openclaw/

路径（Docker）：stdout（使用 docker logs 查看）

过滤日志

按类别过滤：

openclaw logs --follow --filter "error,warn"
openclaw logs --follow --filter "channel:whatsapp"
openclaw logs --follow --filter "agent"

搜索特定错误

openclaw logs | grep "ERROR"
openclaw logs | grep "EADDRINUSE"

获取帮助

如果以上步骤均未解决问题：

1. 收集日志：openclaw logs --follow（运行 30 秒）
2. 收集状态：openclaw status --deep
3. 运行诊断：openclaw doctor

相关：

• 帮助
• Community Forum
• GitHub Issues