跳转至

故障排除

这是深度运维手册。请先访问 /help/troubleshooting 完成快速分流流程。

命令阶梯

按以下顺序运行:

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

健康信号:

  • openclaw gateway status 显示 Runtime: running、成功的连通性检查,以及 Capability: ... 一行。
  • openclaw doctor 报告没有阻塞性的配置/服务问题。
  • openclaw channels status --probe 显示每个账户的实时传输状态,并在支持的情况下显示 works 或 audit ok。

症状索引

本页是一个索引。运维手册的各章节按症状领域记录在六个页面中。请打开与你当前所见相符的页面。

页面 适用场景
更新与回滚 更新、降级或脑裂安装导致 Gateway 停机或状态不匹配。
技能与模型提供商 技能根目录被跳过,或提供方调用因 429、403 或静默的 Agent 运行错误而失败。
Agent 回复与控制界面 运行因存储错误而失败、没有回复到达,或 Control UI 无法连接。
Gateway 服务与进程 服务无法运行或无法保持运行、macOS 监督机制异常,或内存压力导致退出。
配置验证与检查 Gateway 拒绝了某配置,或 status 和 doctor 输出中出现检查警告。
频道投递与工具 频道已连接但未投递,或节点/浏览器工具调用失败。

各章节移往何处

本页此前发布的所有锚点均保留于此,因此诸如 /gateway/troubleshooting#gateway-rejected-invalid-config 的现有链接仍可解析。每个条目都指向当前承载相应内容的页面。

如果你升级后某些功能突然失效

大多数升级后的故障是配置漂移,或现在强制执行了更严格的默认设置。

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.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

需要检查:

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

常见特征:

  • refusing to bind gateway ... without auth → 非回环绑定但没有有效的网关身份验证路径。
  • 运行时正在运行但连接检查失败 → 网关存活,但使用当前身份验证/URL 无法访问。
3. 配对和设备身份状态已更改
openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

需要检查:

  • 仪表板/节点的待处理设备批准。
  • 策略或身份更改后的待处理 DM 配对批准。

常见特征:

  • device identity required → 设备身份验证未满足。
  • pairing required → 发送方/设备必须被批准。

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

openclaw gateway install --force
openclaw gateway restart

相关:

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw