梦行志OpenClaw 运维日记：一次 Doctor 健康检查与 13 个问题修复实战
从会话卡死到系统恢复——oc-engineer 完整排障全流程记录
楔子：会话 c3b17066 在 11:22 因 sensenova 429 卡死 44 分钟，触发全面体检。从诊断到修复完成，oc-engineer 共处理了 13 个 Doctor 警告，最终将系统从"蓝色隐患"恢复到"健康"状态。
一、事故的起点：一个卡死的会话
今天早上的导火索是一个被卡住的会话。
用户访问 http://127.0.0.1:18789/chat/oc-engineer/c3b17066 时，发现页面一直停留在「处理中…」。日志显示，这个会话在 11:22:58 因 sensenova/deepseek-v4-flash 触发 429 速率限制（inference tpm exhausted）而 abort——用户发了一个 ？，模型连续重试 3 次全部 429，session 就卡死了。
但真正的问题不止这一个。
深入排查后发现两个更深层的症状：
| 症状 | 详情 |
|---|---|
| sensenova 429 | 今日 5 次 429，最后一次 11:22:41 |
| sapiens 间歇性 401 | 284 次请求中 54 次失败（19%），但 API key 本身有效，总是成对出现后自动恢复 |
关键洞察：sapiens 的 401 不是 key 失效——直接 curl 测试永远 200。它更像是 OpenClaw 连接池管理或 sapiens 服务端的间歇性认证挑战，~5-10 秒后自动恢复。
处理完卡死会话后，oc-engineer 决定做一次系统性健康检查，于是 openclaw doctor 被频繁调用，逐步揭示了更多潜在问题。
二、Doctor 诊断：发现 13 个预警
openclaw doctor 是 OpenClaw 内置的健康检查工具，它会扫描配置、插件、Skills、工具引用等多个维度，输出警告和建议。
今天的诊断结果按严重程度分成了几个梯队：
🟢 已知不改（设计决策）
| # | 问题 | 结论 |
|---|---|---|
| 1 | Node 版本差异（service 用 /usr/bin/node） | 不影响启动，不改 |
| 2 | Gateway bind loopback | 本机使用无需改动 |
| 3 | Chief-yuntian exec 权限 | 内部信任 agent，有 workspace 隔离 |
🟡 需要处理（本次修复）
| # | 问题 | 影响 |
|---|---|---|
| 6 | 未知 provider (nvidia-glm5, nvidia-kimi2-5) | 配置残留，可能引起运行时错误 |
| 7 | Skill Workshop 缺失工具 | chief-yuntian 和 oc-engineer 无法用 skill_workshop |
| 8 | kb-writer bootstrap 截断 | AGENTS.md + MEMORY.md 共 92K，超过默认 48K 限制 |
| 9 | Cron 任务认证过期 | 4 个 cron 任务使用 legacy sender-policy |
| 10 | Feishu 工具未知条目 | 8 个 agent 引用了已废弃的飞书工具名 |
| 11 | view_image 工具不可用 | 3 个 agent 的 allowlist 包含不支持的工具 |
| 12 | Skill 优先级冲突 | ~40 条 collision 日志，workspace 有重复 skill |
| 13 | Skill 缺少 description | qmd-index-vault/SKILL.md 缺少 frontmatter |
需关注（长期跟踪）
- 没有备份：
No successful backup is recorded - 258 个孤立 agent 目录：历史遗留，不影响运行但占用磁盘
- Memory Dreaming Promotion cron 曾 stuck：已自动恢复
三、修复全过程
修复 1：清理未知 provider 引用
根因：models.providers.nvidia 只声明了 minimaxai/minimax-m2.5，但别名引用了不存在的 model id z-ai/glm5 和 moonshotai/kimi-k2.5。
# 从 agents.defaults.models 中删除
- nvidia-glm5/z-ai/glm5 → {"alias": "nvapi-glm5"}
- nvidia-kimi2-5/moonshotai/kimi-k2.5 → {"alias": "nvapi-kimi2.5"}
# 从 agents.defaults.modelPolicy.allow 中删除
- nvidia-glm5/z-ai/glm5
- nvidia-kimi2-5/moonshotai/kimi-k2.5验证：grep -c "nvidia-glm5\|nvidia-kimi2-5" ~/.openclaw/openclaw.json 返回 0 ✅
修复 2：补全 Skill Workshop 工具权限
根因：doctor 要求 chief-yuntian 和 oc-engineer 的 tools profile 包含 skill_workshop。
# 添加到 agents.entries.chief-yuntian.tools.alsoAllow
- "skill_workshop"
# 添加到 agents.entries.oc-engineer.tools.alsoAllow
- "skill_workshop"修复 3：调大 kb-writer bootstrap 限制
根因：kb-writer 的 AGENTS.md (49K) + MEMORY.md (43K) = 92K raw，超过默认 48K 限制，导致部分指令被截断。
# 在 agents.entries.kb-writer 中添加
bootstrapMaxChars: 50000
bootstrapTotalMaxChars: 100000修复 4：重新授权 Cron 任务
根因：6 个 cron 任务使用 legacy sender-policy resolution，存储的 account authority 不可验证。
# 重新授权 4 个主要 cron 任务
openclaw automations edit 6716c207... --tools "exec,process,sessions_list,sessions_history,write,read"
openclaw automations edit 539deef8... --tools "exec,process,sessions_list,sessions_history,write,read"
openclaw automations edit 41893b79... --tools "exec,process"
openclaw automations edit e776a515... --tools "exec,process"修复 5：清理飞书工具残留引用
根因：配置中引用了不存在的 feishu 工具名（旧版插件的工具名，当前插件已不提供）。
从以下 8 个 agent 的 tools.allow/alsoAllow 中移除了 6 个无效工具：
| 移除的工具 | 说明 |
|---|---|
feishu_calendar_calendar | 旧版日历工具 |
feishu_oauth | 旧版 OAuth 工具 |
feishu_sheet | 旧版表格工具 |
feishu_task_task | 旧版任务工具 |
feishu_task_agent | 旧版任务代理工具 |
feishu_task_attachment | 旧版任务附件工具 |
涉及 agent：main, chief-yuntian, oc-engineer, editor-yuntianyue, scout-yuntianhuo, marketing-content-creator, pub-yuntianxing, debt-rebirth-oklife
修复 6：移除 view_image 工具引用
根因：当前 runtime/provider/model 不支持 view_image 工具，但某些 agent 的 allowlist 中仍包含。
从以下 agent 的 tools.alsoAllow 中移除 view_image：
- agents-orchestrator
- design-yuntianguang
- search-scout-yuntianyan
修复 7：清理 Skill 优先级冲突
根因：同一 skill 在多个目录存在（workspace/skills vs managed/skills vs bundled/skills），导致 precedence collision。
# 删除 7 个与 managed 版本相同的 workspace skill 副本
rm -rf ~/.openclaw/workspace/skills/{agent-browser-clawdbot,bb-browser,humanizer,
openclaw-feishu-channel-rules,openclaw-feishu-fetch-doc,openclaw-feishu-update-doc,
skill-creator}
# 保留 browser-use（.agents/skills 版本与 managed 不同）
# 保留 1password, apple-notes, coding-agent, gog 的 managed 版本（与 bundled 不同）修复 8：修复 qmd-index-vault 缺少 frontmatter
根因：SKILL.md 缺少 YAML frontmatter，导致 gateway 跳过加载。
---
name: qmd-index-vault
description: 对 Obsidian vault 库进行 qmd 索引的创建、刷新、验证和清理。这是 oc-engineer 的本职工作，直接执行，不委派给其他 agent。
---四、问题跟踪文档的诞生
这次排障过程中，oc-engineer 创建了一份现存非阻断问题清单（2026-09-02-现存非阻断问题清单.md），将所有已知问题按状态分类归档：
| 分类 | 数量 | 用途 |
|---|---|---|
| 🟢 已解决 | 8 个 | 不再跟踪，变更记录 |
| 🟡 观察中 | 5 个 | 暂不处理，等触发条件 |
| 📌 待处理 | 2 个 | 低优先级，用到再处理 |
这份文档的核心价值在于：避免重复讨论已归档问题，变更前后查阅即可。
五、最终状态验证
所有修复完成后，执行 openclaw doctor 和 openclaw config validate 验证：
| 项目 | 值 |
|---|---|
| OpenClaw 版本 | 2026.8.2 (0965053) |
| Gateway PID | 136232 (active, running) |
| 插件数量 | 62/82 enabled |
| 飞书通道 | 5/5 connected, works ✅ |
| 配置 validate | 通过 |
| Doctor 警告 | 仅剩 #4 GitHub token、#5 Browser Relay（低优先级） |
| Skill 冲突 | 已清理 7 个重复 skill |
| Feishu 工具引用 | 已清理 8 个 agent 的无效引用 |
| bootstrap 截断 | 已调大限制 |
健康等级：从"蓝色隐患"恢复到"健康"。
六、经验教训
1. 配置清理优先级
高优先级：未知 provider/model 引用 → 可能引起运行时错误
高优先级：Bootstrap 限制问题 → 影响 agent 上下文完整性
中优先级：Cron 任务认证 → 累积过期会影响定时任务
低优先级：工具引用残留 → 不影响运行但增加噪声2. Doctor 是运维最佳入口
# 健康检查与配置验证
openclaw doctor
openclaw config validate
# Cron 任务管理
openclaw automations show <id>
openclaw automations edit <id> --tools "..."3. 修改配置的三步法
# ① 修改前先备份
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.pre-xxx
# ② 修改后验证
openclaw config validate
# ③ 重大变更记录到问题清单4. Skill 冲突的根因与预防
同一 skill 在多个目录存在是冲突的根因。预防方法：
~/.openclaw/skills/（managed）是权威来源~/.openclaw/workspace/skills/是用户自定义覆盖层，仅在需要修改时使用~/.nvm/.../skills/（bundled）是插件自带的，一般不动
5. 会话卡死的应急处理
# 查看卡住的会话
openclaw sessions list --agent oc-engineer
# 强制 reset（需要 --yes）
openclaw sessions delete <session-key> --yes
# 重启 Gateway（最后手段）
systemctl --user restart openclaw-gateway七、附录：今天的 timeline
| 时间 | 事件 |
|---|---|
| 09:48 | Gateway 重启恢复 c3b17066 会话 |
| 10:32 | 用户问"这个会话出了什么问题" |
| 11:07 | 诊断完成：sensenova 429 + sapiens 401 |
| 11:22 | c3b17066 再次 abort（429） |
| 12:00 | 开始第一轮 Doctor 诊断 |
| 13:00 | 修复问题 6-9（provider/Workshop/bootstrap/cron） |
| 13:20 | 修复问题 10-13（feishu/view_image/skill 冲突） |
| 13:27 | 追加 GitHub token 和 Browser Relay 待处理记录 |
| 13:30 | 系统恢复健康，写博客归档 |
参考来源
FAQ
Q: openclaw doctor 具体检查哪些内容？
A: openclaw doctor 会扫描配置、插件、Skills、工具引用等多个维度，输出警告和建议。建议定期运行以维护系统健康。
Q: Skill 优先级冲突怎么解决？ A: 冲突通常由同一 skill 在多个目录存在导致（workspace/skills vs managed/skills vs bundled/skills）。解决方法是对比 md5 哈希，删除重复版本，保留权威来源（managed/skills）。
Q: kb-writer bootstrap 截断是什么问题？
A: kb-writer 的 AGENTS.md + MEMORY.md 总大小超过默认 48K 限制时，部分指令会被截断。解决方法是在 agent 配置中调大 bootstrapMaxChars 和 bootstrapTotalMaxChars。
Q: 如何处理卡死的会话？
A: 使用 openclaw sessions list --agent <name> 查看状态，然后 openclaw sessions delete <session-key> --yes 强制清除。最后可重启 Gateway。
关联阅读
- [[OpenClaw 运维日记：一次 Doctor 健康检查与 13 个问题修复实战]]
- [[2026-05-15 2026-5-12升级后doctor超时排查与agent-ops配置修复]]
- [[2026-06-04 1834全面自检与残留问题诊断]]
- [[kb-writer模式D-blog-pipeline升级踩坑记录]]