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

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

---
# 固定元数据头（必须，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/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”；
- 特殊字符内容：自动过滤无效字符，确保二维码可正常识别。

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)}"

# 发布命令格式
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

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