OpenClaw 自定義 Skill 開發(fā)完整指南（最新版）

OpenClaw 之所以能成為極具擴(kuò)展性的開源 AI Agent，核心在于其 Skill 擴(kuò)展機(jī)制。不同于傳統(tǒng) Agent 需通過嚴(yán)格 API 對接擴(kuò)展功能，OpenClaw 的 Skill 僅需“文件夾 + 自然語言描述文件”即可實(shí)現(xiàn)，AI 能通過閱讀描述自動理解何時調(diào)用、如何使用該技能，極大降低了開發(fā)門檻，讓普通用戶也能打造專屬 AI 能力。

我們一起從核心原則、開發(fā)流程、基礎(chǔ)/進(jìn)階示例、社區(qū)發(fā)布等維度，完整拆解 OpenClaw 自定義 Skill 的開發(fā)全流程，幫助你快速上手并實(shí)現(xiàn)個性化需求。

一、核心認(rèn)知：什么是 OpenClaw Skill？

OpenClaw 中的每個 Skill，本質(zhì)是一套“能力描述 + 執(zhí)行邏輯”的組合包，核心特征如下：

• 核心載體：以文件夾為單位，文件夾內(nèi)必須包含 SKILL.md 文件（能力描述核心）；

• 擴(kuò)展文件：可選agent.py（Python 執(zhí)行邏輯）、index.ts（TypeScript 執(zhí)行邏輯）、references/（輔助文檔/示例資源）等；

• 核心優(yōu)勢：AI 通過閱讀 SKILL.md 的自然語言描述理解技能，無需嚴(yán)格遵循代碼接口，靈活度極高；

• 加載優(yōu)先級：OpenClaw 按以下順序加載技能（高優(yōu)先級覆蓋低優(yōu)先級）：

  1. 工作區(qū)技能：<your-workspace>/skills/（項(xiàng)目級技能，適合團(tuán)隊(duì)協(xié)作）；

  2. 用戶技能：~/.openclaw/skills/（個人級技能，推薦新手使用）；

  3. 內(nèi)置技能：OpenClaw 安裝時自帶的基礎(chǔ)能力（如文件讀寫、瀏覽器操作）。

二、Skill 開發(fā)核心原則（必看）

開發(fā)前需明確 3 個核心原則，避免踩坑：

1. SKILL.md 是核心：無論是否編寫代碼，SKILL.md 都必須完整——它直接決定 AI 是否能正確識別、調(diào)用技能；

2. 描述越詳細(xì)，AI 越精準(zhǔn)：重點(diǎn)寫清“何時用、怎么用、異常情況怎么處理”，多舉示例幫助 AI 理解；

3. 權(quán)限明確化：若技能需文件讀寫、網(wǎng)絡(luò)訪問、Shell 執(zhí)行等權(quán)限，務(wù)必在 SKILL.md 中明確標(biāo)注，既方便用戶判斷安全性，也符合社區(qū)發(fā)布規(guī)范。

三、推薦開發(fā)流程（新手優(yōu)先用戶技能目錄）

新手建議優(yōu)先使用“用戶技能目錄”（~/.openclaw/skills/）開發(fā)，無需修改項(xiàng)目配置，步驟如下：

步驟 1：創(chuàng)建技能目錄

通過終端命令創(chuàng)建獨(dú)立的技能文件夾（文件夾名稱建議簡潔，用小寫字母+橫杠，如 my-weather-skill）：

# 1. 創(chuàng)建用戶技能目錄（若不存在則自動創(chuàng)建）
mkdir -p ~/.openclaw/skills/
# 2. 創(chuàng)建具體技能文件夾（以“天氣查詢”技能為例）
mkdir -p ~/.openclaw/skills/my-weather-skill
# 3. 進(jìn)入技能目錄，準(zhǔn)備編寫文件
cd ~/.openclaw/skills/my-weather-skill

步驟 2：編寫核心文件（SKILL.md + 可選代碼）

根據(jù)需求選擇“純文本描述”（新手入門）或“文本描述 + 代碼”（進(jìn)階功能），具體示例見下文。

步驟 3：測試驗(yàn)證

1. 重啟 OpenClaw Gateway（修改 SKILL.md 可無需重啟，系統(tǒng)自動監(jiān)聽；修改代碼必須重啟）；

2. 通過網(wǎng)頁 Dashboard（http://127.0.0.1:18789/）或聊天工具（WhatsApp/Telegram）發(fā)送指令測試；

3. 查看日志排查問題：終端執(zhí)行 openclaw logs，或在 Dashboard 查看“Logs”板塊。

步驟 4：發(fā)布到社區(qū)（可選）

技能測試穩(wěn)定后，可發(fā)布到 ClawHub（OpenClaw 官方技能市場），供其他用戶一鍵安裝。

四、基礎(chǔ)示例：純 SKILL.md 技能（新手入門首選）

無需編寫任何代碼，僅通過 SKILL.md 的自然語言描述即可實(shí)現(xiàn)技能，適合簡單場景（如查詢、指令分發(fā)、固定回復(fù)等）。以下以“全球天氣查詢”技能為例，完整演示開發(fā)過程。

1. 編寫 SKILL.md 文件

在 my-weather-skill 目錄下創(chuàng)建 SKILL.md 文件，內(nèi)容分為“固定元數(shù)據(jù)頭”和“詳細(xì)描述”兩部分：

---
# 固定元數(shù)據(jù)頭（必須，AI 優(yōu)先讀?。?
name: weather-query
description: 查詢?nèi)蛑饕鞘袑?shí)時天氣，支持中文查詢（含溫度、天氣狀況、濕度、風(fēng)力）
version: 1.0.0
author: 你的名字
permissions: 網(wǎng)絡(luò)訪問權(quán)限（用于調(diào)用天氣 API）
---
# Weather Query Skill（技能名稱，可自定義）
## 1. Description（技能詳細(xì)說明）
當(dāng)用戶詢問天氣相關(guān)問題時，使用此技能查詢實(shí)時天氣數(shù)據(jù)，以清晰、友好的中文格式返回結(jié)果，幫助用戶快速了解目標(biāo)城市的天氣情況。
## 2. When to use（觸發(fā)場景：明確 AI 何時調(diào)用此技能）
- 用戶說：“北京今天天氣怎么樣？”
- 用戶說：“上海明天會下雨嗎？”
- 用戶說：“紐約當(dāng)前溫度是多少？”
- 用戶說：“成都后天的天氣預(yù)報”
- 用戶說：“幫我查一下廣州近 3 天的天氣”
## 3. How to use（調(diào)用邏輯：教 AI 如何使用技能）
1. 從用戶消息中提取 2 個核心信息：
   - 目標(biāo)城市（必須，如“北京”“上?！保?；
   - 查詢時間（可選，默認(rèn)“今天”，支持“明天”“后天”）；
2. 調(diào)用內(nèi)置天氣查詢工具（或外部公開天氣 API）獲取數(shù)據(jù)；
3. 整理數(shù)據(jù)并返回，格式要求：
   - 開頭明確“城市 + 時間”（如“北京 2026年2月10日 天氣”）；
   - 核心信息：溫度（默認(rèn)攝氏度）、天氣狀況（晴/雨/多云等）、濕度、風(fēng)力；
   - 結(jié)尾補(bǔ)充溫馨提示（如“今日有雨，建議帶傘”）；
4. 若未提取到城市，主動追問用戶確認(rèn)具體城市。
## 4. Edge cases（邊緣場景：處理異常情況）
- 模糊地點(diǎn)（如“家附近”“公司旁邊”）：回復(fù)“請告訴我具體城市名稱，以便準(zhǔn)確查詢天氣”；
- 未支持城市（如小眾縣城）：回復(fù)“暫不支持該城市的天氣查詢，建議嘗試省會或主要城市”；
- 未來多天查詢（如“深圳近一周天氣”）：優(yōu)先返回未來 3 天概覽，說明“長期預(yù)報精度有限，僅作參考”；
- 無網(wǎng)絡(luò)情況：回復(fù)“當(dāng)前網(wǎng)絡(luò)不可用，無法查詢天氣，請檢查網(wǎng)絡(luò)連接后重試”。

2. 測試純文本技能

1. 確保 OpenClaw Gateway 已啟動（若未啟動，執(zhí)行 openclaw gateway）；

2. 在聊天工具或 Dashboard 發(fā)送測試指令：幫我查一下北京今天的天氣；

3. 驗(yàn)證結(jié)果：若 AI 正確返回天氣信息，說明技能生效；若未調(diào)用，檢查 SKILL.md 中“When to use”場景描述是否清晰，或查看日志排查。

五、進(jìn)階示例：帶 Python 代碼的 Skill（實(shí)現(xiàn)復(fù)雜功能）

對于需要執(zhí)行具體操作（如生成文件、調(diào)用外部 API、操作本地設(shè)備）的技能，需搭配代碼實(shí)現(xiàn)。以下以“生成二維碼”技能為例，演示“SKILL.md + Python 代碼”的完整開發(fā)流程。

1. 創(chuàng)建技能目錄結(jié)構(gòu)

技能目錄需包含核心描述文件和代碼文件，結(jié)構(gòu)如下：

~/.openclaw/skills/generate-qr-code/  # 技能根目錄
├── SKILL.md                     # 核心描述文件（必須）
├── agent.py                     # Python 執(zhí)行邏輯（核心代碼文件）
└── references/                  # 輔助資源文件夾（可選）
    └── example-qr.png           # 示例二維碼圖片（用于說明技能效果）

2. 編寫 SKILL.md（關(guān)聯(lián)代碼邏輯）

---
name: generate-qr-code
description: 生成二維碼/條形碼，支持文本、URL、WiFi 配置等內(nèi)容，可自定義尺寸、顏色并指定保存路徑
version: 1.0.0
author: 你的名字
permissions: 文件寫入權(quán)限（用于保存二維碼圖片）
---
# Generate QR Code Skill（生成二維碼技能）
## 1. Description
當(dāng)用戶需要將文本、URL、WiFi 信息等轉(zhuǎn)換為可視化二維碼時，使用此技能生成二維碼圖片，并保存到指定路徑（默認(rèn)保存到桌面），支持自定義尺寸和顏色。
## 2. When to use
- 用戶說：“幫我把 https://openclaw.ai 生成二維碼”
- 用戶說：“生成一個包含 WiFi 信息的二維碼，名稱：MyWiFi，密碼：12345678”
- 用戶說：“生成黑色二維碼，內(nèi)容是‘Hello OpenClaw’，保存到 D 盤根目錄”
- 用戶說：“幫我做一個 400px 大小的二維碼，內(nèi)容是我的手機(jī)號 13800138000”
## 3. How to use
1. 從用戶消息中提取核心參數(shù)：
   - 必選：生成內(nèi)容（文本/URL/WiFi 信息，WiFi 格式需為“WIFI:S:名稱;T:類型;P:密碼;;”）；
   - 可選：尺寸（默認(rèn) 300px）、顏色（默認(rèn)黑色）、保存路徑（默認(rèn)桌面）；
2. 若用戶未指定可選參數(shù)，使用默認(rèn)值；
3. 調(diào)用 agent.py 中的 generate_qr 函數(shù)執(zhí)行生成操作；
4. 返回結(jié)果：告知用戶二維碼保存路徑，若生成失敗，說明具體原因（如路徑無權(quán)限、內(nèi)容為空）。
## 4. Implementation（代碼關(guān)聯(lián)說明）
- 依賴庫：qrcode（生成二維碼）、Pillow（圖片處理）；
- 核心函數(shù)：async def generate_qr(text: str, size: int = 300, color: str = "black", save_path: str = None)；
- 參數(shù)說明：
  - text：二維碼內(nèi)容（必選）；
  - size：二維碼尺寸（單位 px，默認(rèn) 300）；
  - color：填充顏色（默認(rèn) black，支持英文顏色名或十六進(jìn)制色值，如 #FF0000）；
  - save_path：保存路徑（默認(rèn)桌面，文件名：qr_code.png）。
## 5. Edge cases
- 內(nèi)容為空：回復(fù)“請?zhí)峁┬枰啥S碼的內(nèi)容（如文本、URL、WiFi 信息）”；
- 保存路徑無權(quán)限：回復(fù)“指定路徑無寫入權(quán)限，請更換保存路徑（如桌面）”；
- 未安裝依賴庫：自動嘗試安裝 qrcode 和 Pillow，若安裝失敗，提示用戶手動執(zhí)行“pip install qrcode pillow”；
- 特殊字符內(nèi)容：自動過濾無效字符，確保二維碼可正常識別。

3. 編寫 Python 代碼（agent.py）

實(shí)現(xiàn)生成二維碼的核心邏輯，注意函數(shù)需為 async 異步函數(shù)（適配 OpenClaw 的異步調(diào)度機(jī)制）：

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:
    """
    生成二維碼并保存到指定路徑，返回生成結(jié)果
    參數(shù)：
    text: 二維碼內(nèi)容（必選，文本/URL/WiFi 信息等）
    size: 二維碼尺寸（px，默認(rèn) 300）
    color: 填充顏色（默認(rèn) black，支持英文或十六進(jìn)制色值）
    save_path: 保存路徑（默認(rèn)桌面 qr_code.png）
    """
    # 1. 校驗(yàn)必填參數(shù)
    if not text or text.strip() == "":
        return "生成失敗：請?zhí)峁┬枰啥S碼的內(nèi)容（如文本、URL、WiFi 信息）"
    # 2. 處理默認(rèn)保存路徑（適配 Windows/macOS/Linux 多系統(tǒng)）
    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:
        # 配置二維碼參數(shù)（version：1-40，box_size：方塊大小，border：邊框?qū)挾龋?
        qr = qrcode.QRCode(
            version=1,
            error_correction=qrcode.constants.ERROR_CORRECT_M,  # 中等容錯率（30% 錯誤可識別）
            box_size=10,
            border=4,
        )
        qr.add_data(text.strip())  # 添加二維碼內(nèi)容
        qr.make(fit=True)  # 自動適配內(nèi)容大小
        # 生成圖片并調(diào)整尺寸
        img = qr.make_image(fill_color=color, back_color="white")
        img = img.resize((size, size), Image.Resampling.LANCZOS)  # 高質(zhì)量縮放
        # 確保保存目錄存在（若路徑不存在則創(chuàng)建）
        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提示：若無法找到文件，可復(fù)制路徑到文件管理器直接打開"
    except PermissionError:
        return f"生成失?。簾o權(quán)限寫入指定路徑（{save_path}），請更換保存路徑（如桌面）或提升文件權(quán)限"
    except Exception as e:
        return f"生成失敗：未知錯誤 - {str(e)}"

4. 測試代碼型 Skill

1. 安裝依賴庫（若未自動安裝）：終端執(zhí)行 pip install qrcode pillow；

2. 重啟 OpenClaw Gateway（修改代碼必須重啟）：openclaw gateway restart；

3. 發(fā)送測試指令：幫我生成一個包含 URL https://openclaw.ai 的二維碼，尺寸 400px，顏色紅色，保存到桌面；

4. 驗(yàn)證結(jié)果：查看桌面是否存在二維碼圖片，AI 是否返回成功提示；若失敗，通過 openclaw logs 查看錯誤日志。

六、發(fā)布技能到 ClawHub（社區(qū)共享）

開發(fā)完成的技能可發(fā)布到 OpenClaw 官方社區(qū)技能市場 ClawHub，供全球用戶一鍵安裝。發(fā)布前需確保技能結(jié)構(gòu)完整、無惡意代碼、描述清晰。

1. 發(fā)布前置檢查

• 目錄結(jié)構(gòu)完整：至少包含 SKILL.md，代碼文件（若有）可獨(dú)立運(yùn)行；

• SKILL.md 規(guī)范：元數(shù)據(jù)頭完整，“觸發(fā)場景、調(diào)用邏輯、邊緣情況”描述清晰；

• 權(quán)限說明明確：需在 SKILL.md 中標(biāo)注技能所需權(quán)限（如文件讀寫、網(wǎng)絡(luò)訪問）；

• 無惡意代碼：禁止包含竊取數(shù)據(jù)、破壞設(shè)備、運(yùn)行病毒等惡意邏輯。

2. 執(zhí)行發(fā)布命令

終端中運(yùn)行以下命令，發(fā)布技能到 ClawHub：

# 發(fā)布命令格式
clawhub publish [技能目錄路徑] \
  --slug [技能唯一標(biāo)識] \
  --name [技能展示名稱] \
  --version [版本號] \
  --description [技能簡短描述] \
  --public \
  --author [作者名] \
  --license [開源許可證]
# 示例（發(fā)布“天氣查詢”技能）
clawhub publish ~/.openclaw/skills/my-weather-skill \
  --slug my-weather-query \
  --name "我的天氣查詢技能" \
  --version 1.0.0 \
  --description "支持全球主要城市實(shí)時天氣查詢，中文友好，自動識別查詢場景" \
  --public \
  --author "你的名字" \
  --license MIT

參數(shù)說明：

• --slug：技能唯一標(biāo)識（小寫字母+橫杠，不可重復(fù)，如 my-weather-query）；

• --public：公開技能（所有人可見可安裝），若為私有技能則去掉此參數(shù)；

• --license：推薦使用 MIT 許可證（與 OpenClaw 一致，兼容性更好）。

3. 驗(yàn)證發(fā)布結(jié)果

1. 發(fā)布成功后，終端會返回技能在 ClawHub 的訪問鏈接（如 https://clawhub.com/skills/my-weather-query）；

2. 可通過搜索驗(yàn)證：終端執(zhí)行 clawhub search my-weather-query，若能找到技能則說明發(fā)布成功。

4. 其他用戶安裝你的技能

發(fā)布后，其他用戶僅需執(zhí)行以下命令即可一鍵安裝：

clawhub install my-weather-query  # my-weather-query 是你發(fā)布時的 --slug 參數(shù)

七、實(shí)用開發(fā)技巧 & 避坑指南

1. SKILL.md 編寫技巧：

   • “When to use”部分多舉示例：AI 對具體示例的理解遠(yuǎn)優(yōu)于抽象描述；

   • “How to use”按步驟拆解：用 1、2、3 清晰說明執(zhí)行流程，降低 AI 理解成本；

   • 邊緣場景全覆蓋：提前考慮“用戶輸入模糊”“權(quán)限不足”“網(wǎng)絡(luò)異常”等情況，避免技能執(zhí)行失敗。

2. 代碼開發(fā)避坑：

   • 函數(shù)必須為 async 異步函數(shù)：OpenClaw 基于異步機(jī)制調(diào)度技能，同步函數(shù)會導(dǎo)致阻塞；

   • 適配多系統(tǒng)：文件路徑使用 os.path模塊處理，避免硬編碼（如不直接寫“C:/Desktop”“/Users/xxx/Desktop”）；

   • 添加異常捕獲：用 try-except 捕獲可能的錯誤（如權(quán)限不足、文件不存在），并返回友好提示。

3. 測試技巧：

   • 優(yōu)先用 Dashboard 測試：網(wǎng)頁端日志更清晰，方便排查問題；

   • 強(qiáng)制 AI 顯示思考過程：測試時在指令后添加“請說明你的思考過程”，如“查北京天氣，請說明你的思考過程”，可判斷 AI 是否正確識別技能；

   • 單獨(dú)測試代碼：先脫離 OpenClaw，直接運(yùn)行代碼函數(shù)（如調(diào)用 agent.py 中的 generate_qr），確認(rèn)代碼可獨(dú)立運(yùn)行再集成。

4. 動態(tài)刷新機(jī)制：

   • 修改 SKILL.md：無需重啟 Gateway，系統(tǒng)會自動監(jiān)聽文件變化并刷新；

   • 修改代碼文件（agent.py/index.ts）：必須重啟 Gateway 才能生效。

八、推薦學(xué)習(xí)路徑（新手到進(jìn)階）

1. 入門階段：開發(fā) 1-2 個純 SKILL.md 技能（如“問候語技能”“簡單計算器技能”），熟悉 SKILL.md 的核心結(jié)構(gòu)；

2. 基礎(chǔ)代碼階段：開發(fā)帶 Python/TS 代碼的技能（如“文本文件生成”“本地圖片壓縮”），掌握代碼與 SKILL.md 的關(guān)聯(lián)方式；

3. 進(jìn)階階段：開發(fā)調(diào)用外部 API 的技能（如“股票查詢”“翻譯工具”），學(xué)習(xí)異步請求、API 密鑰安全管理（避免硬編碼）；

4. 社區(qū)學(xué)習(xí)階段：參考 ClawHub 上高下載量技能（如官方內(nèi)置技能），學(xué)習(xí)優(yōu)秀的 SKILL.md 寫法和代碼實(shí)現(xiàn)思路；

5. 發(fā)布階段：將成熟技能發(fā)布到 ClawHub，收集社區(qū)反饋，優(yōu)化技能兼容性和用戶體驗(yàn)。

九、官方參考資源

• OpenClaw 官方 Skill 開發(fā)文檔：https://docs.openclaw.ai/tools/skills

• ClawHub 社區(qū)技能市場：https://clawhub.com（瀏覽優(yōu)秀技能示例）

• OpenClaw GitHub 內(nèi)置技能源碼：https://github.com/openclaw/openclaw/tree/main/skills

• MCP 協(xié)議文檔（技能開發(fā)標(biāo)準(zhǔn)）：https://docs.openclaw.ai/tools/mcp

• 官方 Discord 技能開發(fā)交流區(qū)：https://discord.gg/openclaw（提問、分享經(jīng)驗(yàn)）

十、總結(jié)

OpenClaw 自定義 Skill 開發(fā)的核心優(yōu)勢在于“低門檻 + 高靈活”——無需復(fù)雜的 API 對接，僅通過自然語言描述即可實(shí)現(xiàn)基礎(chǔ)技能，搭配簡單代碼就能擴(kuò)展復(fù)雜功能。對于新手，建議從純 SKILL.md 技能入手，熟悉 AI 對描述的理解邏輯；對于進(jìn)階用戶，可通過代碼集成外部 API、本地設(shè)備操作等能力，打造專屬的“AI 數(shù)字員工”。

開發(fā)技能的關(guān)鍵在于“把 AI 當(dāng)作合作者”，用清晰、詳細(xì)的描述幫它理解你的需求——你描述得越清楚，AI 執(zhí)行得就越精準(zhǔn)。趕緊動手開發(fā)第一個專屬 Skill，解鎖 OpenClaw 的無限可能吧！

到此這篇關(guān)于OpenClaw自定義Skill開發(fā)完整步驟的文章就介紹到這了,更多相關(guān)OpenClaw自定義Skill內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評論