技能設定

所有技能相關的設定都在 ~/.openclaw/openclaw.json 的 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（閘道執行環境仍為 Node；不建議使用 bun）
    },
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 也可使用純文字字串
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

欄位說明

• allowBundled：僅針對內建技能的選用允許清單。設定後，只有清單中的內建技能才有資格（受管理/工作區技能不受影響）。
• load.extraDirs：要掃描的額外技能目錄（優先序最低）。
• load.watch：監控技能資料夾並重新整理技能快照（預設：true）。
• load.watchDebounceMs：技能監控事件的防彈跳時間，單位為毫秒（預設：250）。
• install.preferBrew：可用時優先使用 brew 安裝（預設：true）。
• install.nodeManager：Node 安裝工具偏好（npm | pnpm | yarn | bun，預設：npm）。 這只影響技能安裝；閘道執行環境仍應使用 Node （不建議 WhatsApp/Telegram 使用 Bun）。
• entries.<skillKey>：每個技能的覆寫設定。

每個技能的欄位：

• enabled：設為 false 可停用技能，即使它是內建或已安裝的。
• env：為代理執行注入的環境變數（僅在未設定時注入）。
• apiKey：為宣告主要環境變數的技能提供的便捷設定。 支援純文字字串或 SecretRef 物件（{ source, provider, id }）。

注意事項

• entries 下的鍵值預設對應技能名稱。如果技能定義了 metadata.openclaw.skillKey，請使用該鍵值。
• 啟用監控器時，技能變更會在下一個代理回合時生效。

沙箱化技能與環境變數

當工作階段處於沙箱中時，技能程序在 Docker 內執行。沙箱 不會繼承主機的 process.env。

請使用以下方式之一：

• agents.defaults.sandbox.docker.env（或每個代理的 agents.list[].sandbox.docker.env）
• 將環境變數烘焙到你的自訂沙箱映像中

全域 env 和 skills.entries.<skill>.env/apiKey 僅適用於主機執行。