Gateway 故障排查

本页是深度排查手册。如果你想先走快速分诊流程，请从 /openclaw/help/troubleshooting 开始。

排查命令梯队

按顺序依次执行：

bash

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 显示频道已连接/就绪。

Anthropic 429：长上下文需要额外用量

当日志/错误中出现以下内容时使用： HTTP 429: rate_limit_error: Extra usage is required for long context requests

bash

openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models

排查要点：

所选 Anthropic Opus/Sonnet 模型是否设置了 params.context1m: true。
当前 Anthropic 凭据是否不符合长上下文用量资格。
请求是否仅在会话/模型运行时间较长、需要 1M beta 路径时才失败。

解决方案：

对该模型禁用 context1m，回退到普通上下文窗口。
使用有账单的 Anthropic API key，或在订阅账号上开启 Anthropic Extra Usage。
配置备用模型，在 Anthropic 长上下文请求被拒绝时继续运行。

相关文档：

无回复

如果频道已连接但没有任何回复，在重连任何东西之前先检查路由和策略。

bash

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 → 发送者/频道被策略过滤。

相关文档：

控制台 UI 连接问题

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

bash

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

排查要点：

正确的探测 URL 和控制台 URL。
客户端与 Gateway 之间的认证模式/token 不匹配。
设备身份验证需要但使用了 HTTP（非安全上下文）。

常见特征：

device identity required → 非安全上下文或缺少设备认证。
device nonce required / device nonce mismatch → 客户端未完成基于挑战的设备认证流程（connect.challenge + device.nonce）。
device signature invalid / device signature expired → 客户端对当前握手签名了错误的载荷（或时间戳过期）。
AUTH_TOKEN_MISMATCH 且 canRetryWithDeviceToken=true → 客户端可以使用缓存的设备 token 重试一次。
重试后仍然 unauthorized → 共享 token/设备 token 漂移；刷新 token 配置并在必要时重新审批/轮换设备 token。
gateway connect failed: → 目标主机/端口/URL 错误。

认证详情代码速查表

从失败的 connect 响应中提取 error.details.code 来决定下一步操作：

详情代码	含义	建议操作
`AUTH_TOKEN_MISSING`	客户端未发送必需的共享 token	粘贴/设置 token 后重试。控制台路径：`openclaw config get gateway.auth.token`，然后在 Control UI 设置中粘贴。
`AUTH_TOKEN_MISMATCH`	共享 token 与 Gateway 认证 token 不匹配	如果 `canRetryWithDeviceToken=true`，允许一次受信任重试。仍失败则运行 token 漂移恢复清单。
`AUTH_DEVICE_TOKEN_MISMATCH`	每设备缓存 token 已过期或被吊销	使用 devices CLI 轮换/重新审批设备 token，然后重新连接。
`PAIRING_REQUIRED`	设备身份已知但未审批此角色	审批待处理请求：`openclaw devices list` 然后 `openclaw devices approve <requestId>`。

设备认证 v2 迁移检查：

bash

openclaw --version
openclaw doctor
openclaw gateway status

如果日志显示 nonce/签名错误，更新连接客户端并确认其：

等待 connect.challenge
对绑定挑战的载荷签名
在 connect.params.device.nonce 中发送相同的挑战 nonce

相关文档：

Gateway 服务未运行

当服务已安装但进程无法持续运行时使用。

bash

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

排查要点：

Runtime: stopped 并附带退出提示。
服务配置不匹配（Config (cli) 与 Config (service) 不一致）。
端口/监听冲突。

常见特征：

Gateway start blocked: set gateway.mode=local → 未启用本地 Gateway 模式。修复：在配置中设置 gateway.mode="local"（或运行 openclaw configure）。通过 Podman 运行 OpenClaw 时，默认配置路径为 ~/.openclaw/openclaw.json。
refusing to bind gateway ... without auth → 非回环地址绑定但未配置认证。
another gateway instance is already listening / EADDRINUSE → 端口冲突。

相关文档：

频道已连接但消息不流通

如果频道状态为已连接但消息传输停滞，重点检查策略、权限和频道特定交付规则。

bash

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 → 频道认证/权限问题。

相关文档：

/openclaw/channels/troubleshooting

定时任务和心跳未执行

如果定时任务或心跳未运行或未推送，先验证调度器状态，再检查投递目标。

bash

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

排查要点：

定时任务已启用且下次唤醒时间存在。
任务运行历史状态（ok、skipped、error）。
心跳跳过原因（quiet-hours、requests-in-flight、alerts-disabled）。

常见特征：

cron: scheduler disabled; jobs will not run automatically → 定时任务已禁用。
cron: timer tick failed → 调度器 tick 失败；检查文件/日志/运行时错误。
heartbeat skipped 且 reason=quiet-hours → 不在活跃时间窗口内。
heartbeat: unknown accountId → 心跳投递目标的账号 ID 无效。
heartbeat skipped 且 reason=dm-blocked → 心跳目标解析为 DM 类型目标，但 agents.defaults.heartbeat.directPolicy（或每 agent 覆盖）设置为 block。

相关文档：

节点已配对但工具失败

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

bash

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

排查要点：

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

常见特征：

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

相关文档：

浏览器工具失败

当 Gateway 本身正常但浏览器工具操作失败时使用。

bash

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

排查要点：

有效的浏览器可执行文件路径。
CDP 配置文件可达性。
existing-session / user 配置文件需要本地 Chrome 可用。

常见特征：

Failed to start Chrome CDP on port → 浏览器进程启动失败。
browser.executablePath not found → 配置的路径无效。
No Chrome tabs found for profile="user" → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签。
Browser attachOnly is enabled ... not reachable → 仅附加模式的配置文件没有可达目标。

相关文档：

/openclaw/tools/browser

升级后某些功能突然失效

大多数升级后的故障是配置漂移，或更严格的默认值开始生效。

1）认证和 URL 覆盖行为已变更

bash

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

检查要点：

如果 gateway.mode=remote，CLI 调用可能指向远程 Gateway，而你的本地服务是正常的。
显式 --url 调用不会回退到存储的凭据。

常见特征：

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

2）绑定和认证保护更严格

bash

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）配对和设备身份状态已变更

bash

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

检查要点：

控制台/节点的待处理设备审批。
策略或身份变更后的 DM 配对待审批。

常见特征：

device identity required → 设备认证未满足。
pairing required → 发送者/设备必须审批。

如果服务配置与运行时在检查后仍不一致，从同一配置文件/状态目录重新安装服务元数据：

bash

openclaw gateway install --force
openclaw gateway restart

相关文档：

Gateway 故障排查 ​

排查命令梯队 ​

Anthropic 429：长上下文需要额外用量 ​

无回复 ​

控制台 UI 连接问题 ​

认证详情代码速查表 ​

Gateway 服务未运行 ​

频道已连接但消息不流通 ​

定时任务和心跳未执行 ​

节点已配对但工具失败 ​

浏览器工具失败 ​

升级后某些功能突然失效 ​

1）认证和 URL 覆盖行为已变更 ​

2）绑定和认证保护更严格 ​

3）配对和设备身份状态已变更 ​

Gateway 故障排查

排查命令梯队

Anthropic 429：长上下文需要额外用量

无回复

控制台 UI 连接问题

认证详情代码速查表

Gateway 服务未运行

频道已连接但消息不流通

定时任务和心跳未执行

节点已配对但工具失败

浏览器工具失败

升级后某些功能突然失效

1）认证和 URL 覆盖行为已变更

2）绑定和认证保护更严格

3）配对和设备身份状态已变更