Skill 配置

所有 Skill 相关的配置都在 ~/.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 runtime still Node; bun not recommended)
    },
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

配置字段

• allowBundled：可选的内置 Skill 白名单。设置后，只有列表中的内置 Skill 可用（不影响托管的或 Workspace 中的 Skill）。
• load.extraDirs：额外扫描的 Skill 目录（优先级最低）。
• load.watch：监听 Skill 文件夹变化并刷新 Skill 快照（默认：true）。
• load.watchDebounceMs：Skill 监听器事件的防抖延迟，单位毫秒（默认：250）。
• install.preferBrew：优先使用 brew 安装器（默认：true）。
• install.nodeManager：Node 安装器偏好（npm | pnpm | yarn | bun，默认：npm）。 这只影响 Skill 安装；Gateway Runtime 仍然使用 Node （不推荐用 Bun 运行 WhatsApp/Telegram）。
• entries.<skillKey>：针对单个 Skill 的配置覆盖。

单个 Skill 的配置字段：

• enabled：设为 false 可禁用某个 Skill，即使它已内置或已安装。
• env：为 Agent 运行注入的环境变量（仅在未设置时注入）。
• apiKey：可选的便捷字段，用于声明主要环境变量的 Skill。

注意事项

• entries 下的键默认映射到 Skill 名称。如果某个 Skill 定义了 metadata.openclaw.skillKey，则使用该键。
• 启用监听器时，Skill 的变更会在下一次 Agent 回合时生效。

Sandbox 中的 Skill 和环境变量

当 Session 处于 Sandbox 模式时，Skill 进程在 Docker 内运行。Sandbox 不会继承宿主机的 process.env。

你需要使用以下方式之一：

• agents.defaults.sandbox.docker.env（或针对单个 Agent 的 agents.list[].sandbox.docker.env）
• 将环境变量打包到你的自定义 Sandbox 镜像中

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