openclaw开发skill详细教程

OpenClaw 的 Skill 本质上是给 AI Agent 看的"任务说明书 + 工具包" ，核心是一个包含 SKILL.md的目录。它不需要复杂的编译，主要靠 Markdown 指令引导 Agent 调用系统工具（如 exec、browser、web_fetch）或自定义脚本。

以下是详细的开发教程：

前置准备

已安装并运行 OpenClaw（Gateway 正常启动）。
熟悉基础命令行与 YAML/Markdown 语法。
知道你的技能目录位置，通常是 ~/.openclaw/workspace/skills/。

Skill 标准结构

一个典型的 Skill 目录如下，SKILL.md是唯一必需的文件：

perl 复制代码

my-custom-skill/
├── SKILL.md        # 核心指令（元数据+YAML frontmatter+Markdown正文）
├── scripts/        # 可选：Shell/Python/Node.js 执行脚本
│   └── run.sh
├── references/     # 可选：API文档、详细参考，按需加载节省 Token
└── assets/         # 可选：静态资源

编写核心文件 SKILL.md

这是 Skill 的灵魂，分为 **Frontmatter（元数据）** 和 **Markdown 正文（指令）** 两部分。

YAML Frontmatter（头部元数据）

放在文件顶部，用 ---包裹，定义技能的"身份"与"触发条件"：

yaml 复制代码

---
name: hello-world          # 技能名，小写kebab-case，与文件夹名一致
description: 当用户需要打招呼或说hello时使用的简单演示技能
trigger: "打招呼|hello|hi|问好"  # 触发词（关键词或正则），AI据此激活技能
tools: [exec, browser]     # 声明本技能需要用到的系统工具
version: 1.0.0
author: yourname
config:                    # 可选：需要的配置项（如API Key）
  API_KEY:
    type: string
    required: true
---

name：必须唯一，仅含小写字母、数字、短横线。
trigger ：不写则需用户显式指定；写 "*"表示全局常驻；也可写正则 /^deploy .+ to (staging|prod)$/i。

Markdown 正文（给 AI 的指令）

Frontmatter 之后写具体内容，像给同事下达任务一样清晰：

markdown 复制代码

# Hello World 技能

## 何时使用
当用户请求问候、说"你好"、"hello"或需要测试连接时使用此技能。

## 执行步骤
1. 使用 `echo` 工具（或 exec 运行 `echo`）输出："Hello from your custom skill! 🚀"
2. 如果是中文语境，额外输出当前日期。

## 输入/输出
- 输入：无特定参数
- 输出：一段友好的问候语字符串

## 注意事项
- 不要执行任意用户输入的代码，仅输出固定问候。
- 保持输出简洁。

（可选）编写执行脚本

如果逻辑复杂，可在 scripts/下放脚本，在 SKILL.md 里指示 Agent 调用：

bash 复制代码

#!/bin/bash
# scripts/fetch_news.sh
CATEGORY=$1
curl -s "https://news.example.com/api/$CATEGORY" | jq '.[].title'

在 SKILL.md 正文中写明：运行 node scripts/fetch_news.js tech 获取科技新闻。确保脚本有执行权限 (chmod +x)。

加载与测试

放置目录 ：将 my-custom-skill放入 ~/.openclaw/workspace/skills/。
刷新/重启 ：让 Agent 发现新技能，执行 openclaw gateway restart或在聊天中说"刷新技能"。
验证列表 ：运行 openclaw skills list确认状态为 ready。
测试触发：
- 发送消息："跟我打个招呼"
- 或用命令行测试：openclaw agent --message "give me a greeting"。
本地调试（SDK 模式） ：若用 TypeScript/JS SDK 开发，可用 clawhub dev模拟调用。

进阶与发布

Workshop 提案 ：可用 openclaw skills workshop propose-create让 AI 辅助审查再落地。
发布到 ClawHub ：登录 clawhub login后执行 clawhub publish，需确保 SKILL.md完整且无硬编码密钥。
安全建议 ：使用 exec工具时严防命令注入；敏感信息（API Key）通过 env或 openclaw.json5的 config注入，勿写死在文件里。

最佳实践总结

描述精准 ：description和 trigger决定 AI 会不会用，关键词要覆盖全。
指令明确：写"做什么、按什么顺序、输出什么格式"，减少歧义。
Token 优化 ：重内容放 references/，SKILL.md只留核心流程。
单一职责：一个 Skill 专注一件事（如"查天气"而非"查天气+发邮件"）。

下面我写一个简单的例子：

下面给你一个可直接用的 OpenClaw 查天气 Skill 完整示例 ，包含 SKILL.md+ 脚本 + 配置说明，适合新手直接复制跑通。

一、Skill 目录结构

sql 复制代码

weather/
├── SKILL.md
├── scripts/
│   └── get_weather.sh
└── references/
    └── open-meteo-api.md

✅ 只需要 SKILL.md+ scripts/get_weather.sh就能运行

📄 references/仅用于给 AI 查阅 API 文档，节省 Token

二、SKILL.md（核心文件）

路径：~/.openclaw/workspace/skills/weather/SKILL.md

yaml 复制代码

---
name: weather
description: 查询城市当前天气和未来预报，支持中文城市名自动解析经纬度
trigger: "天气|气温|下雨|forecast|weather|查天气"
tools: [exec]
version: 1.0.0
author: you
config:
  UNITS:
    type: string
    default: "metric"
    description: "metric(摄氏度) 或 imperial(华氏度)"
---
# Weather 天气查询技能

## 何时使用
当用户询问某个城市的天气、气温、是否下雨、未来几天天气时使用本技能。

## 执行流程

1. **解析城市**
   - 如果用户给出的是中文城市名（如"北京"），先使用 geocoding API 转换为经纬度。
   - 接口示例：

geocoding-api.open-meteo.com/v1/search?n...北京&count=1

markdown 复制代码

2. **调用天气 API**
- 使用 Open-Meteo（无需 API Key）
- 基础 URL：

api.open-meteo.com/v1/forecast

diff 复制代码

- 必须参数：
- latitude
- longitude
- current_weather=true
- hourly=temperature_2m,precipitation_probability
- timezone=auto

3. **运行脚本**
- 调用本地脚本获取天气数据：

bash

bash scripts/get_weather.sh "城市名"

diff 复制代码

- 示例：

bash

bash scripts/get_weather.sh "Beijing"

bash scripts/get_weather.sh "东京"

markdown 复制代码

4. **输出规范**
- 使用自然语言总结，不要直接输出 JSON
- 至少包含：
- 城市名
- 当前气温
- 天气状况（晴 / 雨 / 阴等）
- 降水概率
- 风速
- 示例输出：
> 北京当前气温 22°C，晴朗，降水概率 10%，风速 12 km/h。

## 错误处理
- 若城市无法解析：提示用户检查城市名称拼写
- 若 API 超时：提示"暂时无法获取天气数据，请稍后重试"

## 参考
- API 详细字段说明见 `references/open-meteo-api.md`

三、scripts/get_weather.sh（执行脚本）

路径：~/.openclaw/workspace/skills/weather/scripts/get_weather.sh

ini 复制代码

#!/bin/bash

set -euo pipefail

CITY="$1"

# 1. 地理编码
GEO=$(curl -s "https://geocoding-api.open-meteo.com/v1/search?name=${CITY}&count=1")
LAT=$(echo "$GEO" | jq -r '.results[0].latitude // empty')
LON=$(echo "$GEO" | jq -r '.results[0].longitude // empty')
NAME=$(echo "$GEO" | jq -r '.results[0].name // empty')

if [[ -z "$LAT" || -z "$LON" ]]; then
  echo "❌ 无法找到城市：$CITY"
  exit 1
fi

# 2. 获取天气
WEATHER=$(curl -s "https://api.open-meteo.com/v1/forecast?latitude=$LAT&longitude=$LON&current_weather=true&hourly=temperature_2m,precipitation_probability&timezone=auto")

TEMP=$(echo "$WEATHER" | jq -r '.current_weather.temperature')
WIND=$(echo "$WEATHER" | jq -r '.current_weather.windspeed')
CODE=$(echo "$WEATHER" | jq -r '.current_weather.weathercode')
RAIN=$(echo "$WEATHER" | jq -r '.hourly.precipitation_probability[0]')

# 3. 天气代码映射
case $CODE in
  0) COND="晴朗" ;;
  1|2|3) COND="多云" ;;
  45|48) COND="雾" ;;
  51|53|55) COND="小雨" ;;
  61|63|65) COND="雨" ;;
  71|73|75) COND="雪" ;;
  95|96|99) COND="雷暴" ;;
  *) COND="未知" ;;
esac

# 4. 输出
echo "${NAME} 当前气温 ${TEMP}°C，${COND}，降水概率 ${RAIN}%，风速 ${WIND} km/h。"

赋予执行权限：

ruby 复制代码

chmod +x ~/.openclaw/workspace/skills/weather/scripts/get_weather.sh

四、references/open-meteo-api.md（可选）

diff 复制代码

# Open-Meteo API 说明

## 地理编码
GET https://geocoding-api.open-meteo.com/v1/search?name=城市名

返回字段：
- results[0].latitude
- results[0].longitude
- results[0].name

## 天气预报
GET https://api.open-meteo.com/v1/forecast

常用参数：
- latitude
- longitude
- current_weather=true
- hourly=temperature_2m,precipitation_probability
- timezone=auto

天气代码（weathercode）：
- 0: 晴朗
- 1--3: 多云
- 45,48: 雾
- 51--55: 小雨
- 61--65: 雨
- 71--75: 雪
- 95+: 雷暴

五、加载 & 测试

1️⃣ 重启 Gateway

复制代码

openclaw gateway restart

2️⃣ 查看技能状态

复制代码

openclaw skills list

3️⃣ 聊天中测试

复制代码

查一下上海的天气

预期输出示例：

上海当前气温 26°C，多云，降水概率 20%，风速 14 km/h。

六、常见增强方向（进阶）

你可以继续扩展这个 Skill：

✅ 支持未来 3～7 天预报（daily=）
✅ 自动识别用户所在城市（IP → 经纬度）
✅ 多语言输出（中 / 英）
✅ 封装为 HTTP skill（OpenClaw 的 http工具）
✅ 发布到 ClawHub：clawhub publish

七、调试小技巧

手动测试脚本：
bash 复制代码
```
./scripts/get_weather.sh "Beijing"
```
查看 Agent 实际调用命令（Gateway 日志）
若 AI 不触发 Skill，检查：
- trigger是否覆盖用户说法
- Skill 是否在 skills list中显示为 ready