Skip to content
OpenClaw 书稿预览

第14章 排障手册：从现象到根因

🎯 本章目标：学完这章，你能系统化地排查和解决问题

⏱️ 预计时间：30分钟

📋 前置要求：已完成前13章

本章你将学会什么

Section titled “本章你将学会什么”
  • 官方排障命令阶梯（先看状态，再下诊断）
  • 安装与启动问题的定位方法
  • 模型鉴权与可用性问题的定位方法
  • 渠道消息不通、配对失败的排查方法
  • Skill 不可用（不在可用清单 --eligible）的根因定位方法

14.1 排障方法论（先别乱改配置）

Section titled “14.1 排障方法论（先别乱改配置）”

14.1.1 核心口诀

Section titled “14.1.1 核心口诀”
先看状态，再看服务，再看日志，最后修配置

14.1.2 官方命令阶梯（按这个顺序跑）

Section titled “14.1.2 官方命令阶梯（按这个顺序跑）”
Terminal window
openclaw status
Terminal window
openclaw gateway status
Terminal window
openclaw logs --follow
Terminal window
openclaw doctor
Terminal window
openclaw channels status --probe

给小白一个“30秒定位卡”：

  • 命令都报错/找不到：先看 Node/npm 和安装路径；
  • 能运行但没回复：先看 gateway status 和 logs --follow；
  • 特定渠道不通：直接跑 channels status --probe；
  • 技能装了不能用：先看可用清单 skills list --eligible。

操作提醒：排障时一次只改一项（只改模型、或只改渠道、或只改配置），每改一次就立刻复测，避免把问题越改越混。

14.1.3 每条命令在看什么

Section titled “14.1.3 每条命令在看什么”
  • openclaw status：看全局概览（Gateway、会话、渠道摘要）。
  • openclaw gateway status：看服务状态 + RPC 探测（是不是“进程活着但连不上”）。
  • openclaw logs --follow：看实时报错，拿到第一现场。
  • openclaw doctor：跑自动体检，必要时可加 --repair 走引导修复。
  • openclaw channels status --probe：对渠道做探测（连通性/权限/状态）。

你可以把它理解成：
概览命令负责“判方向”，日志命令负责“拿证据”。

14.2 安装问题排查

Section titled “14.2 安装问题排查”

14.2.1 “command not found”

Section titled “14.2.1 “command not found””

症状：输入 openclaw 提示找不到命令。

排查步骤：

Terminal window
node --version
Terminal window
npm --version
Terminal window
which openclaw
Terminal window
npm prefix -g
Terminal window
echo $PATH

如果 npm prefix -g 对应的 bin 不在 PATH，把它补进 shell 配置后重开终端。

14.2.2 安装失败（尤其是 EACCES）

Section titled “14.2.2 安装失败（尤其是 EACCES）”

常见报错是 EACCES: permission denied（全局 npm 目录不可写）。

优先方案（更稳）：使用官方无 root 安装脚本：

Terminal window
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

如果你仍使用 npm 全局安装，再按你机器策略处理权限（例如用户级 prefix）。

14.2.3 Gateway 起不来/启动后立刻退出

Section titled “14.2.3 Gateway 起不来/启动后立刻退出”

先跑：

Terminal window
openclaw gateway status
Terminal window
openclaw logs --follow
Terminal window
openclaw doctor

常见根因：

  • gateway.mode 未设为 local（本地网关被阻止启动）
  • 端口冲突（EADDRINUSE）
  • 非 loopback 绑定但没配鉴权（安全护栏拦截）

快速核对：

Terminal window
openclaw config get gateway.mode
Terminal window
openclaw config get gateway.bind
Terminal window
openclaw config get gateway.auth.mode

14.3 模型问题排查

Section titled “14.3 模型问题排查”

14.3.1 401/403错误

Section titled “14.3.1 401/403错误”

症状：模型调用返回 401/403 或 unauthorized。

排查步骤：

Terminal window
openclaw models status --probe
Terminal window
openclaw models list
Terminal window
openclaw logs --follow

再看三件事：

  1. Key/Token 是否有效（是否被重置或过期）
  2. 账户额度是否耗尽
  3. 选中的 provider/model 是否存在于当前配置

14.3.2 模型响应慢/超时

Section titled “14.3.2 模型响应慢/超时”

排查：

Terminal window
openclaw models status --probe
Terminal window
openclaw logs --follow

解决方案：

  • 切换到更快或更稳定的模型
  • 检查网络连接
  • 降低单次输出长度（避免一次输出过大）

14.3.3 “Model not found”

Section titled “14.3.3 “Model not found””

原因：配置的模型名称错误，或 provider 没启用。

解决：

Terminal window
openclaw models list
Terminal window
openclaw models set <provider/model>

14.4 渠道问题排查

Section titled “14.4 渠道问题排查”

14.4.1 消息发出去没反应

Section titled “14.4.1 消息发出去没反应”

排查流程：

Terminal window
openclaw channels list
Terminal window
openclaw channels status --probe
Terminal window
openclaw pairing list <channel>
Terminal window
openclaw logs --follow

14.4.2 飞书长连接失败

Section titled “14.4.2 飞书长连接失败”

症状：飞书平台显示“长连接订阅失败”。

检查清单：

  • 应用已发布（版本管理与发布 → 已发布）
  • Gateway 正在运行
  • 事件订阅已开启
  • 订阅了 im.message.receive_v1 事件

解决：

Terminal window
openclaw gateway restart

然后在飞书平台按“先关闭长连接并保存，再开启并保存”的顺序重置订阅。

14.4.3 @机器人没反应

Section titled “14.4.3 @机器人没反应”

检查：

  1. 机器人在群里吗？
  2. 是否启用了 requireMention（群聊是否必须 @）？
  3. 用户配对了吗？
  4. 群聊白名单包含这个群吗？

核对配置可用：

Terminal window
openclaw config get channels

14.5 Skill问题排查

Section titled “14.5 Skill问题排查”

14.5.1 Skill不显示在列表

Section titled “14.5.1 Skill不显示在列表”

排查：

Terminal window
ls ~/.openclaw/workspace/skills/
Terminal window
ls ~/.openclaw/workspace/skills/your-skill/SKILL.md
Terminal window
openclaw skills check

14.5.2 Skill运行失败

Section titled “14.5.2 Skill运行失败”

排查：

Terminal window
openclaw skills info your-skill
Terminal window
openclaw skills list --eligible
Terminal window
openclaw logs --follow

14.5.3 Skill依赖缺失

Section titled “14.5.3 Skill依赖缺失”

症状：openclaw skills info 显示缺少 bins/env/config，或技能不在可用清单（--eligible）里。

排查顺序：

Terminal window
openclaw skills info <skill-name>
Terminal window
openclaw skills check
Terminal window
openclaw config get tools.profile
Terminal window
openclaw config get tools.allow
Terminal window
openclaw config get tools.deny

如果会话启用了 sandbox，还要再看：

Terminal window
openclaw sandbox explain

这条命令可以理解成“沙箱解释器”：
它会告诉你到底是工具权限拦了，还是沙箱规则拦了。

14.6 排障决策树

Section titled “14.6 排障决策树”
问题类型判断
    ↓
安装问题？ → 检查Node版本 → 检查PATH/安装路径 → 再看gateway status
    ↓
模型问题？ → models status --probe → 检查额度/鉴权 → 切换模型验证
    ↓
渠道问题？ → channels status --probe → pairing list → 查日志
    ↓
Skill问题？ → list --eligible → skills info/check → sandbox explain
    ↓
其他问题？ → 查看logs → 搜索文档 → 社区求助

14.7 何时寻求帮助

Section titled “14.7 何时寻求帮助”

如果你已经：

  • 按本章步骤排查过
  • 试过重启 Gateway
  • 查看过日志但无法解决

求助渠道：

  1. 官方文档：https://docs.openclaw.ai
  2. GitHub Issues：https://github.com/openclaw/openclaw/issues
  3. 官方社区入口：以 docs 站点导航中的 Community 为准

提问时请提供：

  • OpenClaw版本：openclaw --version
  • 操作系统版本
  • 完整的错误信息
  • 已尝试的解决方法

本章小结

Section titled “本章小结”

排障的核心要点：

  1. status → gateway status → logs → doctor → channels probe - 系统化排查
  2. 分层定位 - 安装/模型/渠道/Skill
  3. 检查清单 - 按清单逐项排查
  4. 日志为王 - 日志里有答案
  5. 及时求助 - 别在死胡同里打转

下一步：第15章，多Workspace与多Agent配置。

动手试试

Section titled “动手试试”
  1. 运行 openclaw doctor，看看有没有潜在问题
  2. 查看 openclaw logs，熟悉日志格式
  3. 模拟一个错误（如停掉Gateway），再按本章命令阶梯完整走一遍