附錄 C：技能開發模板

OpenClaw 的技能（Skill）系統是其核心擴展機制。本附錄提供基於官方信息的技能開發指南。

注意：OpenClaw 官方文檔中技能開發相關內容正在完善中。本附錄基於社區資源和官方 CLI 幫助信息整理。

技能開發概覽

什麼是 Skill？

根據 OpenClaw 官方文檔，Skills 是擴展 OpenClaw 能力的模塊化組件：

添加新的工具（Tools）供 Agent 調用
集成第三方 API 和服務
自定義 Agent 的行爲和響應
實現特定的業務邏輯

Skills vs Tools

根據官方說明：

Tools（工具）：決定 OpenClaw 能不能做某類動作（"手腳"和"權限開關"）
Skills（技能）：給 OpenClaw 增加特殊能力的"小程序"或"插件"

技能類型

OpenClaw 支持三種類型的技能：

Bundled Skills（捆綁技能）：隨 OpenClaw 安裝的內置技能（優先級最低）
Managed Skills（託管技能）：安裝在 ~/.openclaw/skills 的技能
Workspace Skills（工作空間技能）：工作空間目錄下 <workspace>/skills/ 的技能（優先級最高）

一、技能管理 CLI

查看技能

bash

# 列出所有可用技能
openclaw skills list

# 僅顯示就緒的技能
openclaw skills list --eligible

# 顯示詳細信息（包括缺失的需求）
openclaw skills list -v

# JSON 格式輸出
openclaw skills list --json

查看技能詳情

bash

openclaw skills info <skill-name>

檢查技能狀態

bash

openclaw skills check

通過 ClawHub 管理技能

bash

# 搜索、安裝和同步技能
npx clawhub

二、技能配置

在配置中啓用技能

編輯 ~/.openclaw/openclaw.json：

json5

{
  skills: {
    entries: {
      "skill-name": {
        enabled: true,
        // 技能特定的配置
        apiKey: {
          source: "env",
          provider: "default",
          id: "SKILL_API_KEY"
        }
      }
    }
  }
}

使用 SecretRef 配置憑證

json5

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey"
        }
      }
    }
  }
}

支持的 source 類型：

env：從環境變量讀取
file：從文件讀取
exec：從命令執行輸出讀取

三、工作空間技能開發

工作空間技能目錄

工作空間技能位於 Agent 的工作空間目錄中：

~/.openclaw/workspace/
└── skills/
    ├── my-skill/
    │   ├── SKILL.md       # 技能定義文件（YAML frontmatter + Markdown 指令）
    │   └── ...             # 其他輔助文件

SKILL.md 結構

每個技能是一個包含 SKILL.md 文件的目錄。SKILL.md 使用 YAML frontmatter 聲明元數據，後面跟 Markdown 格式的指令：

markdown

---
name: my-skill
description: 技能描述（這是最重要的字段，決定 AI 何時調用此技能）
user-invocable: true
disable-model-invocation: false
metadata:
  openclaw:
    requires:
      env:
        - MY_API_KEY
      bins:
        - curl
---

# 技能指令

這裏寫 Markdown 格式的技能指令，告訴 AI 如何使用這個技能。

可以用 `{baseDir}` 引用技能所在目錄。

YAML Frontmatter 字段說明：

字段	必填	說明
`name`	是	技能標識符
`description`	是	技能描述，AI 根據此決定何時調用
`user-invocable`	否	是否可通過斜槓命令調用（默認 true）
`disable-model-invocation`	否	是否從模型提示中排除（默認 false）
`metadata.openclaw.requires.env`	否	需要的環境變量
`metadata.openclaw.requires.bins`	否	需要的系統命令
`metadata.openclaw.requires.config`	否	需要的配置路徑

技能開發步驟

創建工作空間技能目錄

bash

mkdir -p ~/.openclaw/workspace/skills/my-skill
cd ~/.openclaw/workspace/skills/my-skill

創建 SKILL.md

markdown

---
name: hello-world
description: 一個簡單的示例技能，當用戶說 hello 或 hi 時觸發
---

# Hello World 技能

當用戶打招呼時，回覆一段友好的歡迎語。

驗證技能

bash

openclaw skills check
openclaw skills info hello-world

測試技能 通過聊天界面發送觸發關鍵詞，測試技能是否正常工作。

四、技能最佳實踐

1. 命名規範

使用小寫字母和連字符： ✅ my-awesome-skill ❌ MyAwesomeSkill ❌ my_awesome_skill

2. 版本控制

遵循語義化版本規範（SemVer）：

MAJOR.MINOR.PATCH
例如：1.2.3

3. 配置安全

使用 SecretRef 存儲敏感信息
不要將 API 密鑰硬編碼在 SKILL.md 中
使用環境變量或文件存儲憑證

4. 錯誤處理

提供清晰的錯誤信息
優雅處理 API 失敗情況
記錄調試信息

5. 文檔編寫

每個技能應包含：

SKILL.md：技能定義文件（frontmatter 元數據 + Markdown 指令）
可選的輔助文件（腳本、配置模板等）

五、技能開發工具

使用內置的 skill-creator

OpenClaw 內置了 skill-creator 技能，可以幫助創建新技能：

bash

# 查看內置技能
openclaw skills list --built-in

# 使用 skill-creator（通過聊天界面）
# 發送消息：幫我創建一個天氣查詢技能

插件開發

對於更復雜的擴展，可以開發插件：

bash

# 列出插件
openclaw plugins list

# 安裝插件
openclaw plugins install <path|.tgz|npm-spec>

# 啓用/禁用插件
openclaw plugins enable <id>
openclaw plugins disable <id>

# 插件診斷
openclaw plugins doctor

六、技能發佈

發佈到 ClawHub

準備技能包

bash

# 確保包含所有必要文件
my-skill/
├── SKILL.md
└── ...

提交到 ClawHub
- 訪問 clawhub.ai
- 按照提交指南上傳技能

本地共享

bash

# 打包技能
tar -czf my-skill.tgz my-skill/

# 分享給其他用戶
# 其他用戶安裝：
openclaw plugins install ./my-skill.tgz

七、故障排查

技能無法加載

bash

# 檢查技能狀態
openclaw skills check

# 查看詳細信息
openclaw skills info <skill-name> -v

# 檢查網關日誌
openclaw logs

技能配置錯誤

bash

# 驗證配置
openclaw config validate

# 查看配置
openclaw config get skills.entries.<skill-name>

技能權限問題

確保技能文件有正確的權限：

bash

chmod 755 ~/.openclaw/workspace/skills/my-skill/

八、參考資源

官方資源

社區資源

九、實戰案例：tavily-search 技能解析

以 ClawHub 上的 tavily-search（v1.0.0）爲例，看一個真實技能的完整結構。這是一個通過 Tavily API 爲 AI Agent 提供網絡搜索能力的技能。

目錄結構

tavily-search-1.0.0/
├── SKILL.md           # 技能定義（frontmatter + 使用說明）
├── _meta.json         # ClawHub 發佈元數據
└── scripts/
    ├── search.mjs     # 網絡搜索實現
    └── extract.mjs    # 網頁內容提取實現

SKILL.md 完整內容

markdown

---
name: tavily
description: AI-optimized web search via Tavily API. Returns concise, relevant results for AI agents.
homepage: https://tavily.com
metadata: {"clawdbot":{"emoji":"🔍","requires":{"bins":["node"],"env":["TAVILY_API_KEY"]},"primaryEnv":"TAVILY_API_KEY"}}
---

# Tavily Search

AI-optimized web search using Tavily API. Designed for AI agents - returns clean, relevant content.

## Search

```bash
node {baseDir}/scripts/search.mjs "query"
node {baseDir}/scripts/search.mjs "query" -n 10
node {baseDir}/scripts/search.mjs "query" --deep
node {baseDir}/scripts/search.mjs "query" --topic news
```

## Options

- `-n <count>`: Number of results (default: 5, max: 20)
- `--deep`: Use advanced search for deeper research (slower, more comprehensive)
- `--topic <topic>`: Search topic - `general` (default) or `news`
- `--days <n>`: For news topic, limit to last n days

## Extract content from URL

```bash
node {baseDir}/scripts/extract.mjs "https://example.com/article"
```

Notes:
- Needs `TAVILY_API_KEY` from https://tavily.com
- Tavily is optimized for AI - returns clean, relevant snippets
- Use `--deep` for complex research questions
- Use `--topic news` for current events

解析要點

1. Frontmatter 設計

字段	值	作用
`name`	`tavily`	技能標識符，用戶通過 `clawhub install tavily-search` 安裝後以此名稱識別
`description`	`AI-optimized web search...`	AI 根據這段描述判斷何時調用此技能——寫清楚"做什麼"很關鍵
`homepage`	`https://tavily.com`	指向服務官網，方便用戶註冊獲取 API Key
`metadata.requires.bins`	`["node"]`	聲明需要 Node.js 運行時，OpenClaw 會在技能加載時檢查
`metadata.requires.env`	`["TAVILY_API_KEY"]`	聲明需要環境變量，未設置時技能標記爲"不可用"而非報錯
`metadata.primaryEnv`	`TAVILY_API_KEY`	告訴 OpenClaw 配置嚮導該提示用戶填哪個 Key

2. 腳本設計模式

search.mjs 的核心邏輯（約 100 行）：

javascript

// 1. 解析命令行參數
const query = args[0];
let n = 5, searchDepth = "basic", topic = "general";

// 2. 讀取環境變量中的 API Key
const apiKey = (process.env.TAVILY_API_KEY ?? "").trim();
if (!apiKey) { console.error("Missing TAVILY_API_KEY"); process.exit(1); }

// 3. 調用 Tavily API
const resp = await fetch("https://api.tavily.com/search", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ api_key: apiKey, query, search_depth: searchDepth, ... }),
});

// 4. 格式化輸出爲 Markdown（AI 友好的格式）
if (data.answer) console.log("## Answer\n" + data.answer);
for (const r of results) {
  console.log(`- **${r.title}** (relevance: ${(r.score * 100).toFixed(0)}%)`);
  console.log(`  ${r.url}`);
}

關鍵設計原則：

輸出 Markdown 格式：AI Agent 能直接解析結構化結果
參數校驗前置：缺少 API Key 時 process.exit(1) 而非拋異常，讓 OpenClaw 能捕獲並提示用戶
結果截斷：content.slice(0, 300) 避免輸出過長影響 Agent 上下文窗口
{baseDir} 變量：SKILL.md 中用 {baseDir} 引用技能目錄，OpenClaw 運行時自動替換爲實際路徑

3. 配置方式

用戶安裝後，在 openclaw.json 中配置 API Key：

json

{
  "skills": {
    "entries": {
      "tavily": {
        "enabled": true
      }
    }
  },
  "env": {
    "TAVILY_API_KEY": "tvly-你的密鑰"
  }
}

或直接設置環境變量：export TAVILY_API_KEY=tvly-你的密鑰

十、技能開發清單

開發技能前，確保完成以下檢查：

[ ] SKILL.md frontmatter 包含 name 和 description
[ ] description 清晰描述觸發條件（AI 靠這個決定何時調用）
[ ] 環境變量需求在 metadata.requires.env 中聲明
[ ] 系統命令依賴在 metadata.requires.bins 中聲明
[ ] 腳本輸出 Markdown 格式（對 AI 友好）
[ ] 敏感信息使用環境變量或 SecretRef，不硬編碼
[ ] 錯誤處理完善（缺少 Key 時 exit(1)，API 失敗時輸出清晰錯誤）
[ ] 在本地測試通過（openclaw skills check + 實際對話測試）

提示：OpenClaw 的技能系統正在快速發展中，建議關注官方文檔和 GitHub 倉庫獲取最新信息。更多技能示例可在 ClawHub 瀏覽。

附錄 C：技能開發模板 ​

技能開發概覽 ​

什麼是 Skill？ ​

Skills vs Tools ​

技能類型 ​

一、技能管理 CLI ​

查看技能 ​

查看技能詳情 ​

檢查技能狀態 ​

通過 ClawHub 管理技能 ​

二、技能配置 ​

在配置中啓用技能 ​

使用 SecretRef 配置憑證 ​

三、工作空間技能開發 ​

工作空間技能目錄 ​

SKILL.md 結構 ​

技能開發步驟 ​

四、技能最佳實踐 ​

1. 命名規範 ​

2. 版本控制 ​

3. 配置安全 ​

4. 錯誤處理 ​

5. 文檔編寫 ​

五、技能開發工具 ​

使用內置的 skill-creator ​

插件開發 ​

六、技能發佈 ​

發佈到 ClawHub ​

本地共享 ​

七、故障排查 ​

技能無法加載 ​

技能配置錯誤 ​

技能權限問題 ​

八、參考資源 ​

官方資源 ​

社區資源 ​

九、實戰案例：tavily-search 技能解析 ​

目錄結構 ​

SKILL.md 完整內容 ​

解析要點 ​

十、技能開發清單 ​

附錄 C：技能開發模板

技能開發概覽

什麼是 Skill？

Skills vs Tools

技能類型

一、技能管理 CLI

查看技能

查看技能詳情

檢查技能狀態

通過 ClawHub 管理技能

二、技能配置

在配置中啓用技能

使用 SecretRef 配置憑證

三、工作空間技能開發

工作空間技能目錄

SKILL.md 結構

技能開發步驟

四、技能最佳實踐

1. 命名規範

2. 版本控制

3. 配置安全

4. 錯誤處理

5. 文檔編寫

五、技能開發工具

使用內置的 skill-creator

插件開發

六、技能發佈

發佈到 ClawHub

本地共享

七、故障排查

技能無法加載

技能配置錯誤

技能權限問題

八、參考資源

官方資源

社區資源

九、實戰案例：tavily-search 技能解析

目錄結構

SKILL.md 完整內容

解析要點

十、技能開發清單