OpenClaw开发自定义Skills的实战指南

2026-05-20 15:14:28 江上清风山间明月

为 OpenClaw（小龙虾）开发自定义 Skills，就像是给它装上能按你心意干活的新“手脚”。这个过程比你想象的要简单，只要遵循一定的规范和流程，即便是新手也能在短时间内开发出第一个可运行的 Skill 。

下面是开发流程的详细介绍，包括两种主要的开发路径，你可以根据自己的需求和技术栈来选择。

1. 引言

核心概念与开发路径

在动手之前，需要先理解 OpenClaw Skill 的本质。它是一个遵循特定规范的模块，负责“接收指令、执行操作、返回结果”，本身不参与意图解析和权限管理，因此提倡专注单一能力和无状态设计 。

目前，OpenClaw 支持两种主流的开发规范，你可以根据实际情况选择：

特性	路径一：JavaScript/TypeScript 模块	路径二：SKILL.md + 脚本
核心文件	`plugin.json` (元信息), `index.ts/js` (逻辑)	`SKILL.md` (配置+说明), `scripts/` (脚本目录)
开发语言	JavaScript / TypeScript	任意脚本语言 (Shell, Python, JS 等)
适用场景	深度集成 OpenClaw 内核，实现复杂逻辑、文件处理、API调用等	快速封装现有脚本、调用系统命令、实现轻量级自动化任务
优势	类型安全、与 OpenClaw 生态结合紧密	语言无关、开发门槛极低、跨平台性好

环境准备（所有路径通用）

在开始编码前，请确保你的开发环境满足以下条件：

Node.js 环境：OpenClaw 核心依赖 Node.js，推荐安装 v18 或更高版本（v22.x 更佳）。
包管理器：npm（Node.js 自带）或 yarn、pnpm。
OpenClaw 运行环境：你需要在本地或服务器上成功部署并运行 OpenClaw 网关服务（通常监听于 http://localhost:18789）。
代码编辑器：VS Code 或其他你习惯的编辑器。
核心工具（可选但推荐）：
- Git：用于版本管理和从社区获取 Skill 。
- ClawHub CLI：OpenClaw 官方的技能管理工具，可通过 npm install -g clawhub 安装，方便测试和发布 Skill 。

实战演练：两种开发路径

下面通过两个具体案例，带你走通两种开发路径。

案例一：开发一个 TypeScript 文件统计 Skill （路径一）

这个 Skill 的功能是统计指定目录下的文件类型和数量，并生成一个 Markdown 格式的报表。

初始化项目
首先，创建一个项目目录并初始化。

mkdir file-report-skill
cd file-report-skill
npm init -y
npm install typescript @types/node --save-dev
npx tsc --init --target ES2020 --module CommonJS --outDir dist

编写元信息文件 plugin.json
这个文件是 Skill 的“身份证”，告诉 OpenClaw 内核它的名字、能做什么、需要什么权限。

{
  "name": "file-report-skill",
  "version": "1.0.0",
  "description": "统计指定目录的文件类型和数量，生成Markdown格式报表",
  "author": "Your Name",
  "skills": [
    {
      "action": "generate-file-report",
      "description": "统计目录文件并生成Markdown报表",
      "parameters": [
        {
          "name": "dirPath",
          "type": "string",
          "required": true,
          "description": "要统计的目录绝对路径，如 D:/Documents 或 /home/user/docs"
        },
        {
          "name": "outputPath",
          "type": "string",
          "required": false,
          "default": "./file-report.md",
          "description": "报表保存的路径（含文件名）"
        }
      ],
      "permissions": [
        "file.read",
        "file.write"
      ]
    }
  ]
}

编写核心逻辑 index.ts
这是 Skill 的“干活的手”，实现具体的统计和报表生成逻辑。

import fs from 'fs';
import path from 'path';
function countFilesByType(dirPath: string): Record<string, number> {
  // ... (实现细节，参考搜索结果中的完整代码) ...
  const stats: Record<string, number> = {};
  if (!fs.existsSync(dirPath)) throw new Error(`目录不存在：${dirPath}`);
  const files = fs.readdirSync(dirPath, { withFileTypes: true });
  for (const file of files) {
    if (file.isDirectory()) continue;
    const ext = path.extname(file.name).toLowerCase() || '无扩展名';
    stats[ext] = (stats[ext] || 0) + 1;
  }
  return stats;
}
function generateMarkdownReport(stats: Record<string, number>, dirPath: string): string {
  // ... (生成 Markdown 表格) ...
}
export default async function run(action: string, params: any) {
  try {
    if (action !== 'generate-file-report') {
      return { success: false, message: `不支持的动作：${action}`, data: null };
    }
    const { dirPath, outputPath = './file-report.md' } = params;
    const fileStats = countFilesByType(dirPath);
    const markdown = generateMarkdownReport(fileStats, dirPath);
    const fullOutputPath = path.isAbsolute(outputPath) ? outputPath : path.join(process.cwd(), outputPath);
    fs.writeFileSync(fullOutputPath, markdown, 'utf8');
    return {
      success: true,
      message: `文件统计报表已生成`,
      data: { stats: fileStats, reportPath: fullOutputPath }
    };
  } catch (error) {
    return {
      success: false,
      message: `执行失败：${(error as Error).message}`,
      data: null
    };
  }
}

案例二：开发一个 Shell 脚本 RSS 抓取 Skill （路径二）

这个 Skill 的功能是从指定的 RSS 源抓取最新的资讯标题。

创建目录结构
在 OpenClaw 的 Skill 根目录（例如 ~/.openclaw/skills/）下创建项目。

cd ~/.openclaw/skills/
mkdir -p rss-fetch/{scripts,assets}
cd rss-fetch

编写核心配置文件 SKILL.md
这个文件包含了 YAML 格式的元信息和 Markdown 格式的使用说明。

---
name: rss-fetch
description: 全网RSS源资讯标题抓取，支持自定义抓取条数
author: your-name
version: 1.0.0
---
# rss-fetch
## 功能说明
轻量级RSS资讯抓取工具，通过RSS地址快速获取资讯标题。
## 使用方法
@openclaw rss-fetch [RSS_URL] [LIMIT=5]
- 必选参数：RSS_URL（合法的RSS源地址）
- 可选参数：LIMIT（抓取条数，默认5条）
示例：@openclaw rss-fetch https://blog.openclaw.com/rss 10

编写执行脚本 scripts/main.sh
这是实际干活儿的脚本，用 Shell 实现。

#!/bin/bash
# scripts/main.sh

RSS_URL="$1"
LIMIT="${2:-5}"
MAX_LIMIT=20
TIMEOUT=30

# 参数校验
if [ -z "$RSS_URL" ]; then
    echo "错误：请输入RSS地址！"
    exit 1
fi

if [ "$LIMIT" -gt "$MAX_LIMIT" ]; then
    LIMIT="$MAX_LIMIT"
fi

# 核心抓取逻辑
curl -s --connect-timeout "$TIMEOUT" "$RSS_URL" \
| xmllint --format - 2>/dev/null \
| grep -oP '(?<=<title>)[^<]+' 2>/dev/null \
| tail -n +2 \
| head -n "$LIMIT"

# 检查执行结果
if [ $? -ne 0 ]; then
    echo "错误：抓取失败，请检查RSS地址或网络。"
    exit 1
fi

别忘了给脚本添加可执行权限：

chmod +x scripts/main.sh

调试与测试

开发完成后，需要验证 Skill 是否能正常工作。

使用 OpenClaw CLI 测试：这是最推荐的方式，可以模拟内核调用，快速定位问题。

# 测试 RSS 抓取 Skill
openclaw skill test rss-fetch --params "https://example.com/rss 5"

检查日志输出：OpenClaw 会生成运行日志，仔细查看错误信息是解决问题的关键。

遵循开发原则：

标准化输入输出：确保你的 Skill 返回的数据结构是内核期望的。
完备的异常处理：用 try...catch 或脚本的错误退出码来捕获所有可能的错误，并返回友好的错误信息。
最小权限原则：只申请确实需要的权限（如file.read），避免安全风险。

总结

开发 OpenClaw Skill 的核心在于理解其“模块化、可复用”的设计思想。你可以通过 TypeScript 开发功能复杂的深度集成 Skill，也可以通过简单的 SKILL.md + 脚本 快速封装现有能力。

记得在开发过程中始终遵循渐进式披露的设计原则，保持 Skill 的核心指令简洁，将详细的参考信息放在独立的文件中，这样可以有效节省 AI 的上下文窗口，提升执行效率。

希望这份指南能帮助你顺利开启 OpenClaw 的自定义 Skill 开发之旅！

以上就是OpenClaw开发自定义Skills的实战指南的详细内容，更多关于OpenClaw开发自定义Skills的资料请关注脚本之家其它相关文章！