Skills Config (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: "GEMINI_KEY_HERE",
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE"
        }
      },
      peekaboo: { enabled: true },
      sag: { enabled: false }
    }
  }
}

字段

  • allowBundled: 仅用于 bundled skills 的可选 allowlist (允许列表)。设置后,只有 列表中的 bundled skills 符合条件(managed/workspace skills 不受影响)。
  • load.extraDirs: 要扫描的额外 skill 目录(优先级最低)。
  • load.watch: 监视 skill 文件夹并刷新 skills 快照(默认: true)。
  • load.watchDebounceMs: skill watcher 事件的防抖时间,单位毫秒(默认: 250)。
  • install.preferBrew: 在可用时优先使用 brew 安装器(默认: true)。
  • install.nodeManager: node 安装器偏好设置(npm | pnpm | yarn | bun, 默认: npm)。 这只影响 skill 安装; Gateway 运行时应该仍然是 Node (不推荐使用 Bun 用于 WhatsApp/Telegram)。
  • entries.<skillKey>: 每个 skill 的覆盖。

每个 skill 的字段:

  • enabled: 设置 false 以禁用 skill,即使它是 bundled/installed。
  • env: 为 agent 运行注入的环境变量(仅当尚未设置时)。
  • apiKey: 对于声明主要 env var 的 skills 的可选便利。

注意事项

  • entries 下的 key 默认映射到 skill 名称。如果 skill 定义了 metadata.openclaw.skillKey,则使用该 key。
  • 当启用 watcher 时,在下一个 agent turn 时会捕获对 skills 的更改。

Sandboxed skills + env vars (沙盒 skills + 环境变量)

当会话被沙盒化时,skill 进程在 Docker 内运行。沙盒 不继承主机 process.env。

使用以下之一:

  • agents.defaults.sandbox.docker.env(或每个 agent 的 agents.list[].sandbox.docker.env)
  • 将 env 烘焙到你的自定义沙盒镜像中

全局 env 和 skills.entries.<skill>.env/apiKey 仅应用于 host 运行。

← 返回文档首页