11.22 技能配置

所有技能配置都位于 ~/.openclaw/openclaw.json 中的 "skills" 字段下。它控制内置/已安装技能的资格、加载、安装和每个技能的特定行为。

概述

技能配置系统提供了灵活的方式来管理技能的加载、安装和运行时行为。您可以控制哪些技能可用、如何加载它们、以及为每个技能提供特定的配置。

主要配置选项

技能过滤

• skills.allowBundled - 仅用于内置技能的可选白名单

加载配置

• skills.load.extraDirs - 要扫描的额外技能目录(优先级最低)
• skills.load.watch - 监视文件夹并刷新快照(默认: true)
• skills.load.watchDebounceMs - 监视器防抖时间(默认: 250ms)

安装配置

• skills.install.preferBrew - 优先使用 brew 安装器(默认: true)
• skills.install.nodeManager - 安装器偏好(npm | pnpm | yarn | bun; 默认: npm)

单个技能配置

• skills.entries.<skillKey> - 针对每个技能的覆盖配置(enabled, env, apiKey)

完整配置示例

{
  "skills": {
    // 只允许这些内置技能
    "allowBundled": ["gemini", "peekaboo"],
    
    // 加载配置
    "load": {
      "extraDirs": ["~/Projects/agent-scripts/skills"],
      "watch": true,
      "watchDebounceMs": 250
    },
    
    // 安装配置
    "install": {
      "preferBrew": true,
      "nodeManager": "npm"
    },
    
    // 单个技能配置
    "entries": {
      "nano-banana-pro": {
        "enabled": true,
        "apiKey": "GEMINI_KEY_HERE",
        "env": {
          "GEMINI_API_KEY": "GEMINI_KEY_HERE"
        }
      },
      "peekaboo": {
        "enabled": true
      },
      "sag": {
        "enabled": false
      }
    }
  }
}

环境变量和 API 密钥

环境变量 (env)

• 仅在尚未设置时注入
• 仅适用于宿主运行(不会继承到 Docker 沙箱)
• 对于沙箱会话,使用 agents.defaults.sandbox.docker.env 或自定义镜像

API 密钥 (apiKey)

• 为声明主环境变量的技能提供的便捷字段
• 通常与 env 中的特定键配合使用

// 配置技能的环境变量
{
  "skills": {
    "entries": {
      "my-skill": {
        "enabled": true,
        "apiKey": "YOUR_API_KEY",
        "env": {
          "CUSTOM_ENV_VAR": "value"
        }
      }
    }
  }
}

优先级规则

• extraDirs 中的技能具有最低优先级
• entries 下的键映射到技能名称,除非定义了 metadata.openclaw.skillKey
• 同名技能时,内置技能优先于外部目录中的技能

安装器配置详解

nodeManager

nodeManager 仅影响技能安装;网关运行时必须保持使用 Node。

preferBrew

当设置为 true 时,系统会优先使用 Homebrew 安装器来安装技能依赖(仅 macOS)。

监视器行为

• 当 watch 启用时,文件更改会在下一次代理轮次时应用
• watchDebounceMs 控制多次快速更改的防抖时间
• 这允许在不重启网关的情况下热重载技能

沙箱环境注意事项

技能键映射

在 entries 中使用的键通常是技能名称,但可以通过技能的 metadata.openclaw.skillKey 字段自定义:

---
name: My Awesome Skill
metadata:
  openclaw:
    skillKey: custom-key
---

这样配置时,应该使用 skills.entries["custom-key"] 而不是技能名称。