技能
OpenClaw 使用 AgentSkills 相容的技能資料夾來教導代理如何使用工具，包含載入、設定及管理方式。
OpenClaw 使用與 AgentSkills 相容的技能資料夾來教導代理如何使用工具。每個技能是一個包含 SKILL.md 的目錄，其中含有 YAML frontmatter 和指令。OpenClaw 載入內建技能加上選用的本地覆寫，並在載入時根據環境、設定和二進位檔存在與否進行過濾。
位置和優先順序
技能從三個位置載入：
- 內建技能：隨安裝附帶（npm 套件或 OpenClaw.app）
- 受管理/本地技能：
~/.openclaw/skills - 工作區技能：
<workspace>/skills
若技能名稱衝突，優先順序為：
<workspace>/skills（最高） -> ~/.openclaw/skills -> 內建技能（最低）
此外，你可以透過 ~/.openclaw/openclaw.json 中的 skills.load.extraDirs 設定額外的技能資料夾（最低優先順序）。
每個代理 vs 共享技能
在多代理設定中，每個代理有自己的工作區。這意味著：
- 每個代理的技能位於該代理專屬的
<workspace>/skills。 - 共享技能位於
~/.openclaw/skills（受管理/本地），對同一機器上的所有代理可見。 - 共享資料夾也可以透過
skills.load.extraDirs（最低優先順序）新增，若你想讓多個代理使用共同的技能包。
若相同技能名稱存在於多個位置，一般優先順序適用：工作區優先，然後是受管理/本地，最後是內建。
外掛 + 技能
外掛可以透過在 openclaw.plugin.json 中列出 skills 目錄來附帶自己的技能（路徑相對於外掛根目錄）。外掛技能在外掛啟用時載入，並參與正常的技能優先順序規則。你可以透過外掛設定條目上的 metadata.openclaw.requires.config 進行控制。參閱 外掛 了解探索/設定，以及 工具 了解這些技能所教導的工具介面。
ClawHub（安裝 + 同步）
ClawHub 是 OpenClaw 的公開技能登錄庫。瀏覽 https://clawhub.com。使用它來探索、安裝、更新和備份技能。完整指南：ClawHub。
常見流程：
- 將技能安裝到你的工作區：
clawhub install <skill-slug>
- 更新所有已安裝的技能：
clawhub update --all
- 同步（掃描 & 發布更新）：
clawhub sync --all
預設情況下，clawhub 安裝到目前工作目錄下的 ./skills（或退回到已設定的 OpenClaw 工作區）。OpenClaw 在下次工作階段時將其識別為 <workspace>/skills。
安全注意事項
- 將第三方技能視為不受信任的程式碼。啟用前請先閱讀。
- 對於不受信任的輸入和有風險的工具，建議使用沙箱執行。參閱 沙箱。
skills.entries.*.env和skills.entries.*.apiKey將密鑰注入該代理回合的主機程序（而非沙箱）。將密鑰遠離提示詞和記錄。- 更廣泛的威脅模型和檢查清單，請參閱 安全性。
格式（AgentSkills + Pi 相容）
SKILL.md 至少必須包含：
---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
---注意事項：
- 我們遵循 AgentSkills 規範的佈局/意圖。
- 內嵌代理使用的解析器僅支援單行 frontmatter 鍵。
metadata應為單行 JSON 物件。- 在指令中使用
{baseDir}來引用技能資料夾路徑。 - 選用的 frontmatter 鍵：
-
homepage— 在 macOS Skills UI 中顯示為 “Website” 的 URL（也支援透過metadata.openclaw.homepage）。 -
user-invocable—true|false（預設：true）。為true時，技能會公開為使用者斜線命令。 -
disable-model-invocation—true|false（預設：false）。為true時，技能從模型提示中排除（仍可透過使用者呼叫使用）。 -
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: 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",
},
}
---metadata.openclaw 下的欄位：
always: true— 永遠包含此技能（跳過其他閘門）。emoji— macOS Skills UI 使用的選用 emoji。homepage— macOS Skills UI 中顯示為 “Website” 的選用 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在技能載入時於主機上檢查。- 若代理處於沙箱中，二進位檔也必須存在於容器內。透過
agents.defaults.sandbox.docker.setupCommand（或自訂映像）安裝。setupCommand在容器建立後執行一次。套件安裝也需要網路出口、可寫入的根檔案系統和沙箱中的 root 使用者。
安裝器範例：
---
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)",
},
],
},
}
---注意事項：
- 若列出多個安裝器，閘道會選擇單一偏好選項（有 brew 時使用 brew，否則使用 node）。
- 若所有安裝器都是
download，OpenClaw 會列出每個條目以供你查看可用的檔案。 - 安裝器規格可包含
os: ["darwin"|"linux"|"win32"]以按平台過濾選項。 - Node 安裝遵循
openclaw.json中的skills.install.nodeManager（預設：npm；選項：npm/pnpm/yarn/bun）。這僅影響技能安裝；閘道執行環境仍應使用 Node（不建議使用 Bun 於 WhatsApp/Telegram）。 - Go 安裝：若缺少
go但有brew，閘道會先透過 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: {
entries: {
"nano-banana-pro": {
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 },
},
},
}注意：若技能名稱包含連字號，請將鍵加上引號（JSON5 允許引號鍵）。
設定鍵預設匹配技能名稱。若技能定義了 metadata.openclaw.skillKey，請在 skills.entries 下使用該鍵。
規則：
enabled: false即使技能為內建/已安裝也會停用。env：僅在變數尚未在程序中設定時注入。apiKey：對於宣告metadata.openclaw.primaryEnv的技能的便利功能。支援純文字字串或 SecretRef 物件（{ source, provider, id }）。config：選用的自訂每個技能欄位容器；自訂鍵必須放在這裡。allowBundled：僅針對內建技能的選用允許清單。若設定，僅清單中的內建技能符合資格（受管理/工作區技能不受影響）。
環境注入（每次代理執行）
當代理執行開始時，OpenClaw：
- 讀取技能中繼資料。
- 將
skills.entries.<key>.env或skills.entries.<key>.apiKey套用到process.env。 - 使用符合資格的技能建構系統提示。
- 執行結束後恢復原始環境。
這僅作用於代理執行範圍，而非全域 shell 環境。
工作階段快照（效能）
OpenClaw 在工作階段開始時對符合資格的技能進行快照，並在同一工作階段的後續回合中重複使用該清單。技能或設定的變更在下次新工作階段時生效。
技能也可以在工作階段中途重新整理（當技能監視器啟用或出現新的符合資格遠端節點時）。可以將此視為熱重載：重新整理的清單在下次代理回合時被拾取。
遠端 macOS 節點（Linux 閘道）
若閘道在 Linux 上運行但有 macOS 節點已連線且允許 system.run（Exec 核准安全性未設為 deny），OpenClaw 可以在該節點上存在所需二進位檔時將 macOS 專用技能視為符合資格。代理應透過 nodes 工具（通常是 nodes.run）執行這些技能。
這依賴節點回報其命令支援及透過 system.run 的二進位檔探測。若 macOS 節點稍後離線，技能仍然可見；呼叫可能會失敗直到節點重新連線。
技能監視器（自動重新整理）
預設情況下，OpenClaw 監視技能資料夾並在 SKILL.md 檔案變更時更新技能快照。在 skills.load 下設定：
{
skills: {
load: {
watch: true,
watchDebounceMs: 250,
},
},
}Token 影響（技能清單）
當技能符合資格時，OpenClaw 將精簡的 XML 可用技能清單注入系統提示（透過 pi-coding-agent 中的 formatSkillsForPrompt）。成本是確定性的：
- 基礎開銷（僅當有 >= 1 個技能時）： 195 字元。
- 每個技能： 97 字元 + XML 轉義的
<name>、<description>和<location>值的長度。
公式（字元）：
total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))注意事項：
- XML 轉義會將
& < > " '展開為實體（&、<等），增加長度。 - Token 計數因模型分詞器而異。粗略的 OpenAI 風格估計為約 4 字元/token，所以97 字元約 24 tokens每個技能，加上你實際欄位的長度。
受管理技能生命週期
OpenClaw 在安裝中附帶一組基線技能作為內建技能（npm 套件或 OpenClaw.app）。~/.openclaw/skills 用於本地覆寫（例如，在不更改內建副本的情況下固定/修補技能）。工作區技能為使用者擁有，在名稱衝突時覆寫兩者。
設定參考
參閱 技能設定 了解完整的設定 schema。