AI创想

标题: OpenClaw 自定义 Skill 开发完整指南（最新版） [打印本页]
作者: 创想小编    时间: 昨天 22:40
标题: OpenClaw 自定义 Skill 开发完整指南（最新版）
作者：CSDN博客
OpenClaw 自定义 Skill 开发完整指南（最新版）

文章目录


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

(, 下载次数: 0)

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

OpenClaw 中的每个 Skill，本质是一套“能力描述 + 执行逻辑”的组合包，核心特征如下：
二、Skill 开发核心原则（必看）

开发前需明确 3 个核心原则，避免踩坑：
三、推荐开发流程（新手优先用户技能目录）

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

通过终端命令创建独立的技能文件夹（文件夹名称建议简洁，用小写字母+横杠，如 my-weather-skill）：
  1. # 1. 创建用户技能目录（若不存在则自动创建）mkdir -p ~/.openclaw/skills/
  3. # 2. 创建具体技能文件夹（以“天气查询”技能为例）mkdir -p ~/.openclaw/skills/my-weather-skill
  5. # 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 文件，内容分为“固定元数据头”和“详细描述”两部分：
  1. ---
  2. # 固定元数据头（必须，AI 优先读取）
  3. name: weather-query
  4. description: 查询全球主要城市实时天气，支持中文查询（含温度、天气状况、湿度、风力）
  5. version: 1.0.0
  6. author: 你的名字
  7. permissions: 网络访问权限（用于调用天气 API）
  8. ---
  10. # Weather Query Skill（技能名称，可自定义）
  12. ## 1. Description（技能详细说明）
  13. 当用户询问天气相关问题时，使用此技能查询实时天气数据，以清晰、友好的中文格式返回结果，帮助用户快速了解目标城市的天气情况。
  15. ## 2. When to use（触发场景：明确 AI 何时调用此技能）
  16. - 用户说：“北京今天天气怎么样？”
  17. - 用户说：“上海明天会下雨吗？”
  18. - 用户说：“纽约当前温度是多少？”
  19. - 用户说：“成都后天的天气预报”
  20. - 用户说：“帮我查一下广州近 3 天的天气”
  22. ## 3. How to use（调用逻辑：教 AI 如何使用技能）
  23. 1. 从用户消息中提取 2 个核心信息：
  24.    - 目标城市（必须，如“北京”“上海”）；
  25.    - 查询时间（可选，默认“今天”，支持“明天”“后天”）；
  26. 2. 调用内置天气查询工具（或外部公开天气 API）获取数据；
  27. 3. 整理数据并返回，格式要求：
  28.    - 开头明确“城市 + 时间”（如“北京 2026年2月10日 天气”）；
  29.    - 核心信息：温度（默认摄氏度）、天气状况（晴/雨/多云等）、湿度、风力；
  30.    - 结尾补充温馨提示（如“今日有雨，建议带伞”）；
  31. 4. 若未提取到城市，主动追问用户确认具体城市。
  33. ## 4. Edge cases（边缘场景：处理异常情况）
  34. - 模糊地点（如“家附近”“公司旁边”）：回复“请告诉我具体城市名称，以便准确查询天气”；
  35. - 未支持城市（如小众县城）：回复“暂不支持该城市的天气查询，建议尝试省会或主要城市”；
  36. - 未来多天查询（如“深圳近一周天气”）：优先返回未来 3 天概览，说明“长期预报精度有限，仅作参考”；
  37. - 无网络情况：回复“当前网络不可用，无法查询天气，请检查网络连接后重试”。
复制代码
2. 测试纯文本技能

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

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

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

实现生成二维码的核心逻辑，注意函数需为 async 异步函数（适配 OpenClaw 的异步调度机制）：
  1. import qrcode
  2. from PIL import Image
  3. import os
  4. import subprocess
  5. import sys
  7. # 自动安装依赖库（若用户未安装）definstall_dependencies():
  8.     required_packages =["qrcode","pillow"]for package in required_packages:try:__import__(package)# 检查库是否已安装except ImportError:# 自动安装缺失的库
  9.             subprocess.check_call([sys.executable,"-m","pip","install", package])# 初始化：安装依赖库
  10. install_dependencies()asyncdefgenerate_qr(text:str, size:int=300, color:str="black", save_path:str=None)->str:"""
  11.     生成二维码并保存到指定路径，返回生成结果
  12.    
  13.     参数：
  14.     text: 二维码内容（必选，文本/URL/WiFi 信息等）
  15.     size: 二维码尺寸（px，默认 300）
  16.     color: 填充颜色（默认 black，支持英文或十六进制色值）
  17.     save_path: 保存路径（默认桌面 qr_code.png）
  18.     """# 1. 校验必填参数ifnot text or text.strip()=="":return"生成失败：请提供需要生成二维码的内容（如文本、URL、WiFi 信息）"# 2. 处理默认保存路径（适配 Windows/macOS/Linux 多系统）ifnot save_path:if sys.platform =="win32":# Windows 桌面路径
  19.             save_path = os.path.join(os.environ["USERPROFILE"],"Desktop","qr_code.png")else:# macOS/Linux 桌面路径
  20.             save_path = os.path.expanduser("~/Desktop/qr_code.png")# 3. 生成二维码try:# 配置二维码参数（version：1-40，box_size：方块大小，border：边框宽度）
  21.         qr = qrcode.QRCode(
  22.             version=1,
  23.             error_correction=qrcode.constants.ERROR_CORRECT_M,# 中等容错率（30% 错误可识别）
  24.             box_size=10,
  25.             border=4,)
  26.         qr.add_data(text.strip())# 添加二维码内容
  27.         qr.make(fit=True)# 自动适配内容大小# 生成图片并调整尺寸
  28.         img = qr.make_image(fill_color=color, back_color="white")
  29.         img = img.resize((size, size), Image.Resampling.LANCZOS)# 高质量缩放# 确保保存目录存在（若路径不存在则创建）
  30.         save_dir = os.path.dirname(save_path)ifnot os.path.exists(save_dir):
  31.             os.makedirs(save_dir)# 保存图片
  32.         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：
  1. # 发布命令格式
  2. clawhub publish [技能目录路径]\
  3.   --slug [技能唯一标识]\
  4.   --name [技能展示名称]\
  5.   --version [版本号]\
  6.   --description [技能简短描述]\
  7.   --public \
  8.   --author [作者名]\
  9.   --license [开源许可证]# 示例（发布“天气查询”技能）
  10. clawhub publish ~/.openclaw/skills/my-weather-skill \
  11.   --slug my-weather-query \
  12.   --name "我的天气查询技能"\
  13.   --version 1.0.0 \
  14.   --description "支持全球主要城市实时天气查询，中文友好，自动识别查询场景"\
  15.   --public \
  16.   --author "你的名字"\
  17.   --license MIT
复制代码
参数说明：
3. 验证发布结果

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

发布后，其他用户仅需执行以下命令即可一键安装：
  1. clawhub install my-weather-query  # my-weather-query 是你发布时的 --slug 参数
复制代码
七、实用开发技巧 & 避坑指南

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

九、官方参考资源

十、总结

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

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



欢迎光临 AI创想 (https://llms-ai.com/) Powered by Discuz! X3.4