Skills 配置参考

概述

Skills 配置集中在 ~/.openclaw/openclaw.json 的 skills 字段下，控制 Skills 的加载、安装、白名单和每个 Skill 的环境变量注入。Agent 级别的 Skill 可见性通过 agents.defaults.skills 和 agents.list[].skills 控制。

核心功能

allowBundled：限制内置 Skills 白名单，不影响 managed/workspace skills
load.extraDirs：追加额外 Skill 目录（最低优先级）
load.allowSymlinkTargets：允许 symlink 指向的可信目标目录（用于 sibling-repo 布局）
load.watch：监听 Skill 文件变化并热重载快照（默认 true）
install.preferBrew：安装时优先使用 Homebrew（默认 true）
install.nodeManager：Skill 安装使用的 Node 包管理器（npm/pnpm/yarn/bun）
install.allowUploadedArchives：允许通过 Gateway 上传私有 zip 安装（默认 false）
entries.<skillKey>：每个 Skill 的 enabled/env/apiKey/config 覆盖

配置/使用

完整配置示例

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

Agent 级别白名单

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" },                    // 继承 defaults
      { id: "docs", skills: ["docs-search"] }, // 替换 defaults
      { id: "locked-down", skills: [] },   // 无 skills
    ],
  },
}

沙箱环境变量注意事项

skills.entries.<skill>.env 和 apiKey 仅对 host 运行有效，沙箱内不继承 host process.env。沙箱内需通过 agents.defaults.sandbox.docker.env 单独配置。

Symlink 布局配置

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

Wiki AI

目录