Skills 配置

所有 Skills 相关的配置都在 ~/.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 (Gateway 运行时仍是 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：可选的内置 Skills 白名单。设置后，只有列表中的内置 Skills 才有资格加载（托管/工作区 Skills 不受影响）。
• load.extraDirs：额外的 Skills 目录扫描路径（优先级最低）。
• load.watch：监视 Skills 文件夹并刷新 Skills 快照（默认 true）。
• load.watchDebounceMs：Skills 监视器事件的防抖时间，毫秒（默认 250）。
• install.preferBrew：可用时优先使用 brew 安装器（默认 true）。
• install.nodeManager：node 安装器偏好（npm | pnpm | yarn | bun，默认 npm）。 这只影响 Skills 安装；Gateway 运行时应该继续用 Node （WhatsApp/Telegram 不推荐用 Bun）。
• entries.<skillKey>：按 Skill 的覆盖配置。

按 Skill 字段：

• enabled：设为 false 可禁用一个 Skill，即使它是内置/已安装的。
• env：为 Agent 运行注入的环境变量（仅在未设置时注入）。
• apiKey：便捷字段，用于声明了主要环境变量的 Skills。 支持纯文本字符串或 SecretRef 对象（{ source, provider, id }）。

说明

• entries 下的 key 默认对应 Skill 名称。如果 Skill 定义了 metadata.openclaw.skillKey，请使用该 key。
• 启用监视器后，Skills 的变更会在下一次 Agent 轮次时被感知。

沙箱化 Skills + 环境变量

当会话处于沙箱化状态时，Skill 进程在 Docker 内运行。沙箱不会继承主机的 process.env。

请使用以下方式之一：

• agents.defaults.sandbox.docker.env（或按 Agent 的 agents.list[].sandbox.docker.env）
• 将环境变量烘焙到自定义沙箱镜像中

全局 env 和 skills.entries.<skill>.env/apiKey 仅对主机运行生效。