从 0 到 1 开发第一个 OpenClaw 技能

想要开发一个自定义技能？本文带你一步步开发第一个技能，了解 OpenClaw 技能开发的基本流程。

什么是 OpenClaw 技能

技能是 OpenClaw 扩展功能的基本单元。一个技能可以提供一个或多个工具给 AI 使用。

我们今天来开发一个简单的 “字数统计” 技能，它可以统计文本或文件中的字数。

步骤 1: 创建技能目录结构

首先在 workspace 下创建技能目录：

mkdir -p ~/.openclaw/workspace/skills/word-counter
cd ~/.openclaw/workspace/skills/word-counter

创建两个必需文件：

touch SKILL.md
touch index.js

步骤 2: 编写 SKILL.md

SKILL.md 是技能的说明文件，描述技能的用途、工具、参数。这是给 AI 看的，要写清楚。

# Word Counter 字数统计技能

统计文本或文件中的字数、词数、行数。

## 可用工具

### count_words(text: string)
统计文本字数。

**参数：**
- text: string - 要统计的文本

**返回：** 统计结果 JSON

### count_file(file_path: string)
统计文件字数。

**参数：**
- file_path: string - 文件路径（相对于 workspace）

**返回：** 统计结果 JSON

步骤 3: 编写技能代码

编辑 index.js：

/**
 * Word Counter Skill
 * 统计字数的技能示例
 */

// 统计文本字数
function countWords(text) {
  // 按空白符分词
  const words = text.trim().split(/\s+/).filter(w => w.length > 0);
  // 行数
  const lines = text.split('\n').length;
  // 字符数（包含空格）
  const chars = text.length;
  
  return {
    chars: chars,
    words: words.length,
    lines: lines
  };
}

// 处理工具调用
async function handleToolCall(toolName, params, context) {
  if (toolName === 'count_words') {
    const result = countWords(params.text);
    return JSON.stringify(result, null, 2);
  }
  
  if (toolName === 'count_file') {
    const fs = require('fs');
    const path = require('path');
    const filePath = path.join(context.workspaceRoot, params.file_path);
    
    if (!fs.existsSync(filePath)) {
      return JSON.stringify({ error: '文件不存在: ' + filePath });
    }
    
    const text = fs.readFileSync(filePath, 'utf-8');
    const result = countWords(text);
    return JSON.stringify(result, null, 2);
  }
  
  return JSON.stringify({ error: '未知工具: ' + toolName });
}

// 技能导出
module.exports = {
  // 技能信息
  name: 'word-counter',
  description: '字数统计工具，统计文本和文件的字数、行数、字符数',
  
  // 工具调用入口
  handleToolCall
};

步骤 4: 测试技能

重启 OpenClaw 后，就可以让 AI 使用你的技能了。试试：

帮我统计这篇文章的字数："Hello world! This is my first OpenClaw skill."

AI 应该会调用 count_words 工具，给你返回统计结果。

技能开发要点

目录结构

skills/your-skill/
├── SKILL.md      ← 必需，技能说明（AI 阅读）
└── index.js      ← 必需，入口代码

可以添加其他文件（比如依赖包、其他模块），只要入口是 index.js 就行。

导出接口

你的模块必须导出：

• name – 技能名称
• description – 技能描述
• handleToolCall(toolName, params, context) – 工具调用处理函数

context 对象

context 包含：

• workspaceRoot – 当前 Agent 的 workspace 根目录
• sessionId – 当前会话 ID
• agentId – 当前 Agent ID

可以用它来解析相对路径。

返回值

返回字符串就行，如果是 JSON 建议格式化，AI 更容易读取。

常用技巧

依赖第三方包

如果需要 npm 依赖，在技能目录下初始化：

cd your-skill
npm init
npm install some-package

然后在代码中 require 使用即可。

错误处理

遇到错误时，返回包含 error 字段的 JSON，AI 知道出错了会告诉你。

完整示例代码

本教程的完整代码可以在这里找到：

https://github.com/openclaw/openclaw/examples/word-counter

总结

恭喜你！你已经完成了第一个 OpenClaw 技能的开发。

开发一个技能其实很简单：

1. 创建目录和文件
2. 写 SKILL.md 说明（给 AI 看）
3. 写 index.js 实现工具调用处理
4. 重启 OpenClaw 就能用了

接下来你可以尝试：

• 给你的技能增加更多工具
• 开发更复杂的功能，比如调用外部 API
• 把你的技能分享给其他人

Happy hacking! 🚀