Skip to content
OpenClaw 书稿预览

排障手册：从现象到根因的最短路径

这一章是你的值班救火手册。

想象一下：凌晨三点，系统报警，你揉着眼睛打开电脑——心里慌不慌？这章就是让你在这种时候能淡定地掏出「标准动作表」，一步步把问题搞定。不管是新手上路还是老手复习，照着做就行。

本章你将学会什么

Section titled “本章你将学会什么”
  • 用统一方法减少”瞎猜问题”，不再抓瞎
  • 快速搞定安装启动、模型调用、渠道消息、技能执行这四类高频故障
  • 学会看日志里的关键词，直接对应到修复动作
  • 把一次故障变成可复用的经验，下次就快了

读者前置

Section titled “读者前置”
  • 你已完成第 2 章和第 7 章
  • 你能跑这两个命令：
Terminal window
openclaw status
Terminal window
openclaw logs --follow

如果这两个命令还跑不熟，先回去翻第 2 章，不丢人。

12.1 排障方法论（最短路径）

Section titled “12.1 排障方法论（最短路径）”

核心原则：排障快不快，不看你工作年限，看你有没有用对方法。

12.1.1 先跑命令阶梯，再分析细节

Section titled “12.1.1 先跑命令阶梯，再分析细节”

什么叫”命令阶梯”？就是先跑简单的、必跑的命令，再根据结果决定下一步查什么。这就像去医院挂号——护士先让你量体温测血压，不会一来就让你做 CT。

官方建议你先跑这组命令，按顺序来：

Terminal window
openclaw status              # ① 看整体状态，健康不健康
openclaw gateway status     # ② 看网关活着没
openclaw logs --follow       # ③ 看实时日志，一边跑一边观察
openclaw doctor              # ④ 让系统自己诊断问题
openclaw channels status --probe  # ⑤ 探一下各渠道通不通

小贴士：--follow 参数的意思是”持续输出”，像看直播一样，日志会源源不断刷新。想知道具体参数啥意思？加 --help 就能看到官方解释。

12.1.2 统一四步法

Section titled “12.1.2 统一四步法”

任何故障都按这四步走，别跳步，别偷懒：

步骤干啥的举个例子
1. 现象确认先稳定复现问题，别慌里慌张就开始修用户说”收不到消息”，你得先确认是不是每次都收不到
2. 分层定位猜猜问题出在哪一层：网关 / 模型 / 渠道 / 技能是所有渠道都不通，还是就微信不行？
3. 最小修复一次只改一件事，别改一堆别同时改配置又重装服务又换模型，出了新问题你都不知道谁害的
4. 回归验证改完了一定要复测，别以为改了就完事了再发条消息看看能不能收到

人话版：就像修水管——先看水漏在哪（现象），判断是水管破了还是水龙头坏了（分层），只换那一段管子（最小修复），打开水龙头试试漏不漏（回归验证）。

12.1.3 不要做的三件事

Section titled “12.1.3 不要做的三件事”

这三件事，新手特别容易犯，一定要避开：

  1. 同时改多项配置 — 出了新问题，你都不知道是哪个改动的锅
  2. 不看日志直接重装 — 重装能解决一切的话，要医生干嘛？日志里有线索
  3. 没有回滚点就升级 — 升级前先备份配置！否则升级翻车了，你连退都退不回去

12.2 安装与启动问题

Section titled “12.2 安装与启动问题”

这部分专门针对刚装完或者启动时报错的情况。

12.2.1 网关起不来

Section titled “12.2.1 网关起不来”

症状：输入 openclaw gateway start 或者相关命令，系统报错说网关启动失败。

先跑这两个命令：

Terminal window
openclaw gateway status --deep   # 深入检查网关状态
openclaw doctor                  # 让系统自己诊断

常见原因就三个：

错误现象可能原因怎么办
报 EADDRINUSE端口被占用 — 别的程序用了 8080 或者 8081 端口换端口或者关掉占用程序
报 gateway.mode 相关错误网关模式配错了（比如配了 gateway 但配的是 standalone）检查 openclaw.yaml 里的 gateway.mode 配置
鉴权失败API Key 没填或者填错了去渠道后台重新生成 key，填到配置里

12.2.2 安装后命令可执行但行为异常

Section titled “12.2.2 安装后命令可执行但行为异常”

症状：命令能跑，但结果不对。比如 openclaw status 显示一切正常，但 Bot 就是不响应。

优先检查三件事：

  1. Node 版本 — 太低或者太高都可能出问题
    Terminal window
    node --version  # 看看是啥版本
  2. 旧字段残留 — 配置里可能有已经废弃的字段，doctor 会提示你迁移
  3. state 目录权限 — 读写权限不对，Bot 存不了数据
    Terminal window
    ls -la ~/.openclaw/state  # 看看权限对不对

12.2.3 快速修复动作

Section titled “12.2.3 快速修复动作”

如果实在不知道问题在哪，先跑这个，让它自己试着修：

Terminal window
openclaw doctor --repair

如果 doctor 搞不定，强制重装网关：

Terminal window
openclaw gateway install --force

记住：重装是最后一招，不是第一招。先跑 doctor，让它告诉你问题在哪。

12.3 模型调用失败

Section titled “12.3 模型调用失败”

模型就是帮你处理对话的”大脑”。大脑罢工了，Bot 就不会说话。

12.3.1 先判断是”单模型失败”还是”全局失败”

Section titled “12.3.1 先判断是”单模型失败”还是”全局失败””
  • 单模型失败：只有某个模型不能用，其他模型正常 — 优先查这个模型的 ID、Key、Provider 配置
  • 全局失败：所有模型都挂了 — 优先查网关和基础配置

12.3.2 最短排查命令

Section titled “12.3.2 最短排查命令”

按这个顺序跑，一根烟的功夫就能定位：

Terminal window
openclaw models list                    # ① 看有哪些模型，配对了没
openclaw logs --follow                   # ② 看实时日志，报啥错
openclaw doctor                          # ③ 让系统诊断

12.3.3 高概率错误速查

Section titled “12.3.3 高概率错误速查”
日志里看到什么可能原因第一动作
Unknown model模型 ID 拼写错了，或者根本没配置重新跑 openclaw models set <model-id>
401 或 403Key 过期了，或者权限不够去模型提供商的后台更新 Key，然后 models set 重新配置
频繁 timeout网络太慢，或者模型提供商服务器拥塞检查 fallback 配置（备选模型）和超时设置

人话版：401 就是”你不认识我”，403 是”你认识我但我没权限”。跟门口保安似的——401 是没带身份证，403 是带了身份证但没带邀请函。

12.4 渠道消息不通

Section titled “12.4 渠道消息不通”

渠道就是 Bot 接收消息的入口：飞书、Slack、Telegram……

12.4.1 入口策略先查，不要先重连

Section titled “12.4.1 入口策略先查，不要先重连”

很多人一看”收不到消息”，第一反应就是”网络断了”、“重连一下”——其实大部分时候是策略配置挡住了。

先查这几个配置：

配置项干啥的常见值
dmPolicy私聊消息策略pairing（要审批）、allowlist（只给白名单）、open（谁都能聊）、disabled（禁用）
groupPolicy群聊策略同上
mention gating@Bot 时是否必须 @有的渠道要求必须 @，有的不用

12.4.2 最短排查命令

Section titled “12.4.2 最短排查命令”
Terminal window
openclaw channels status --probe     # ① 探一下各渠道通不通
openclaw pairing list <channel>      # ② 看谁提交了配对申请还没批
openclaw config get channels          # ③ 直接看渠道配置

12.4.3 常见信号解释

Section titled “12.4.3 常见信号解释”
日志/现象什么意思怎么办
pairing request用户想加 Bot，但你没审批去后台批准
blocked / allowlist入口策略拒绝了消息检查白名单/黑名单配置
missing_scope / Forbidden / 401/403渠道权限或 Token 有问题去渠道后台检查 App 权限，重新生成 Token

12.5 技能执行异常

Section titled “12.5 技能执行异常”

技能就是 Bot 的”技能包”，让它能查天气、查数据库、调用外部 API。

12.5.1 先看资格，再看执行

Section titled “12.5.1 先看资格，再看执行”

别一上来就改 prompt！先看看这个技能有没有资格执行：

Terminal window
openclaw skills list --eligible        # ① 看哪些技能现在能用
openclaw skills info <name>            # ② 看具体某个技能的详情

如果技能不在 --eligible 列表里，说明依赖条件没满足——可能是：

  • 缺少某个二进制工具（bins）
  • 缺少环境变量（env）
  • 配置文件不对（config）

先修依赖，别改 prompt。prompt 改对了但工具没有，照样跑不起来。

12.5.2 沙箱与主机环境错位

Section titled “12.5.2 沙箱与主机环境错位”

高频问题：

  • 在你的电脑上跑，技能正常
  • 在沙箱（Sandbox，安全隔离环境）里跑，挂了

常见原因：

  • 沙箱里缺少依赖包
  • 沙箱里没有网络
  • 沙箱里环境变量没传进去

先跑这个命令定位：

Terminal window
openclaw sandbox explain

它会告诉你沙箱里有什么、缺什么。

12.5.3 技能排障最短闭环

Section titled “12.5.3 技能排障最短闭环”

记住这个万能公式，每次都这么走：

skills info → logs follow → 最小输入复测 → 修一项 → 再复测

翻译成人话：

  1. 先看技能配置（skills info）
  2. 盯着日志跑一遍（logs --follow）
  3. 用最简单的输入试试能不能跑通
  4. 只改一个地方（配置/依赖/prompt 选一个）
  5. 再跑一次验证

坚持走这个闭环，你永远不会陷入”越修越乱”的死循环。

本章小结

Section titled “本章小结”
  • 排障速度来自方法，不是来自经验。多跑 doctor + status + logs 这三件套，比啥都强。
  • 入口策略（dmPolicy / groupPolicy）、模型配置、技能依赖是三大高发区，80% 的问题出在这。
  • 每次修完故障，一定要写记录。下次再遇到，一翻笔记就知道咋整，不用从头排查。
  • 记住四步法：现象确认 → 分层定位 → 最小修复 → 回归验证。别跳步，别偷懒。

最后一句大实话：故障不可避免，但有了这套方法，你能从”慌得一批”变成”稳如老狗”。