OpenClaw Skill 开发避坑指南：从入门到放弃（不是）

目录

今天花了整整一下午调试 OpenClaw 的 Skill，踩了无数坑，最后发现最大的坑是API 兼容性。这篇避坑指南记录了整个调试过程，希望能帮到其他开发者。

背景

我想给 OpenClaw 添加一个微信读书 Skill，让用户可以在飞书里问”我最近在读什么书”，然后自动返回书单。听起来很简单对吧？结果…

坑一：Skill 文件格式

错误示范

<tool>exec</tool>
<command>python3 script.py</command>

正确姿势

<tool name="exec">
<command>python3 script.py</command>
</tool>

教训：OpenClaw 使用类似 XML 的工具调用格式，tool 标签需要有 name 属性。

坑二：Session 缓存

每次修改 SKILL.md 后，Agent 还是使用旧的描述。必须清理 session 缓存：

rm -f ~/.openclaw/agents/main/sessions/*
openclaw gateway restart

教训：OpenClaw 的 session 会缓存 skill 的快照，修改后不清理缓存，Agent 永远看不到新内容。

坑三：Safe Bin 配置

OpenClaw 2026.3.8 版本要求为解释器配置 safeBinProfiles，否则 exec 会被忽略。

{
  "tools": {
    "exec": {
      "safeBins": ["python3"],
      "safeBinProfiles": {
        "python3": {
          "minPositional": 1,
          "maxPositional": 20,
          "allowedValueFlags": ["--list", "--search"],
          "deniedFlags": ["-rf", "--force"]
        }
      }
    }
  }
}

坑中坑：如果使用虚拟环境的 Python，还需要配置 safeBinTrustedDirs：

{
  "safeBinTrustedDirs": [
    "/home/wenjun/wereading_crontab/.venv/bin"
  ]
}

坑四：Agent 不执行命令

配置都正确了，Agent 也识别到了 skill，但它一直说要读取 skill 文件，就是不执行命令。

查看日志发现，Agent 的响应是：

让我先读取 weread 技能的 SKILL.md 文件，了解如何使用它。

然后我修改了 skill 描述，明确告诉它”直接执行命令，不要读取文件”，结果…

坑五：工具调用格式（终极坑）

这才是今天最大的坑！

问题现象

Agent 输出了工具调用，但没有任何反应：

<function_calls>
<invoke name="read">
<parameter name="path">~/.openclaw/skills/weread/SKILL.md</parameter>
</invoke>
</function_calls>

根本原因

• kimi-coding API 返回的是 XML 格式 的工具调用
• OpenClaw 期望的是 JSON 格式 的 tool_use

两者不兼容，导致工具调用被静默丢弃。

验证

查看 session 日志：

cat ~/.openclaw/agents/main/sessions/xxx.jsonl | grep "tool_use"
# 没有任何输出 - 说明工具调用没有被正确解析

坑六：模型切换连环坑

尝试切换到其他模型解决问题：

1. moonshot/kimi-k2-5 → HTTP 404，模型不存在
2. synthetic/hf:moonshotai/Kimi-K2-Thinking → 401 Invalid API Key
3. kimi-coding/k2p5 → XML 工具调用，不兼容
4. deepseek/deepseek-chat → ✅ 终于正常了！

教训：不是所有的 OpenAI 兼容 API 都能完美支持工具调用。DeepSeek 的 API 对工具调用的支持最好。

最终解决方案

1. 配置 DeepSeek API

{
  "models": {
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "sk-xxx",
        "api": "openai-completions",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "DeepSeek Chat",
            "contextWindow": 64000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat"
      }
    }
  }
}

2. 简化 Skill 设计

由于工具调用有各种坑，我最终选择把数据直接写在 skill 里，避免实时执行命令：

---
name: weread
description: "微信读书查询 - 回复用户书单查询结果"
---

## 当前书单

1. 《一人企业》- 保罗·贾维斯 (80条笔记)
2. 《AI Agent智能体与MCP开发实践》- 王晓华 (2条笔记)
...

3. Shell 函数备用方案

同时创建一个 shell 函数，可以直接在终端查询：

weread() {
    case "$1" in
        list)
            /home/wenjun/wereading_crontab/.venv/bin/python3 \
                /home/wenjun/wereading_crontab/weread_books.py --list
            ;;
        search)
            /home/wenjun/wereading_crontab/.venv/bin/python3 \
                /home/wenjun/wereading_crontab/weread_books.py --search "$2"
            ;;
    esac
}

调试技巧总结

1. 查看日志

openclaw logs 2>&1 | grep -E "(exec|skill|error)"

2. 查看 session

# 找到最新的 session
ls -lt ~/.openclaw/agents/main/sessions/*.jsonl

# 查看 Agent 实际调用了什么工具
cat xxx.jsonl | grep "tool_use"

3. 验证 API

curl https://api.xxx.com/v1/models \
  -H "Authorization: Bearer sk-xxx"

4. 测试脚本

直接测试脚本是否能正常运行：

/home/wenjun/wereading_crontab/.venv/bin/python3 \
    /home/wenjun/wereading_crontab/weread_books.py --list

结论

1. API 兼容性是最大的坑，不是所有 “OpenAI 兼容” API 都真的兼容
2. 工具调用格式需要仔细检查，XML vs JSON 差异很大
3. Session 缓存容易被忽视，修改配置后记得清理
4. Skill 设计要简单直接，复杂逻辑容易出问题

最后，DeepSeek 的 API 是目前测试下来最稳定的，推荐优先使用。

---

附：我的微信读书书单里有 64 本书，如果你也对《一人企业》、《AI Agent 开发实践》感兴趣，欢迎交流！

文章作者：阿文

文章链接： https://www.awen.me/post/3ea5e532.html

版权声明：本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 阿文的博客！