技能开发实战 (Skills Development)

本文将深入讲解如何开发 OpenClaw 自定义技能，包括 JSON Schema 定义、TypeScript 实现、以及 Streaming Tool 开发。

1. 技能结构 (Skill Structure)

一个标准的 OpenClaw Skill 是一个文件夹，必须包含以下文件：

my-skill/
├── package.json       # 元数据和依赖
├── SKILL.md           # LLM 使用说明书 (System Prompt)
├── TOOLS.md           # Tool Schema 定义 (JSON Schema 简写)
└── index.js           # 业务逻辑实现 (CommonJS 或 ESM)

1.1 SKILL.md：告诉 LLM 怎么用

这是最重要的文件。LLM 并不知道你的代码怎么写，它只看文档。

# My Weather Skill

当用户询问天气时使用此技能。

支持以下城市：Beijing, Shanghai, New York.
如果用户没有指定城市，默认使用 Beijing。

## Tools
- `get_weather(city)`: 获取指定城市的天气。

1.2 TOOLS.md：告诉 Gateway 怎么调

这是一个简化的 JSON Schema 定义。Gateway 会用它来校验参数。

- get_weather: 获取天气信息。
  - city: (string) 城市名称，例如 "Beijing"。

或者使用完整 JSON Schema (推荐复杂参数使用)：

{
  "name": "get_weather",
  "description": "获取天气信息",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string", "description": "城市名称" }
    },
    "required": ["city"]
  }
}

1.3 index.js：业务逻辑

module.exports = {
  // 定义 Tool 的实现函数
  async get_weather({ city }) {
    if (!city) throw new Error("City is required");
    
    // 调用外部 API (这里模拟一下)
    const data = await fetch(`https://api.weather.com/${city}`);
    const json = await data.json();
    
    return `当前 ${city} 的天气是：${json.temp}°C, ${json.condition}`;
  }
};

---

2. 高级模式 (Advanced Patterns)

2.1 流式工具 (Streaming Tools)

有些工具运行很慢（比如 ping 或者 tail -f）。OpenClaw 支持 Streaming Tool，可以把输出实时推送到前端。

module.exports = {
  async ping({ host }, { stream }) {
    const { spawn } = require('child_process');
    const proc = spawn('ping', ['-c', '5', host]);

    proc.stdout.on('data', (data) => {
      // 实时推送数据块
      stream.write(data.toString());
    });

    return new Promise((resolve) => {
      proc.on('close', () => resolve("Ping finished"));
    });
  }
};

2.2 交互式 Canvas (Interactive UI)

OpenClaw 支持 canvas 工具，可以在前端渲染 HTML/JS 界面。

module.exports = {
  async show_chart({ data }) {
    // 返回一段 HTML，前端会在 iframe 里渲染
    return {
      type: "canvas",
      html: `
        <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
        <canvas id="myChart"></canvas>
        <script>
          new Chart(document.getElementById('myChart'), {
            type: 'bar',
            data: ${JSON.stringify(data)}
          });
        </script>
      `
    };
  }
};

2.3 浏览器自动化 (Browser Automation)

OpenClaw 内置了 CDP (Chrome DevTools Protocol) 支持。你可以直接控制浏览器。

module.exports = {
  async screenshot_webpage({ url }, { browser }) {
    // browser 对象是 Puppeteer 的 Page 实例
    await browser.goto(url);
    const buffer = await browser.screenshot();
    return { type: "image", buffer };
  }
};

---

👉 下一步：模型工程与 RAG