5.7 Skill 调试技巧

概述

一、调试基本流程

Skill 不生效？
    ↓
1. 检查文件是否正确保存
    ↓
2. 检查触发条件是否写对
    ↓
3. 检查 Skill 是否被加载
    ↓
4. 测试触发
    ↓
5. 查看日志定位问题

二、每一步排查方法

第一步：检查文件是否正确保存

# 查看文件是否存在
ls -la ~/.openclaw/workspace/skills/你的Skill名/SKILL.md
# 查看文件内容
cat ~/.openclaw/workspace/skills/你的Skill名/SKILL.md

常见错误：

• 文件名拼写错误（应该是 SKILL.md，不是 skill.md）
• 保存到了错误的目录
• 文件内容为空

第二步：检查触发条件

常见错误：

❌ 触发条件太模糊

当用户说任何话时都可能触发

✅ 触发条件要具体

当用户提到以下关键词时触发：
"画图"
"生成图片"
"生成一张"

第三步：检查 Skill 是否被加载

openclaw skills list

应该看到你的 Skill 列表中有它

如果看不到，尝试：

# 重新加载 Skills
openclaw skills reload
# 重启 Gateway
openclaw gateway restart

第四步：测试触发

发送带有触发词的消息：

用户：测试技能

检查：

• AI 是否响应
• 是否有错误提示
• 返回内容是否符合预期

第五步：查看日志

# 查看最近 100 行日志
tail -100 ~/.openclaw/logs/gateway.log
# 搜索 Skill 相关日志
tail -100 ~/.openclaw/logs/gateway.log | grep -i skill
# 搜索错误日志
tail -100 ~/.openclaw/logs/error.log

三、常见错误及解决方法

错误 1：Skill 不触发

错误 2：API 调用失败

错误 3：返回格式不对

检查点：

• SKILL.md 中的返回格式说明是否准确
• API 实际返回的数据结构是否符合说明
• AI 是否正确解析了返回数据

解决方法： 用实际 API 调用结果对照 SKILL.md 中的说明。

四、调试技巧

技巧 1：添加日志

在 Skill 中添加调试信息：

```markdown
# 测试 Skill

## 触发条件
当用户说"测试Skill"时，触发后返回：
"Skill 已触发，参数：xxx"
```

技巧 2：逐步验证

1. 先测试触发 → 是否响应

2. 再测试参数提取 → 是否正确提取

3. 最后测试 API 调用 → 是否成功

技巧 3：简化测试

先写一个最简单的 Skill，确认能触发后，再逐步添加复杂逻辑。

五、调试清单

□ 文件路径正确：~/.openclaw/workspace/skills/xxx/SKILL.md
□ 文件名正确：SKILL.md（大写）
□ 文件内容不为空
□ 触发条件包含测试时使用的关键词
□ openclaw skills list 能看到该 Skill
□ 日志中没有报错

六、无法解决怎么办

1. 收集信息： - Skill 文件完整内容 - openclaw skills list 输出 - 相关日志

2. 在群里提问，提供以上信息

七、下一步学什么

• 5.8 如何发布和分享 Skill → 分享你的 Skill
• 第六章：进阶功能 → 了解更多高级功能

调试是写 Skill 的必经之路，多尝试就会越来越熟练！

常见问题