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

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

文章目录

• OpenClaw 自定义 Skill 开发完整指南（最新版）
• • 一、核心认知：什么是 OpenClaw Skill？
  • 二、Skill 开发核心原则（必看）
  • 三、推荐开发流程（新手优先用户技能目录）
  • • 步骤 1：创建技能目录
    • 步骤 2：编写核心文件（SKILL.md + 可选代码）
    • 步骤 3：测试验证
    • 步骤 4：发布到社区（可选）
  • 四、基础示例：纯 SKILL.md 技能（新手入门首选）
  • • 1. 编写 SKILL.md 文件
    • 2. 测试纯文本技能
  • 五、进阶示例：带 Python 代码的 Skill（实现复杂功能）
  • • 1. 创建技能目录结构
    • 2. 编写 SKILL.md（关联代码逻辑）
    • 3. 编写 Python 代码（agent.py）
    • 4. 测试代码型 Skill
  • 六、发布技能到 ClawHub（社区共享）
  • • 1. 发布前置检查
    • 2. 执行发布命令
    • 3. 验证发布结果
    • 4. 其他用户安装你的技能
  • 七、实用开发技巧 & 避坑指南
  • 八、推荐学习路径（新手到进阶）
  • 九、官方参考资源
  • 十、总结

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

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

一、核心认知：什么是 OpenClaw Skill？

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

• 核心载体：以文件夹为单位，文件夹内必须包含SKILL.md文件（能力描述核心）；

• 扩展文件：可选agent.py（Python 执行逻辑）、index.ts（TypeScript 执行逻辑）、references/（辅助文档/示例资源）等；

• 核心优势：AI 通过阅读 SKILL.md 的自然语言描述理解技能，无需严格遵循代码接口，灵活度极高；

• 加载优先级：OpenClaw 按以下顺序加载技能（高优先级覆盖低优先级）：

  1. 工作区技能：<your-workspace>/skills/（项目级技能，适合团队协作）；

  2. 用户技能：~/.openclaw/skills/（个人级技能，推荐新手使用）；

  3. 内置技能：OpenClaw 安装时自带的基础能力（如文件读写、浏览器操作）。

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

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

1. SKILL.md 是核心：无论是否编写代码，SKILL.md 都必须完整——它直接决定 AI 是否能正确识别、调用技能；

2. 描述越详细，AI 越精准：重点写清“何时用、怎么用、异常情况怎么处理”，多举示例帮助 AI 理解；

3. 权限明确化：若技能需文件读写、网络访问、Shell 执行等权限，务必在 SKILL.md 中明确标注，既方便用户判断安全性，也符合社区发布规范。

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

新手建议优先使用“用户技能目录”（~/.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：测试验证

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

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

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

步骤 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. 测试纯文本技能

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

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

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

五、进阶示例：带 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 大小的二维码，内容是我的手机号 [phone]” ## 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 的异步调度机制）：

importqrcodefromPILimportImageimportosimportsubprocessimportsys# 自动安装依赖库（若用户未安装）definstall_dependencies():required_packages=["qrcode","pillow"]forpackageinrequired_packages:try:__import__(package)# 检查库是否已安装exceptImportError:# 自动安装缺失的库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. 校验必填参数ifnottextortext.strip()=="":return"生成失败：请提供需要生成二维码的内容（如文本、URL、WiFi 信息）"# 2. 处理默认保存路径（适配 Windows/macOS/Linux 多系统）ifnotsave_path:ifsys.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)ifnotos.path.exists(save_dir):os.makedirs(save_dir)# 保存图片img.save(save_path)returnf"二维码生成成功！已保存到：{save_path}\n提示：若无法找到文件，可复制路径到文件管理器直接打开"exceptPermissionError:returnf"生成失败：无权限写入指定路径（{save_path}），请更换保存路径（如桌面）或提升文件权限"exceptExceptionase:returnf"生成失败：未知错误 -{str(e)}"

4. 测试代码型 Skill

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

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

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

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

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

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

1. 发布前置检查

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

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

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

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

2. 执行发布命令

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

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

参数说明：

• --slug：技能唯一标识（小写字母+横杠，不可重复，如 my-weather-query）；

• --public：公开技能（所有人可见可安装），若为私有技能则去掉此参数；

• --license：推荐使用 MIT 许可证（与 OpenClaw 一致，兼容性更好）。

3. 验证发布结果

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

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

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

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

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

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

1. SKILL.md 编写技巧：

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

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

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

2. 代码开发避坑：

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

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

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

3. 测试技巧：

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

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

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

4. 动态刷新机制：

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

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

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

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

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

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

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

5. 发布阶段：将成熟技能发布到 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 的无限可能吧！