Skills config

大多數技能配置位於 ~/.openclaw/openclaw.json 中的 skills 下。特定於代理程式的可見性位於 agents.defaults.skills 和 agents.list[].skills 下。

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
    install: {
      preferBrew: true,
      nodeManager: "npm",
      allowUploadedArchives: false,
    },
    workshop: {
      autonomous: { enabled: false },
      approvalPolicy: "pending",
      maxPending: 50,
      maxSkillBytes: 40000,
    },
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

載入 (`skills.load`)

要掃描的其他技能目錄，優先順序最低（在內建和插件技能之後）。路徑會使用 `~` 支援進行展開。符號連結技能資料夾可能解析到的受信任真實目標目錄，即使符號連結位於設定的根目錄之外。將此用於有意的同層級存放庫佈局，例如 `/skills/manager -> ~/Projects/manager/skills`。請保持此列表狹窄 — 不要指向像 `~` 或 `~/Projects` 這樣的廣泛根目錄。監看技能資料夾，並在 `SKILL.md` 檔案變更時重新整理技能快照。涵蓋群組技能根目錄下的巢狀檔案。技能監看器事件的防顫視窗（毫秒）。

安裝 (`skills.install`)

當 `brew` 可用時，優先使用 Homebrew 安裝程式。技能安裝的 Node 套件管理器偏好設定。這僅影響技能安裝 — Gateway 執行時仍應使用 Node（不建議針對 WhatsApp/Telegram 使用 Bun）。針對 npm、pnpm 或 bun 使用 `openclaw setup --node-manager`；若是基於 Yarn 的技能安裝，請手動設定 `"yarn"`。允許受信任的 `operator.admin` Gateway 用戶端安裝透過 `skills.upload.*` 暫存的私人 zip 壓縮檔。一般的 ClawHub 安裝不需要此設定。

隨附技能允許清單

僅適用於 **隨附 (bundled)** 技能的選用允許清單。設定後，僅清單中的隨附技能符合資格。受管理、代理層級和工作區技能不受影響。

個別技能項目 (`skills.entries`)

entries 下的索引鍵預設會比對技能 name。如果技能定義了 metadata.openclaw.skillKey，請改用該索引鍵。請用引號括住帶有連字號的名稱（JSON5 允許使用帶引號的索引鍵）。

`false` 會停用技能，即使已隨附或安裝也一樣。`coding-agent` 隨附技能為選用 — 將其設為 `true` 並確保已安裝並驗證 `claude`、`codex`、`opencode` 或其他支援的 CLI。針對宣告 `metadata.openclaw.primaryEnv` 的技能提供的便利欄位。支援純文字字串或 SecretRef：`{ source: "env", provider: "default", id: "VAR_NAME" }`。為代理執行注入的環境變數。僅在程序中尚未設定該變數時才會注入。自訂各技能設定欄位的選用性物件袋。

Agent 允許列表 (`agents`)

當您希望使用相同的機器/工作區技能根目錄，但每個 Agent 有不同的可見技能集時，請使用 Agent 配置。

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

省略 `agents.list[].skills` 的 Agent 繼承的共享基準允許列表。完全省略此項可讓技能預設不受限制。該 Agent 的明確最終技能集。明確列表會**取代**繼承的預設值 —— 它們不會合併。設為 `[]` 可讓該 Agent 不顯示任何技能。

Workshop (`skills.workshop`)

當設為 `true` 時，Agent 可以在成功執行後從持續的對話訊號中建立待處理提案。無論此設定為何，使用者提示建立的技能一律會透過 Skill Workshop 進行。 `pending` 要求在 Agent 初始化的套用、拒絕或隔離之前獲得操作員批准。`auto` 允許在無需批准的情況下執行這些操作。每個工作區保留的最大待處理和隔離提案數量。提案主體的大小上限（位元組）。由於提案描述會出現在探索和列表輸出中，因此其硬性上限為 160 位元組。

符號連結的技能根目錄

根據預設，工作區、專案 Agent、額外目錄和捆綁的技能根目錄都是隔離邊界。在 <workspace>/skills 下解析至根目錄外部的符號連結技能資料夾將會被跳過並記錄訊息。

若要允許有意安排的符號連結佈局，請宣告受信任的目標：

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

使用此配置，<workspace>/skills/manager -> ~/Projects/manager/skills 在解析 realpath 後會被接受。extraDirs 會直接掃描同層級的 repo； allowSymlinkTargets 則會為現有佈局保留符號連結路徑。

受管理的 ~/.openclaw/skills 和個人的 ~/.agents/skills 目錄已接受技能目錄的符號連結（單一技能的 SKILL.md 限制仍然適用）。

沙盒化技能與環境變數

使用以下方式將祕密傳遞至 Docker 沙盒：

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          env: { GEMINI_API_KEY: "your-key-here" },
        },
      },
    },
  },
}

載入順序提醒

workspace/skills      (highest)
workspace/.agents/skills
~/.agents/skills
~/.openclaw/skills
bundled skills
skills.load.extraDirs (lowest)

當監看器啟用時，對技能和配置的變更會在下一個新工作階段生效，或在監看器偵測到變更時的下一個 Agent 輪次生效。

Skills config

載入 (skills.load)

安裝 (skills.install)

隨附技能允許清單

個別技能項目 (skills.entries)

Agent 允許列表 (agents)

Workshop (skills.workshop)