OpenClaw自定义Skill开发完整步骤记录(2026最新版)

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

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

重启 OpenClaw Gateway（修改 SKILL.md 可无需重启，系统自动监听；修改代码必须重启）；

通过网页 Dashboard（`http://127.0.0.1:18789/`）或聊天工具（WhatsApp/Telegram）发送指令测试；

查看日志排查问题：终端执行 `openclaw logs`，或在 Dashboard 查看“Logs”板块。

技能测试稳定后，可发布到 ClawHub（OpenClaw 官方技能市场），供其他用户一键安装。

无需编写任何代码，仅通过 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 天概览，说明“长期预报精度有限，仅作参考”；
- 无网络情况：回复“当前网络不可用，无法查询天气，请检查网络连接后重试”。

确保 OpenClaw Gateway 已启动（若未启动，执行 `openclaw gateway`）；

在聊天工具或 Dashboard 发送测试指令：`帮我查一下北京今天的天气`；

验证结果：若 AI 正确返回天气信息，说明技能生效；若未调用，检查 SKILL.md 中“When to use”场景描述是否清晰，或查看日志排查。

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

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

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

---
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”；
- 特殊字符内容：自动过滤无效字符，确保二维码可正常识别。

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

import qrcode
from PIL import Image
import os
import subprocess
import sys
# 自动安装依赖库（若用户未安装）
def install_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()
async def generate_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. 校验必填参数
    if not text or text.strip() == "":
        return "生成失败：请提供需要生成二维码的内容（如文本、URL、WiFi 信息）"
    # 2. 处理默认保存路径（适配 Windows/macOS/Linux 多系统）
    if not 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)
        if not os.path.exists(save_dir):
            os.makedirs(save_dir)
        # 保存图片
        img.save(save_path)
        return f"二维码生成成功！已保存到：{save_path}n提示：若无法找到文件，可复制路径到文件管理器直接打开"
    except PermissionError:
        return f"生成失败：无权限写入指定路径（{save_path}），请更换保存路径（如桌面）或提升文件权限"
    except Exception as e:
        return f"生成失败：未知错误 - {str(e)}"

安装依赖库（若未自动安装）：终端执行 `pip install qrcode pillow`；

重启 OpenClaw Gateway（修改代码必须重启）：`openclaw gateway restart`；

发送测试指令：`帮我生成一个包含 URL https://openclaw.ai 的二维码，尺寸 400px，颜色红色，保存到桌面`；

验证结果：查看桌面是否存在二维码图片，AI 是否返回成功提示；若失败，通过 `openclaw logs` 查看错误日志。

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

目录结构完整：至少包含 SKILL.md，代码文件（若有）可独立运行；

SKILL.md 规范：元数据头完整，“触发场景、调用逻辑、边缘情况”描述清晰；

权限说明明确：需在 SKILL.md 中标注技能所需权限（如文件读写、网络访问）；

无恶意代码：禁止包含窃取数据、破坏设备、运行病毒等恶意逻辑。

终端中运行以下命令，发布技能到 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

参数说明：

--slug：技能唯一标识（小写字母+横杠，不可重复，如 my-weather-query）；
--public：公开技能（所有人可见可安装），若为私有技能则去掉此参数；
--license：推荐使用 MIT 许可证（与 OpenClaw 一致，兼容性更好）。

发布成功后，终端会返回技能在 ClawHub 的访问链接（如 `https://clawhub.com/skills/my-weather-query`）；

可通过搜索验证：终端执行 `clawhub search my-weather-query`，若能找到技能则说明发布成功。

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

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

SKILL.md 编写技巧：

“When to use”部分多举示例：AI 对具体示例的理解远优于抽象描述；

“How to use”按步骤拆解：用 1、2、3 清晰说明执行流程，降低 AI 理解成本；

边缘场景全覆盖：提前考虑“用户输入模糊”“权限不足”“网络异常”等情况，避免技能执行失败。

代码开发避坑：

函数必须为 async 异步函数：OpenClaw 基于异步机制调度技能，同步函数会导致阻塞；

适配多系统：文件路径使用 `os.path`模块处理，避免硬编码（如不直接写“C:/Desktop”“/Users/xxx/Desktop”）；

添加异常捕获：用 try-except 捕获可能的错误（如权限不足、文件不存在），并返回友好提示。

测试技巧：

优先用 Dashboard 测试：网页端日志更清晰，方便排查问题；

强制 AI 显示思考过程：测试时在指令后添加“请说明你的思考过程”，如“查北京天气，请说明你的思考过程”，可判断 AI 是否正确识别技能；

单独测试代码：先脱离 OpenClaw，直接运行代码函数（如调用 agent.py 中的 generate_qr），确认代码可独立运行再集成。

动态刷新机制：

修改 SKILL.md：无需重启 Gateway，系统会自动监听文件变化并刷新；

修改代码文件（agent.py/index.ts）：必须重启 Gateway 才能生效。

入门阶段：开发 1-2 个纯 SKILL.md 技能（如“问候语技能”“简单计算器技能”），熟悉 SKILL.md 的核心结构；

基础代码阶段：开发带 Python/TS 代码的技能（如“文本文件生成”“本地图片压缩”），掌握代码与 SKILL.md 的关联方式；

进阶阶段：开发调用外部 API 的技能（如“股票查询”“翻译工具”），学习异步请求、API 密钥安全管理（避免硬编码）；

社区学习阶段：参考 ClawHub 上高下载量技能（如官方内置技能），学习优秀的 SKILL.md 写法和代码实现思路；

发布阶段：将成熟技能发布到 ClawHub，收集社区反馈，优化技能兼容性和用户体验。

OpenClaw 官方 Skill 开发文档：https://docs.openclaw.ai/tools/skills

ClawHub 社区技能市场：https://clawhub.com（浏览优秀技能示例）

OpenClaw GitHub 内置技能源码：https://github.com/openclaw/openclaw/tree/main/skills

MCP 协议文档（技能开发标准）：https://docs.openclaw.ai/tools/mcp

官方 Discord 技能开发交流区：https://discord.gg/openclaw（提问、分享经验）

OpenClaw 自定义 Skill 开发的核心优势在于“低门槛 + 高灵活”——无需复杂的 API 对接，仅通过自然语言描述即可实现基础技能，搭配简单代码就能扩展复杂功能。对于新手，建议从纯 SKILL.md 技能入手，熟悉 AI 对描述的理解逻辑；对于进阶用户，可通过代码集成外部 API、本地设备操作等能力，打造专属的“AI 数字员工”。

开发技能的关键在于“把 AI 当作合作者”，用清晰、详细的描述帮它理解你的需求——你描述得越清楚，AI 执行得就越精准。赶紧动手开发第一个专属 Skill，解锁 OpenClaw 的无限可能吧！

到此这篇关于OpenClaw自定义Skill开发完整步骤的文章就介绍到这了,更多相关OpenClaw自定义Skill内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！

华夏福临门盛世加强版怎么样？产品责任是重中之重

国寿福庆典版值得买吗？附投保建议

理财中低风险是几级？中低风险理财会亏吗

瑞泰泰安心防癌险优缺点是什么？这份分析不容错过

2020最新自助免费申请Office365教育版，免费5TOneDrive云盘详细图文教程

MacBook怎么绕过BootCamp安装Win10双系统？

国内知名的前端博客

域名为什么会被墙？如何检测域名是否被墙？域名被墙如何处理？

最新的windows xp sp3产品密匙 xp sp3序列号 xp sp3激活码

OpenClaw自定义Skill开发完整步骤记录(2026最新版)

目录

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

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

技能测试稳定后，可发布到 ClawHub（OpenClaw 官方技能市场），供其他用户一键安装。

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

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

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

发布成功后，终端会返回技能在 ClawHub 的访问链接（如 https://clawhub.com/skills/my-weather-query）； 可通过搜索验证：终端执行 clawhub search my-weather-query，若能找到技能则说明发布成功。

发布后，其他用户仅需执行以下命令即可一键安装： clawhub install my-weather-query # my-weather-query 是你发布时的 --slug 参数

更多文章

站内搜索

标签云

热门文章

友情链接

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

发布成功后，终端会返回技能在 ClawHub 的访问链接（如 `https://clawhub.com/skills/my-weather-query`）；

可通过搜索验证：终端执行 `clawhub search my-weather-query`，若能找到技能则说明发布成功。

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

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