OpenClaw Skills 基础教程 - 从零开始创建你的第一个技能
OpenClaw Skills 基础教程
本教程将带你从零开始，一步步学会如何创建、配置和使用 OpenClaw Skills。无论你是完全的新手还是有一定编程基础，都能跟着这个教程完成你的第一个 Skill。
📚 目录
什么是 OpenClaw Skills
概念介绍
OpenClaw Skills 是 OpenClaw Agent 系统的扩展能力模块。通过 Skills，你可以让 AI Agent 具备各种实际操作能力，比如：
-
🌐 访问网页并提取信息
-
📁 读写本地文件
-
🔧 执行系统命令
-
📧 发送邮件和消息
-
🔍 搜索和查询数据
-
🎨 生成图片和文档
Skills 的工作原理
用户请求 → OpenClaw Agent → 分析意图 → 选择合适的 Skill → 执行 Skill → 返回结果简单来说，Skill 就是给 AI 的一个"工具箱"，告诉它：
-
什么时候用（使用场景）
-
怎么用（参数说明）
-
用了会怎样（返回结果）
环境准备
1. 安装 OpenClaw
如果你还没有安装 OpenClaw，请先完成安装：
# 使用 pip 安装
pip install openclaw
# 或使用 pipx（推荐）
pipx install openclaw
# 验证安装
openclaw --version2. 初始化配置
# 初始化 OpenClaw 配置
openclaw init
# 这会在 ~/.openclaw/ 目录下创建配置文件3. 确认 Skills 目录
Skills 默认存放在 ~/.openclaw/skills/ 目录下：
# 查看 skills 目录
ls ~/.openclaw/skills/
# 如果目录不存在，创建它
mkdir -p ~/.openclaw/skills/4. 查看已安装的 Skills
# 列出所有已安装的 Skills
openclaw skills list
# 输出示例：
# ┌──────────────────┬─────────┬────────────────────────────┐
# │ Name │ Version │ Description │
# ├──────────────────┼─────────┼────────────────────────────┤
# │ web_search │ 1.2.0 │ 网页搜索 │
# │ web_fetch │ 1.1.0 │ 网页内容抓取 │
# │ file_operations │ 1.0.0 │ 文件读写操作 │
# └──────────────────┴─────────┴────────────────────────────┘创建第一个 Skill
让我们创建一个简单的"问候语生成器" Skill，它可以根据时间和场景生成合适的问候语。
步骤 1：创建 Skill 目录
# 创建 Skill 文件夹
mkdir -p ~/.openclaw/skills/greeting-generator
cd ~/.openclaw/skills/greeting-generator步骤 2：创建 SKILL.md 文件
这是最重要的文件，它告诉 AI 这个 Skill 是做什么的。
# 创建 SKILL.md
touch SKILL.md用你喜欢的编辑器打开 SKILL.md，写入以下内容：
# 技能名称：问候语生成器
## 描述（Description）
根据当前时间、场景和对象，生成合适的中文问候语。支持正式场合、日常对话、节日祝福等多种场景。
## 使用场景（When to use）
- 用户需要生成问候语或祝福语
- 用户要写邮件开头的问候
- 用户需要节日祝福文案
- 用户想要个性化的打招呼方式
## 参数（Parameters）
```json
{
"type": "object",
"properties": {
"scene": {
"type": "string",
"description": "场景类型：formal（正式）、casual（日常）、festival（节日）",
"enum": ["formal", "casual", "festival"],
"default": "casual"
},
"target": {
"type": "string",
"description": "问候对象，如：老师、朋友、客户、领导",
"default": "朋友"
},
"festival": {
"type": "string",
"description": "如果是节日场景，指定节日名称",
"default": ""
},
"time_of_day": {
"type": "string",
"description": "时间段：morning、afternoon、evening、night",
"enum": ["morning", "afternoon", "evening", "night"],
"default": "morning"
}
},
"required": ["scene"]
}调用示例（Examples）
用户：帮我写一个给客户的正式问候语
→ 调用 { "scene": "formal", "target": "客户", "time_of_day": "morning" }
用户：春节给朋友的祝福语
→ 调用 { "scene": "festival", "target": "朋友", "festival": "春节" }
用户：早上好怎么说比较有创意
→ 调用 { "scene": "casual", "time_of_day": "morning" }返回格式（Expected Output）
返回 JSON 格式：
{
"status": "success",
"greeting": "生成的问候语",
"alternatives": ["备选问候语1", "备选问候语2"]
}注意事项（Constraints）
-
问候语应该符合中国文化习惯
-
正式场合避免使用网络用语
-
节日祝福要应景
### 步骤 3：刷新 Skills 列表
```bash
# 刷新 Skills
openclaw skills refresh
# 验证 Skill 是否被识别
openclaw skills list | grep greeting步骤 4：测试 Skill
# 使用 Agent 测试
openclaw agent --message "帮我生成一个给老师的正式问候语" --skills greeting-generator🎉 恭喜！你已经创建了第一个 Skill！
Skill 文件结构详解
一个完整的 Skill 目录结构如下：
~/.openclaw/skills/my-skill/
├── SKILL.md # 必需：Skill 说明文档
├── manifest.json # 推荐：元数据配置
├── run.py # 可选：Python 执行脚本
├── run.sh # 可选：Shell 执行脚本
├── index.js # 可选：Node.js 执行脚本
├── requirements.txt # 可选：Python 依赖
├── package.json # 可选：Node.js 依赖
└── README.md # 可选：详细文档各文件说明
| 文件 | 必需 | 说明 |
|---|---|---|
SKILL.md |
✅ 是 | 给 AI 看的说明书，最重要的文件 |
manifest.json |
推荐 | 元数据配置，包含版本、作者等信息 |
run.py |
可选 | Python 执行脚本 |
run.sh |
可选 | Shell 执行脚本 |
index.js |
可选 | Node.js 执行脚本 |
manifest.json 示例
{
"name": "greeting-generator",
"version": "1.0.0",
"description": "问候语生成器",
"author": "Your Name",
"license": "MIT",
"tags": ["greeting", "text", "chinese"],
"runtime": "python",
"entry": "run.py",
"dependencies": {
"python": ">=3.8"
}
}SKILL.md 编写指南
SKILL.md 是 Skill 的核心文件，写好它是成功的关键。
必需部分
1. 技能名称和描述
# 技能名称：XXX
## 描述（Description）
清晰、简洁地说明这个 Skill 能做什么。写作技巧：
-
用一句话概括核心功能
-
说明能解决什么问题
-
提及支持的主要特性
2. 使用场景
## 使用场景（When to use）
- 场景1
- 场景2
- 场景3写作技巧：
-
列出 3-5 个典型场景
-
用用户视角描述
-
包含关键词便于 AI 匹配
3. 参数定义
## 参数（Parameters）
```json
{
"type": "object",
"properties": {
"param1": {
"type": "string",
"description": "参数说明",
"required": true
}
}
}
**参数类型**：
- `string` - 字符串
- `number` / `integer` - 数字
- `boolean` - 布尔值
- `array` - 数组
- `object` - 对象
#### 4. 调用示例
```markdown
## 调用示例（Examples）
```text
用户：具体的用户请求
→ 调用 { "param1": "value1" }
**写作技巧**：
- 提供 2-3 个真实场景的例子
- 覆盖不同的参数组合
- 使用自然语言描述用户请求
### 可选部分
#### 5. 返回格式
```markdown
## 返回格式（Expected Output）
成功时返回：
```json
{
"status": "success",
"data": "..."
}失败时返回：
{
"status": "error",
"message": "错误原因"
}
#### 6. 注意事项
```markdown
## 注意事项（Constraints）
- 限制1
- 限制2
- 安全注意事项7. 执行方式
## 执行方式
用 Python 3.10+ 执行 run.py，输入为 JSON（从 stdin），输出为 JSON（到 stdout）添加执行代码
纯描述型 Skill 只能做 prompt 层面的处理。如果需要真正执行操作，需要添加执行代码。
Python 执行脚本
创建 run.py：
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
问候语生成器 - 执行脚本
"""
import sys
import json
from datetime import datetime
# 问候语模板
GREETINGS = {
"formal": {
"morning": [
"早上好，{target}！祝您今天工作顺利！",
"尊敬的{target}，早安！愿您今日万事如意！",
],
"afternoon": [
"下午好，{target}！感谢您百忙之中的关注！",
"尊敬的{target}，午安！祝您下午工作愉快！",
],
"evening": [
"晚上好，{target}！感谢您的辛勤付出！",
"尊敬的{target}，晚安！祝您今晚休息愉快！",
],
},
"casual": {
"morning": [
"早啊{target}！新的一天开始啦～",
"早上好{target}！今天也要元气满满哦！",
"{target}早！起床第一件事就是想到你～",
],
"afternoon": [
"下午好{target}！记得喝杯下午茶～",
"{target}下午好！今天过得怎么样？",
],
"evening": [
"晚上好{target}！今天辛苦啦！",
"{target}晚安！做个好梦～",
],
},
"festival": {
"春节": [
"新春快乐，{target}！祝您龙年大吉，万事如意！",
"{target}，恭喜发财！红包拿来～",
"给{target}拜年啦！祝新的一年心想事成！",
],
"中秋": [
"中秋快乐，{target}！月圆人团圆！",
"{target}，中秋节快乐！记得吃月饼哦～",
],
"元旦": [
"新年快乐，{target}！愿新的一年一切顺利！",
"{target}，元旦快乐！新年新气象！",
],
},
}
def generate_greeting(params: dict) -> dict:
"""生成问候语"""
scene = params.get("scene", "casual")
target = params.get("target", "朋友")
festival = params.get("festival", "")
time_of_day = params.get("time_of_day", "morning")
try:
if scene == "festival" and festival:
# 节日问候
templates = GREETINGS.get("festival", {}).get(festival, [])
if not templates:
templates = [f"{festival}快乐，{target}！"]
else:
# 普通问候
templates = GREETINGS.get(scene, {}).get(time_of_day, [])
if not templates:
templates = [f"你好，{target}！"]
import random
greeting = random.choice(templates).format(target=target)
alternatives = [t.format(target=target) for t in templates if t != greeting][:2]
return {
"status": "success",
"greeting": greeting,
"alternatives": alternatives,
}
except Exception as e:
return {
"status": "error",
"message": str(e),
}
def main():
"""主函数"""
try:
# 从 stdin 读取输入
input_data = json.load(sys.stdin)
# 生成问候语
result = generate_greeting(input_data)
# 输出结果到 stdout
print(json.dumps(result, ensure_ascii=False, indent=2))
except json.JSONDecodeError:
print(json.dumps({
"status": "error",
"message": "Invalid JSON input"
}))
sys.exit(1)
except Exception as e:
print(json.dumps({
"status": "error",
"message": str(e)
}))
sys.exit(1)
if __name__ == "__main__":
main()Shell 执行脚本
创建 run.sh（适合简单操作）：
#!/bin/bash
# 问候语生成器 - Shell 版本
# 读取输入
INPUT=$(cat)
# 解析参数
SCENE=$(echo "$INPUT" | jq -r '.scene // "casual"')
TARGET=$(echo "$INPUT" | jq -r '.target // "朋友"')
TIME=$(echo "$INPUT" | jq -r '.time_of_day // "morning"')
# 生成问候语
case "$SCENE" in
"formal")
case "$TIME" in
"morning") GREETING="早上好，${TARGET}！祝您今天工作顺利！" ;;
"afternoon") GREETING="下午好，${TARGET}！感谢您的关注！" ;;
*) GREETING="您好，${TARGET}！" ;;
esac
;;
*)
case "$TIME" in
"morning") GREETING="早啊${TARGET}！新的一天开始啦～" ;;
"afternoon") GREETING="下午好${TARGET}！记得喝杯下午茶～" ;;
*) GREETING="你好${TARGET}！" ;;
esac
;;
esac
# 输出结果
echo "{\"status\": \"success\", \"greeting\": \"$GREETING\"}"Node.js 执行脚本
创建 index.js：
#!/usr/bin/env node
/**
* 问候语生成器 - Node.js 版本
*/
const readline = require('readline');
const GREETINGS = {
formal: {
morning: ['早上好，{target}！祝您今天工作顺利！'],
afternoon: ['下午好，{target}！感谢您的关注！'],
evening: ['晚上好，{target}！祝您休息愉快！'],
},
casual: {
morning: ['早啊{target}！新的一天开始啦～', '早上好{target}！今天也要元气满满哦！'],
afternoon: ['下午好{target}！记得喝杯下午茶～'],
evening: ['晚上好{target}！今天辛苦啦！'],
},
};
function generateGreeting(params) {
const { scene = 'casual', target = '朋友', time_of_day = 'morning' } = params;
const templates = GREETINGS[scene]?.[time_of_day] || ['你好，{target}！'];
const greeting = templates[Math.floor(Math.random() * templates.length)]
.replace('{target}', target);
return {
status: 'success',
greeting,
alternatives: templates.slice(0, 2).map(t => t.replace('{target}', target)),
};
}
// 读取 stdin
let input = '';
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
try {
const params = JSON.parse(input);
const result = generateGreeting(params);
console.log(JSON.stringify(result, null, 2));
} catch (e) {
console.log(JSON.stringify({ status: 'error', message: e.message }));
process.exit(1);
}
});测试和调试
本地测试
1. 直接测试执行脚本
# 测试 Python 脚本
echo '{"scene": "casual", "target": "小明", "time_of_day": "morning"}' | python run.py
# 测试 Shell 脚本
echo '{"scene": "formal", "target": "客户"}' | bash run.sh
# 测试 Node.js 脚本
echo '{"scene": "casual", "target": "朋友"}' | node index.js2. 使用 OpenClaw 测试
# 测试 Skill 是否被正确识别
openclaw skills info greeting-generator
# 使用 Agent 测试
openclaw agent --message "生成一个早上好的问候语" --skills greeting-generator --debug调试技巧
1. 启用调试模式
# 设置环境变量
export OPENCLAW_DEBUG=1
# 或在命令中添加 --debug
openclaw agent --message "测试" --skills my-skill --debug2. 查看日志
# 查看 OpenClaw 日志
tail -f ~/.openclaw/logs/openclaw.log
# 查看 Skill 执行日志
tail -f ~/.openclaw/logs/skills.log3. 常见问题排查
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| Skill 未被识别 | SKILL.md 格式错误 | 检查 Markdown 语法 |
| 参数解析失败 | JSON Schema 格式错误 | 验证 JSON 格式 |
| 执行脚本报错 | 依赖未安装 | 安装所需依赖 |
| 权限不足 | 脚本无执行权限 | chmod +x run.py |
发布和分享
发布到 npm（Node.js Skill）
# 初始化 package.json
npm init
# 发布
npm publish发布到 PyPI（Python Skill）
# 创建 setup.py
# 构建
python setup.py sdist bdist_wheel
# 发布
twine upload dist/*分享到 GitHub
# 初始化 Git 仓库
git init
git add .
git commit -m "Initial commit: greeting-generator skill"
# 推送到 GitHub
git remote add origin https://github.com/username/openclaw-skill-greeting.git
git push -u origin main安装他人的 Skill
# 从 npm 安装
openclaw skills install greeting-generator
# 从 GitHub 安装
openclaw skills install https://github.com/username/openclaw-skill-greeting.git
# 从本地安装
openclaw skills install ./path/to/skill常见问题解答
Q1: SKILL.md 和 manifest.json 有什么区别？
A:
-
SKILL.md是给 AI 看的说明书，用自然语言描述 Skill 的功能 -
manifest.json是给程序看的配置文件，包含版本、依赖等元数据
两者都很重要，但 SKILL.md 是必需的。
Q2: 我的 Skill 需要调用外部 API，怎么处理密钥？
A: 使用环境变量或 OpenClaw 的配置系统：
import os
# 方式1：环境变量
api_key = os.environ.get('MY_API_KEY')
# 方式2：OpenClaw 配置
# 在 ~/.openclaw/config.yaml 中配置
# skills:
# my-skill:
# api_key: "your-key"Q3: 如何让 Skill 支持多语言？
A: 在 SKILL.md 中添加多语言描述：
## 描述（Description）
[中文] 这是一个问候语生成器
[English] This is a greeting generatorQ4: Skill 执行超时怎么办？
A: 在 manifest.json 中配置超时时间：
{
"timeout": 60000,
"retry": 3
}Q5: 如何调试复杂的 Skill？
A:
-
使用
--debug参数 -
在代码中添加日志
-
使用单元测试
import logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)
def execute(params):
logger.debug(f"Received params: {params}")
# ...🎯 下一步
恭喜你完成了 OpenClaw Skills 基础教程！接下来你可以：
-
尝试更多内置 Skill
openclaw skills install web_search openclaw skills install code_interpreter -
学习进阶内容
-
加入社区
- GitHub: OpenClaw
- Discord: OpenClaw Community
📚 参考资源
💡 提示：如果你在学习过程中遇到任何问题，欢迎在 GitHub Issues 中提问，或加入我们的 Discord 社区寻求帮助！
相关推荐
评论
