故障排除

这是深度运维手册。请先前往 /help/troubleshooting 查看快速分流流程。

命令阶梯¶

按以下顺序运行：

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

健康信号：

openclaw gateway status 显示 Runtime: running、Connectivity probe: ok 以及一行 Capability: ...。
openclaw doctor 不报告任何阻塞性的配置/服务问题。
openclaw channels status --probe 显示实时的每账号传输状态，并在支持的情况下显示 works 或 audit ok。

症状索引¶

本页面是一个索引。运维手册章节按症状领域整理在六个页面上。请打开与你看到的现象匹配的页面。

页面	适用场景
更新与回滚	更新、降级或裂脑安装导致 Gateway 宕机或版本不匹配。
技能与模型提供方	技能根目录被跳过，或提供方调用以 429、403 或静默的 agent 运行错误失败。
Agent 回复与 Control UI	运行因存储错误失败、没有回复到达，或 Control UI 无法连接。
Gateway 服务与进程	服务无法运行或保持运行、macOS 监管行为异常，或内存迫使进程退出。
配置验证与探针	Gateway 拒绝了配置，或状态与 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 → 非回环绑定但缺少有效的网关认证路径。
运行时运行期间出现 Connectivity 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/state 目录重新安装服务元数据：

openclaw gateway install --force
openclaw gateway restart

故障排除

命令阶梯¶

症状索引¶

各章节迁移位置¶

如果你升级后突然出现问题¶

相关¶