OpenClaw 技能（Skills）系统配置指南

适用版本：OpenClaw v2026.3.8+
配置文件路径：~/.openclaw/openclaw.json

OpenClaw 的核心能力通过 Skills（技能） 扩展实现。每个技能是一个独立的可执行单元，用于完成特定任务（如调用 AI 模型、处理文件、发送邮件等）。所有技能相关的配置均位于 openclaw.json 文件的 skills 字段下。

一、整体结构

{
  "skills": {
    "allowBundled": ["gemini", "peekaboo"],
    "load": { ... },
    "install": { ... },
    "entries": { ... }
  }
}

• allowBundled：控制哪些内置技能可被启用。
• load：定义技能的加载行为与扫描路径。
• install：指定依赖安装时的包管理器偏好。
• entries：对具体技能进行细粒度配置（如启用状态、API 密钥、环境变量等）。

二、字段详解

1. allowBundled（可选）

• 类型：字符串数组
• 作用：显式允许使用的内置技能（bundled skills） 列表。
• 行为：
  • 若未设置，所有内置技能默认可用。
  • 若设置（如 ["gemini", "peekaboo"]），则仅列表中的内置技能可被加载。
  • 不影响通过 load.extraDirs 加载的外部技能或工作区技能。

✅ 推荐用法：在安全敏感环境中，显式声明所需技能，最小化攻击面。

2. load：技能加载配置

示例

"load": {
  "extraDirs": [
    "~/Projects/agent-scripts/skills",
    "~/Projects/oss/some-skill-pack/skills"
  ],
  "watch": true,
  "watchDebounceMs": 250
}

💡 提示：修改技能代码后，若 watch: true，OpenClaw 会在下一次智能体轮询时自动生效新版本。

3. install：依赖安装偏好

字段	可选值	默认值	说明
preferBrew	true / false	true	安装系统依赖时，优先使用 brew（macOS/Linux）。
nodeManager	"npm" | "pnpm" | "yarn" | "bun"	"npm"	安装 Node.js 依赖时使用的包管理器。

⚠️ 重要提醒：

• 此设置仅影响技能自身的依赖安装过程。
• OpenClaw Gateway 运行时必须使用 Node.js，不推荐使用 Bun（尤其在 WhatsApp/Telegram 等渠道中可能存在兼容性问题）。

4. entries：单个技能的精细化配置

此对象的每个键（key）对应一个技能的唯一标识（skillKey）。

如何确定 skillKey？

• 默认为技能目录名。
• 若技能的 metadata.openclaw.skillKey 有定义，则以该值为准。

支持的字段：

apiKey 的两种写法：

方式一：明文（不推荐生产使用）

"apiKey": "sk-actual-api-key-here"

方式二：引用环境变量（推荐）

"apiKey": {
  "source": "env",
  "provider": "default",
  "id": "GEMINI_API_KEY"
}

此配置等价于在 env 中设置 GEMINI_API_KEY，但语义更清晰。

完整示例

"entries": {
  "nano-banana-pro": {
    "enabled": true,
    "apiKey": {
      "source": "env",
      "provider": "default",
      "id": "GEMINI_API_KEY"
    },
    "env": {
      "GEMINI_API_KEY": "your_actual_key_here"
    }
  },
  "peekaboo": {
    "enabled": true
  },
  "sag": {
    "enabled": false
  }
}

三、沙箱（Sandbox）环境下的技能与环境变量

当会话在 Docker 沙箱中运行时，技能进程不会继承宿主机的 process.env。

如何向沙箱技能传递环境变量？

必须通过以下任一方式显式注入：

1. 在沙箱配置中声明（推荐）：

   {
     "agents": {
       "defaults": {
         "sandbox": {
           "docker": {
             "env": {
               "GEMINI_API_KEY": "your_key"
             }
           }
         }
       }
     }
   }
   

2. 构建自定义沙箱镜像，将密钥 bake 进镜像（适用于静态配置）。

❗ 注意：skills.entries.<skill>.env 和全局环境变量仅对非沙箱（host）模式生效，对沙箱无效。

四、最佳实践建议

1. 生产环境：

   • 显式设置 allowBundled，最小化技能集。
   • 使用 apiKey 引用环境变量，避免明文密钥。
   • 将敏感密钥通过 Kubernetes Secret / Vault 注入，而非写入配置文件。

2. 开发环境：

   • 启用 load.watch: true，实现热重载。
   • 通过 extraDirs 快速测试本地技能。

3. 沙箱部署：

   • 务必通过 agents.*.sandbox.docker.env 传递必要环境变量。
   • 避免在沙箱中使用需网络安装依赖的技能（因网络可能受限）。

通过合理配置 skills 模块，您可以灵活、安全地管理和扩展 OpenClaw 的能力边界，使其真正成为可信赖的“AI 数字员工”。