OpenClaw Skills 設定指南：自訂 Agent 能力與環境變數

開發者在管理多個自動化腳本與工具時，經常會遇到設定檔散落各處、權限管理混亂，或是不同專案間依賴衝突的困擾。透過統一的配置方式來管理你的自動化工具，能大幅減少除錯時間，讓你更專注於核心邏輯的開發。

OpenClaw 的 skills 配置功能，讓你能夠輕鬆管理與安裝各類自動化技能。大部分的技能載入與安裝設定都位於 ~/.openclaw/openclaw.json 檔案中的 skills 區塊，而針對特定 Agent 的技能權限，則可以在 agents.defaults.skills 或 agents.list[].skills 中進行設定。

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills", "~/Projects/oss/some-skill-pack/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun (Gateway runtime still Node; bun not recommended)
    },
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

若你需要內建的圖像生成或編輯功能，建議優先使用 agents.defaults.imageGenerationModel 搭配核心的 image_generate 工具。skills.entries.* 僅適用於自訂或第三方技能的工作流程。

如果你選擇了特定的圖像供應商或模型，請記得同時設定該供應商的認證或 API 金鑰。常見的範例如 GEMINI_API_KEY 或 GOOGLE_API_KEY（適用於 google/*）、OPENAI_API_KEY（適用於 openai/*），以及 FAL_KEY（適用於 fal/*）。

範例：

• 原生 Nano Banana 風格設定：agents.defaults.imageGenerationModel.primary: "google/gemini-3.1-flash-image-preview"
• 原生 fal 設定：agents.defaults.imageGenerationModel.primary: "fal/fal-ai/flux/dev"

Agent 技能白名單

當你希望在同一台機器或工作區使用相同的技能根目錄，但又想為每個 Agent 設定不同的可見技能清單時，可以使用 Agent 配置。

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

規則：

1. agents.defaults.skills：為那些省略了 agents.list[].skills 的 Agent 提供共享的基礎白名單。
2. 若省略 agents.defaults.skills，則預設不限制任何技能。
3. agents.list[].skills：為該 Agent 設定明確的最終技能集；它不會與預設值合併。
4. agents.list[].skills: []：表示該 Agent 不開放任何技能。

欄位說明

此處詳細說明各項配置欄位的功能與預設行為。

1. 內建的技能根目錄始終包含 ~/.openclaw/skills、~/.agents/skills、<workspace>/.agents/skills 以及 <workspace>/skills。
2. allowBundled：僅針對 bundled 技能的可選白名單。設定後，僅清單中的 bundled 技能有效（管理技能、Agent 技能與工作區技能不受影響）。
3. load.extraDirs：額外掃描的技能目錄（優先級最低）。
4. load.watch：監控技能資料夾並重新整理技能快照（預設：true）。
5. load.watchDebounceMs：技能監控事件的防抖動時間，單位為毫秒（預設：250）。
6. install.preferBrew：在可用時優先使用 brew 安裝程式（預設：true）。
7. install.nodeManager：Node.js 安裝程式偏好（npm | pnpm | yarn | bun，預設：npm）。這僅影響 skill installs；Gateway 執行環境仍應使用 Node.js（不建議在 WhatsApp/Telegram 中使用 bun）。
8. openclaw setup --node-manager 的範圍較窄，目前接受 npm、pnpm 或 bun。若你想使用 Yarn 來安裝技能，請手動設定 skills.install.nodeManager: "yarn"。
9. entries.<skillKey>：針對個別技能的覆寫設定。
10. agents.defaults.skills：可選的預設技能白名單，由省略 agents.list[].skills 的 Agent 繼承。
11. agents.list[].skills：可選的個別 Agent 最終技能白名單；明確的清單會取代繼承的預設值，而非進行合併。

個別技能欄位：

1. enabled：設為 false 可停用該技能，即使它是 bundled 或已安裝的。
2. env：注入 Agent 執行時的環境變數（僅在尚未設定時生效）。
3. apiKey：為宣告主要環境變數的技能提供的便利選項。支援純文字字串或 SecretRef 物件（{ source, provider, id }）。

注意事項

了解載入順序與沙盒環境的差異，能幫助你更精準地除錯。

1. entries 下的鍵預設對應技能名稱。如果技能定義了 metadata.openclaw.skillKey，請改用該鍵。
2. 載入優先順序為 <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/openclaw.json → bundled 技能 → skills.load.extraDirs。
3. 當啟用監控功能時，技能的變更會在下一次 Agent 執行時生效。

沙盒技能與環境變數

當工作階段處於 sandboxed 狀態時，技能處理程序會在設定的沙盒後端內執行。沙盒不會繼承主機的 process.env。

請使用下列方式之一：

1. 針對 Docker 後端使用 agents.defaults.sandbox.docker.env（或個別 Agent 的 agents.list[].sandbox.docker.env）。
2. 將環境變數寫入你的自訂沙盒映像檔或遠端沙盒環境中。

全域的 env 與 skills.entries.<skill>.env/apiKey 僅適用於主機 (host) 執行。

---

若需要進一步協助，請參考 AI Setup Assistant。

相關文件

• Agent Config
• Secret Management