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

​
位置與優先順序

OpenClaw 會從這些來源載入 skills，優先順序由高到低：
#來源路徑
1Workspace skills<workspace>/skills
2專案 agent skills<workspace>/.agents/skills
3個人 agent skills~/.agents/skills
4受管理/本機 skills~/.openclaw/skills
5內建 skills隨安裝提供
6額外 skill 資料夾skills.load.extraDirs (config)
如果 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：
範圍路徑可見對象
個別 agent<workspace>/skills僅該 agent
專案 agent<workspace>/.agents/skills僅該 workspace 的 agent
個人 agent~/.agents/skills該機器上的所有 agents
共用受管理/本機~/.openclaw/skills該機器上的所有 agents
共用額外目錄skills.load.extraDirs (最低優先順序)該機器上的所有 agents
相同名稱出現在多個位置 → 最高來源勝出。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
    ],
  },
}
  • 省略 agents.defaults.skills，預設即可不限制 skills。
  • 省略 agents.list[].skills 以繼承 agents.defaults.skills。
  • 設定 agents.list[].skills: [] 以停用所有 skills。
  • 非空的 agents.list[].skills 清單是該 agent 的最終集合 - 它不會與預設值合併。
  • 有效的 allowlist 會套用於 prompt 建構、skill slash-command discovery、sandbox sync，以及 skill snapshots。

​
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。
動作命令
將 skill 安裝到 workspaceopenclaw skills install <skill-slug>
更新所有已安裝的 skillsopenclaw skills update --all
同步（掃描 + 發布更新）clawhub sync --all
原生 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> 處理誤判。

​
安全性

將第三方 skills 視為不受信任的程式碼。啟用前請先閱讀。 對不受信任的輸入和高風險工具，優先使用 sandboxed runs。請參閱 Sandboxing 了解 agent 端控制。
  • 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-lab
description: Generate or edit images via a provider-backed image workflow
---
OpenClaw 遵循 AgentSkills spec 的版面/意圖。嵌入式 agent 使用的 parser 僅支援單行 frontmatter keys； metadata 應為單行 JSON 物件。在指示中使用 {baseDir} 來參照 skill 資料夾路徑。

​
選用 frontmatter keys

​
homepage
string
在 macOS Skills UI 中顯示為「網站」的 URL。也支援透過 metadata.openclaw.homepage 設定。
​
user-invocable
boolean
預設值:"true"
當為 true 時，skill 會公開為使用者 slash command。
​
disable-model-invocation
boolean
預設值:"false"
當為 true 時，OpenClaw 會將 skill 的指示排除在 agent 的一般 prompt 之外。skill 仍會安裝，且當 user-invocable 也是 true 時， 仍可作為 slash command 明確執行。
​
command-dispatch
"tool"
設為 tool 時，slash command 會繞過模型並直接分派到工具。
​
command-tool
string
設定 command-dispatch: tool 時要叫用的工具名稱。
​
command-arg-mode
"raw"
預設值:"raw"
對於工具分派，會將原始 args 字串轉交給工具（不進行核心解析）。工具會以 { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" } 叫用。

​
Gating（載入時篩選器）

OpenClaw 會在載入時使用 metadata（單行 JSON）篩選 skills： 
---
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
boolean
當為 true 時，一律包含該 skill（略過其他閘門）。
​
emoji
string
macOS Skills UI 使用的選用 emoji。
​
homepage
string
在 macOS Skills UI 中顯示為「網站」的選用 URL。
​
os
"darwin" | "linux" | "win32"
選用平台清單。如果設定，該 skill 只會在這些作業系統上符合資格。
​
requires.bins
string[]
每一項都必須存在於 PATH。
​
requires.anyBins
string[]
至少一項必須存在於 PATH。
​
requires.env
string[]
環境變數必須存在，或在設定中提供。
​
requires.config
string[]
必須為 truthy 的 openclaw.json 路徑清單。
​
primaryEnv
string
與 skills.entries.<name>.apiKey 相關聯的環境變數名稱。
​
install
object[]
macOS Skills UI 使用的選用安裝程式規格（brew/node/go/uv/download）。
如果沒有 metadata.openclaw，該 skill 一律符合資格（除非 在設定中停用，或對 bundled skills 被 skills.allowBundled 封鎖）。
當 metadata.openclaw 不存在時，舊版 metadata.clawdbot 區塊仍會被接受， 因此較舊的已安裝 skills 會保留其 相依性閘門和安裝程式提示。新的和更新後的 skills 應使用 metadata.openclaw。

​
沙箱注意事項

  • requires.bins 會在 skill 載入時於主機上檢查。
  • 如果 agent 在沙箱中，該二進位檔也必須存在於容器內。請透過 agents.defaults.sandbox.docker.setupCommand（或自訂映像檔）安裝它。setupCommand 會在容器建立後執行一次。套件安裝也需要網路出口、可寫入的根檔案系統，以及沙箱中的 root 使用者。
  • 範例：summarize skill（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）。這只會影響 skill 安裝；Gateway 執行階段仍應是 Node - WhatsApp/Telegram 不建議使用 Bun。
  • Gateway 後援的安裝程式選擇由偏好驅動：當安裝規格混合多種 kind 時，OpenClaw 會在 skills.install.preferBrew 啟用且 brew 存在時偏好 Homebrew，接著是 uv，接著是設定的 node 管理器，接著是其他備援如 go 或 download。
  • 如果每個安裝規格都是 download，OpenClaw 會顯示所有下載選項，而不是摺疊成一個偏好的安裝程式。
  • **Go 安裝：**如果缺少 go 且 brew 可用，gateway 會先透過 Homebrew 安裝 Go，並在可能時將 GOBIN 設為 Homebrew 的 bin。
  • 下載安裝：url（必要）、archive（tar.gz | tar.bz2 | zip）、extract（預設：偵測到封存檔時自動）、stripComponents、targetDir（預設：~/.openclaw/tools/<skillKey>）。

​
設定覆寫

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 },
    },
  },
}
​
enabled
boolean
false 會停用該 skill，即使它是 bundled 或已安裝。 bundled coding-agent skill 需要選擇加入：先設定 skills.entries.coding-agent.enabled: true，再將其公開給 agents， 然後確認 claude、codex、opencode 或 pi 其中之一已安裝且 已為其自己的 CLI 完成驗證。
​
apiKey
string | { source, provider, id }
供宣告 metadata.openclaw.primaryEnv 的 skills 使用的便利項。支援純文字或 SecretRef。
​
env
Record<string, string>
只有在變數尚未於程序中設定時才注入。
​
config
object
自訂每個 skill 欄位的選用容器。自訂鍵必須放在這裡。
​
allowBundled
string[]
僅供 bundled skills 使用的選用允許清單。如果設定，只有清單中的 bundled skills 符合資格（受管理/工作區 skills 不受影響）。
如果 skill 名稱包含連字號，請引用該鍵（JSON5 允許引用鍵）。 設定鍵預設會符合 skill 名稱 - 如果某個 skill 定義了 metadata.openclaw.skillKey，請在 skills.entries 下使用該鍵。
若要在 OpenClaw 內進行庫存圖片生成/編輯，請使用核心 image_generate tool 搭配 agents.defaults.imageGenerationModel， 而不是 bundled skill。這裡的 skill 範例適用於自訂或第三方 工作流程。若要進行原生圖片分析，請使用 image tool 搭配 agents.defaults.imageModel。如果你選擇 openai/*、google/*、 fal/* 或其他供應商特定的圖片模型，也請加入該供應商的 驗證/API 金鑰。

​
環境注入

當 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 逸出會將 & < > " ' 展開成實體（&amp;、&lt; 等）， 使長度增加。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 設定。

​
相關