Skills 技能系统

Skills 是 OpenClaw 的核心能力扩展机制。技能本质上是一份指导文档，教会 Agent 如何完成特定任务。本章介绍技能的概念、安装方法以及如何创建自定义技能。

什么是 Skill？

Skill 是一个包含 SKILL.md 文件的目录。SKILL.md 是一个带有 YAML frontmatter 的 Markdown 文件，包含对 Agent 的指导说明。技能不是可执行代码，而是告诉 Agent"在什么情况下应该做什么"的文档。

为什么是文档而非代码？

OpenClaw 的设计哲学是让 AI 模型理解指令，而不是硬编码行为。技能文件会被注入到 Agent 的系统提示词中，模型根据这些指导来决定如何使用工具完成任务。这种方式的优势：

灵活性：模型可以根据上下文调整行为
可读性：技能内容一目了然，便于理解和修改
跨平台：不依赖特定编程语言或运行时

技能的作用

一个典型的技能告诉 Agent：

什么情况下应该使用这个技能
应该调用哪些工具
如何处理输入和输出
有哪些限制和注意事项

技能加载位置

OpenClaw 从多个位置加载技能，按优先级从高到低：

位置	优先级	作用范围
`<workspace>/skills/`	最高	当前 Agent 专属
`~/.openclaw/skills/`	中等	所有 Agent 共享
Bundled（随安装附带）	最低	全局内置
`skills.load.extraDirs`	最低	自定义共享目录

当存在同名技能时，优先级高的会覆盖优先级低的。

安装技能

使用 ClawHub 搜索

ClawHub 是 OpenClaw 的官方技能市场，收录了大量社区贡献的技能。

# 搜索关键词相关技能
openclaw skills search weather

# 搜索特定功能的技能
openclaw skills search "calendar"

# 查看搜索结果限制
openclaw skills search "browser" --limit 10

安装技能

# 从 ClawHub 安装技能
openclaw skills install skill-name

# 安装特定版本
openclaw skills install skill-name --version 1.2.0

# 强制覆盖已存在的技能
openclaw skills install skill-name --force

安装后，技能会被放到当前工作空间的 skills/ 目录下。

管理已安装技能

# 列出已安装技能
openclaw skills list

# 查看技能详情
openclaw skills info skill-name

# 检查技能就绪状态
openclaw skills check

# 只显示就绪的技能
openclaw skills list --eligible

# 更新单个技能
openclaw skills update skill-name

# 更新所有已安装技能
openclaw skills update --all

更新到特定版本

# 更新到指定版本
openclaw skills update skill-name --version 1.3.0

SKILL.md 文件格式

每个技能的核心是 SKILL.md 文件，包含 YAML frontmatter（元数据）和 Markdown 正文（指令内容）。

基本结构

---
name: my-skill
description: 一句话描述技能的用途，Agent 用它判断何时使用此技能
metadata:
  openclaw:
    os:
      - darwin
      - linux
    requires:
      bins:
        - git
      config:
        - agents.defaults.workspace
---

# 技能名称

这里写详细的技能说明，告诉 Agent 如何完成任务。

## 使用场景

描述什么情况下应该使用这个技能。

## 操作步骤

1. 第一步做什么
2. 第二步做什么
3. ...

## 注意事项

- 重要限制
- 需要确认的操作
- 错误处理方式

Frontmatter 字段说明

字段	必填	说明
`name`	是	技能唯一标识符，使用 snake_case 格式
`description`	是	一行描述，Agent 用它判断何时激活此技能
`metadata.openclaw.os`	否	操作系统过滤，如 `["darwin", "linux"]`
`metadata.openclaw.requires.bins`	否	需要的二进制文件（必须在 PATH 中）
`metadata.openclaw.requires.anyBins`	否	需要的二进制文件（至少一个存在）
`metadata.openclaw.requires.env`	否	需要的环境变量（或通过配置提供）
`metadata.openclaw.requires.config`	否	需要的配置项路径
`metadata.openclaw.always`	否	设为 `true` 时始终加载，跳过其他过滤条件
`metadata.openclaw.emoji`	否	macOS Skills UI 中显示的图标
`metadata.openclaw.homepage`	否	技能主页 URL，显示在 Skills UI
`metadata.openclaw.primaryEnv`	否	与 `skills.entries.<name>.apiKey` 关联的环境变量名
`metadata.openclaw.skillKey`	否	配置中使用的键名（默认使用 name）
`metadata.openclaw.install`	否	安装器配置数组（brew/node/go/uv/download）
`homepage`	否	技能主页 URL（顶层字段，等同于 metadata.openclaw.homepage）
`user-invocable`	否	`true/false`（默认 `true`），是否暴露为用户斜杠命令
`disable-model-invocation`	否	`true/false`（默认 `false`），是否从模型提示词中排除
`command-dispatch`	否	设为 `tool` 时，斜杠命令直接派发到工具
`command-tool`	否	当 `command-dispatch: tool` 时调用的工具名
`command-arg-mode`	否	参数模式，默认 `raw`（原始参数传递给工具）

重要提示

Frontmatter 只支持单行键值对
metadata 必须是单行 JSON 对象
在指令中使用 {baseDir} 引用技能目录路径

description 的重要性

description 字段非常关键，Agent 根据它来判断是否应该使用这个技能。描述应该：

简洁明确，一行说完
包含关键词，方便匹配
说明触发条件

好的描述示例：

description: 当用户询问天气、气温、降雨情况时使用此技能

不好的描述示例：

description: 天气技能  # 太模糊，Agent 不知道何时使用

创建自定义技能

当官方技能无法满足需求时，可以创建自定义技能。

创建技能目录

# 在工作空间创建技能目录
mkdir -p ~/.openclaw/workspace/skills/my-skill

编写 SKILL.md

创建 ~/.openclaw/workspace/skills/my-skill/SKILL.md：

---
name: daily-standup
description: 当用户需要生成日报、站会总结或工作汇报时使用此技能
---

# 每日站报生成器

这个技能帮助用户生成每日工作总结。

## 触发条件

用户请求以下内容时激活：
- 生成日报
- 准备站会内容
- 总结今天的工作
- 汇报工作进展

## 工作流程

1. **收集信息**
   - 使用 `exec` 工具执行 `git log --since="today"` 查看今天的提交
   - 读取项目中的 TODO.md 或任务文件
   - 查看 MEMORY.md 中的日程安排

2. **整理内容**
   - 按项目分类整理已完成的工作
   - 列出进行中的任务
   - 标记遇到的问题和阻塞

3. **生成报告**
   使用以下格式：

   ## 今日完成
   - [任务1描述]
   - [任务2描述]

   ## 进行中
   - [任务描述] - 当前状态

   ## 明日计划
   - [计划任务]

   ## 问题与阻塞
   - [问题描述]

## 注意事项

- 不要编造内容，只报告有据可查的工作
- 如果无法获取 git 信息，询问用户
- 敏感项目名称需要脱敏处理

工具定义（可选）

Skills 可以定义自定义工具 Schema，让 Agent 知道有哪些可用的工具及其参数。工具定义放在 frontmatter 的 tools 字段中。

内置工具 vs 自定义工具

OpenClaw 已经内置了丰富的工具：

工具类别	工具名称	说明
文件操作	`read`, `write`, `edit`, `glob`, `grep`	文件读写和搜索
命令执行	`exec`	执行 Shell 命令
浏览器	`browser_*` 系列	浏览器自动化
记忆	`memory_search`, `memory_get`	记忆检索
网络	`fetch`	HTTP 请求

大多数情况下，Skills 只需告诉 Agent 何时以及如何使用这些内置工具，而不需要定义新工具。

定义自定义工具

如果需要定义新工具，在 frontmatter 中添加 tools 字段：

---
name: my-api-tool
description: 调用自定义 API 的工具
tools:
  - name: call_my_api
    description: 调用我的自定义 API
    parameters:
      type: object
      properties:
        endpoint:
          type: string
          description: API 端点路径
        method:
          type: string
          enum: [GET, POST, PUT, DELETE]
          default: GET
        data:
          type: object
          description: 请求体数据
      required: [endpoint]
---

工具 Schema 遵循 JSON Schema 格式，与 OpenAI/Anthropic 的工具定义格式兼容。

工具实现

定义工具 Schema 只是第一步，还需要有实际的工具实现。有两种方式：

插件方式：开发插件提供工具实现，Skills 作为文档指导 Agent 使用
内置工具包装：Skill 指导 Agent 使用内置工具完成特定任务

对于大多数场景，第二种方式更简单：

---
name: git-operations
description: 执行 Git 操作，如提交、分支、合并等
---

# Git 操作技能

## 可用工具

使用内置的 `exec` 工具执行 Git 命令。

## 常用操作

### 提交更改
使用命令：`git add -A && git commit -m "message"`

### 创建分支
使用命令：`git checkout -b branch-name`

### 查看状态
使用命令：`git status`

斜杠命令配置

Skills 可以配置为用户可调用的斜杠命令，让用户直接通过命令触发特定功能。

基本配置

---
name: daily-report
description: 生成每日工作报告
user-invocable: true
---

# 每日报告

执行此命令时，生成包含以下内容的工作报告：
- 今日完成的任务
- 进行中的工作
- 明日计划

用户可以通过 /daily-report 直接调用此技能。

直接派发到工具

配置 command-dispatch: tool 可以让斜杠命令绕过模型，直接调用工具：

---
name: system-status
description: 查看系统状态
user-invocable: true
command-dispatch: tool
command-tool: exec
---

此技能直接调用 exec 工具执行预定义命令。

调用时工具会收到以下参数：

{
  "command": "<用户输入的参数>",
  "commandName": "system-status",
  "skillName": "system-status"
}

参数传递

command-arg-mode 控制参数如何传递：

模式	说明
`raw`（默认）	原始参数字符串直接传递给工具

禁用模型调用

如果技能只供用户调用，不需要模型自动触发：

---
name: admin-command
description: 管理员专用命令
user-invocable: true
disable-model-invocation: true
---

这样技能不会出现在模型的可用技能列表中，只能通过斜杠命令调用。

测试技能

# 重启 Gateway 或开始新会话
# 然后测试技能是否生效
openclaw agent --message "帮我生成今天的站报"

安装器配置

Skills 可以定义安装器，让 macOS Skills UI 能够自动安装所需的依赖。

安装器类型

类型	说明	适用场景
`brew`	Homebrew 包管理器	macOS 系统工具
`node`	npm 包	Node.js 工具和库
`go`	Go 包	Go 编写的工具
`uv`	Python 包（uv）	Python 工具
`download`	直接下载二进制	预编译的可执行文件

配置示例

---
name: my-skill
description: 需要外部工具的技能
metadata:
  openclaw:
    install:
      # Homebrew 安装
      - type: brew
        package: my-tool
      
      # Node.js 安装
      - type: node
        package: my-cli-tool
      
      # Go 安装
      - type: go
        package: github.com/user/my-tool@latest
      
      # Python 安装
      - type: uv
        package: my-python-tool
      
      # 直接下载
      - type: download
        url: https://github.com/user/tool/releases/download/v1.0/tool-linux-amd64
        archive: tar.gz
        targetDir: ~/.openclaw/tools/my-skill
      -
        os: ["darwin", "linux"]
---

安装器选择逻辑

当配置多个安装器时，Gateway 会按优先级选择：

如果系统有 brew，优先使用 brew 安装
否则选择第一个可用的安装器

Node 包管理器配置

可以通过配置指定 Node 包管理器：

{
  "skills": {
    "install": {
      "nodeManager": "pnpm"
    }
  }
}

可选值：npm（默认）、pnpm、yarn、bun。

Go 安装自动处理

如果 go 不在 PATH 中但系统有 brew，Gateway 会先通过 Homebrew 安装 Go，并设置 GOBIN。

安全注意事项

第三方技能风险

将第三方技能视为不可信代码：

安装前仔细阅读 SKILL.md 内容
了解技能会调用哪些工具
注意是否有执行任意命令的风险

安全建议

使用沙箱：对不可信输入和危险工具启用沙箱

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

限制工具：按需限制 Agent 可用的工具

{
  "tools": {
    "deny": ["exec", "browser"]
  }
}

审批策略：设置技能安装审批

{
  "skills": {
    "installPolicy": "approve"
  }
}

敏感信息处理

不要在 Skills 中硬编码敏感信息：

# 错误示例 ❌
API Key: sk-xxxxx
密码: mypassword

# 正确示例 ✓
使用环境变量 MY_API_KEY
通过 skills.entries.my-skill.apiKey 配置

使用配置注入 API Key：

{
  "skills": {
    "entries": {
      "my-skill": {
        "apiKey": "${MY_API_KEY}"
      }
    }
  }
}

环境注入安全

skills.entries.*.env 和 skills.entries.*.apiKey 注入的环境变量作用于 Agent 运行时，而非沙箱内部。保持敏感信息远离提示词和日志。

路径安全

工作空间技能发现只接受：

技能根目录
SKILL.md 文件的实际路径在配置的根目录内

这防止了通过符号链接访问预期之外的文件。

危险代码扫描

Gateway 在安装技能依赖时会运行内置的危险代码扫描器：

critical 级别发现默认阻止安装
suspicious 级别仅警告

注意：openclaw skills install <slug> 直接下载 ClawHub 技能文件夹，不使用此扫描流程。

技能最佳实践

单一职责

一个技能只做一件事。不要创建"万能技能"，而是针对特定任务创建专门的技能。

推荐：daily-standup、code-review、meeting-notes

不推荐：work-helper（太宽泛）

清晰的触发条件

description 和文档开头的触发条件要清晰，让 Agent 准确判断何时使用。

---
description: 当用户明确要求发送邮件或提到"发邮件"、"send email"时使用
---

## 触发条件

只在以下情况使用此技能：
- 用户明确说"发送邮件"
- 用户要求"通知某人"
- 用户要求"发消息到邮箱"

不要在以下情况使用：
- 用户只是在讨论邮件
- 用户问"怎么发邮件"（这是咨询，不是执行）

明确的工具使用

告诉 Agent 使用哪些工具，以及如何使用：

## 可用工具

此技能使用以下工具：

- `exec`：执行 shell 命令
- `read`：读取文件内容
- `write`：写入文件

### 命令示例

查看今日 git 提交：
```bash
git log --since="midnight" --oneline --author="$(git config user.name)"

读取任务文件：

read ~/tasks.md

### 安全考虑

如果技能涉及敏感操作，必须明确警告：

```markdown
## 安全警告

此技能会执行以下敏感操作：
- 发送邮件（不可撤销）
- 提交代码到远程仓库

### 必须确认

在执行以下操作前，必须向用户确认：
- 发送邮件
- 推送代码
- 删除文件

提供示例

给 Agent 提供具体示例，帮助它理解预期输出：

## 输出示例

成功生成日报后，输出格式如下：

📅 2026-04-03 工作日报

完成事项

完成用户认证模块重构
修复 #123 号 bug

进行中

API 文档编写（进度 60%）

明日计划

完成文档编写
开始集成测试

技能目录结构

一个完整的技能目录可能包含：

my-skill/
├── SKILL.md          # 必需：技能说明文件
├── templates/        # 可选：模板文件
│   └── report.md
├── examples/         # 可选：示例文件
│   └── sample.json
└── README.md         # 可选：人类阅读的说明

只有 SKILL.md 是必需的，其他文件可以按需添加。如果技能需要读取模板或示例，可以在 SKILL.md 中说明如何访问这些文件。

ClawHub CLI

除了使用 openclaw skills 命令，还可以使用独立的 clawhub CLI 进行更高级的操作。

安装 ClawHub CLI

# 使用 npm 安装
npm install -g clawhub

# 或使用 bun 安装
bun install -g clawhub

认证登录

# 浏览器登录
clawhub login

# 使用 token 登录
clawhub login --token YOUR_TOKEN

# 查看当前登录状态
clawhub whoami

# 登出
clawhub logout

发布技能

# 发布技能到 ClawHub
clawhub skill publish ./my-skill \
  --slug my-skill \
  --name "My Skill" \
  --version 1.0.0 \
  --tags "productivity,automation" \
  --changelog "Initial release"

# 同步多个技能
clawhub sync

# 干运行（预览发布内容）
clawhub skill publish ./my-skill --dry-run

管理已发布技能

# 删除技能
clawhub delete my-skill --yes

# 恢复已删除的技能
clawhub undelete my-skill --yes

技能与插件的关系

概念	说明	包含内容
Skill	指导文档	`SKILL.md` + 可选资源文件
Plugin	扩展包	可以包含工具、技能、配置等

技能是轻量级的，只需要一个 Markdown 文件。插件是更完整的扩展，可以包含：

自定义工具（实际的代码实现）
技能文档
配置模板
依赖声明

如果你想添加新的工具能力，需要开发插件。如果只是教 Agent 更好地使用现有工具，创建技能就足够了。

常见问题

技能没有被触发

可能原因：

description 不够清晰，Agent 无法判断何时使用
技能文件位置不正确
会话需要重启才能加载新技能

解决方法：

# 确认技能位置
ls ~/.openclaw/workspace/skills/

# 检查 SKILL.md 格式
cat ~/.openclaw/workspace/skills/my-skill/SKILL.md

# 开始新会话测试
openclaw agent --message "测试触发技能的关键词"

技能冲突

多个技能的 description 重叠时，Agent 可能难以选择。

解决方法：确保每个技能的 description 有明确区分，避免模糊描述。

技能安装失败

# 检查网络连接
openclaw skills search test

# 使用强制覆盖
openclaw skills install skill-name --force

# 手动下载并安装
# 从 ClawHub 网站下载 zip 文件，解压到 skills/ 目录

下一步

Memory 记忆系统 - 配置 AI 的长期记忆
定时任务 - 设置自动化任务
多 Agent 协作 - 打造 AI 团队

什么是 Skill？​

为什么是文档而非代码？​

技能的作用​

技能加载位置​

安装技能​

使用 ClawHub 搜索​

安装技能​

管理已安装技能​

更新到特定版本​

SKILL.md 文件格式​

基本结构​

Frontmatter 字段说明​

重要提示​

description 的重要性​

创建自定义技能​

创建技能目录​

编写 SKILL.md​

工具定义（可选）​

内置工具 vs 自定义工具​

定义自定义工具​

工具实现​

斜杠命令配置​

基本配置​

直接派发到工具​

参数传递​

禁用模型调用​

测试技能​

安装器配置​

安装器类型​

配置示例​

安装器选择逻辑​

Node 包管理器配置​

Go 安装自动处理​

安全注意事项​

第三方技能风险​

安全建议​

敏感信息处理​

环境注入安全​

路径安全​

危险代码扫描​

技能最佳实践​

单一职责​

清晰的触发条件​

明确的工具使用​

提供示例​

完成事项​

进行中​

明日计划​

技能目录结构​

ClawHub CLI​

安装 ClawHub CLI​

认证登录​

发布技能​

管理已发布技能​

技能与插件的关系​

常见问题​

技能没有被触发​

技能冲突​

技能安装失败​

下一步​

什么是 Skill？

为什么是文档而非代码？

技能的作用

技能加载位置

安装技能

使用 ClawHub 搜索

安装技能

管理已安装技能

更新到特定版本

SKILL.md 文件格式

基本结构

Frontmatter 字段说明

重要提示

description 的重要性

创建自定义技能

创建技能目录

编写 SKILL.md

工具定义（可选）

内置工具 vs 自定义工具

定义自定义工具

工具实现

斜杠命令配置

基本配置

直接派发到工具

参数传递

禁用模型调用

测试技能

安装器配置

安装器类型

配置示例

安装器选择逻辑

Node 包管理器配置

Go 安装自动处理

安全注意事项

第三方技能风险

安全建议

敏感信息处理

环境注入安全

路径安全

危险代码扫描

技能最佳实践

单一职责

清晰的触发条件

明确的工具使用

提供示例

完成事项

进行中

明日计划

技能目录结构

ClawHub CLI

安装 ClawHub CLI

认证登录

发布技能

管理已发布技能

技能与插件的关系

常见问题

技能没有被触发

技能冲突

技能安装失败

下一步