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

对于内置图像生成/编辑，建议优先使用 agents.defaults.imageGenerationModel 加核心 image_generate 工具。skills.entries.* 仅用于自定义或第三方技能工作流。

如果你选择了特定的图像 Provider/模型，还需要配置该 Provider 的认证/API Key。典型示例：google/* 用 GEMINI_API_KEY 或 GOOGLE_API_KEY，openai/* 用 OPENAI_API_KEY，fal/* 用 FAL_KEY。

示例：

• 原生 Nano Banana 风格设置：agents.defaults.imageGenerationModel.primary: "google/gemini-3-pro-image-preview"
• 原生 fal 设置：agents.defaults.imageGenerationModel.primary: "fal/fal-ai/flux/dev"

字段说明

• allowBundled：仅针对内置技能的可选白名单。设置后只有白名单中的内置技能符合条件（managed/工作区技能不受影响）。
• load.extraDirs：额外的技能目录（优先级最低）。
• load.watch：监视技能文件夹并刷新技能快照（默认：true）。
• load.watchDebounceMs：技能监视器事件的防抖时间，单位毫秒（默认：250）。
• install.preferBrew：有 brew 时优先使用 brew 安装器（默认：true）。
• install.nodeManager：Node 安装器偏好（npm | pnpm | yarn | bun，默认：npm）。 这只影响技能安装；Gateway 运行时仍应使用 Node（WhatsApp/Telegram 不推荐用 bun）。
• entries.<skillKey>：单技能覆盖。

单技能字段：

• enabled：设为 false 可禁用技能，即使已内置/安装。
• env：Agent 运行时注入的环境变量（只有当变量尚未设置时才注入）。
• apiKey：声明了主 env 变量的技能的可选便捷配置。 支持纯文本字符串或 SecretRef 对象（{ source, provider, id }）。

注意事项

• entries 下的 key 默认与技能名称匹配。如果技能定义了 metadata.openclaw.skillKey，改用该 key。
• 启用监视器时，技能变更在下一次 Agent 轮次时生效。

沙箱会话中的技能与环境变量

当会话处于沙箱模式时，技能进程在 Docker 内运行。沙箱不继承宿主的 process.env。

使用以下方式之一：

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

全局 env 和 skills.entries.<skill>.env/apiKey 只适用于宿主运行模式。