11.21 技能系统

OpenClaw 使用兼容 AgentSkills 的技能文件夹来教导代理如何使用工具。每个技能都是一个包含 SKILL.md 的目录,其中包含 YAML 前置数据和使用说明。

概述

技能是教学层——包含 SKILL.md 的目录——用于指导代理如何使用工具。技能与工具不同,工具是实际的可执行程序或 API,而技能是告诉代理如何正确使用这些工具的说明文档。

技能与工具的区别

• 工具:实际可执行的功能,如浏览器控制、文件操作、Web搜索等
• 技能:教导代理如何使用工具的说明文档和配置

启用和禁用技能

在 ~/.openclaw/openclaw.json 中通过 skills.entries.<name>.enabled 控制技能的启用状态:

{
  "skills": {
    "entries": {
      "nano-banana-pro": {
        "enabled": true
      }
    }
  }
}

还可以通过 skills.allowBundled 过滤内置技能。

安装技能

使用 ClawHub CLI 命令安装和管理技能:

# 安装技能到 ./skills 目录
clawhub install <skill>

# 更新所有技能
clawhub update --all

# 同步所有技能
clawhub sync --all

创建自定义技能

创建一个包含 SKILL.md 文件的文件夹,文件需包含必要的 YAML 前置数据:

技能文件结构

---
name: nano-banana-pro
description: 通过 Gemini 3 Pro Image 生成或编辑图像
metadata:
  openclaw:
    requires:
      bins: ["uv"]
      env: ["GEMINI_API_KEY"]
---

## 使用说明

这里是技能的详细使用说明...

## 示例

示例命令和用法...

必需的前置数据字段

• name - 技能名称
• description - 技能描述
• metadata (可选) - 元数据配置,可包含依赖要求

依赖要求

可以通过 metadata.openclaw.requires 指定技能的依赖:

• bins - 需要的二进制程序
• env - 需要的环境变量

配置覆盖

可以在配置文件中为特定技能设置环境变量和 API 密钥:

{
  "skills": {
    "entries": {
      "nano-banana-pro": {
        "enabled": true,
        "apiKey": "YOUR_API_KEY",
        "env": {
          "GEMINI_API_KEY": "YOUR_KEY"
        }
      }
    }
  }
}

技能的工作原理

• 技能在会话开始时加载快照
• 修改技能后需要新建会话或启用观察者实现热重载
• 插件技能遵循相同的优先级规则
• 远程 macOS 节点如果允许 system.run,可以启用 macOS 专用技能

安装器偏好

技能安装器的依赖安装优先级:

1. brew (Homebrew)
2. node (Node.js)
3. go (Go)
4. download (直接下载)

可以通过 skills.install.nodeManager 控制使用的 Node.js 包管理器(npm/pnpm/yarn/bun)。

性能考虑

XML 技能列表的大小计算:

• 基础大小:约 195 字符
• 每个技能:约 97 字符 + 转义字段的长度