技能系统

技能教会 OpenClaw 代理如何使用工具和执行任务。它们使用与 AgentSkills 兼容的格式，包含 SKILL.md 文件。

什么是技能？

OpenClaw 技能是：

包含 SKILL.md 文件的目录，包含指令和元数据
与 AgentSkills 兼容 - 遵循标准格式
从多个位置加载，具有优先级排序
热重载 - 更改自动应用
声明式 - 在 YAML 前置元数据中指定要求

技能加载位置

技能按优先级顺序从三个位置加载：

工作区技能: <工作区>/skills（最高优先级）
托管/本地技能: ~/.openclaw/skills
捆绑技能: 随安装包含（最低优先级）

较高优先级的技能会覆盖同名的较低优先级技能。

SKILL.md 文件格式

每个技能是一个包含带有 YAML 前置元数据的 SKILL.md 文件的目录：

最小示例

---
name: my-skill
description: 此技能功能的简要描述
---

# 我的技能

关于代理如何使用此技能的详细说明。

## 用法

告诉代理："使用 my-skill 做某事"

## 示例

- "使用 my-skill 生成图像"
- "使用 my-skill 处理数据"

带元数据的完整示例

---
name: nano-banana-pro
description: 通过 Gemini 3 Pro Image 生成或编辑图像
homepage: https://github.com/example/nano-banana-pro
user-invocable: true
disable-model-invocation: false
command-dispatch: tool
metadata: {"openclaw": {"requires": {"bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"]}, "os": ["darwin", "linux"]}}
---

# Nano Banana Pro

使用 Gemini 3 Pro Image 模型生成和编辑图像。

## 用法

要求代理生成或编辑图像：
- "生成一张日落的图像"
- "编辑这张图片添加一只猫"

## 要求

- 必须安装 `uv` 命令
- 必须设置 `GEMINI_API_KEY` 环境变量
- 必须在配置中启用浏览器控制

## 实现

此技能使用 Gemini API 生成图像...

前置元数据字段

必需字段

name - 唯一的技能标识符（slug 格式）
description - 向代理显示的简要描述

可选字段

homepage - 技能文档或仓库的 URL
user-invocable - 技能是否显示为斜杠命令（默认：true）
disable-model-invocation - 从模型提示中排除（默认：false）
command-dispatch - 设置为 tool 以进行直接工具调度
metadata - 用于加载过滤器和要求的 JSON 对象

加载过滤器（门控）

使用 metadata.openclaw 控制技能何时加载：

要求二进制文件

metadata: {"openclaw": {"requires": {"bins": ["curl", "jq", "python3"]}}}

仅当 PATH 中所有指定命令可用时才加载技能。

要求环境变量

metadata: {"openclaw": {"requires": {"env": ["API_KEY", "SECRET_TOKEN"]}}}

仅当设置了所有指定的环境变量时才加载技能。

要求配置

metadata: {"openclaw": {"requires": {"config": ["browser.enabled", "voice.enabled"]}}}

仅当所有指定的配置路径为真时才加载技能。

平台限制

metadata: {"openclaw": {"os": ["darwin", "linux"]}}

仅在指定平台上加载技能（darwin、linux、win32）。

组合要求

metadata: {
  "openclaw": {
    "requires": {
      "bins": ["uv"],
      "env": ["GEMINI_API_KEY"],
      "config": ["browser.enabled"]
    },
    "os": ["darwin"]
  }
}

ClawHub - 技能注册表

ClawHub 是 OpenClaw 技能的公共注册表。

安装技能

# 安装技能
clawhub install nano-banana-pro

# 安装到特定位置
clawhub install peekaboo --to ./skills

# 安装多个技能
clawhub install skill-one skill-two skill-three

更新技能

# 更新特定技能
clawhub update nano-banana-pro

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

# 同步所有技能（获取最新版本）
clawhub sync --all

搜索技能

# 按关键字搜索
clawhub search "图像生成"

# 浏览类别
clawhub browse --category automation

技能信息

# 显示技能详情
clawhub info nano-banana-pro

# 列出已安装的技能
clawhub list

配置覆盖

在 ~/.openclaw/openclaw.json 中覆盖技能设置：

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: {
          source: "env",
          provider: "default",
          id: "GEMINI_API_KEY"
        },
        env: {
          GEMINI_API_KEY: "your-key-here"
        },
        config: {
          endpoint: "https://custom-endpoint.com",
          timeout: 30000
        }
      },
      "peekaboo": {
        enabled: true,
        env: {
          SCREENSHOT_DIR: "/tmp/screenshots"
        }
      }
    }
  }
}

配置选项

enabled - 启用/禁用技能（默认：true）
apiKey - 带有源和提供商的 API 密钥配置
env - 此技能的环境变量
config - 技能特定配置

多代理场景

每个代理的技能

将技能放在工作区目录中以获得代理特定的技能：

~/.openclaw/workspaces/personal/skills/
~/.openclaw/workspaces/work/skills/

每个代理只能看到其工作区中的技能。

共享技能

将技能放在托管目录中供所有代理使用：

~/.openclaw/skills/

所有代理都可以使用这些技能。

额外的技能目录

在配置中添加额外的共享目录：

{
  skills: {
    load: {
      extraDirs: [
        "/opt/company-skills",
        "~/shared-skills"
      ]
    }
  }
}

技能热重载

OpenClaw 监视技能目录，并在 SKILL.md 更改时自动重新加载。

配置热重载

{
  skills: {
    load: {
      watch: true,  // 启用监视（默认：true）
      debounce: 500  // 防抖延迟（毫秒）
    }
  }
}

禁用热重载

{
  skills: {
    load: {
      watch: false
    }
  }
}

创建自定义技能

基本技能结构

my-skill/
├── SKILL.md          # 必需：技能定义
├── README.md         # 可选：文档
├── tool.py           # 可选：工具实现
└── requirements.txt  # 可选：依赖项

示例：天气技能

---
name: weather-check
description: 检查任何位置的天气
metadata: {"openclaw": {"requires": {"env": ["WEATHER_API_KEY"]}}}
---

# 天气检查

获取任何位置的当前天气和预报。

## 用法

询问代理：
- "旧金山的天气怎么样？"
- "东京明天会下雨吗？"
- "显示伦敦的 5 天预报"

## 实现

此技能使用 OpenWeather API 获取天气数据。

代理将：
1. 从您的查询中提取位置
2. 调用天气 API
3. 格式化并呈现结果

## 配置

设置您的 API 密钥：
```bash
export WEATHER_API_KEY="your-api-key"

或在配置中：

{
  skills: {
    entries: {
      "weather-check": {
        env: { WEATHER_API_KEY: "your-key" }
      }
    }
  }
}


### 发布到 ClawHub

1. 创建包含 `SKILL.md` 的技能目录
2. 在工作区中本地测试
3. 提交到 ClawHub：

```bash
clawhub publish ./my-skill

安全注意事项

将第三方技能视为不受信任

安装前审查技能代码
检查所需权限
验证作者声誉
阅读用户评论

沙箱

在沙箱环境中运行不受信任的技能：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",  // 沙箱所有代理
        runtime: "docker"
      }
    }
  }
}

密钥管理

使用 env 和 apiKey 字段存储凭据
永远不要在 SKILL.md 中硬编码密钥
将密钥排除在提示和日志之外
使用 SecretRef 进行安全凭据注入

权限

技能继承代理权限。限制代理能力：

{
  agents: {
    defaults: {
      permissions: {
        filesystem: "read-only",
        network: "restricted",
        exec: false
      }
    }
  }
}

令牌开销

技能作为紧凑的 XML 注入到系统提示中：

基础开销（≥1 个技能）：约 195 个字符
每个技能：约 97 个字符 + 名称 + 描述 + 位置长度

10 个技能的示例：约 1,500 个字符（约 375 个令牌）

最小化令牌使用

保持描述简洁
对很少使用的技能使用 disable-model-invocation: true
禁用未使用的技能
使用工作区特定的技能来减少全局技能数量

列出技能

通过 CLI

# 列出所有可用技能
openclaw skills

# 仅列出工作区技能
openclaw skills --workspace ~/.openclaw/workspaces/personal

# 列出捆绑技能
openclaw skills --bundled

# 列出托管技能
openclaw skills --managed

通过 ClawHub

# 列出已安装的技能
clawhub list

# 显示技能详情
clawhub info <技能名称>

故障排除

技能未加载

检查要求：

# 验证二进制文件
which curl jq python3

# 检查环境变量
env | grep API_KEY

# 验证配置
openclaw config get browser.enabled

技能不工作

检查网关日志：openclaw logs --follow
验证技能语法：审查 SKILL.md 前置元数据
测试要求：确保满足所有依赖项
重新加载技能：重启网关或等待热重载

技能之间的冲突

较高优先级的技能覆盖较低优先级：

工作区 > 托管 > 捆绑

从较低优先级位置删除冲突的技能。

最佳实践

使用描述性名称 - 清晰、唯一的技能标识符
编写清晰的描述 - 帮助代理理解何时使用技能
指定要求 - 使用元数据过滤器处理依赖项
先在本地测试 - 发布前在工作区中验证
版本化您的技能 - 使用 git 标签进行版本控制
彻底记录 - 包括用法示例和配置
保持技能专注 - 一个技能，一个目的
优雅地处理错误 - 提供清晰的错误消息

下一步

浏览 ClawHub 查看可用技能
了解配置指南
探索高级用法
查看 CLI 参考