Skills 設定

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills", "~/Projects/oss/some-skill-pack/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun (Gateway runtime still Node; bun not recommended)
      allowUploadedArchives: false,
    },
    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 },
    },
  },
}

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

​

代理程式 Skills 允許清單

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

• agents.defaults.skills：供省略 agents.list[].skills 的代理程式使用的共用基準允許清單。
• 省略 agents.defaults.skills 會讓 Skills 預設不受限制。
• agents.list[].skills：該代理程式的明確最終 Skills 集合；它不會 與預設值合併。
• agents.list[].skills: []：不向該代理程式公開任何 Skills。

​

欄位

• 內建 Skills 根目錄一律包含 ~/.openclaw/skills、~/.agents/skills、 <workspace>/.agents/skills 和 <workspace>/skills。
• allowBundled：僅適用於隨附 Skills 的選用允許清單。設定後，只有 清單中的隨附 Skills 符合資格（受管理、代理程式和工作區 Skills 不受影響）。
• load.extraDirs：要掃描的其他 Skills 目錄（最低優先順序）。
• load.allowSymlinkTargets：受信任的真實目標目錄，符號連結的 Skills 資料夾即使位於該目標根目錄之外，也可以解析到其中。 將它用於有意設計的同層 repo 配置，例如 ~/.agents/skills/manager -> ~/Projects/manager/skills。
• load.watch：監看 Skills 資料夾並重新整理 Skills 快照（預設：true）。
• load.watchDebounceMs：Skills 監看器事件的 debounce，單位為毫秒（預設：250）。
• install.preferBrew：可用時優先使用 brew 安裝器（預設：true）。
• install.nodeManager：Node 安裝器偏好設定（npm | pnpm | yarn | bun，預設：npm）。 這只影響 Skills 安裝；Gateway runtime 仍應使用 Node （WhatsApp/Telegram 不建議使用 Bun）。
  • openclaw setup --node-manager 範圍較窄，目前接受 npm、 pnpm 或 bun。如果你想要以 Yarn 支援的 Skills 安裝，請手動設定 skills.install.nodeManager: "yarn"。
• install.allowUploadedArchives：允許受信任的 operator.admin Gateway 用戶端安裝透過 skills.upload.* 暫存的私有 zip 封存 （預設：false）。這只會啟用上傳封存路徑；一般 ClawHub 安裝不需要它。
• entries.<skillKey>：每個 Skill 的覆寫。
• agents.defaults.skills：選用的預設 Skills 允許清單，會由省略 agents.list[].skills 的代理程式繼承。
• agents.list[].skills：選用的每代理程式最終 Skills 允許清單；明確 清單會取代繼承的預設值，而不是合併。

​

符號連結的同層 repo

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}

• enabled：設定為 false 可停用某個 Skill，即使它是隨附/已安裝的 Skill。
• env：為代理程式執行注入的環境變數（僅在尚未設定時）。
• apiKey：供宣告主要環境變數的 Skills 使用的選用便利設定。 支援純文字字串或 SecretRef 物件（{ source, provider, id }）。

​

注意事項

• entries 之下的鍵預設會對應到 Skill 名稱。如果某個 Skill 定義了 metadata.openclaw.skillKey，請改用該鍵。
• 載入優先順序為 <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → 隨附 Skills → skills.load.extraDirs。
• 啟用監看器時，Skills 的變更會在下一次代理程式回合被接收。

​

沙盒化 Skills 與環境變數

• Docker 後端使用 agents.defaults.sandbox.docker.env（或每代理程式的 agents.list[].sandbox.docker.env）。
• 將環境變數建入你的自訂沙盒映像檔或遠端沙盒環境。

​

相關