故障排除
这是深度运维手册。请先访问 /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 的现有链接仍可解析。每个条目都指向当前承载相应内容的页面。
- 更新之后
- 已准备好的模型运行时发布超时
- 脑裂安装与较新配置保护
- 修复 PATH
- 重新安装 Gateway 服务
- 移除过时的包装器
- 回滚后的协议不匹配
- 技能符号链接因路径逃逸被跳过
- Anthropic 429:长上下文需要额外用量
- 使用标准上下文窗口
- 使用符合条件的凭据
- 配置备用模型
- 上游 403 拦截的响应
- 本地 OpenAI 兼容后端通过直接检查,但 Agent 运行失败
- 常见特征(本地后端)
- 修复选项(本地后端)
- Agent 运行因存储错误而失败
- 无回复
- Dashboard 控制界面连通性
- 连接 / 认证签名
- 认证详情代码速查表
- 等待 connect.challenge
- 对 payload 签名
- 发送设备 nonce
- Gateway 服务未运行
- 常见特征(Gateway 服务)
- macOS Gateway 静默停止响应,随后在你触碰 Dashboard 时恢复
- macOS launchd 监督循环(存在重复的 gateway/node LaunchAgents)
- Gateway 在高内存占用时退出
- Gateway 拒绝了无效配置
- 发生了什么
- 检查与修复
- 常见特征(无效配置)
- 修复选项(无效配置)
- Gateway 检查警告
- 频道已连接,消息未流动
- Cron 与心跳投递
- 常见特征(Cron 与心跳)
- Node 已配对,工具失败
- 浏览器工具失败
- 插件 / 可执行文件特征
- Chrome MCP / 现有会话特征
- Element / 截图 / 上传特征
如果你升级后某些功能突然失效¶
大多数升级后的故障是配置漂移,或现在强制执行了更严格的默认设置。
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→ 发送方/设备必须被批准。
如果检查后服务配置和运行时仍然不一致,请从相同的配置文件/状态目录重新安装服务元数据:
相关:
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw