报错回顾 - 自动分析并修复工具报错

当用户说「报错回顾」时，整理当前 session 中工具调用的所有报错，分析根因并自动修复，含分类/去重/压缩/淘汰机制

报错回顾 Skill

用户说「报错回顾」时触发。自动整理当前 session 的工具报错历史，分析根因，修复文档。

核心原则

分类

类别	判断标准	修复位置
SKILL 问题	SKILL.md 写了错误/过时的命令、API、参数	修 SKILL.md
TOOLS.md 缺失	缺少个人环境特有的配置、路径、坑	记 TOOLS.md 正文区
模型判断失误	AI 自己的逻辑错误，文档没问题	记 TOOLS.md 报错记录区（带计数器）

工具使用不当归入模型判断失误。

分类判断：

• 如果下次换个人来执行也会报错 → 文档/配置问题（SKILL 问题 或 TOOLS.md 缺失）
• 如果下次换个人来执行不会出错 → 模型判断失误

三拍机制（去重 → 压缩 → 计数）

每次执行，对每个报错按「错误签名」处理：

① 去重（错误签名匹配）

每个错误有一个唯一「签名」— 人能看懂的摘要（如「clawhub publish 命令格式用错」）。

• 搜索 TOOLS.md 的 ## 报错记录 区，按签名匹配
• 签名已存在 → 不写新条目，仅计数器 +1
• 签名不存在 → 新建条目，计数器 = 1

例外：

• SKILL.md 修正是因为根因已被永久消除，不参与去重计数
• 如果旧签名对应的内容已被 SKILL.md 修复、不再适用，则删除该条目

② 压缩

每条报错记录固定格式，不超过 1 行：

text

- **[错误签名]** → 修复说明（N次）

示例：

text

- [clawhub publish 命令用错] → 改用 `clawhub publish`（2次）
- [npm 全局安装权限拒绝] → 加 `--prefix ~/.npm-global` 安装到用户目录（2次）

⚠️ 签名必须通用化：错误签名要提炼通用规律，不要绑定具体工具名。比如：

• ❌ [weixin-mp-cli npm 权限拒绝] → ✅ [npm 全局安装权限拒绝]
• ❌ [tdl session 误删] → ✅ [误删重要配置文件]
• ❌ [mcpporter mcporter 命令找不到] → ✅ [全局命令未加入 PATH]

这样下次遇到同类问题时，去重匹配才能命中。

去掉详细报错信息，只留「原因+修复+次数」。

③ 计数规则总结

• 计数 ≥ 10 的条目 → 标记 ⚠️ 高频

• 极端情况下条目过多，提示用户手动清理

• 所有报错（含模型判断失误）都记入 TOOLS.md 的 ## 报错记录

• 同签名错误重复出现 → 不新增，只累加计数

• SKILL.md 修正是永久修复，不记入计数

• 汇报时在每条报错后展示当前计数

执行流程

Step 1：获取当前 session 的历史

使用 sessions_history 工具：

• sessionKey: "current"
• includeTools: true
• limit: 适当数值（通常 80 够用，超长 session 分页拉取）

Step 2：提取所有报错

遍历历史消息，找到所有 toolResult 且 isError: true 的记录。

每条报错记录提取：

1. toolName: 哪个工具报错了
2. error: 报错内容（用于生成签名）
3. context: 前一条 assistant 消息的 toolCall arguments
4. timestamp: 报错时间

Step 3：分析根因并分类

对每个报错按核心原则分为 3 类。

Step 4：修复（按分类执行）

SKILL 问题

• 找到对应 skill 的实际路径：find ~/.openclaw/skills -name "SKILL.md" -path "*skill名*"
• 修改 SKILL.md 中错误/过时的内容
• ⚠️ 不要改 /opt/homebrew/lib/node_modules/openclaw/skills/ 下的

TOOLS.md 缺失

• 追加到 ~/.openclaw/workspace/TOOLS.md 正文区（不是报错记录区）
• 去重：先 grep 目标关键词，已有 → 跳过或合并；没有 → 新增

模型判断失误 → 写入 TOOLS.md 报错记录区

格式化的新增/更新流程：

1. 确定错误签名（简洁摘要）
2. 读 TOOLS.md 的 ## 报错记录 区
3. 按签名匹配：
   • 已存在 → 计数器 +1
   • 不存在 → 在末尾加新条目（计数器 = 1）
4. 如果条目过多（>100），提示用户手动清理
5. 用 edit 工具做文本替换（如遇复杂引号嵌套，分多次 edit 完成，每次匹配一小段）

Step 5：修改（直接执行）

无需用户确认，直接执行修改。

Step 6：汇报

修改完成后，给用户的结构化汇报：

text

## 报错回顾

本次共检测到 X 个报错：新增 Y 条，累加 Z 次计数。

1. **[错误签名]**
   - 分类：SKILL问题 / TOOLS.md缺失 / 模型判断失误
   - 修复：已修改 SKILL.md / 已记录到 TOOLS.md / 计数 +1（当前 N 次）
   - 去重：新建 / 累加计数（已有同类记录）
   ...

### 修改文件清单
- <path>：改了啥

向后兼容

执行前检查：本次 session 中是否已有报错回顾的执行记录。 若有（上次已修复过），则只统计新增报错，不重复报旧的。

注意事项

• ⚠️ 不要修改 OpenClaw 内部 skill（/opt/homebrew/lib/node_modules/openclaw/skills/），只改 ~/.openclaw/skills/ 下的
• SKILL.md 路径确认：find ~/.openclaw/skills -name "SKILL.md" -path "*skill名*"
• 字符串替换用 edit 工具，不要用 exec 跑脚本
• 最终回复不要发原始 JSON，整理成易读的中文汇报
• TOOLS.md 去重匹配用 grep -q 或 Shell 字符串匹配，不要目测判断