排障手册：从现象到根因的最短路径
这一章是“救火手册”。
你可以把它当值班时的标准动作表：先做什么、再看什么、最后怎么修。
本章你将学会什么
Section titled “本章你将学会什么”- 用统一排障方法减少“拍脑袋猜问题”。
- 快速处理安装启动、模型、渠道、技能四大类高频故障。
- 读懂关键日志关键词并映射到修复动作。
- 把一次故障沉淀成可复用的排障资产。
- 你已完成第 2 章和第 7 章。
- 你能运行：
openclaw statusopenclaw logs --follow12.1 排障方法论（最短路径）
Section titled “12.1 排障方法论（最短路径）”12.1.1 先跑命令阶梯，再分析细节
Section titled “12.1.1 先跑命令阶梯，再分析细节”官方建议的基础阶梯：
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe12.1.2 统一四步法
Section titled “12.1.2 统一四步法”任何故障都按这四步走：
- 现象确认（能稳定复现）；
- 分层定位（网关 / 模型 / 渠道 / 技能）；
- 最小修复（一次只改一项）；
- 回归验证（复测核心闭环）。
12.1.3 不要做的三件事
Section titled “12.1.3 不要做的三件事”- 同时改多项配置；
- 不看日志直接重装；
- 没有回滚点就升级。
12.2 安装与启动问题
Section titled “12.2 安装与启动问题”12.2.1 网关起不来
Section titled “12.2.1 网关起不来”先看：
openclaw gateway status --deepopenclaw doctor常见原因：
- 端口冲突（
EADDRINUSE）； - 网关模式不对（
gateway.mode）； - 鉴权配置不完整。
12.2.2 安装后命令可执行但行为异常
Section titled “12.2.2 安装后命令可执行但行为异常”优先检查：
- Node 版本与依赖；
- 配置是否含旧字段（doctor 会提示迁移）；
- state 目录权限是否异常。
12.2.3 快速修复动作
Section titled “12.2.3 快速修复动作”openclaw doctor --repair必要时：
openclaw gateway install --force12.3 模型调用失败
Section titled “12.3 模型调用失败”12.3.1 先判断是“单模型失败”还是“全局失败”
Section titled “12.3.1 先判断是“单模型失败”还是“全局失败””- 单模型失败：优先查 model id / key / provider；
- 全局失败：优先查 gateway 与基础配置。
12.3.2 最短排查命令
Section titled “12.3.2 最短排查命令”openclaw models listopenclaw logs --followopenclaw doctor12.3.3 高概率错误速查
Section titled “12.3.3 高概率错误速查”| 日志/现象 | 可能原因 | 第一动作 |
|---|---|---|
Unknown model | 模型 ID 拼写或未配置 | 重新 models set |
401/403 | key 失效或权限不足 | 更新 key 并复测 |
| 频繁 timeout | 网络或 provider 拥塞 | 检查 fallback 与超时策略 |
12.4 渠道消息不通
Section titled “12.4 渠道消息不通”12.4.1 入口策略先查，不要先重连
Section titled “12.4.1 入口策略先查，不要先重连”很多“收不到消息”不是网络问题，而是策略挡住了。
先查：
dmPolicy（pairing/allowlist/open/disabled）groupPolicy与群组 allowlist- mention gating（是否要求 @）
12.4.2 最短排查命令
Section titled “12.4.2 最短排查命令”openclaw channels status --probeopenclaw pairing list <channel>openclaw config get channels12.4.3 常见信号解释
Section titled “12.4.3 常见信号解释”pairing request：用户未审批；blocked/allowlist：入口策略命中拒绝；missing_scope/Forbidden/401/403：渠道权限或 token 配置问题。
12.5 技能执行异常
Section titled “12.5 技能执行异常”12.5.1 先看资格，再看执行
Section titled “12.5.1 先看资格，再看执行”openclaw skills list --eligibleopenclaw skills info <name>如果技能不在 --eligible，先修依赖条件（bins/env/config），不要直接改 prompt。
12.5.2 沙箱与主机环境错位
Section titled “12.5.2 沙箱与主机环境错位”高频问题：
host 能跑，sandbox 失败（缺依赖、缺环境变量、网络不可达）。
先跑：
openclaw sandbox explain12.5.3 技能排障最短闭环
Section titled “12.5.3 技能排障最短闭环”skills info -> logs follow -> 最小输入复测 -> 修一项 -> 再复测你只要坚持这条，不会陷入“越修越乱”。
- 排障速度来自方法，而不是经验年限。
- 入口策略、模型配置、技能依赖是三大高发区。
doctor + status + logs是你的常驻三件套。- 每次修复都要留记录，才能形成团队可复用手册。