网关故障排查

这是深度排查手册。如果你想先走快速分类流程，先看 /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 显示通道已连接/就绪。

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

日志/错误中出现以下内容时参考此节： HTTP 429: rate_limit_error: Extra usage is required for long context requests。

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

排查方向：

  • 选中的 Anthropic Opus/Sonnet 模型设置了 params.context1m: true。
  • 当前 Anthropic 凭证不具备长上下文使用资格。
  • 只有需要 1M beta 路径的长会话/模型运行才会失败。

修复方案：

  1. 关闭该模型的 context1m，回退到正常上下文窗口。
  2. 使用有计费的 Anthropic API 密钥，或在订阅账户上启用 Anthropic Extra Usage。
  3. 配置备选模型，让 Anthropic 长上下文请求被拒绝时运行可以继续。

相关文档：

没有回复

通道连上了但没有响应时，先检查路由和策略，别急着重连。

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 连不上时，检查 URL、认证模式和安全上下文假设。

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

排查方向：

  • 探测 URL 和面板 URL 是否正确。
  • 客户端和网关之间的认证模式/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 然后粘贴到控制 UI 设置中。
AUTH_TOKEN_MISMATCH共享 token 与网关 auth token 不匹配。如果 canRetryWithDeviceToken=true，允许一次可信重试。仍然失败则参考 token 漂移恢复检查清单。
AUTH_DEVICE_TOKEN_MISMATCH缓存的设备 token 过期或已撤销。通过 devices CLI 轮换/重新审批设备 token，然后重连。
PAIRING_REQUIRED设备身份已知但未被批准用于此角色。审批待处理请求：openclaw devices list 然后 openclaw devices approve <requestId>。

设备认证 v2 迁移检查：

openclaw --version
openclaw doctor
openclaw gateway status

如果日志出现 nonce/签名错误，更新连接客户端并确认它：

  1. 等待 connect.challenge
  2. 签名包含挑战的载荷
  3. 在 connect.params.device.nonce 中发送同一个 challenge nonce

相关文档：

网关服务未运行

服务已安装但进程起不来时参考此节。

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.mode="local"（或运行 openclaw configure）。如果你通过 Podman 使用专用 openclaw 用户运行，配置在 ~openclaw/.openclaw/openclaw.json。
  • refusing to bind gateway ... without auth → 非回环绑定但没有配置 token/密码。
  • another gateway instance is already listening / EADDRINUSE → 端口冲突。

相关文档：

通道已连接但消息不流通

通道状态显示已连接但消息不通时，重点排查策略、权限和通道特定的投递规则。

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 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 → 心跳投递目标的 account id 无效。
  • heartbeat skipped 带 reason=dm-blocked → 心跳目标解析到 DM 类型的目的地，而 agents.defaults.heartbeat.directPolicy（或 per-agent 覆盖）设为 block。

相关文档：

节点已配对但工具调用失败

节点已配对但工具失败时，逐步排查前台状态、权限和审批状态。

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 → 命令被白名单拦截。

相关文档：

浏览器工具失败

网关本身健康但浏览器工具操作失败时参考此节。

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

排查方向：

  • 浏览器可执行路径是否有效。
  • CDP profile 是否可达。
  • profile="chrome" 时扩展 relay tab 是否已附加。

典型日志特征：

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

相关文档：

升级后突然出问题

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

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 但运行时在运行 → 网关存活但当前认证/URL 访问不了。

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

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

排查方向：

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

典型日志特征：

  • device identity required → 设备认证未满足。
  • pairing required → 发送者/设备需要审批。

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

openclaw gateway install --force
openclaw gateway restart

相关文档：

arrow_back
上一页
Multiple Gateways
下一页
Security
arrow_forward