Skills

OpenClaw 使用與 AgentSkills 相容的 skill 資料夾來教導 agent 如何使用工具。每個 skill 都是一個目錄， 其中包含帶有 YAML frontmatter 和指示的 SKILL.md。OpenClaw 會載入內建 skills 加上選用的本機覆寫，並在載入時根據 環境、設定和二進位檔是否存在來篩選它們。

位置與優先順序

OpenClaw 會從這些來源載入 skills，優先順序由高到低：

如果 skill 名稱衝突，最高來源會勝出。

Codex CLI 原生的 $CODEX_HOME/skills 目錄不是 OpenClaw 的 skill 根目錄之一。在 Codex harness 模式中，本機 app-server 啟動會使用隔離的 個別 agent Codex homes，因此個人 Codex CLI skills 不會被隱含載入。 使用 openclaw migrate codex --dry-run 來清點它們，並使用 openclaw migrate codex 透過互動式核取方塊提示選擇 skill 目錄， 再將它們複製到目前的 OpenClaw agent workspace。 對於非互動式執行，請重複 --skill <name> 以指定要複製的精確 skills。

個別 agent 與共用 skills

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

相同名稱出現在多個位置 → 最高來源勝出。Workspace 優先於 專案 agent，優先於個人 agent，優先於受管理/本機，優先於內建， 優先於額外目錄。

Agent skill allowlists

Skill 位置和 skill 可見性是不同的控制。 位置/優先順序決定同名 skill 的哪份副本勝出；agent allowlists 決定 agent 實際可以使用哪些 skills。

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

Plugins 與 skills

Plugins 可以在 openclaw.plugin.json 中列出 skills 目錄來隨附自己的 skills （路徑相對於 Plugin 根目錄）。Plugin skills 會在 Plugin 啟用時載入。 這是放置工具專用操作指南的正確位置，這些指南對工具描述來說太長， 但應該在安裝 Plugin 時可用 - 例如，browser Plugin 隨附 browser-automation skill，用於多步驟瀏覽器控制。

Plugin skill 目錄會合併到與 skills.load.extraDirs 相同的低優先順序路徑， 因此同名的內建、受管理、agent 或 workspace skill 會覆寫它們。 你可以透過 Plugin 設定項目上的 metadata.openclaw.requires.config 來設置門檻。

請參閱 Plugins 了解探索/設定，並參閱 工具 了解這些 skills 教導的工具介面。

Skill Workshop

選用的實驗性 Skill Workshop Plugin 可以根據 agent 工作期間觀察到的可重用程序， 建立或更新 workspace skills。它預設停用，必須透過 plugins.entries.skill-workshop 明確啟用。

Skill Workshop 只會寫入 <workspace>/skills，掃描產生的內容， 支援待核准或自動安全寫入，隔離不安全的提案，並在成功寫入後 重新整理 skill snapshot，讓新的 skills 無需重新啟動 Gateway 即可使用。

用它來處理像是 「下次，請驗證 GIF 歸屬」 這類更正， 或像媒體 QA 檢查清單這類得來不易的工作流程。先從待核准開始； 只有在受信任的 workspaces 中審查其提案後，才使用自動寫入。 完整指南：Skill Workshop Plugin。

ClawHub（安裝與同步）

ClawHub 是 OpenClaw 的公開 skills registry。 使用原生 openclaw skills 命令來探索/安裝/更新，或使用獨立的 clawhub CLI 進行發布/同步工作流程。完整指南： ClawHub。

原生 openclaw skills install 會安裝到作用中 workspace 的 skills/ 目錄。獨立的 clawhub CLI 也會安裝到目前工作目錄下的 ./skills（或退回到已設定的 OpenClaw workspace）。OpenClaw 會在下一個 session 將其識別為 <workspace>/skills。 已設定的 skill roots 也支援一層分組，例如 skills/<group>/<skill>/SKILL.md，因此相關的第三方 skills 可以保留在 共用資料夾下，而不需要廣泛遞迴掃描。

需要私有、非 ClawHub 傳遞的 Gateway clients 可以使用 skills.upload.begin、 skills.upload.chunk 和 skills.upload.commit 暫存 zip skill 封存，然後使用 skills.install({ source: "upload", uploadId, slug, force?, sha256? }) 安裝已提交的上傳。這是供受信任 clients 使用的明確管理員上傳路徑， 不是一般的 openclaw skills install <slug> 或 ClawHub 安裝流程。 它預設關閉，且只有在 openclaw.json 中設定 skills.install.allowUploadedArchives: true 時才會運作。上傳模式仍會安裝到 預設 agent workspace 的 skills/<slug> 目錄；封存內部的資料夾名稱會被忽略， 不會用於最終安裝目標。

ClawHub skill 頁面會在安裝前顯示最新的安全掃描狀態， 並提供 VirusTotal、ClawScan 和靜態分析的 scanner 詳細資料頁。 openclaw skills install <slug> 仍然只是安裝路徑；發布者可透過 ClawHub 儀表板或 clawhub skill rescan <slug> 處理誤判。

安全性

• Workspace 和 extra-dir skill discovery 只接受其解析後 realpath 仍位於已設定根目錄內的 skill roots 和 SKILL.md 檔案。
• Gateway private archive installs 預設關閉。明確啟用時， 它們需要包含 SKILL.md 的已提交 zip upload，並重用與 ClawHub skill installs 相同的封存解壓縮、路徑穿越、符號連結、force 和 rollback 保護。 它們由 skills.install.allowUploadedArchives 控制；一般 ClawHub installs 不需要 該設定。
• Gateway-backed skill dependency installs（skills.install、onboarding，以及 Skills settings UI）會在執行 installer metadata 前先執行內建 dangerous-code scanner。除非呼叫端明確設定 dangerous override，否則 critical findings 預設會阻擋；suspicious findings 仍只會警告。
• openclaw skills install <slug> 不同 - 它會將 ClawHub skill 資料夾下載到 workspace，且不使用上述 installer-metadata 路徑。
• skills.entries.*.env 和 skills.entries.*.apiKey 會將 secrets 注入該 agent turn 的 host process（不是 sandbox）。請避免將 secrets 放入 prompts 和 logs。

若需更廣泛的 threat model 和 checklists，請參閱 安全性。

SKILL.md 格式

SKILL.md 至少必須包含：

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

OpenClaw 遵循 AgentSkills spec 的版面/意圖。嵌入式 agent 使用的 parser 僅支援單行 frontmatter keys； metadata 應為單行 JSON 物件。在指示中使用 {baseDir} 來參照 skill 資料夾路徑。

選用 frontmatter keys

Gating（載入時篩選器）

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

---name: image-labdescription: Generate or edit images via a provider-backed image workflowmetadata:  {    "openclaw":      {        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },        "primaryEnv": "GEMINI_API_KEY",      },  }---

metadata.openclaw 底下的欄位：

如果沒有 metadata.openclaw，該 skill 一律符合資格（除非 在設定中停用，或對 bundled skills 被 skills.allowBundled 封鎖）。

沙箱注意事項

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

安裝程式規格

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

設定覆寫

Bundled 和受管理的 skills 可以在 ~/.openclaw/openclaw.json 的 skills.entries 下切換，並提供 env 值：

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

如果 skill 名稱包含連字號，請引用該鍵（JSON5 允許引用鍵）。 設定鍵預設會符合 skill 名稱 - 如果某個 skill 定義了 metadata.openclaw.skillKey，請在 skills.entries 下使用該鍵。

環境注入

當 agent 執行開始時，OpenClaw 會：

1. 讀取 skill metadata。
2. 將 skills.entries.<key>.env 和 skills.entries.<key>.apiKey 套用至 process.env。
3. 使用符合資格的 skills 建構系統提示。
4. 在執行結束後還原原始環境。

環境注入限定於 agent 執行，不是全域 shell 環境。

對於 bundled claude-cli 後端，OpenClaw 也會將相同的 符合資格快照實體化為暫時的 Claude Code plugin，並透過 --plugin-dir 傳遞。Claude Code 接著可以使用其原生 skill resolver， 而 OpenClaw 仍掌握優先順序、每個 agent 的允許清單、gating，以及 skills.entries.* env/API key 注入。其他 CLI 後端只使用 提示目錄。

快照與重新整理

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

Skills 可以在兩種情況下於工作階段中途重新整理：

• Skills watcher 已啟用。
• 新的符合資格遠端節點出現。

可將此視為熱重新載入：重新整理的清單會在下一個 agent 回合採用。如果該工作階段的有效 agent skill 允許清單變更， OpenClaw 會重新整理快照，讓可見 skills 與目前的 agent 保持一致。

Skills watcher

預設情況下，OpenClaw 會監看 skill 資料夾，並在 SKILL.md 檔案變更時遞增 skills 快照。 在 skills.load 下設定：

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

對於內建 skill 根目錄包含符號連結的有意 sibling-repo 版面配置， 請使用 allowSymlinkTargets，例如 ~/.agents/skills/manager -> ~/Projects/manager/skills。目標清單會在 realpath 解析後 進行比對，且應保持狹窄。

遠端 macOS 節點（Linux gateway）

如果 Gateway 在 Linux 上執行，但有一個macOS 節點已連線且 允許 system.run（Exec approvals 安全性未設為 deny）， 當必要的二進位檔存在於該節點上時，OpenClaw 可以將僅限 macOS 的 skills 視為符合資格。 agent 應透過 exec tool 搭配 host=node 執行這些 skills。

這仰賴節點回報其命令支援，以及透過 system.which 或 system.run 進行 bin probe。 離線節點不會讓僅限遠端的 skills 可見。如果已連線節點停止回應 bin probes，OpenClaw 會清除其快取的 bin 符合項，讓 agents 不再看見 目前無法在該處執行的 skills。

Token 影響

當 skills 符合資格時，OpenClaw 會將可用 skills 的精簡 XML 清單注入系統提示（透過 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 chars/token，因此每個 skill 97 個字元 ≈ 24 tokens，外加你的實際欄位長度。

受管理 skills 生命週期

OpenClaw 會隨安裝（npm 套件或 OpenClaw.app）提供一組基準 skills 作為 bundled skills。 ~/.openclaw/skills 用於 本機覆寫 - 例如，在不變更 bundled 副本的情況下釘選或修補某個 skill。 Workspace skills 由使用者擁有，且會在名稱衝突時覆寫兩者。

想尋找更多 skills？

瀏覽 https://clawhub.ai。完整設定 schema：Skills 設定。

相關

• ClawHub - public skills registry
• 建立 skills - 建構自訂 skills
• Plugins - plugin 系統概覽
• Skill Workshop plugin - 從 agent 工作生成 skills
• Skills 設定 - skill 設定參考
• Slash commands - 所有可用的 slash commands