OpenClaw 技能管理指南：擴充 Agent 能力與設定優先級

OpenClaw 使用 AgentSkills 相容 的 skill 資料夾來教導 agent 如何使用工具。每個 skill 都是一個目錄，裡面包含一個帶有 YAML frontmatter 和指令的 SKILL.md。OpenClaw 會載入 內建 skills 以及選用的本地覆蓋，並在載入時根據環境、設定和 binary 是否存在進行過濾。

位置與優先順序

OpenClaw 從以下來源載入 skills：

額外的 skill 資料夾：透過 skills.load.extraDirs 設定
內建 skills：隨安裝程式附帶（npm 套件或 OpenClaw.app）
受管理/本地 skills：~/.openclaw/skills
個人 agent skills：~/.agents/skills
專案 agent skills：<workspace>/.agents/skills
Workspace skills：<workspace>/skills

如果 skill 名稱衝突，優先順序如下：

<workspace>/skills（最高）→ <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → 內建 skills → skills.load.extraDirs（最低）

每個 Agent 專屬 vs 共用 Skills

在 多 agent 設定中，每個 agent 都有自己的 workspace。這代表：

每個 Agent 專屬的 skills 放在該 agent 的 <workspace>/skills 中。
專案 agent skills 放在 <workspace>/.agents/skills，會在一般的 workspace skills/ 資料夾之前套用到該 workspace。
個人 agent skills 放在 ~/.agents/skills，會套用到該機器上的所有 workspace。
共用 skills 放在 ~/.openclaw/skills（受管理/本地），對同一台機器上的 所有 agent 都可見。
如果你想讓多個 agent 使用共同的 skills 套件，也可以透過 skills.load.extraDirs（最低優先順序）加入 共用資料夾。

如果同一個 skill 名稱出現在多個地方，會套用一般的優先順序：workspace 優先，接著是專案 agent skills、個人 agent skills、受管理/本地、內建，最後是額外目錄。

Agent Skill 允許清單

Skill 的位置和 skill 的 可見性 是分開控制的。

位置/優先順序決定了同名 skill 中哪一個版本勝出。
Agent 允許清單決定了 agent 實際上可以使用哪些可見的 skills。

你可以使用 agents.defaults.skills 來設定共用的基準，然後在 agents.list[].skills 中針對每個 agent 進行覆蓋：

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

規則如下：

若要預設不限制 skills，請省略 agents.defaults.skills。
若要繼承 agents.defaults.skills，請省略 agents.list[].skills。
若要不使用任何 skills，請將 agents.list[].skills 設為 []。
非空的 agents.list[].skills 清單就是該 agent 的最終集合，它不會與預設值合併。

OpenClaw 會在建構 prompt、skill 斜線指令探索、sandbox 同步和 skill 快照中套用生效的 agent skill 集合。

Plugin 與 Skills

Plugin 可以透過在 openclaw.plugin.json 中列出 skills 目錄（路徑相對於 plugin 根目錄）來提供自己的 skills。當 plugin 被啟用時，這些 plugin skills 就會載入。目前這些目錄會被合併到與 skills.load.extraDirs 相同的低優先順序路徑中，因此同名的內建、受管理、agent 或 workspace skill 會覆蓋它們。你可以透過 plugin 設定項目中的 metadata.openclaw.requires.config 來過濾它們。關於探索與設定請參考 Plugins，關於這些 skills 所教導的工具介面請參考 Tools。

ClawHub (安裝與同步)

ClawHub 是 OpenClaw 的公開技能註冊表。你可以在 https://clawhub.ai 瀏覽。使用原生的 openclaw skills 指令來發現、安裝或更新技能，或者在需要發佈與同步工作流時使用獨立的 clawhub CLI。完整指南：ClawHub。

常見流程：

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

原生的 openclaw skills install 會安裝到目前工作區的 skills/ 目錄下。獨立的 clawhub CLI 也會安裝到你目前工作目錄下的 ./skills（或者回退到配置的 OpenClaw 工作區）。OpenClaw 會在下一次工作階段將其識別為 <workspace>/skills。

安全注意事項

將第三方技能視為不可信的程式碼。在啟用前請先閱讀它們。
對於不可信的輸入和有風險的工具，建議優先使用沙盒執行。參考 Sandboxing。
工作區和額外目錄的技能發現僅接受技能根目錄和 SKILL.md 檔案，且其解析後的真實路徑必須留在配置的根目錄內。
由 Gateway 支援的技能依賴安裝（skills.install、引導流程和技能設定 UI）在執行安裝程式元數據之前，會先執行內建的危險程式碼掃描器。除非呼叫者明確設定了危險覆蓋，否則 critical（嚴重）發現預設會阻斷執行；suspicious（可疑）發現則僅會發出警告。
openclaw skills install <slug> 則不同：它會將 ClawHub 技能資料夾下載到工作區，且不使用上述的安裝程式元數據路徑。
skills.entries.*.env 和 skills.entries.*.apiKey 會將祕鑰注入到該 Agent 輪次的主機程序中（而非沙盒）。請確保祕鑰不會出現在 Prompt 或日誌中。
關於更廣泛的威脅模型和檢查清單，請參考 Security。

格式 (AgentSkills 與 Pi 相容)

SKILL.md 必須至少包含：

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
---

注意事項：

我們遵循 AgentSkills 規範的佈局與意圖。
內嵌 Agent 使用的解析器僅支援單行 frontmatter 鍵值。
metadata 應該是一個單行 JSON 物件。
在指令中使用 {baseDir} 來引用技能資料夾路徑。
選填的 frontmatter 鍵值：
- homepage — 在 macOS Skills UI 中顯示為「網站」的 URL（也支援透過 metadata.openclaw.homepage 設定）。
- user-invocable — true|false（預設為 true）。當為 true 時，該技能會作為使用者的斜線指令公開。
- disable-model-invocation — true|false（預設為 false）。當為 true 時，該技能會從模型 Prompt 中排除（但仍可透過使用者呼叫）。
- 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: image-lab
description: Generate or edit images via a provider-backed image workflow
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

metadata.openclaw 下的欄位：

always: true — 總是包含該技能（跳過其他門控）。
emoji — macOS Skills UI 使用的選填表情符號。
homepage — macOS Skills UI 中顯示為「網站」的選填 URL。
os — 選填的平台列表（darwin, linux, win32）。如果設定，該技能僅在這些作業系統上可用。
requires.bins — 列表；每個項目必須存在於 PATH 中。
requires.anyBins — 列表；至少有一個必須存在於 PATH 中。
requires.env — 列表；環境變數必須存在或在配置中提供。
requires.config — openclaw.json 路徑列表，其值必須為真值。
primaryEnv — 與 skills.entries.<name>.apiKey 關聯的環境變數名稱。
install — macOS Skills UI 使用的選填安裝程式規範陣列（brew/node/go/uv/download）。

關於沙盒的注意事項：

requires.bins 會在技能載入時於主機上檢查。
如果 Agent 被沙盒化，二進位檔案也必須存在於容器內部。請透過 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)",
            },
          ],
      },
  }
---

注意事項：

如果列出了多個安裝程式，Gateway 會選擇單個偏好的選項（可用時優先選擇 brew，否則選擇 node）。
如果所有安裝程式都是 download，OpenClaw 會列出每個項目，以便你查看可用的產物。
安裝程式規範可以包含 os: ["darwin"|"linux"|"win32"] 來按平台過濾選項。
Node 安裝會遵循 openclaw.json 中的 skills.install.nodeManager（預設：npm；選項：npm/pnpm/yarn/bun）。這僅影響技能安裝；Gateway 執行環境仍應為 Node（不建議將 Bun 用於 WhatsApp/Telegram）。
由 Gateway 支援的安裝程式選擇是偏好驅動的，而不僅限於 Node：當安裝規範混合多種類型時，如果啟用了 skills.install.preferBrew 且 brew 存在，OpenClaw 會優先選擇 Homebrew，然後是 uv，接著是配置的 Node 管理器，最後是其他備選方案如 go 或 download。
如果每個安裝規範都是 download，OpenClaw 會顯示所有下載選項，而不是摺疊為一個偏好的安裝程式。
Go 安裝：如果缺少 go 且 brew 可用，Gateway 會先透過 Homebrew 安裝 Go，並在可能的情況下將 GOBIN 設定為 Homebrew 的 bin。
Download 安裝：url（必填）、archive（tar.gz | tar.bz2 | zip）、extract（預設：偵測到壓縮檔時自動執行）、stripComponents、targetDir（預設：~/.openclaw/tools/<skillKey>）。

如果不存在 metadata.openclaw，則該技能始終符合資格（除非在配置中被停用，或被內建技能的 skills.allowBundled 阻斷）。

設定覆蓋 (`~/.openclaw/openclaw.json`)

內建或受管理的技能（skills）可以隨時切換開關，並提供環境變數（env values）：

{
  skills: {
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

注意：如果技能名稱包含連字號（hyphens），請幫 key 加上引號（JSON5 支援引號 key）。

如果你想要在 OpenClaw 內部進行標準的圖片生成或編輯，請使用核心的 image_generate 工具搭配 agents.defaults.imageGenerationModel，而不是用內建技能。這裡的技能範例是給自定義或第三方工作流使用的。

進行原生圖片分析時，請使用 image 工具搭配 agents.defaults.imageModel。原生圖片生成或編輯則使用 image_generate 搭配 agents.defaults.imageGenerationModel。如果你選擇 openai/*、google/*、fal/* 或其他特定供應商的圖片模型，記得也要加上該供應商的認證或 API key。

設定的 key 預設會對應 skill name。如果技能有定義 metadata.openclaw.skillKey，請在 skills.entries 下使用該 key。

規則：

enabled: false：即使技能已內建或安裝，也會將其停用。
env：僅在該變數尚未設定於 process 中時才會注入。
apiKey：為宣告了 metadata.openclaw.primaryEnv 的技能提供便利。支援純文字字串或 SecretRef 物件 ({ source, provider, id })。
config：選填，用於存放每個技能的自定義欄位；自定義 key 必須放在這裡。
allowBundled：選填，僅限內建技能的白名單。如果設定了，則只有清單中的內建技能才符合資格（受管理或工作區技能不受影響）。

環境變數注入（每次 Agent 執行）

當 Agent 開始執行時，OpenClaw 會：

讀取技能元數據（metadata）。
將任何 skills.entries.<key>.env 或 skills.entries.<key>.apiKey 套用到 process.env。
使用符合資格的技能來建立系統提示詞（system prompt）。
在執行結束後恢復原始環境。

這僅限於 Agent 執行的範圍，而不是全域的 shell 環境。

對於內建的 claude-cli 後端，OpenClaw 還會將同樣符合資格的快照實體化為暫時的 Claude Code 插件，並透過 --plugin-dir 傳遞。這樣 Claude Code 就能使用其原生的技能解析器，同時 OpenClaw 依然保有優先權、各 Agent 的白名單、門控（gating）以及 skills.entries.* 的環境變數與 API key 注入。其他的 CLI 後端則僅使用提示詞目錄（prompt catalog）。

會話快照（效能）

OpenClaw 會在會話（session）開始時快照符合資格的技能，並在該會話後續的輪次中重複使用該清單。對技能或設定的更改將在下一個新會話中生效。

當啟用了技能監聽器（skills watcher）或出現新的符合資格的遠端節點時（見下文），技能也可以在會話中途重新整理。你可以把這看作是熱重載（hot reload）：重新整理後的清單會在下一次 Agent 輪次中被採用。

如果該會話的有效 Agent 技能白名單發生變化，OpenClaw 會重新整理快照，讓可見的技能與目前的 Agent 保持一致。

遠端 macOS 節點 (Linux Gateway)

如果 Gateway 執行在 Linux 上，但連接了一個允許 system.run 的 macOS 節點（執行核准安全性未設定為 deny），當該節點上存在所需的二進位檔案時，OpenClaw 可以將僅限 macOS 的技能視為符合資格。Agent 應該透過 exec 工具並設定 host=node 來執行這些技能。

這依賴於節點回報其指令支援情況，以及透過 system.run 進行的二進位檔案探測（bin probe）。如果 macOS 節點稍後離線，技能仍會顯示，但呼叫可能會失敗，直到節點重新連線。

Skills watcher (自動重新整理)

預設情況下，OpenClaw 會監控 skill 資料夾，並在 SKILL.md 檔案變動時更新 skills 快照。你可以在 skills.load 底下進行設定：

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

Token 消耗影響 (skills 列表)

當 skill 符合條件時，OpenClaw 會將可用 skill 的精簡 XML 列表注入到 system prompt 中（透過 pi-coding-agent 裡的 formatSkillsForPrompt 處理）。這部分的消耗是固定的：

基礎開銷（僅在有 1 個以上 skill 時）： 195 個字元。
每個 skill： 97 個字元 + XML 轉義後的 <name>、<description> 和 <location> 數值長度。

計算公式（字元）：

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

注意事項：

XML 轉義會將 & < > " ' 轉換為實體（例如 &, < 等），這會增加長度。
Token 數量取決於模型的 tokenizer。以 OpenAI 風格的粗略估計，大約是 4 個字元換 1 個 token，所以每個 skill 大約是 97 個字元 ≈ 24 tokens，再加上你實際欄位的長度。

託管技能生命週期

OpenClaw 在安裝時（無論是透過 npm package 還是 OpenClaw.app）都會附帶一組基礎的 bundled skills。~/.openclaw/skills 目錄是用來進行本地覆蓋（local overrides）的，例如你想要固定（pinning）或修補（patching）某個技能，但又不想動到原本打包好的副本。Workspace skills 則是由使用者擁有的，如果名稱發生衝突，它們的優先權會高於上述兩者。

設定參考

請參考 Skills config 查看完整的設定結構（schema）。

想要更多技能嗎？

瀏覽 https://clawhub.ai。

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。

OpenClaw 技能管理指南：擴充 Agent 能力與設定優先級

位置與優先順序

每個 Agent 專屬 vs 共用 Skills

Agent Skill 允許清單

Plugin 與 Skills

ClawHub (安裝與同步)

安全注意事項

格式 (AgentSkills 與 Pi 相容)

門控 (載入時過濾)

設定覆蓋 (~/.openclaw/openclaw.json)

環境變數注入（每次 Agent 執行）

會話快照（效能）

遠端 macOS 節點 (Linux Gateway)

Skills watcher (自動重新整理)

Token 消耗影響 (skills 列表)

託管技能生命週期

設定參考

想要更多技能嗎？

相關內容

還是卡住了？

設定覆蓋 (`~/.openclaw/openclaw.json`)