​

Skills（OpenClaw）

​

位置與優先順序

1. 內建 Skills：隨安裝一起提供（npm 套件或 OpenClaw.app）
2. 受管／本機 Skills：~/.openclaw/skills
3. 工作區 Skills：<workspace>/skills

​

每代理程式與共用 Skills

• 每代理程式 Skills 僅存在於該代理程式的 <workspace>/skills 中。
• 共用 Skills 存在於 ~/.openclaw/skills（受管／本機），並且 對同一台機器上的所有代理程式可見。
• 若你希望多個代理程式共用同一組 Skills，也可以透過 skills.load.extraDirs 新增共用資料夾（最低優先順序）。

​

外掛程式 + Skills

​

ClawHub（安裝 + 同步）

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

​

安全性注意事項

• 將第三方 Skills 視為不受信任的程式碼。在啟用前請先閱讀。 13. 在啟用之前請先閱讀。
• 對於不受信任的輸入與高風險工具，優先使用沙箱化執行。 15. 請參閱 Sandboxing。
• skills.entries.*.env 與 skills.entries.*.apiKey 會在該代理程式回合中，將祕密注入主機程序（而非沙箱）。請避免在提示詞與記錄中包含祕密。 16. 將祕密排除在提示與日誌之外。
• 更完整的威脅模型與檢查清單，請參閱 Security。

​

格式（AgentSkills + Pi 相容）

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

• 版面配置與意圖遵循 AgentSkills 規範。
• 內嵌代理程式所使用的解析器僅支援單行 frontmatter 金鑰。
• metadata 應為單行 JSON 物件。
• 在說明指示中使用 {baseDir} 來參照 Skill 資料夾路徑。
• 可選的 frontmatter 金鑰：
  • homepage — 在 macOS Skills UI 中顯示為「Website」的 URL（亦支援透過 metadata.openclaw.homepage）。
  • user-invocable — true|false（預設：true）。當為 true 時，Skill 會以使用者斜線指令公開。 17. 當為 true 時，該技能會以使用者斜線指令公開。
  • disable-model-invocation — true|false（預設：false）。當為 true 時，該 Skill 會從模型提示詞中排除（仍可由使用者呼叫）。 當為 true 時，該技能會從模型提示中排除（仍可透過使用者呼叫）。 當為 true 時，該技能會從模型提示中排除（仍可透過使用者呼叫）。
  • command-dispatch — tool（可選）。設為 tool 時，斜線指令會略過模型並直接派送至工具。 command-dispatch — tool（可選）。設為 tool 時，斜線指令會略過模型並直接派送至工具。 When set to tool, the slash command bypasses the model and dispatches directly to a tool.
  • command-tool — 當設定 command-dispatch: tool 時要呼叫的工具名稱。
  • command-arg-mode — raw（預設）。用於工具派送時，會將原始參數字串轉送給工具（不做核心解析）。 2. 對於工具派發，會將原始的 args 字串轉送給工具（不進行核心解析）。 工具會以下列參數被呼叫： { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }。

​

3. 門控（載入時過濾器）

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

• always: true — 永遠包含該 Skill（略過其他閘控）。
• emoji — macOS Skills UI 使用的可選表情符號。
• homepage — macOS Skills UI 中顯示為「Website」的可選 URL。
• os — 可選的平台清單（darwin、linux、win32）。若設定，Skill 僅在這些作業系統上符合資格。 22. 若設定，該技能僅在這些作業系統上符合資格。
• 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 會在 Skill 載入時於主機上檢查。
• 如果代理程式在沙箱中執行，該二進位檔也必須存在於 容器內部。 6. 透過 agents.defaults.sandbox.docker.setupCommand 安裝（或使用自訂映像）。 25. setupCommand 會在容器建立後執行一次。 8. 8. 套件安裝也需要網路對外連線、可寫入的根檔案系統，以及沙盒中的 root 使用者。 Example: the summarize skill (skills/summarize/SKILL.md) needs the summarize CLI in the sandbox container to run there.

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

• If multiple installers are listed, the gateway picks a single preferred option (brew when available, otherwise node).
• 若所有安裝器皆為 download，OpenClaw 會列出每個項目，讓你查看可用的成品。
• 安裝器規格可包含 os: ["darwin"|"linux"|"win32"] 以依平台篩選選項。
• Node 安裝會遵循 skills.install.nodeManager 於 openclaw.json 中的設定（預設：npm；選項：npm/pnpm/yarn/bun）。 這只影響 Skill 安裝；Gateway 閘道器的執行階段仍應使用 Node （不建議在 WhatsApp／Telegram 使用 Bun）。 29. 這只影響技能安裝；Gateway 執行階段仍應為 Node（不建議 WhatsApp/Telegram 使用 Bun）。
• Go 安裝：若缺少 go 且有 brew 可用，Gateway 閘道器會先透過 Homebrew 安裝 Go，並在可行情況下將 GOBIN 設為 Homebrew 的 bin。
• Download 安裝：url（必填）、archive（tar.gz | tar.bz2 | zip）、extract（預設：偵測到封存檔時自動）、stripComponents、targetDir（預設：~/.openclaw/tools/<skillKey>）。

​

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

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

• enabled: false 會停用該 Skill，即使它是內建或已安裝。
• env：僅在該變數尚未於程序中設定時才注入。
• apiKey：為宣告 metadata.openclaw.primaryEnv 的 Skills 提供的便利方式。
• config：可選的自訂每 Skill 欄位容器；自訂金鑰必須放在此處。
• allowBundled：僅適用於內建 Skills 的可選允許清單。若設定，只有清單中的內建 Skills 符合資格（不影響受管／工作區 Skills）。 31. 若設定，僅清單中的隨附技能符合資格（受管/工作區技能不受影響）。

​

環境注入（每次代理程式執行）

1. Reads skill metadata.
2. 將任何 skills.entries.<key>.env 或 skills.entries.<key>.apiKey 套用到 process.env。
3. 以符合資格的 Skills 建立系統提示詞。
4. 在執行結束後還原原始環境。

​

34. 工作階段快照（效能）

37. 當啟用技能監看器或出現新的符合資格的遠端節點時，技能也可在工作階段中途重新整理（見下文）。 當啟用技能監看器或出現新的符合資格的遠端節點時，技能也可在工作階段中途重新整理（見下文）。 Think of this as a hot reload: the refreshed list is picked up on the next agent turn.

​

遠端 macOS 節點（Linux Gateway）

40. 這依賴於節點回報其命令支援，以及透過 system.run 進行的二進位探測。 這依賴於節點回報其命令支援，以及透過 system.run 進行的二進位探測。 If the macOS node goes offline later, the skills remain visible; invocations may fail until the node reconnects.

​

Skills watcher（自動重新整理）

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

​

Token 影響（Skills 清單）

• **基礎負擔（僅在 ≥1 個 Skill 時）：**195 個字元。
• **每個 Skill：**97 個字元 + XML 轉義後的 <name>、<description> 與 <location> 值的長度。

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

• XML 轉義會將 & < > " ' 展開為實體（&、< 等），增加長度。
• Token counts vary by model tokenizer. Token 數量會依模型的 tokenizer 而異。以 OpenAI 風格的粗略估計約為 4 個字元／token，因此97 個字元 ≈ 24 個 token，再加上實際欄位長度。

​

受管 Skills 的生命週期

​

設定參考

​

想找更多 Skills？