OpenClaw Skill 开发入门：从 0 到 1 完整教程（2026 版）

OpenClaw 的核心扩展能力来自于 Skill 系统，它允许你自定义自动化任务、集成外部服务、扩展 Agent 能力。本文将带你从零开始，完整了解 OpenClaw Skill 的架构设计、编写方法、调试技巧，最终独立完成你的第一个自定义 Skill。无论你是开发者还是自动化爱好者，这篇教程都能帮助你掌握 OpenClaw Skill 开发的核心技能。

一、前置要求与环境准备

在开始编写 OpenClaw Skill 之前，你需要确保基础环境已经就绪。OpenClaw 基于 Node.js 运行，因此需要安装相应版本的运行时环境。同时，建议熟悉基本的命令行操作和 JavaScript/TypeScript 语法，这将帮助你更好地理解 Skill 的执行逻辑和工具调用方式。

• 系统要求：Ubuntu 20.04+ / macOS 12+ / Windows 11（WSL2 推荐）
• Node.js 版本：v18.0 或更高（推荐 v20 LTS）
• OpenClaw 版本：v1.0 或更高
• 代码编辑器：VS Code、WebStorm 或任意文本编辑器
• 基础知识：JavaScript/TypeScript、JSON 格式、命令行操作

如果你还没有安装 OpenClaw，建议先阅读《OpenClaw 在 Ubuntu 24.04 上的完整安装指南》完成基础环境配置。确保 openclaw 命令可以在终端中正常执行，这是后续开发 Skill 的前提条件。

二、Skill 架构与执行流程

OpenClaw Skill 是一个结构化的配置单元，核心文件是 SKILL.md。它定义了 Skill 的元数据、输入参数、工具调用逻辑和执行流程。理解这个架构是编写有效 Skill 的关键。Skill 通过声明式配置与命令式脚本相结合的方式，实现灵活的自动化能力。

# 查看当前已加载的 Skills
openclaw skills list

# 创建新的 Skill 目录
mkdir -p ~/.openclaw/workspace/skills/my-first-skill
cd ~/.openclaw/workspace/skills/my-first-skill

每个 Skill 都独立存在于自己的目录中，目录名称即为 Skill 的标识符。Skill 目录中至少需要包含 SKILL.md 文件，这是 Skill 的核心配置文件。复杂 Skill 还可以包含辅助脚本、资源文件、配置文件等。

三、SKILL.md 文件结构详解

SKILL.md 是 Skill 的核心配置文件，采用 YAML 格式编写。它包含 Skill 的元数据、参数定义、工具调用规则等信息。下面是一个完整的 SKILL.md 示例，展示了所有可用的配置项和它们的用途。

---
name: my-first-skill
description: 我的第一个 OpenClaw Skill，用于演示 Skill 开发基础
metadata:
  clawdbot:
    requires: {}
    primaryEnv: ""
    files: []
    tags: ["示例", "入门", "Skill 开发"]
examples:
  - "执行我的第一个 Skill"
  - "演示 Skill 如何调用工具"
---

# My First Skill（Skill 开发示例）

## 核心用途
- 演示 OpenClaw Skill 的基本结构
- 展示如何调用 exec、read、write 等工具
- 提供 Skill 开发的入门模板

## 输入参数
| 参数 | 类型 | 必填 | 说明 | 示例 |
|------|------|------|------|------|
| action | string | 是 | 执行的动作类型 | "create"、"read"、"update" |
| target | string | 否 | 目标文件或路径 | "~/.openclaw/workspace/test.txt" |
| content | string | 否 | 要写入的内容 | "Hello, OpenClaw!" |

## 执行流程

### 步骤一：参数验证
检查输入参数是否完整，action 参数必须提供。

### 步骤二：执行对应操作
根据 action 参数调用相应的工具：
- create：使用 write 工具创建文件
- read：使用 read 工具读取文件内容
- update：使用 edit 工具修改文件

### 步骤三：返回结果
输出执行结果，包括成功状态和详细信息。

SKILL.md 分为两个主要部分：YAML Front Matter 和 Markdown 正文。Front Matter 定义了 Skill 的元数据和参数规范，Markdown 正文提供了 Skill 的详细文档和执行说明。Agent 会同时参考这两部分来理解和执行 Skill。

四、工具调用实战示例

OpenClaw 提供了丰富的内置工具，包括文件操作、命令执行、浏览器控制、消息发送等。在 Skill 中调用这些工具是实现自动化功能的关键。下面通过具体示例展示如何在 Skill 中调用常见工具。

// 示例 1：使用 exec 工具执行 shell 命令
// 在 Skill 的上下文中，可以通过 Agent 调用 exec 工具
{
  "action": "exec",
  "command": "ls -la ~/.openclaw/workspace",
  "workdir": "/root/.openclaw/workspace"
}

// 示例 2：使用 read 工具读取文件
{
  "action": "read",
  "path": "~/.openclaw/workspace/SOUL.md",
  "limit": 50
}

// 示例 3：使用 write 工具创建文件
{
  "action": "write",
  "path": "~/.openclaw/workspace/skills/my-skill/output.txt",
  "content": "这是 Skill 执行后生成的内容\n"
}

在实际 Skill 开发中，你通常需要根据输入参数动态决定调用哪些工具。可以通过条件判断、循环等逻辑组合多个工具调用，实现复杂的自动化流程。每个工具调用都是独立的，Agent 会按顺序执行并收集结果。

#!/usr/bin/env python3
"""
示例：Skill 辅助脚本
用于处理复杂的数据转换或外部 API 调用
"""

import json
import requests
from datetime import datetime

def fetch_weather_data(city: str) -> dict:
    """获取天气数据的示例函数"""
    url = f"https://wttr.in/{city}?format=j1"
    response = requests.get(url)
    data = response.json()
    
    return {
        "city": city,
        "temperature": data["current_condition"][0]["temp_C"],
        "description": data["current_condition"][0]["weatherDesc"][0]["value"],
        "timestamp": datetime.now().isoformat()
    }

def save_to_file(data: dict, filepath: str) -> bool:
    """将数据保存到 JSON 文件"""
    try:
        with open(filepath, 'w', encoding='utf-8') as f:
            json.dump(data, f, ensure_ascii=False, indent=2)
        return True
    except Exception as e:
        print(f"保存失败：{e}")
        return False

if __name__ == "__main__":
    weather = fetch_weather_data("Beijing")
    save_to_file(weather, "~/.openclaw/workspace/weather_data.json")
    print(f"天气数据已保存：{weather}")

五、完整 Skill 开发案例

下面是一个完整的 Skill 开发案例，展示了从需求分析到最终实现的完整过程。这个 Skill 的功能是定时检查指定网站的状态，并在网站不可用时发送通知消息。通过这个案例，你可以了解 Skill 开发的完整流程。

---
name: website-monitor
description: 网站状态监控 Skill，定期检查网站可用性并发送通知
metadata:
  clawdbot:
    requires: {}
    primaryEnv: ""
    files: ["monitor.sh"]
    tags: ["监控", "通知", "定时任务"]
examples:
  - "检查 example.com 的网站状态"
  - "配置每 5 分钟监控一次网站"
---

# Website Monitor Skill（网站监控）

## 核心用途
- 定期检查指定网站的 HTTP 状态码
- 网站不可用时发送钉钉/Telegram 通知
- 记录监控历史到本地日志文件

## 输入参数
| 参数 | 类型 | 必填 | 说明 | 示例 |
|------|------|------|------|------|
| url | string | 是 | 要监控的网站 URL | "https://example.com" |
| interval | number | 否 | 检查间隔（分钟） | 5 |
| channel | string | 否 | 通知渠道 | "dingtalk"、"telegram" |
| threshold | number | 否 | 连续失败次数阈值 | 3 |

## 执行流程

### 步骤一：HTTP 请求检测
使用 exec 工具调用 curl 命令检查网站状态。

### 步骤二：状态判断
如果状态码不是 200，记录失败次数。

### 步骤三：通知发送
失败次数达到阈值时，通过 message 工具发送通知。

### 步骤四：日志记录
将每次检查结果写入日志文件。

这个监控 Skill 展示了如何组合多个工具实现完整功能。实际开发中，你还可以扩展更多功能，如支持多个网站监控、添加恢复通知、生成监控报告等。关键是根据需求合理设计 Skill 的结构和工具调用逻辑。

六、调试技巧与最佳实践

Skill 开发过程中，调试是不可避免的环节。OpenClaw 提供了多种调试手段，包括日志输出、工具调用追踪、错误捕获等。掌握这些技巧可以大大提高开发效率，减少排查问题的时间。

问题	原因	解决方案
Skill 无法加载	SKILL.md 格式错误	使用 YAML 验证器检查语法
工具调用失败	参数格式不正确	参考 TOOLS.md 检查参数
文件路径错误	相对路径解析问题	使用绝对路径或~开头
定时任务不执行	cron 配置错误	检查 cron job 配置和权限

最佳实践方面，建议为每个 Skill 编写清晰的文档，包括用途说明、参数定义、使用示例等。代码注释要详细，便于后续维护。同时，合理组织 Skill 目录结构，将相关资源文件集中管理，保持工作区整洁有序。

七、Skill 发布与分享

当你完成一个实用的 Skill 后，可以考虑将其分享给其他 OpenClaw 用户。发布 Skill 前，需要确保代码质量、文档完整、测试充分。可以通过 GitHub、GitLab 等平台托管 Skill 代码，方便他人下载和使用。

# Skill 发布前检查清单
# 1. 确保 SKILL.md 格式正确
yamllint SKILL.md

# 2. 测试所有功能
openclaw skills test my-skill

# 3. 检查文件权限
chmod -R 755 ~/.openclaw/workspace/skills/my-skill

# 4. 创建 README.md
echo "# My Skill" > README.md
echo "Description..." >> README.md

# 5. 提交到 Git 仓库
git add .
git commit -m "Release v1.0 of my-skill"
git push origin main

分享 Skill 时，建议提供详细的使用说明、配置示例和常见问题解答。这能帮助其他用户快速上手，减少支持成本。同时，欢迎社区反馈和改进建议，持续优化你的 Skill。

八、总结与下一步

通过本教程，你已经掌握了 OpenClaw Skill 开发的核心知识：从 SKILL.md 结构到工具调用，从调试技巧到发布流程。现在你可以开始编写自己的 Skill，实现各种自动化场景。建议从简单功能入手，逐步扩展复杂度，在实践中不断提升开发能力。

下一步学习建议：阅读《MCP 协议详解：如何在 OpenClaw 中自定义 MCP 服务》了解如何扩展更多外部工具；参考《OpenClaw 安全配置：保护你的 API 密钥和数据》确保 Skill 运行安全；加入 OpenClaw 社区与其他开发者交流经验，获取更多灵感和支持。