OpenClaw Skill Development Pitfall Guide: From Beginner to Giving Up (Not Really)

目录

I spent a whole afternoon today debugging an OpenClaw Skill, stepped in countless pits, and in the end discovered the biggest pit was API compatibility. This pitfall guide records the entire debugging process, and I hope it helps other developers.

Background

I wanted to add a WeRead (WeChat Reading) Skill to OpenClaw, so users could ask in Feishu “what have I been reading lately” and get their booklist back automatically. Sounds simple, right? Turned out…

Pitfall One: Skill File Format

Wrong way

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

Right way

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

Lesson: OpenClaw uses an XML-like tool-calling format, and the tool tag needs a name attribute.

Pitfall Two: Session Cache

Every time I edited SKILL.md, the Agent still used the old description. You must clear the session cache:

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

Lesson: OpenClaw’s session caches a snapshot of the skill; if you don’t clear the cache after editing, the Agent will never see the new content.

Pitfall Three: Safe Bin Configuration

OpenClaw 2026.3.8 requires configuring safeBinProfiles for the interpreter, otherwise exec gets ignored.

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

The pit inside the pit: If you use a virtualenv Python, you also need to configure safeBinTrustedDirs:

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

Pitfall Four: Agent Doesn’t Execute Commands

Everything was configured correctly, the Agent recognized the skill, but it kept saying it wanted to read the skill file and just wouldn’t run the command.

Checking the logs, the Agent’s response was:

Let me first read the SKILL.md file of the weread skill to understand how to use it.

Then I edited the skill description to explicitly tell it “execute the command directly, don’t read the file,” and the result was…

Pitfall Five: Tool-Calling Format (the ultimate pit)

This was the biggest pit of the day!

Symptom

The Agent emitted a tool call, but nothing happened:

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

Root cause

• The kimi-coding API returns tool calls in XML format
• OpenClaw expects the JSON format tool_use

The two are incompatible, so the tool calls were silently dropped.

Verification

Check the session log:

cat ~/.openclaw/agents/main/sessions/xxx.jsonl | grep "tool_use"
# no output - meaning the tool call was never parsed correctly

Pitfall Six: The Model-Switching Chain of Pits

Trying to switch to another model to fix the problem:

1. moonshot/kimi-k2-5 → HTTP 404, model doesn’t exist
2. synthetic/hf:moonshotai/Kimi-K2-Thinking → 401 Invalid API Key
3. kimi-coding/k2p5 → XML tool calls, incompatible
4. deepseek/deepseek-chat → ✅ finally worked!

Lesson: Not every OpenAI-compatible API supports tool calls perfectly. DeepSeek’s API has the best support for tool calls.

The Final Solution

1. Configure the 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. Simplify the Skill Design

Because tool calls had so many pitfalls, I ultimately chose to write the data directly into the skill, avoiding real-time command execution:

---
name: weread
description: "WeRead lookup - replies with the user's booklist query results"
---

## Current booklist

1. *Company of One* - Paul Jarvis (80 notes)
2. *AI Agent and MCP Development in Practice* - Wang Xiaohua (2 notes)
...

3. Shell Function as a Fallback

I also created a shell function so I can query directly in the terminal:

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
}

Debugging Tips Summary

1. View logs

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

2. Inspect the session

# Find the latest session
ls -lt ~/.openclaw/agents/main/sessions/*.jsonl

# See what tool the Agent actually called
cat xxx.jsonl | grep "tool_use"

3. Verify the API

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

4. Test the script

Test directly whether the script runs:

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

Conclusion

1. API compatibility is the biggest pit — not every “OpenAI-compatible” API is actually compatible
2. Tool-calling format needs to be checked carefully — the XML vs. JSON difference is huge
3. Session cache is easy to overlook — remember to clear it after changing the config
4. Skill design should be simple and direct — complex logic easily goes wrong

In the end, DeepSeek’s API is the most stable of the ones I’ve tested, so I’d recommend using it first.

---

P.S. My WeRead booklist has 64 books. If you’re also interested in Company of One or AI Agent Development in Practice, feel free to reach out!

中英对照

文章作者：阿文

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

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