技能配置

所有与技能相关的配置都位于 ~/.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：仅用于内置技能的可选允许列表。设置后，仅列表中的内置技能可用（托管/工作区技能不受影响）。
• load.extraDirs：要扫描的额外技能目录（最低优先级）。
• load.watch：监视技能文件夹并刷新技能快照（默认：true）。
• load.watchDebounceMs：技能监视器事件的防抖时间（毫秒）（默认：250）。
• install.preferBrew：可用时优先使用 brew 安装器（默认：true）。
• install.nodeManager：Node 安装器偏好（npm | pnpm | yarn | bun，默认：npm）。这仅影响技能安装；Gateway 运行时应该仍使用 Node（不推荐将 Bun 用于 WhatsApp/Telegram）。
• entries.<skillName>：每技能覆盖。每技能字段：
  • 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 仅适用于主机运行。