Skills

Skills 是 Markdown 指示檔案，用來教導代理程式應如何以及何時使用工具。每個 Skill 都位於一個目錄中，其中包含具有 YAML frontmatter 與 Markdown 內文的 SKILL.md 檔案。OpenClaw 會載入內建 Skills 與任何本機覆寫項目，並在載入時根據環境、設定及二進位檔是否存在進行篩選。

建立 Skills

從零開始建立並測試自訂 Skill。

Skill 工作坊

審查並核准代理程式草擬的 Skill 提案。

Skills 設定

完整的 skills.* 設定結構描述與代理程式允許清單。

ClawHub

瀏覽並安裝社群 Skills。

載入順序

OpenClaw 會從下列來源載入，並以優先順序最高者為先。當相同的 Skill 名稱出現在多個位置時，以優先順序最高的來源為準。

優先順序	來源	路徑
1 — 最高	工作區 Skills	`<workspace>/skills`
2	專案代理程式 Skills	`<workspace>/.agents/skills`
3	個人代理程式 Skills	`~/.agents/skills`
4	受管理／本機 Skills	`~/.openclaw/skills`
5	內建 Skills	隨安裝項目提供
6 — 最低	額外目錄	`skills.load.extraDirs` + 外掛 Skills

Skill 根目錄支援分組式配置。只要在已設定的根目錄下任何位置（最多深入 6 層）出現 SKILL.md，OpenClaw 就會探索該 Skill：

<workspace>/skills/research/SKILL.md          ✓ 找到，名稱為 "research"
<workspace>/skills/personal/research/SKILL.md ✓ 也找到，名稱為 "research"

資料夾路徑僅用於組織。Skill 的名稱與斜線命令來自 name frontmatter 欄位（若缺少 name，則使用目錄名稱）。代理程式允許清單（如下）也會比對此 name。

Codex 命令列介面的原生 $CODEX_HOME/skills 目錄不是 OpenClaw Skill 根目錄。使用 openclaw migrate plan codex 盤點這些 Skills，然後使用 openclaw migrate codex 將它們複製到你的 OpenClaw 工作區。

節點託管的 Skills

已連線的無頭節點可發布其作用中 OpenClaw Skills 目錄中安裝的 Skills（預設為 ~/.openclaw/skills；會套用設定檔環境覆寫）。節點連線時，它們會出現在一般代理程式 Skill 清單中，中斷連線時則會消失。發生名稱衝突時，本機或閘道 Skill 會保留其名稱；節點 Skill 則會獲得具有確定性的節點前綴名稱。節點託管 v1 要求目錄名稱必須與 Skill 的 name frontmatter 欄位相符。 Skill 項目包含節點定位器。其檔案、相對參照與二進位檔都位於節點上，因此請使用 exec host=node node=<node-id> 載入並執行。變更 Skill 檔案後，請重新啟動節點主機。配對與關閉開關請參閱節點。

各代理程式專用與共用 Skills

在多代理程式設定中，每個代理程式都有自己的工作區。請使用符合所需可見範圍的路徑：

範圍	路徑	可見對象
各代理程式專用	`<workspace>/skills`	僅該代理程式
專案代理程式	`<workspace>/.agents/skills`	僅該工作區的代理程式
個人代理程式	`~/.agents/skills`	此機器上的所有代理程式
共用受管理	`~/.openclaw/skills`	此機器上的所有代理程式
額外目錄	`skills.load.extraDirs`	此機器上的所有代理程式

代理程式允許清單

Skill 的位置（優先順序）與 Skill 的可見性（哪些代理程式可以使用它）是各自獨立的控制項。使用允許清單限制代理程式能看到哪些 Skills，而不受其載入來源影響。

{
  agents: {
    defaults: {
      skills: ["github", "weather"], // 共用基準
    },
    list: [
      { id: "writer" }, // 繼承 github、weather
      { id: "docs", skills: ["docs-search"] }, // 完全取代預設值
      { id: "locked-down", skills: [] }, // 無 Skills
    ],
  },
}

允許清單規則

省略 agents.defaults.skills，預設不限制所有 Skills。
省略 agents.entries.*.skills，以繼承 agents.defaults.skills。
將 agents.entries.*.skills: [] 設定為不向該代理程式提供任何 Skills。
非空的 agents.entries.*.skills 清單是最終集合，不會與預設值合併。
有效的允許清單會套用至提示詞建構、斜線命令探索、沙箱同步及 Skill 快照。
這不是主機 Shell 的授權邊界。如果同一個代理程式可以使用 exec，請另外使用沙箱、作業系統使用者隔離、exec 拒絕／允許清單，以及每項資源的認證資訊來限制該 Shell。

外掛與 Skills

外掛可以在 openclaw.plugin.json 中列出 skills 目錄（相對於外掛根目錄的路徑），藉此隨附自己的 Skills。外掛啟用時會載入外掛 Skills，例如瀏覽器外掛隨附 browser-automation Skill，可進行多步驟瀏覽器控制。外掛 Skill 目錄會在與 skills.load.extraDirs 相同的低優先順序層級合併，因此名稱相同的內建、受管理、代理程式或工作區 Skill 會覆寫它們。與任何其他 Skill 相同，可透過其 frontmatter 中的 metadata.openclaw.requires 控制外掛 Skill 本身是否符合使用資格。如需完整外掛系統，請參閱外掛與工具。

Skill 工作坊

Skill 工作坊是代理程式與你作用中 Skill 檔案之間的提案佇列。當代理程式發現可重複使用的工作時，會草擬提案，而不是直接寫入 SKILL.md。任何內容變更前，都必須由你審查並核准。

openclaw skills workshop list
openclaw skills workshop inspect <proposal-id>
openclaw skills workshop apply <proposal-id>

如需完整生命週期、命令列介面參考資料與設定，請參閱 Skill 工作坊。

從 ClawHub 安裝

ClawHub 是公開的 Skills 登錄檔。使用 openclaw skills 命令進行安裝與更新，或使用 clawhub 命令列介面進行發布與同步。

動作	命令
將 Skill 安裝到工作區	`openclaw skills install @owner/<slug>`
從 Git 儲存庫安裝	`openclaw skills install git:owner/repo@ref`
安裝本機 Skill 目錄	`openclaw skills install ./path/to/skill --as my-tool`
為所有本機代理程式安裝	`openclaw skills install @owner/<slug> --global`
更新所有工作區 Skills	`openclaw skills update --all`
更新共用受管理的 Skill	`openclaw skills update @owner/<slug> --global`
更新所有共用受管理的 Skills	`openclaw skills update --all --global`
驗證 Skill 的信任範圍	`openclaw skills verify @owner/<slug>`
輸出產生的 Skill 卡片	`openclaw skills verify @owner/<slug> --card`
透過 ClawHub 命令列介面發布／同步	`clawhub sync --all`

安裝詳細資訊

openclaw skills install 預設會安裝到作用中工作區的 skills/ 目錄。加入 --global 可安裝到共用的 ~/.openclaw/skills 目錄；除非代理程式允許清單限縮範圍，否則所有本機代理程式均可看到。Git 與本機安裝預期來源根目錄中存在 SKILL.md。若 SKILL.md frontmatter 的 name 有效，Slug 會取自該值，否則回退使用目錄或儲存庫名稱。使用 --as <slug> 可覆寫。 openclaw skills update 僅追蹤 ClawHub 安裝項目；若要重新整理 Git 或本機來源，請重新安裝。

驗證與安全性掃描

openclaw skills verify @owner/<slug> 會向 ClawHub 要求 Skill 的 clawhub.skill.verify.v1 信任範圍。已安裝的 ClawHub Skills 會依據 .clawhub/origin.json 中記錄的版本與登錄檔進行驗證。現有已安裝或無歧義的 Skills 仍可使用單獨的 Slug，但包含擁有者的參照可避免發布者身分產生歧義。ClawHub Skill 頁面會在安裝前顯示最新的安全性掃描狀態，並提供 VirusTotal、ClawScan 與靜態分析的詳細資訊頁面。當 ClawHub 將驗證標記為失敗時，該命令會以非零狀態結束。發布者可透過 ClawHub 儀表板或 clawhub skill rescan @owner/<slug> 處理誤判。

私人封存檔安裝

需要透過 ClawHub 以外方式傳遞的閘道用戶端，可以使用 skills.upload.begin、skills.upload.chunk 與 skills.upload.commit 暫存 ZIP 格式的 Skill 封存檔，然後使用 skills.install({ source: "upload", ... }) 安裝。此路徑預設關閉，且需要在 openclaw.json 中設定 skills.install.allowUploadedArchives: true。一般 ClawHub 安裝完全不需要此設定。

安全性

將第三方 Skills 視為不受信任的程式碼。啟用前請先閱讀。對於不受信任的輸入和高風險工具，請優先使用沙箱執行。代理程式端控制項請參閱沙箱。

路徑限制

工作區、專案代理程式及額外目錄的 Skill 探索，只接受解析後的 realpath 仍位於已設定根目錄內的 Skill 根目錄，除非 skills.load.allowSymlinkTargets 明確信任某個目標根目錄。僅在啟用 skills.workshop.allowSymlinkTargetWrites 時，Skill 工作坊才會透過這些受信任的目標寫入。受管理的 ~/.openclaw/skills 與個人的 ~/.agents/skills 可以包含符號連結的 Skill 資料夾，但每個 SKILL.md 的 realpath 仍必須位於其解析後的 Skill 目錄內。

操作員安裝政策

設定 security.installPolicy，在繼續安裝 Skill 前執行受信任的本機政策命令。該政策會接收中繼資料與暫存的來源路徑，適用於 ClawHub、上傳、Git、本機、更新及相依套件安裝程式路徑；當命令無法傳回有效決策時，會採取封閉式失敗。

密鑰注入範圍

skills.entries.*.env 與 skills.entries.*.apiKey 只會在該次代理程式執行期間，將密鑰注入主機程序，而不會注入沙箱。請勿在提示詞和日誌中包含密鑰。

如需更廣泛的威脅模型與安全性檢查清單，請參閱安全性。

SKILL.md 格式

每個 Skill 的 frontmatter 至少需要 name 與 description：

---
name: image-lab
description: 透過由供應商支援的影像工作流程產生或編輯影像
---

當使用者要求產生影像時，使用 `image_generate` 工具……

OpenClaw 遵循 AgentSkills 規格。Frontmatter 會先以 YAML 剖析；若失敗，則回退至僅支援單行的剖析器。巢狀 metadata 區塊（包括多行 YAML 對應）會攤平成 JSON 字串，再以 JSON5 重新剖析，因此條件控管中顯示的區塊形式可正常運作。在內文中使用 {baseDir} 參照 Skill 資料夾路徑。

選用的 frontmatter 鍵

string

在 macOS Skills 使用者介面中顯示為 “Website” 的 URL。也可透過 metadata.openclaw.homepage 支援。

boolean

預設值:"true"

當 true 時，該 Skill 會公開為使用者可叫用的斜線命令。

boolean

預設值:"false"

當 true 時，OpenClaw 不會將該 Skill 的指示納入代理程式的一般提示詞。若 user-invocable 同時為 true，該 Skill 仍可作為斜線命令使用。

"tool"

設為 tool 時，斜線命令會略過模型，並直接分派給已註冊的工具。

string

設定 command-dispatch: tool 時要叫用的工具名稱。

"raw"

預設值:"raw"

對於工具分派，會將原始引數字串轉送給工具，不進行任何核心解析。工具會收到 { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }。

門檻條件

OpenClaw 會在載入時使用 metadata.openclaw 篩選 Skills（嵌入 frontmatter 中的 JSON5 物件；請參閱上方的剖析說明）。沒有 metadata.openclaw 區塊的 Skill 一律符合資格，除非遭到明確停用。

---
name: image-lab
description: 透過供應商支援的影像工作流程產生或編輯影像
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

boolean

當 true 時，一律納入該 Skill，並略過所有其他門檻條件。

string

顯示於 macOS Skills UI 中的選用表情符號。

string

在 macOS Skills UI 中顯示為 “Website” 的選用 URL。

("darwin" | "linux" | "win32")[]

平台篩選器。設定後，該 Skill 僅在列出的作業系統上符合資格。

string[]

每個二進位檔都必須存在於 PATH。

string[]

至少一個二進位檔必須存在於 PATH。

string[]

每個環境變數都必須存在於處理程序中，或透過設定提供。

string[]

每個 openclaw.json 路徑都必須為真值。

string

與 skills.entries.<name>.apiKey 關聯的環境變數名稱。

object[]

macOS Skills UI 使用的選用安裝程式規格（brew / node / go / uv / download）。

當缺少 metadata.openclaw 時，仍會接受舊版 metadata.clawdbot 區塊，因此較早安裝的 Skills 會保留其相依性門檻與安裝程式提示。新的 Skills 應使用 metadata.openclaw。

安裝程式規格

安裝程式規格會告知 macOS Skills UI 如何安裝相依性：

---
name: gemini
description: 使用 Gemini CLI 取得程式設計協助及執行 Google 搜尋查詢。
metadata:
  {
    "openclaw":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gemini-cli",
              "bins": ["gemini"],
              "label": "安裝 Gemini CLI (brew)",
            },
          ],
      },
  }
---

安裝程式選擇規則

列出多個安裝程式時，閘道會選擇一個偏好的選項（可用時選擇 brew，否則選擇 node）。
如果所有安裝程式都是 download，OpenClaw 會列出每個項目，讓你可以查看所有可用的成品。
規格可包含 os: ["darwin"|"linux"|"win32"]，以依平台篩選。
Node 安裝會採用 openclaw.json 中的 skills.install.nodeManager （預設：npm；選項：npm / pnpm / yarn / bun）。這只會影響 Skill 安裝；閘道執行階段仍應使用 Node。
閘道安裝程式偏好順序：Homebrew → uv → 已設定的 node 管理程式 → go → download。

各安裝程式詳細資訊

Homebrew： OpenClaw 不會自動安裝 Homebrew，也不會將 brew 公式轉換為系統套件命令。在沒有 brew 的 Linux 容器中，只支援 brew 的安裝程式會被隱藏；請使用自訂映像或手動安裝相依性。
Go： OpenClaw 的自動 Skill 安裝需要 Go 1.21 或更新版本。如果缺少 go 且 Homebrew 可用，OpenClaw 會先透過 Homebrew 安裝 Go；在沒有 Homebrew 的 Linux 上，若重新整理後的 golang-go 候選版本符合最低版本要求，則可改以 root 身分或透過免密碼的 sudo 使用 apt-get。相依性的實際 go install 一律以 OpenClaw 管理的專用 bin 目錄為目標（全新安裝時為 Homebrew 的 bin，否則為 ~/.local/bin），而不是你設定的 GOBIN；系統會讀取你自己的 GOBIN、GOPATH 和 GOTOOLCHAIN 環境變數，但絕不覆寫。
下載： url（必要）、archive（tar.gz | tar.bz2 | zip）、 extract（預設：偵測到封存檔時為 auto）、stripComponents、 targetDir（預設：~/.openclaw/tools/<skillKey>）。

沙箱化注意事項

載入 Skill 時，會在主機上檢查 requires.bins。如果代理程式在沙箱中執行，二進位檔也必須存在於容器內部。請透過 agents.defaults.sandbox.docker.setupCommand 或自訂映像安裝。setupCommand 會在容器建立後執行一次，並需要網路輸出、可寫入的根檔案系統，以及沙箱中的 root 使用者。

設定覆寫

在 ~/.openclaw/openclaw.json 的 skills.entries 下切換及設定隨附或受管理的 Skills：

{
  skills: {
    entries: {
      "image-lab": {
        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 },
    },
  },
}

boolean

false 會停用該 Skill，即使它是隨附或已安裝的 Skill。隨附的 coding-agent Skill 採選擇加入制——請設定 skills.entries.coding-agent.enabled: true，並確保已安裝且驗證 claude、codex、opencode 或其他受支援的命令列介面其中之一。

string | { source, provider, id }

適用於宣告 metadata.openclaw.primaryEnv 的 Skills 的便利欄位。支援純文字字串或 SecretRef 物件。

Record<string, string>

為代理程式執行注入的環境變數。僅在該變數尚未於處理程序中設定時注入。

object

用於每個 Skill 自訂設定欄位的選用集合。

string[]

僅適用於隨附 Skills 的選用允許清單。設定後，只有清單中的隨附 Skills 符合資格。受管理及工作區 Skills 不受影響。

設定鍵預設會與 Skill 名稱相符。如果 Skill 定義了 metadata.openclaw.skillKey，請改用 skills.entries 下的該鍵。請將含連字號的名稱加上引號：JSON5 允許加引號的鍵。

環境注入

代理程式開始執行時，OpenClaw 會：

讀取 Skill 中繼資料

OpenClaw 會解析代理程式的有效 Skill 清單，並套用門檻規則、允許清單及設定覆寫。

注入環境變數和 API 金鑰

在執行期間，會將 skills.entries.<key>.env 和 skills.entries.<key>.apiKey 套用至 process.env。

建立系統提示詞

符合資格的 Skills 會編譯成精簡的 XML 區塊，並注入系統提示詞。

還原環境

執行結束後，會還原原始環境。

環境變數注入僅限於主機代理程式執行，而非沙箱。在沙箱內，env 和 apiKey 不會生效。請參閱 Skills 設定，瞭解如何將密鑰傳入沙箱化執行。

對於隨附的 claude-cli 後端，OpenClaw 也會將相同的合格 Skill 快照具體化為暫時的 Claude Code 外掛，並透過 --plugin-dir 傳入。其他命令列介面後端僅使用提示詞目錄。

快照與重新整理

OpenClaw 會在工作階段開始時建立符合資格的 Skills 快照，並在該工作階段的所有後續輪次中重複使用該清單。Skills 或設定的變更會在下一個新工作階段生效。在兩種情況下，Skills 會在工作階段期間重新整理：

Skills 監看器偵測到 SKILL.md 變更。
新的合格遠端節點連線。

重新整理後的清單會在代理程式下一輪採用。如果有效的代理程式允許清單發生變更，OpenClaw 會重新整理快照，確保可見的 Skills 保持一致。

Skills 監看器

OpenClaw 預設會監看 Skill 資料夾，並在 SKILL.md 檔案變更時更新快照。請在 skills.load 下設定：

{
  skills: {
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
      watch: true, // 預設值
    },
  },
}

監看器事件使用內建的 250 ms 防彈跳。對於 Skill 根目錄符號連結指向已設定根目錄外部的刻意符號連結配置，請使用 allowSymlinkTargets，例如 <workspace>/skills/manager -> ~/Projects/manager/skills。僅當 Skill Workshop 也應透過這些受信任的符號連結路徑套用提案時，才啟用 skills.workshop.allowSymlinkTargetWrites。

遠端 macOS 節點（Linux 閘道）

如果閘道在 Linux 上執行，但已連線一個允許 system.run 的 macOS 節點，當該節點上存在必要的二進位檔時，OpenClaw 可將僅限 macOS 的 Skills 視為符合資格。代理程式應使用 exec 工具搭配 host=node 執行這些 Skills。離線節點不會讓僅限遠端的 Skills 顯示。如果節點停止回應二進位檔探查，OpenClaw 會清除其快取的二進位檔相符項目。

Token 影響

Skills 符合資格時，OpenClaw 會將精簡的 XML 區塊注入系統提示詞。成本是確定的，並隨每個 Skill 線性增加：

基本額外負擔（僅在有 1 個以上符合資格的 Skills 時）：固定的簡介文字區塊，加上 <available_skills> 包裝器。
**每個 Skill：**約 97 個字元，加上你的 name、description 和 location 欄位長度。
XML 跳脫會將 & < > " ' 展開為實體，每次出現會增加幾個字元。
以約 4 個字元/token 計算，在加上欄位長度前，每個 Skill 的 97 個字元 ≈ 24 個 token。

如果轉譯後的區塊會超過已設定的提示預算 (skills.limits.maxSkillsPromptChars)，OpenClaw 會先保留不含描述的精簡格式所能容納的最大數量 Skills 識別資訊（名稱、位置和版本）。接著會將所有剩餘預算用於縮短後的描述。如果沒有剩餘的描述預算，則會省略描述。每當需要使用精簡格式或截斷清單時，提示中都會包含指向 openclaw skills check 的附註。請保持描述簡短且具描述性，以將提示額外負擔降至最低。

建立 Skills

編寫自訂 Skill 的逐步指南。

Skill 工作坊

由代理程式草擬之 Skills 的提案佇列。

Skills 設定

完整的 skills.* 設定結構描述與代理程式允許清單。

斜線命令

Skill 斜線命令的註冊與路由方式。

ClawHub

在公開登錄檔中瀏覽及發布 Skills。

外掛

外掛可隨其所記錄的工具一併提供 Skills。

Overview

Plugins

Plugin guides

Building plugins

Automation

Tools

Agent coordination

Skills

建立 Skills

Skill 工作坊

Skills 設定

ClawHub

載入順序

節點託管的 Skills

各代理程式專用與共用 Skills

代理程式允許清單

外掛與 Skills

Skill 工作坊

從 ClawHub 安裝

安全性

SKILL.md 格式

選用的 frontmatter 鍵

門檻條件

安裝程式規格

設定覆寫

環境注入

快照與重新整理

Token 影響

相關內容

建立 Skills

Skill 工作坊

Skills 設定

斜線命令

ClawHub

外掛

建立 Skills

Skill 工作坊

Skills 設定

ClawHub

​載入順序

​節點託管的 Skills

​各代理程式專用與共用 Skills

​代理程式允許清單

​外掛與 Skills

​Skill 工作坊

​從 ClawHub 安裝

​安全性

​SKILL.md 格式

​選用的 frontmatter 鍵

​門檻條件

​安裝程式規格

​設定覆寫

​環境注入

​快照與重新整理

​Token 影響

​相關內容

建立 Skills

Skill 工作坊

Skills 設定

斜線命令

ClawHub

外掛

載入順序

節點託管的 Skills

各代理程式專用與共用 Skills

代理程式允許清單

外掛與 Skills

Skill 工作坊

從 ClawHub 安裝

安全性

SKILL.md 格式

選用的 frontmatter 鍵

門檻條件

安裝程式規格

設定覆寫

環境注入

快照與重新整理

Token 影響

相關內容