技能（OpenClaw）

OpenClaw 使用相容 AgentSkills 規格的技能資料夾，教導代理如何使用工具。每個技能是一個包含 SKILL.md（含 YAML 前置資料與說明）的目錄。OpenClaw 載入內建技能加上選用的本機覆寫，並在載入時根據環境、設定和二進位檔案是否存在來篩選技能。

位置與優先序

技能從三個地方載入：

內建技能：隨安裝一起出貨（npm 套件或 OpenClaw.app）
受管理/本機技能：~/.openclaw/skills
工作區技能：<workspace>/skills

名稱衝突時的優先序：

<workspace>/skills（最高） → ~/.openclaw/skills → 內建技能（最低）

此外，你可以透過 ~/.openclaw/openclaw.json 的 skills.load.extraDirs 設定額外的技能資料夾（優先序最低）。

每個代理 vs 共享技能

在多代理架構中，每個代理有自己的工作區。這意味著：

每個代理的技能位於該代理專屬的 <workspace>/skills。
共享技能位於 ~/.openclaw/skills（受管理/本機），對同一台機器上的 所有代理可見。
也可以透過 skills.load.extraDirs（優先序最低）加入共享資料夾，讓多個代理使用同一套技能包。

同名技能存在於多個位置時，照常套用優先序：工作區優先，其次受管理/本機，最後內建。

外掛與技能

外掛可以在 openclaw.plugin.json 中列出 skills 目錄（相對於外掛根目錄的路徑）來附帶技能。外掛啟用時載入外掛技能，並參與正常的技能優先序規則。你可以透過外掛設定項目的 metadata.openclaw.requires.config 來控制它們。請參閱外掛了解探索/設定，以及工具了解這些技能教導的工具介面。

ClawHub（安裝與同步）

ClawHub 是 OpenClaw 的公開技能登錄處。瀏覽 https://clawhub.com。用它來探索、安裝、更新和備份技能。完整指南：ClawHub。

常用流程：

安裝技能到你的工作區：
- clawhub install <skill-slug>
更新所有已安裝的技能：
- clawhub update --all
同步（掃描 + 發布更新）：
- clawhub sync --all

預設情況下，clawhub 會安裝到目前工作目錄的 ./skills（或後備至設定的 OpenClaw 工作區）。OpenClaw 在下一個工作階段會將其視為 <workspace>/skills 載入。

安全注意事項

將第三方技能視為不可信賴的程式碼。啟用前請先閱讀其內容。
對於不可信賴的輸入和高風險工具，建議在沙箱中執行。參閱沙箱。
工作區和額外目錄的技能探索，只接受 realpath 解析後仍在設定根目錄內的技能根目錄和 SKILL.md 檔案。
skills.entries.*.env 和 skills.entries.*.apiKey 會在該代理回合中將密鑰注入主機程序（而非沙箱）。請確保密鑰不會出現在提示詞和日誌中。
更廣泛的威脅模型和檢查清單，請參閱安全性。

格式（AgentSkills + Pi 相容）

SKILL.md 至少必須包含：

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
---

注意事項：

我們遵循 AgentSkills 規格的佈局與意圖。
內嵌代理使用的解析器僅支援單行前置資料鍵值。
metadata 應為單行 JSON 物件。
在說明中使用 {baseDir} 來參考技能資料夾路徑。
選填的前置資料鍵值：
- homepage — 在 macOS 技能 UI 中顯示為「網站」的 URL（也支援透過 metadata.openclaw.homepage）。
- user-invocable — true|false（預設：true）。為 true 時，技能會暴露為使用者斜線指令。
- disable-model-invocation — true|false（預設：false）。為 true 時，技能不會加入模型提示詞（仍可透過使用者呼叫使用）。
- command-dispatch — tool（選填）。設為 tool 時，斜線指令繞過模型直接分派到工具。
- command-tool — 當 command-dispatch: tool 設定時要呼叫的工具名稱。
- command-arg-mode — raw（預設）。工具分派時將原始引數字串轉發給工具（不做核心解析）。
  
  工具以以下參數呼叫： { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }。

閘控（載入時篩選）

OpenClaw 使用 metadata（單行 JSON）在載入時篩選技能：

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

metadata.openclaw 下的欄位：

always: true — 永遠包含此技能（跳過其他閘控）。
emoji — macOS 技能 UI 使用的選填表情符號。
homepage — macOS 技能 UI 中顯示為「網站」的選填 URL。
os — 選填的平台清單（darwin、linux、win32）。設定後，技能僅在這些作業系統上有資格。
requires.bins — 清單；每個都必須存在於 PATH 中。
requires.anyBins — 清單；至少一個必須存在於 PATH 中。
requires.env — 清單；環境變數必須存在或在設定中提供。
requires.config — openclaw.json 中必須為 truthy 的路徑清單。
primaryEnv — 與 skills.entries.<name>.apiKey 關聯的環境變數名稱。
install — macOS 技能 UI 使用的選填安裝程式規格陣列（brew/node/go/uv/download）。

關於沙箱的注意事項：

requires.bins 在技能載入時於主機上檢查。
如果代理在沙箱中，二進位檔案也必須存在於容器內。透過 agents.defaults.sandbox.docker.setupCommand（或自訂映像）安裝。 setupCommand 在容器建立後執行一次。套件安裝還需要網路出口、可寫的根檔案系統和容器中的 root 使用者。範例：summarize 技能（skills/summarize/SKILL.md）需要在沙箱容器中有 summarize CLI 才能在其中執行。

安裝程式範例：

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata:
  {
    "openclaw":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gemini-cli",
              "bins": ["gemini"],
              "label": "Install Gemini CLI (brew)",
            },
          ],
      },
  }
---

注意事項：

如果列出多個安裝程式，閘道會選擇一個偏好選項（brew 可用時優先，否則 node）。
如果所有安裝程式都是 download，OpenClaw 會列出每個項目以便你查看可用的成品。
安裝程式規格可包含 os: ["darwin"|"linux"|"win32"] 按平台篩選選項。
Node 安裝遵循 openclaw.json 中的 skills.install.nodeManager（預設：npm；選項：npm/pnpm/yarn/bun）。這只影響技能安裝；閘道執行環境仍應使用 Node （不建議 WhatsApp/Telegram 使用 Bun）。
Go 安裝：如果缺少 go 但有 brew，閘道會先透過 Homebrew 安裝 Go，並盡可能將 GOBIN 設為 Homebrew 的 bin。
Download 安裝：url（必填）、archive（tar.gz | tar.bz2 | zip）、extract（偵測到壓縮檔時預設：auto）、stripComponents、targetDir（預設：~/.openclaw/tools/<skillKey>）。

如果沒有 metadata.openclaw，技能永遠有資格（除非在設定中停用或被 skills.allowBundled 阻擋）。

設定覆寫（`~/.openclaw/openclaw.json`）

內建/受管理的技能可以切換開關並提供環境變數值：

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 也可使用純文字字串
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

注意：如果技能名稱包含連字號，請用引號包裹鍵值（JSON5 允許帶引號的鍵值）。

設定鍵值預設對應技能名稱。如果技能定義了 metadata.openclaw.skillKey，請在 skills.entries 下使用該鍵值。

規則：

enabled: false 停用技能，即使它是內建或已安裝的。
env：僅在變數尚未設定時才注入。
apiKey：為宣告 metadata.openclaw.primaryEnv 的技能提供的便捷設定。支援純文字字串或 SecretRef 物件（{ source, provider, id }）。
config：選填的自訂每技能欄位容器；自訂鍵值必須放在這裡。
allowBundled：僅針對內建技能的選填允許清單。設定後，只有清單中的內建技能才有資格（受管理/工作區技能不受影響）。

環境注入（每個代理回合）

代理回合開始時，OpenClaw 會：

讀取技能中繼資料。
將 skills.entries.<key>.env 或 skills.entries.<key>.apiKey 套用到 process.env。
使用有資格的技能建構系統提示詞。
回合結束後還原原始環境。

這個作用範圍限於代理回合，不是全域 shell 環境。

工作階段快照（效能）

OpenClaw 在工作階段開始時快照有資格的技能，並在同一工作階段的後續回合中重用該清單。技能或設定的變更在下一個新工作階段才會生效。

技能也可以在工作階段中途重新整理（啟用技能監控器或新的有資格遠端節點出現時）。可以把這想成熱重載：重新整理的清單在下一個代理回合時被採用。

遠端 macOS 節點（Linux 閘道）

如果閘道運行在 Linux 上但有一個 macOS 節點已連線且允許 system.run（Exec 審批安全性未設為 deny），OpenClaw 可以在該節點上有所需二進位檔案時，將僅限 macOS 的技能視為有資格。代理應透過 nodes 工具（通常是 nodes.run）執行這些技能。

這依賴節點回報其指令支援能力以及透過 system.run 的二進位檔案探測。如果 macOS 節點稍後離線，技能仍保持可見；在節點重新連線前呼叫可能會失敗。

技能監控器（自動重新整理）

預設情況下，OpenClaw 監控技能資料夾，在 SKILL.md 檔案變更時更新技能快照。透過 skills.load 設定：

{
  skills: {
    load: {
      watch: true,
      watchDebounceMs: 250,
    },
  },
}

Token 影響（技能清單）

技能有資格時，OpenClaw 會將精簡的 XML 可用技能清單注入系統提示詞（透過 pi-coding-agent 中的 formatSkillsForPrompt）。成本是確定性的：

基礎開銷（至少 1 個技能時）： 195 字元。
每個技能： 97 字元 + XML 跳脫後的 <name>、<description> 和 <location> 值長度。

公式（字元數）：

total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))

注意事項：

XML 跳脫會將 & < > " ' 展開為實體（&、< 等），增加長度。
Token 數量因模型 tokenizer 而異。粗略的 OpenAI 風格估計是每 4 字元約 1 token，因此每個技能 97 字元 ≈ 24 token 加上你的實際欄位長度。

受管理技能生命週期

OpenClaw 將一組基礎技能作為內建技能隨安裝一起出貨（npm 套件或 OpenClaw.app）。~/.openclaw/skills 用於本機覆寫（例如固定/修補技能而不更改內建副本）。工作區技能由使用者擁有，在名稱衝突時覆寫兩者。

設定參考

完整設定 schema 請參閱技能設定。

想找更多技能？

瀏覽 https://clawhub.com。

技能（OpenClaw）

位置與優先序

每個代理 vs 共享技能

外掛與技能

ClawHub（安裝與同步）

安全注意事項

格式（AgentSkills + Pi 相容）

閘控（載入時篩選）

設定覆寫（~/.openclaw/openclaw.json）

環境注入（每個代理回合）

工作階段快照（效能）

遠端 macOS 節點（Linux 閘道）

技能監控器（自動重新整理）

Token 影響（技能清單）

受管理技能生命週期

設定參考

想找更多技能？

設定覆寫（`~/.openclaw/openclaw.json`）