跳转到内容
OpenClaw 实战手册

05-排障 · 01 诊断流程

预计阅读：15 分钟 适用版本：公开稳定包 OpenClaw 2026.5.2；作者端已验证 2026.5.7 · 最后审核：2026-05-09 前置：00-常见问题 / 04-运维/01-日志与监控 本章回答：出了问题怎么分层定位？5 个诊断路径各自适用什么场景？怎么防止瞎猜？

核心方法：分层 + 自顶向下

Section titled “核心方法：分层 + 自顶向下”

排障最大的坑是瞎猜。明明是配置错了，你从 npm 依赖开始翻；明明是记忆索引坏了，你却在改 agent 的 SOUL。

正确的做法：按层级自顶向下排除。OpenClaw 的故障层级：

用户感知层      "飞书不回复"、"回复很慢"、"发错人"
    ↓
渠道层          飞书 / Lark / Slack 插件状态、Webhook 连通
    ↓
Gateway 层      进程是否存活、callback 是否注册、健康状态
    ↓
Agent 层        agent 是否 bootstrap 成功、SOUL 是否冲突
    ↓
记忆 / 工具层   LanceDB 索引、memory 召回、工具链超时
    ↓
系统层          磁盘、权限、launchd、进程泄漏

规则：从”用户说哪儿坏了”往下切，一层层确认健康，直到找到病灶。

5 个诊断路径

Section titled “5 个诊断路径”

按”症状 → 定位路径”映射。

路径 A：Gateway 层诊断

Section titled “路径 A：Gateway 层诊断”

症状：

  • 所有 agent 都不响应
  • 飞书完全收不到回复（不只是慢）
  • openclaw gateway status 报错

步骤：

Terminal window
# A1. 进程是否存活
ps aux | grep openclaw | grep -v grep
# 期望：看到 gateway 主进程


# A2. 健康状态
openclaw gateway status
# 期望：^OK: 开头；如果是 WARN warming 再等 30s


# A3. 端口监听
lsof -i :__PLACEHOLDER_GATEWAY_PORT__ 2>/dev/null
# 期望：LISTEN 状态


# A4. 最近的 gateway 错误
tail -50 ~/.openclaw/logs/gateway.err.log


# A5. launchd 守护（gateway/watchdog 用 ai.* 前缀；digest/maintenance 用 com.* 前缀）
launchctl list | grep -iE "openclaw|claw"
# 期望：ai.openclaw.gateway 的 LastExitCode=0


# A6. gateway 服务路径是否仍指向可用 runtime
bash ~/.openclaw/scripts/runtime-status-report.sh 2>/dev/null || true

常见结论：

  • Gateway 挂了 → openclaw gateway restart
  • launchd 没启 → launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway
  • 端口被占 → lsof -i :PORT 找占用者
  • 重启后”启了但不响应” → 等 ^OK:（详见 04-运维/00-健康检查）
  • 服务路径指向旧 nvm / npm 目录 → bash ~/.openclaw/scripts/repair-gateway-service.sh --repair --restart

路径 B：Agent 层诊断

Section titled “路径 B：Agent 层诊断”

症状：

  • 某个 agent 不响应（其他 agent 正常）
  • 某个 agent 回复变了（人设漂移）
  • 某个 agent 启动报错

步骤：

Terminal window
# B1. 查该 agent 的 session
openclaw sessions list | grep __PLACEHOLDER_AGENT_ID__


# B2. 有没有最近的 bootstrap 错误
grep -i "bootstrap\|__PLACEHOLDER_AGENT_ID__" ~/.openclaw/logs/gateway.err.log | tail -20


# B3. SOUL / IDENTITY 是否损坏
wc -l ~/.openclaw/agents/__PLACEHOLDER_AGENT_ID__/SOUL.md
head -30 ~/.openclaw/agents/__PLACEHOLDER_AGENT_ID__/SOUL.md


# B4. 是否有残留的 .bak 文件占位（有些场景会被误读）
ls ~/.openclaw/agents/__PLACEHOLDER_AGENT_ID__/SOUL.md*


# B5. bootstrap-extra-files 注入是否工作
# 让该 agent 直接回答"你继承了哪些 shared 文件"，应能说出 shared/SOUL.md 等

常见结论：

  • SOUL 被意外改了 → git checkout 或从 .bak 恢复
  • shared/ 改了但没 /reset → 重置 session
  • 不小心加了只有 SOUL 的文件（像 reflector 那样）→ 检查是否故意

路径 C：记忆层诊断

Section titled “路径 C：记忆层诊断”

症状：

  • agent 说”我记得…”但记的是错的
  • memory_recall 不返回预期结果
  • 启动慢 / 响应慢且日志显示 LanceDB 慢查询
  • fragments 数异常（> 500）

步骤：

Terminal window
# C1. LanceDB 状态
ls -la ~/.openclaw/memory/lancedb-pro/memories.lance/
# 期望：能看到 data/ + _versions/ + _transactions/ 三个子目录


# C2. fragments 数（真实 fragment 文件在 data/ 下）
ls ~/.openclaw/memory/lancedb-pro/memories.lance/data/ 2>/dev/null | wc -l
# 阈值：> 500 ⚠️ / > 1000 🚨（对齐 daily-digest.py）


# C3. memory/ 的 md 文件数
find ~/.openclaw/agents/*/memory/ -name "*.md" | wc -l


# C4. 最近一次 consolidation 日志
tail -50 ~/.openclaw/logs/consolidation.log 2>/dev/null \
  || tail -50 ~/.openclaw/logs/daily-maintenance.log


# C5. 手动跑一次召回看效果
# 让 main 执行 memory_recall "已知的某个主题"，看是否返回合理结果

常见结论：

  • fragments > 500 → LanceDB compact 没跑（看 04-运维/00 第 6 节）
  • md 没被索引 → 触发一次 consolidation 脚本
  • 召回返回空 → 向量维度可能变了（升级过 embedding 模型？），需 rebuild

路径 D：派发 / 协作层诊断

Section titled “路径 D：派发 / 协作层诊断”

症状：

  • main → subagent 派发没响应
  • subagent 跑完了但结果没回来
  • 派发链爆炸（看到 N 个 subagent 同时跑）

步骤：

Terminal window
# D1. 当前所有 subagent
openclaw subagents list
# 期望：数量正常（不超过 __PLACEHOLDER_MAX_CONCURRENT__）
# ⚠️ 如果报 `command is unavailable because plugins.allow excludes "subagents"`，
#    把 `subagents` 加进 openclaw.json 的 plugins.allow 数组再重启 gateway。


# D2. 孤儿 subagent（父 agent 已退出，子还在跑）
openclaw subagents list --orphan 2>/dev/null


# D3. 派发历史
grep "sessions_send\|sessions_spawn" ~/.openclaw/logs/gateway.log | tail -30


# D4. 派发是否触发 memoryFlush
grep "memoryFlush\|softThresholdTokens" ~/.openclaw/logs/gateway.log | tail -20


# D5. 并发上限
grep -E "maxConcurrent|maxSpawnDepth|maxChildrenPerAgent" ~/.openclaw/openclaw.json

常见结论：

  • subagent 卡住 → openclaw subagents steer <id> "汇报当前进度" 或 --kill
  • 派发链爆炸 → 检查 maxSpawnDepth，通常应为 2
  • 结果没回 → 派发用了 sessions_send 但目标 agent 在跑别的 / 退出了

路径 E：渠道 / 工具层诊断

Section titled “路径 E：渠道 / 工具层诊断”

症状：

  • 飞书能收到但 agent 回复”消息发送失败”
  • 工具调用报 401 / 403 / 超时
  • callback 注册失败

步骤：

Terminal window
# E1. credentials 是否存在 + 权限
ls -l ~/.openclaw/credentials/
# 期望：-rw------- (600)


# E2. 最近的 auth 错误
grep -Ei "401|403|auth|invalid signature|appSecret" ~/.openclaw/logs/gateway.err.log | tail -20


# E3. 飞书 / Lark 插件状态
grep -E "channels|feishu|lark" ~/.openclaw/openclaw.json | head -20


# E4. 手动测一次渠道连通
# 示例（飞书）：
curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json" \
  -d '{"app_id":"__PLACEHOLDER_APP_ID__","app_secret":"__PLACEHOLDER_APP_SECRET__"}'
# 期望：code=0，返 tenant_access_token


# E5. callback 注册日志
grep -i "callback\|webhook" ~/.openclaw/logs/gateway.log | tail -20

常见结论：

  • appSecret 过期 → 去开发者后台刷新，改 credentials
  • 时间不同步导致签名失败 → 检查系统时区 + NTP
  • callback URL 变了（如切换内网穿透） → 飞书后台改回调地址

自检 checklist（遇到故障时的前 10 分钟）

Section titled “自检 checklist（遇到故障时的前 10 分钟）”

按顺序跑，不要跳：

Terminal window
# 1. doctor 一键自检
openclaw doctor


# 2. gateway 状态
openclaw gateway status


# 3. 今日 err 日志最后 30 条
tail -30 ~/.openclaw/logs/gateway.err.log


# 4. alerts.log 最后 10 条
tail -10 ~/.openclaw/logs/alerts.log


# 5. 磁盘
df -h ~/.openclaw/


# 6. launchd（两套前缀都抓：ai.openclaw.* + com.openclaw.*）
launchctl list | grep -iE "openclaw|claw"


# 7. 当前 subagent
openclaw subagents list


# 8. LanceDB fragments
ls ~/.openclaw/memory/lancedb-pro/memories.lance/data/ 2>/dev/null | wc -l


# 9. gateway 服务路径和 runtime 基线
bash ~/.openclaw/scripts/runtime-status-report.sh 2>/dev/null || true

通常这几步跑完，症状在哪一层就清楚了。再按路径 A-E 深入。

常见”看起来像 X 其实是 Y”

Section titled “常见”看起来像 X 其实是 Y””

排障里最费时间的，是错诊。几个典型错配：

错诊 1：以为是”agent 变笨”，其实是 shared/ 污染

Section titled “错诊 1：以为是”agent 变笨”，其实是 shared/ 污染”
  • 症状：某 agent 回复变差
  • 正确检查：git diff 看 shared/ 最近改了什么。常常是有人改了 shared/SOUL.md，没注意会影响所有 agent

错诊 2：以为是”网络问题”，其实是系统时间漂移

Section titled “错诊 2：以为是”网络问题”，其实是系统时间漂移”
  • 症状：飞书 API 401 invalid signature
  • 正确检查：date 看系统时间，对比 NTP 服务器。macOS 可以 sudo sntp -sS time.apple.com

错诊 3：以为是”记忆坏了”，其实是召回 scope 不对

Section titled “错诊 3：以为是”记忆坏了”，其实是召回 scope 不对”
  • 症状：某 agent 问”我的偏好是什么”，返回了 main 的偏好而不是自己的
  • 正确检查：memory_recall 默认按调用方 agent 的可访问 scope 过滤，跨 agent 查必须显式传 scope

错诊 4：以为是”OpenClaw bug”，其实是 patch 链失配

Section titled “错诊 4：以为是”OpenClaw bug”，其实是 patch 链失配”
  • 症状：升级后某功能表现异常
  • 正确检查：
    • CLI 侧兼容修复：node ~/.openclaw/scripts/apply-openclaw-cli-hotfixes.mjs
    • openclaw-lark 插件侧修复：
      Terminal window
      bash ~/.openclaw/scripts/apply-openclaw-lark-patches.sh
      bash ~/.openclaw/scripts/verify-openclaw-lark-patches.sh

排障记录模板

Section titled “排障记录模板”

每次排障结束后，写一份到 memory/traps/YYYY-MM-DD-<故障名>.md：

# 故障：<一句话>


- 症状：用户视角描述
- 触发：做了什么后出现的
- 误判路径：最初怀疑的方向 + 为什么错
- 根因：真正的原因
- 修复：具体命令 / 改动
- 预防：以后怎么避免 / 怎么早发现


## 时间线
- HH:MM 发现
- HH:MM 开始排查
- HH:MM 修复
- HH:MM 验证完成

重点：写”误判路径”。下次重犯同类错时，这条记忆能救你。

什么时候升级到”求救”

Section titled “什么时候升级到”求救””

自己搞了 > 30 分钟还没头绪时，停下来：

  1. 打开完整 snapshot（tar czf /tmp/debug.tar.gz --exclude credentials ~/.openclaw/logs ~/.openclaw/openclaw.json）
  2. 去 OpenClaw github issues 搜症状
  3. 没有相同 issue → 写一份 bug report（脱敏后）

不要在这 30 分钟里乱改配置。改了还不对 = 你连”原始症状”都描述不清楚了。

验证清单

Section titled “验证清单”
检查项怎么验
能分清 5 个层看到症状能说出”这应该是 C 路径”
前 10 分钟自检走得顺真故障时不慌，8 步扫完
openclaw doctor 跑得通平时就会跑，不是出事才跑
排障记录归档memory/traps/ 有条目

下一步

Section titled “下一步”

本章准确性保证 5 个诊断路径的分层是作者 2026-03 至 2026-04 期间 20+ 次真实故障复盘的归纳。错诊案例全部是作者本人踩过的坑（时间漂移 / shared 污染 / hotfix 失配 / scope 默认值）。命令路径基于作者 ~/.openclaw/ 真实结构（2026-04-18）。

导航：← 常见问题 · 📖 目录 · → npm升级兼容