05-排障 · 常见问题

本章收录作者 20+ 天生产实战中反复踩过的坑。每条都有真实成因 + 具体修复命令。 不是泛泛”看看日志”式建议，是可直接照抄的诊断路径。 适用版本：公开稳定包 OpenClaw 2026.5.2；作者端已验证 2026.5.7 · 最后审核：2026-05-09

---

排障黄金流程

不管症状是什么，先走这四步。90% 的问题在这里就能定位：

① openclaw doctor              ← 让官方自检工具说话
② curl http://127.0.0.1:18789/health
③ tail -200 ~/.openclaw/logs/gateway.err.log
④ openclaw gateway status

四步都绿了还有问题，再查下面的具体症状。

---

1. 飞书机器人不回复

症状：给 bot 发消息，没任何回应（不是”回复慢”，是”完全没反应”）。

排查顺序：

1.1 gateway 还活着吗

curl -s http://127.0.0.1:18789/health
# 期望：{"ok":true,...}
# 如果 curl 直接失败 → gateway 挂了
openclaw gateway start   # 或 restart

如果 openclaw 命令本身能跑，但服务起不来，继续看本章第 13 节的 gateway 服务路径修复。

1.2 公网回调还通吗

飞书事件回调需要公网可达。如果你用内网穿透（cpolar / frp / ngrok），穿透隧道可能断了。

curl -s https://<你的公网地址>/health
# 用同样的 health 路径试试
# 如果这里 404 或超时，而 127.0.0.1 正常 → 穿透问题，不是 OpenClaw 问题

1.3 飞书配置 / 权限

在飞书开放平台检查：

• 机器人已开「接收消息」权限（im:message、im:message:send_as_bot）
• 「事件订阅」里 URL 校验通过（绿色对勾）
• 已订阅 im.message.receive_v1 事件
• 应用已发布到企业内可用

1.4 日志里有什么

tail -200 ~/.openclaw/logs/gateway.err.log | grep -iE 'feishu|lark|callback|signature'

常见错误关键字：

• signature invalid → encryptKey 或 verificationToken 不对，检查 ~/.openclaw/credentials/lark.secrets.json
• app_id mismatch → openclaw.json 的 appId 和飞书后台不一致
• access_token expired → appSecret 改过但没重启 gateway

1.5 重启让新 secrets 生效

改过 credentials/ 下任何文件：

openclaw gateway restart
# ⚠️ 紧接着必须等启动完成（见第 2 节），不能立刻发消息

---

2. ⚠️ gateway 重启后立即发消息失败

症状：刚 openclaw gateway restart，立刻触发一条飞书操作，返回错误或消息石沉大海。

根因：gateway 重启会经历 warming（HTTP 服务已起，但内部 callback 注册还没跑完）阶段。在这期间 HTTP /health 可能已经 ok，但飞书回调注册还没完成，所以发消息会失败。

正确做法：

openclaw gateway restart
# 轮询健康检查脚本，直到输出以 "OK:" 开头
until bash ~/.openclaw/scripts/check-feishu-gateway-health.sh --summary 2>/dev/null | grep -q "^OK:"; do
  sleep 2
done
echo "gateway ready"
# 现在才能发消息

不要用的做法：

• ❌ sleep 10 后就发消息（10 秒可能不够，也可能浪费）
• ❌ 只看 /health（http=1 的时候 callback 可能还没好）

作者实测：从 restart 到完全 ready 一般 8-20 秒，高负载时能到 40 秒。必须等 OK: 再走下一步。

---

3. 飞书回调 /reset /new 不响应（多 bot 场景）

症状：子 agent（planner / yying 等）的飞书私聊对 /reset 或 /new 没反应，但 main 正常。

根因：不同的飞书 bot app 下，同一个真人有不同的 open_id。子 agent 的 allowFrom 白名单是基于 open_id 的，如果你是从 main 的 bot 切到 planner 的 bot，open_id 变了，白名单不认识你。

排查：

# 1. 确认当前真人在该 bot 下的 open_id
# 在该 bot 的飞书私聊里发「/openid」，bot 会回显
# （前提：main 或该 agent 的 SOUL 里有响应 /openid 的规则）

# 2. 检查该 agent 的 allowFrom 配置
grep -A 5 '"allowFrom"' ~/.openclaw/openclaw.json | head -30

# 3. 如果 open_id 不在列表里，加进去
# （编辑 openclaw.json 对应 agent 的 allowFrom 数组）

# 4. 重启
openclaw gateway restart

---

4. ⚠️ hotfix 锚点失效（npm 升级后 CLI 行为异常）

症状：npm install -g openclaw 升级后，某些功能（发卡、记忆写入等）失效，openclaw doctor 不报错但运行时偏差明显。

根因：作者维护一份 ~/.openclaw/scripts/apply-openclaw-cli-hotfixes.mjs，对 OpenClaw CLI 的 dist 做运行时补丁。npm 升级后有两种锚点失效：

1. dist 哈希轮换 —— OpenClaw 打包会给文件加哈希后缀（chunk-abc123.js → chunk-def456.js），补丁硬编码的文件名找不到了
2. upstream 插代码 —— 官方在锚点字符串附近新增代码，导致锚点 match 变模糊

修复：

# 升级后必跑一次
node ~/.openclaw/scripts/apply-openclaw-cli-hotfixes.mjs
# 它会：
# - 动态识别当前 dist 的哈希
# - 对锚点做更长的上下文 match
# - 失败会明确告诉你哪一个 patch 挂了（不是静默 skip）

详见 06-升级/00-npm升级兼容。

---

5. 记忆检索召回不到

症状：明明存过的事，memory_recall 返回空 / 无关结果。

四步诊断（从最常见到最罕见）：

5.1 LanceDB fragments 失控

检查 fragments 数（真实路径是 memories.lance/data/，数据文件在 data/ 目录下）：

ls ~/.openclaw/memory/lancedb-pro/memories.lance/data/ | wc -l
# 正常 < 500，⚠️ > 500，🚨 > 1000（作者 daily-digest.py 阈值）

异常 → 历史维护脚本没跑。修复：

# 跑一次手动压缩
python3 ~/.openclaw/scripts/run-weekly-maintenance.py

详见 02-配置/01-记忆系统 第 5 节。

5.2 scope 错了

memory_recall 默认按调用方 agent 的可访问 scope 过滤。在 planner 里查 minsu 存的东西，默认查不到 —— 必须显式传 scope 参数扩大搜索范围。

5.3 embedding 服务挂了

如果用 SiliconFlow 做 embedding：

curl -sH "Authorization: Bearer $SILICONFLOW_KEY" \
  https://api.siliconflow.cn/v1/models | head
# 失败 → 换 key 或 provider

5.4 表本身存在吗

ls ~/.openclaw/memory/lancedb-pro/
# 该看到 memories.lance/ 目录（作者生产环境是单表部署）

空的 → memory-lancedb-pro plugin 没初始化，看 02-配置/01-记忆系统 初始化步骤。

---

6. Context 溢出 / 模型开始”胡说”

症状：会话越长，回复越跑偏，前面说过的事也不认了。

三种策略：

策略 A（立即止损）：/new 开新会话
策略 B（保留关键结论）：让 agent 先把核心结论写入 L2（memory_store）再 /new
策略 C（长期）：调低 lossless-claw 的 contextThreshold（默认 0.65 → 0.55），更早触发压缩

lossless-claw 的 contextThreshold 默认 0.65，是插件内置默认值——不显式覆盖时，你 grep 自己的 openclaw.json 是搜不到的。要改就在 plugins.entries.lossless-claw.config.contextThreshold 下手动加一行（不是 agents.defaults.compaction 或独立 skill 节）：

"plugins": {
  "entries": {
    "lossless-claw": {
      "enabled": true,
      "config": { "contextThreshold": 0.55 }
    }
  }
}

改完 openclaw gateway restart 生效。

---

7. 子 agent footer 只显示”耗时”，没有 model/cache/context

症状：飞书回复的卡片 footer 栏里，main 的完整，子 agent 的就一行”耗时 XX 秒”。

根因：早期版本的 streaming-card-controller.js 在多 agent 场景下，footer metrics 用了固定 session 路径，而不是按当前 sessionKey 的 agent id 去读对应的 sessions.json。

修复：

• 使用 openclaw-lark 插件：执行并确认通过：

  bash ~/.openclaw/scripts/apply-openclaw-lark-patches.sh
  bash ~/.openclaw/scripts/verify-openclaw-lark-patches.sh

  当前公开稳定包基线为 openclaw-lark 2026.4.8，作者端已验证 2026.5.7；插件升级后必须重新跑这两步。
• 使用官方 Feishu 插件：升级到最新版，此 bug 新版已修

---

8. 配置改了不生效

症状：手改了 openclaw.json，行为没变。

三种原因：

1. 没重启 gateway —— 90% 是这个。openclaw gateway restart 后等 OK:
2. 改错文件 —— 有些配置在 agents/<id>/openclaw.json，有些在主 openclaw.json，注意路径
3. JSON 语法错 —— 用 python3 -m json.tool < ~/.openclaw/openclaw.json > /dev/null 检验，有错会报行号

❌ 不要为了”清缓存”去 rm -rf ~/.openclaw/cache/* 或 rm -rf ~/.openclaw/data/，那里面有记忆库。

---

9. launchd 任务没跑

症状：配了 daily-digest / weekly-maintenance 的 plist，但预期时间没动静。

9.1 确认 plist 已加载

# gateway/watchdog 是 ai.openclaw.*，digest/maintenance 是 com.openclaw.*
launchctl list | grep -iE "openclaw|claw"
# 应该看到你配的 label，如 com.openclaw.daily-digest / ai.openclaw.watchdog

没加载 → 加载：

launchctl load ~/Library/LaunchAgents/com.openclaw.daily-digest.plist

9.2 确认脚本自己能跑

直接手跑一次看结果：

# 找到脚本路径
plutil -p ~/Library/LaunchAgents/com.openclaw.daily-digest.plist | grep -A 2 ProgramArguments
# 直接跑
bash <脚本路径>  # 或 python3 <脚本路径>

9.3 查 launchd 日志

tail -100 ~/.openclaw/logs/<plist 里指定的 StandardOutPath>
tail -100 ~/.openclaw/logs/<plist 里指定的 StandardErrorPath>

---

10. ⚠️ shell 脚本反复踩坑的两个点

作者在维护脚本里翻车过两次，都是”看着对其实不对”：

10.1 redirect-to-same-file 会 truncate

# ❌ 错：会先把 file.txt truncate 成 0 字节，grep 读到空
grep 'pattern' file.txt > file.txt

# ✅ 对：写到中间文件再 mv
grep 'pattern' file.txt > file.tmp && mv file.tmp file.txt

10.2 BSD awk（macOS 原生）的 UTF-8 char class 失效

# ❌ macOS 默认 awk（BSD）处理中文会乱
awk '[\u4e00-\u9fff]' file

# ✅ 用 GNU awk（gawk）或 python
gawk '...' file
# 或
python3 -c "import re, sys; ..." < file   # ← 但对 agent 是"混淆写法"，不能用
# 所以在 agent 环境里：先 echo 代码到 .py 文件，再 python3 /tmp/xxx.py

---

11. ⚠️ 维护脚本 /tmp 易失 + 静默 skip

踩坑背景：作者有段时间 LanceDB fragments 涨到 758，维护脚本看起来在跑，但没有效果。两个 bug：

1. 脚本用 /tmp/ 存状态文件，macOS 重启清空，脚本误判”从未跑过”（或反之）
2. 编排器里某个 step 缺失，代码 return True 静默跳过，没有日志没有报错

修复原则：

• 状态文件持久化：放 ~/.openclaw/data/<scriptname>/state.json，不放 /tmp/
• step 缺失必须 return False：编排器发现 step 找不到实现，必须报错中止，不能静默跳过
• 每次跑要写 heartbeat 日志：~/.openclaw/logs/<scriptname>.log 追加一行 [timestamp] run_id=X status=OK fragments=Y，长期不动 = 没跑

---

12. ⚠️ 安全红线（反面案例）

不要做的事：

• ❌ 把 ~/.openclaw/credentials/ 的文件放 git / 网盘 / 聊天工具截图
• ❌ 用”一键同步”脚本把整个 ~/.openclaw/ 打包给别人（会泄露真实对话记忆、凭据、用户信息）
• ❌ 维护脚本 rm -rf 任何 ~/.openclaw/ 下的目录之前不先备份
• ❌ 在公共论坛贴未脱敏的 openclaw.json（里面有 open_id、app_id、路径等）

作者的基线：

/credentials/

chmod 600 ~/.openclaw/credentials/*.json
chmod 700 ~/.openclaw/credentials
# .gitignore 里必须有：
# /logs/
# /memory/
# /workspace/memory/
# /data/

---

13. Control UI 打不开 / gateway 指向旧 NVM 路径

症状：

• 浏览器打开 http://127.0.0.1:18789/ 失败
• 或显示 Control UI assets not found
• 或日志里出现旧路径，例如 ~/.nvm/versions/node/.../lib/node_modules/openclaw/dist/index.js
• 终端里 openclaw --version 正常，但 launchd / systemd 仍起不来

根因：CLI 和 gateway 服务入口不是同一套。你可能重装了 Node、切过 nvm 版本、改过 npm prefix，shell 里的 openclaw 已经更新，但服务文件还写着旧目录。

优先修复：

bash ~/.openclaw/scripts/repair-gateway-service.sh --repair --restart
bash ~/.openclaw/scripts/runtime-status-report.sh

当前模板的修复脚本会检查可用的 openclaw、node、dist/index.js，必要时按 RUNTIME_BASELINE.json 补装稳定基线，再修 launchd / systemd。

不要只做：

npm install -g openclaw@2026.5.2

这只能保证 npm 包存在，不保证系统服务文件已经同步到新路径。

详见 06-升级/03-CLI与Gateway版本统一。

---

诊断命令速查

# 基础四连
openclaw doctor
curl -s http://127.0.0.1:18789/health
tail -200 ~/.openclaw/logs/gateway.err.log
openclaw gateway status

# 检查 gateway 完全就绪
bash ~/.openclaw/scripts/check-feishu-gateway-health.sh --summary

# 检查 gateway 服务路径和 runtime 基线
bash ~/.openclaw/scripts/runtime-status-report.sh

# 修复 launchd / systemd 指向旧 OpenClaw 路径
bash ~/.openclaw/scripts/repair-gateway-service.sh --repair --restart

# 查看 agent 列表
openclaw gateway status   # 包含 agent 列表

# 查看 launchd 任务（两套前缀：gateway/watchdog 走 ai.*，digest/maintenance 走 com.*）
launchctl list | grep -iE "openclaw|claw"

# 查看端口占用
lsof -iTCP:18789 -sTCP:LISTEN

# 检查凭据权限
ls -l ~/.openclaw/credentials/

# 记忆库健康：fragments（data/）和 versions（_versions/）分别看
ls ~/.openclaw/memory/lancedb-pro/memories.lance/data/ | wc -l      # fragments
ls ~/.openclaw/memory/lancedb-pro/memories.lance/_versions/ | wc -l # versions

---

本章未覆盖的场景

• Discord / Telegram 渠道的排障：不在作者日常使用范围，建议直接查官方 issues
• Windows / WSL 下的路径问题：作者环境是 macOS，路径 / 权限表现可能不同
• 大规模多用户场景：作者是个人 + 小团队部署，10+ 并发用户下的表现未验证

---

本章准确性保证 所有命令、日志路径、plist label 都基于 ~/.openclaw/logs/、~/Library/LaunchAgents/、~/.openclaw/scripts/ 的真实文件验证。⚠️ 标记的 5 条是作者真实踩过的重大坑，每条都有对应事故日期与修复 PR（见 repo commit 历史）。

---

导航：← 备份与恢复 · 📖 目录 · → 诊断流程