本页内容

本页内容

网关

故障排查

这是深度运行手册。请先从 /help/troubleshooting 开始,查看快速分诊流程。

命令阶梯

按以下顺序运行:

bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

健康信号:

  • openclaw gateway status 显示 Runtime: running、成功的连接检查和 Capability: ... 线路。
  • openclaw doctor 报告没有阻塞 config/service 问题。
  • openclaw channels status --probe 显示按账户划分的实时传输状态,并且在支持的情况下显示 works 或 audit ok。

症状指数

此页是一个索引。操作手册部分记录在六页上,按症状区域分组。打开与您所看到的内容相符的页面。

页面 读它的时候
更新和回滚 更新、降级或裂脑安装导致网关关闭或不匹配。
技能与模型提供者 跳过技能根,或者提供商调用因 429、403 或静默代理运行错误而失败。
代理回复和 Control UI 运行因存储错误而失败,没有回复到达,或者 Control UI 将无法连接。
网关服务及流程 服务将无法运行或保持运行状态、macOS 监管行为不当或内存强制退出。
配置验证和检查 网关拒绝配置,或检查状态和医生输出中出现的警告。
渠道交付和工具 通道已连接但未下发,或者节点或浏览器工具调用失败。

各部分移动的地方

此页面用于发布的每个锚点都保留在此处,因此现有链接(例如 /gateway/troubleshooting#gateway-rejected-invalid-config)仍然可以解析。每个条目都指向现在保存内容的页面。

如果你在升级后突然遇到故障

大多数升级期间的故障都是由配置漂移或现在启用了更严格的默认值引起的。

1. Auth 和 URL 覆盖行为已更改
bash
openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

需要检查的内容:

  • 如果 gateway.mode=remote,CLI 调用可能指向远程端,而你的本地服务实际上是正常的。
  • 显式的 --url 调用不会回退到已保存的凭据。

常见特征:

  • gateway connect failed: → 目标 URL 错误。
  • unauthorized → 端点可达,但认证错误。
2. Bind和auth护栏更严格
bash
openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

需要检查的内容:

  • 非环回绑定(lan、tailnet、custom)需要有效的网关身份验证路径:共享 token/password 身份验证,或正确配置的非环回 trusted-proxy 部署。
  • 较旧的键,例如 gateway.token,不能替代 gateway.auth.token。

常见特征:

  • refusing to bind gateway ... without auth → 非 loopback 绑定,但没有有效的 gateway 认证路径。
  • a 在运行时运行时连接检查失败 → 网关处于活动状态,但无法使用当前 auth/url. 进行访问
3. 配对和设备身份状态已更改
bash
openclaw devices listopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --followopenclaw doctor

需要检查的内容:

  • dashboard/nodes. 的待批准设备
  • 在策略或身份变更后,是否存在待处理的 DM 配对批准。

常见特征:

  • device identity required → 设备认证不满足。
  • pairing required → sender/device 必须获得批准。

如果检查后服务配置和运行时仍然不一致,请从同一 profile/state 目录重新安装服务元数据:

bash
openclaw gateway install --forceopenclaw gateway restart

相关:

相关内容

本页有帮助吗?