OpenClaw 自定义 Skill 开发完整指南（最新版）

创想小编 · 发表于昨天 22:40

作者：CSDN博客
OpenClaw 自定义 Skill 开发完整指南（最新版）

文章目录

OpenClaw 之所以能成为极具扩展性的开源 AI Agent，核心在于其 Skill 扩展机制。不同于传统 Agent 需通过严格 API 对接扩展功能，OpenClaw 的 Skill 仅需“文件夹 + 自然语言描述文件”即可实现，AI 能通过阅读描述自动理解何时调用、如何使用该技能，极大降低了开发门槛，让普通用户也能打造专属 AI 能力。

我们一起从核心原则、开发流程、基础/进阶示例、社区发布等维度，完整拆解 OpenClaw 自定义 Skill 的开发全流程，帮助你快速上手并实现个性化需求。
一、核心认知：什么是 OpenClaw Skill？

OpenClaw 中的每个 Skill，本质是一套“能力描述 + 执行逻辑”的组合包，核心特征如下：

文件夹

SKILL.md

自然语言描述

二、Skill 开发核心原则（必看）

开发前需明确 3 个核心原则，避免踩坑：

SKILL.md 是核心

描述越详细，AI 越精准

权限明确化

三、推荐开发流程（新手优先用户技能目录）

新手建议优先使用“用户技能目录”（~/.openclaw/skills/）开发，无需修改项目配置，步骤如下：
步骤 1：创建技能目录

通过终端命令创建独立的技能文件夹（文件夹名称建议简洁，用小写字母+横杠，如 my-weather-skill）：

# 1. 创建用户技能目录（若不存在则自动创建）mkdir -p ~/.openclaw/skills/
# 2. 创建具体技能文件夹（以“天气查询”技能为例）mkdir -p ~/.openclaw/skills/my-weather-skill
# 3. 进入技能目录，准备编写文件cd ~/.openclaw/skills/my-weather-skill

复制代码

步骤 2：编写核心文件（SKILL.md + 可选代码）

根据需求选择“纯文本描述”（新手入门）或“文本描述 + 代码”（进阶功能），具体示例见下文。
步骤 3：测试验证

步骤 4：发布到社区（可选）

技能测试稳定后，可发布到 ClawHub（OpenClaw 官方技能市场），供其他用户一键安装。
四、基础示例：纯 SKILL.md 技能（新手入门首选）

无需编写任何代码，仅通过 SKILL.md 的自然语言描述即可实现技能，适合简单场景（如查询、指令分发、固定回复等）。以下以“全球天气查询”技能为例，完整演示开发过程。
1. 编写 SKILL.md 文件

在 my-weather-skill 目录下创建 SKILL.md 文件，内容分为“固定元数据头”和“详细描述”两部分：

---
# 固定元数据头（必须，AI 优先读取）
name: weather-query
description: 查询全球主要城市实时天气，支持中文查询（含温度、天气状况、湿度、风力）
version: 1.0.0
author: 你的名字
permissions: 网络访问权限（用于调用天气 API）
---
# Weather Query Skill（技能名称，可自定义）
## 1. Description（技能详细说明）
当用户询问天气相关问题时，使用此技能查询实时天气数据，以清晰、友好的中文格式返回结果，帮助用户快速了解目标城市的天气情况。
## 2. When to use（触发场景：明确 AI 何时调用此技能）
- 用户说：“北京今天天气怎么样？”
- 用户说：“上海明天会下雨吗？”
- 用户说：“纽约当前温度是多少？”
- 用户说：“成都后天的天气预报”
- 用户说：“帮我查一下广州近 3 天的天气”
## 3. How to use（调用逻辑：教 AI 如何使用技能）
1. 从用户消息中提取 2 个核心信息：
- 目标城市（必须，如“北京”“上海”）；
- 查询时间（可选，默认“今天”，支持“明天”“后天”）；
2. 调用内置天气查询工具（或外部公开天气 API）获取数据；
3. 整理数据并返回，格式要求：
- 开头明确“城市 + 时间”（如“北京 2026年2月10日天气”）；
- 核心信息：温度（默认摄氏度）、天气状况（晴/雨/多云等）、湿度、风力；
- 结尾补充温馨提示（如“今日有雨，建议带伞”）；
4. 若未提取到城市，主动追问用户确认具体城市。
## 4. Edge cases（边缘场景：处理异常情况）
- 模糊地点（如“家附近”“公司旁边”）：回复“请告诉我具体城市名称，以便准确查询天气”；
- 未支持城市（如小众县城）：回复“暂不支持该城市的天气查询，建议尝试省会或主要城市”；
- 未来多天查询（如“深圳近一周天气”）：优先返回未来 3 天概览，说明“长期预报精度有限，仅作参考”；
- 无网络情况：回复“当前网络不可用，无法查询天气，请检查网络连接后重试”。

复制代码

2. 测试纯文本技能

五、进阶示例：带 Python 代码的 Skill（实现复杂功能）

对于需要执行具体操作（如生成文件、调用外部 API、操作本地设备）的技能，需搭配代码实现。以下以“生成二维码”技能为例，演示“SKILL.md + Python 代码”的完整开发流程。
1. 创建技能目录结构

技能目录需包含核心描述文件和代码文件，结构如下：

~/.openclaw/skills/generate-qr-code/ # 技能根目录
├── SKILL.md # 核心描述文件（必须）
├── agent.py # Python 执行逻辑（核心代码文件）
└── references/ # 辅助资源文件夹（可选）
└── example-qr.png # 示例二维码图片（用于说明技能效果）

复制代码

2. 编写 SKILL.md（关联代码逻辑）

---
name: generate-qr-code
description: 生成二维码/条形码，支持文本、URL、WiFi 配置等内容，可自定义尺寸、颜色并指定保存路径
version: 1.0.0
author: 你的名字
permissions: 文件写入权限（用于保存二维码图片）
---
# Generate QR Code Skill（生成二维码技能）
## 1. Description
当用户需要将文本、URL、WiFi 信息等转换为可视化二维码时，使用此技能生成二维码图片，并保存到指定路径（默认保存到桌面），支持自定义尺寸和颜色。
## 2. When to use
- 用户说：“帮我把 https://openclaw.ai 生成二维码”
- 用户说：“生成一个包含 WiFi 信息的二维码，名称：MyWiFi，密码：12345678”
- 用户说：“生成黑色二维码，内容是‘Hello OpenClaw’，保存到 D 盘根目录”
- 用户说：“帮我做一个 400px 大小的二维码，内容是我的手机号 13800138000”
## 3. How to use
1. 从用户消息中提取核心参数：
- 必选：生成内容（文本/URL/WiFi 信息，WiFi 格式需为“WIFI:S:名称;T:类型;P:密码;;”）；
- 可选：尺寸（默认 300px）、颜色（默认黑色）、保存路径（默认桌面）；
2. 若用户未指定可选参数，使用默认值；
3. 调用 agent.py 中的 generate_qr 函数执行生成操作；
4. 返回结果：告知用户二维码保存路径，若生成失败，说明具体原因（如路径无权限、内容为空）。
## 4. Implementation（代码关联说明）
- 依赖库：qrcode（生成二维码）、Pillow（图片处理）；
- 核心函数：async def generate_qr(text: str, size: int = 300, color: str = "black", save_path: str = None)；
- 参数说明：
- text：二维码内容（必选）；
- size：二维码尺寸（单位 px，默认 300）；
- color：填充颜色（默认 black，支持英文颜色名或十六进制色值，如 #FF0000）；
- save_path：保存路径（默认桌面，文件名：qr_code.png）。
## 5. Edge cases
- 内容为空：回复“请提供需要生成二维码的内容（如文本、URL、WiFi 信息）”；
- 保存路径无权限：回复“指定路径无写入权限，请更换保存路径（如桌面）”；
- 未安装依赖库：自动尝试安装 qrcode 和 Pillow，若安装失败，提示用户手动执行“pip install qrcode pillow”；
- 特殊字符内容：自动过滤无效字符，确保二维码可正常识别。

复制代码

3. 编写 Python 代码（agent.py）

实现生成二维码的核心逻辑，注意函数需为 async 异步函数（适配 OpenClaw 的异步调度机制）：

import qrcode
from PIL import Image
import os
import subprocess
import sys
# 自动安装依赖库（若用户未安装）definstall_dependencies():
required_packages =["qrcode","pillow"]for package in required_packages:try:__import__(package)# 检查库是否已安装except ImportError:# 自动安装缺失的库
subprocess.check_call([sys.executable,"-m","pip","install", package])# 初始化：安装依赖库
install_dependencies()asyncdefgenerate_qr(text:str, size:int=300, color:str="black", save_path:str=None)->str:"""
生成二维码并保存到指定路径，返回生成结果
参数：
text: 二维码内容（必选，文本/URL/WiFi 信息等）
size: 二维码尺寸（px，默认 300）
color: 填充颜色（默认 black，支持英文或十六进制色值）
save_path: 保存路径（默认桌面 qr_code.png）
"""# 1. 校验必填参数ifnot text or text.strip()=="":return"生成失败：请提供需要生成二维码的内容（如文本、URL、WiFi 信息）"# 2. 处理默认保存路径（适配 Windows/macOS/Linux 多系统）ifnot save_path:if sys.platform =="win32":# Windows 桌面路径
save_path = os.path.join(os.environ["USERPROFILE"],"Desktop","qr_code.png")else:# macOS/Linux 桌面路径
save_path = os.path.expanduser("~/Desktop/qr_code.png")# 3. 生成二维码try:# 配置二维码参数（version：1-40，box_size：方块大小，border：边框宽度）
qr = qrcode.QRCode(
version=1,
error_correction=qrcode.constants.ERROR_CORRECT_M,# 中等容错率（30% 错误可识别）
box_size=10,
border=4,)
qr.add_data(text.strip())# 添加二维码内容
qr.make(fit=True)# 自动适配内容大小# 生成图片并调整尺寸
img = qr.make_image(fill_color=color, back_color="white")
img = img.resize((size, size), Image.Resampling.LANCZOS)# 高质量缩放# 确保保存目录存在（若路径不存在则创建）
save_dir = os.path.dirname(save_path)ifnot os.path.exists(save_dir):
os.makedirs(save_dir)# 保存图片
img.save(save_path)returnf"二维码生成成功！已保存到：{save_path}\n提示：若无法找到文件，可复制路径到文件管理器直接打开"except PermissionError:returnf"生成失败：无权限写入指定路径（{save_path}），请更换保存路径（如桌面）或提升文件权限"except Exception as e:returnf"生成失败：未知错误 - {str(e)}"

复制代码

4. 测试代码型 Skill

六、发布技能到 ClawHub（社区共享）

开发完成的技能可发布到 OpenClaw 官方社区技能市场 ClawHub，供全球用户一键安装。发布前需确保技能结构完整、无恶意代码、描述清晰。
1. 发布前置检查

2. 执行发布命令

终端中运行以下命令，发布技能到 ClawHub：

# 发布命令格式
clawhub publish [技能目录路径]\
--slug [技能唯一标识]\
--name [技能展示名称]\
--version [版本号]\
--description [技能简短描述]\
--public \
--author [作者名]\
--license [开源许可证]# 示例（发布“天气查询”技能）
clawhub publish ~/.openclaw/skills/my-weather-skill \
--slug my-weather-query \
--name "我的天气查询技能"\
--version 1.0.0 \
--description "支持全球主要城市实时天气查询，中文友好，自动识别查询场景"\
--public \
--author "你的名字"\
--license MIT

复制代码

参数说明：

3. 验证发布结果

4. 其他用户安装你的技能

发布后，其他用户仅需执行以下命令即可一键安装：

clawhub install my-weather-query # my-weather-query 是你发布时的 --slug 参数

复制代码

七、实用开发技巧 & 避坑指南

SKILL.md 编写技巧

代码开发避坑

测试技巧

动态刷新机制

八、推荐学习路径（新手到进阶）

入门阶段

基础代码阶段

进阶阶段

社区学习阶段

发布阶段

九、官方参考资源

十、总结

OpenClaw 自定义 Skill 开发的核心优势在于“低门槛 + 高灵活”——无需复杂的 API 对接，仅通过自然语言描述即可实现基础技能，搭配简单代码就能扩展复杂功能。对于新手，建议从纯 SKILL.md 技能入手，熟悉 AI 对描述的理解逻辑；对于进阶用户，可通过代码集成外部 API、本地设备操作等能力，打造专属的“AI 数字员工”。
开发技能的关键在于“把 AI 当作合作者”，用清晰、详细的描述帮它理解你的需求——你描述得越清楚，AI 执行得就越精准。赶紧动手开发第一个专属 Skill，解锁 OpenClaw 的无限可能吧！

原文地址：https://blog.csdn.net/haolove527/article/details/157650169

25位大厂高管转战生成式AI创业！吸金猛，不

OpenClaw 自定义 Skill 开发完整指南（最新版）

Teamo增强版Clawdbot一夜爆火！7x24小时分

关于我们

产品与服务

解决方案

产品与服务