OpenClaw_技能机制详解
OpenClaw 是一个强大的 AI 助手框架，其核心是灵活的技能系统。本文将深入解析 OpenClaw 技能的目录结构、加载机制、匹配原理，帮助你快速上手开发自定义技能。
OpenClaw 技能机制详解：从零开始打造你的 AI 助手技能
摘要：OpenClaw 是一个强大的 AI 助手框架，其核心是灵活的技能系统。本文将深入解析 OpenClaw 技能的目录结构、加载机制、匹配原理，帮助你快速上手开发自定义技能。
一、技能目录结构
1.1 标准目录结构树
skill-name/ # 技能根目录（小写 + 连字符命名）
│
├── SKILL.md # 【必需】技能说明文件（唯一必需）
├── _meta.json # 【可选】技能元数据（版本、作者等）
│
├── scripts/ # 【可选】可执行脚本目录
│ ├── main.js # 主脚本文件
│ ├── helper.py # 辅助脚本
│ └── results/ # 【可选】执行结果输出目录
│ └── result-*.json # 执行结果文件
│
├── references/ # 【可选】参考文档目录 (Agent 读)
│ ├── api-docs.md # API 文档
│ ├── schema.json # 数据结构定义
│ └── workflows.md # 工作流程说明
│
├── assets/ # 【可选】资源文件目录（Agent 用）
│ ├── templates/ # 模板文件
│ │ └── template.html # HTML 模板
│ ├── images/ # 图片资源
│ │ └── logo.png # Logo 图片
│ └── fonts/ # 字体文件
│ └── custom.ttf # 自定义字体
│
├── hooks/ # 【可选】钩子脚本目录（自动触发钩子）
│ ├── on-load.sh # 加载时钩子
│ └── on-complete.py # 完成时钩子
│
└── .clawhub/ # 【可选】ClawHub 发布配置
└── config.json # 发布配置文件
1.2 SKILL.md 文件结构
SKILL.md 是技能的核心文件，包含 YAML frontmatter 和 Markdown 正文两部分：
---
# YAML frontmatter 开始标记
name: video-generator # 技能名称（小写 + 连字符，必须与目录名一致）
description: 视频生成技能，自动调用视频生成接口，无需二次确认。 # 技能描述（触发条件，最重要！）
homepage: https://github.com/xxx/xxx # 【可选】项目主页 URL
metadata: # 【可选】元数据配置
openclaw: # OpenClaw 特定配置
emoji: "🎬" # 【可选】技能图标 emoji
os: ["darwin", "linux"] # 【可选】支持的操作系统
requires: # 【可选】依赖要求
bins: ["node", "curl"] # 需要的命令行工具（技能安装/运行时检查）
env: ["API_KEY"] # 需要的环境变量（技能运行时检查）
config: ["channels.discord"] # 需要的配置项（技能安装时检查）
install: # 【可选】安装指令列表
- id: brew # 安装项 ID 用于引用
kind: brew # 安装方式（brew/apt/npm 等）使用哪个包管理器
formula: "node" # 安装包名 要安装的具体包
bins: ["node"] # 安装后提供的命令 用于验证安装成功
label: "Install Node.js" # 安装说明文字 显示给用户的提示
---
# YAML frontmatter 结束标记
# 技能说明正文
# Markdown 格式的详细说明
## 功能
# 功能列表
- ✅ 自动检测视频生成意图
- ✅ 自动调用三个接口
- ✅ 完善的错误处理
## 使用方式
# 使用说明
当用户说：
- "生成视频" # 触发词示例 1
- "做个视频" # 触发词示例 2
- "创建视频" # 触发词示例 3
会自动执行此技能。
## 接口流程
# 工作流程说明
开始 → 接口 1 → 接口 2 → 接口 3 → 完成
## 配置
# 配置说明
### 环境变量
## 脚本说明
# 脚本使用指南
执行主脚本：
```bash
node scripts/generate.js
---
## 二、技能加载时机
### 2.1 加载流程
┌─────────────────────────────────────────────────────────┐
│ 阶段 1: OpenClaw 启动时 │
│ ───────────────────────────────────────────────────── │
│ 只读取每个技能的 SKILL.md 中的 YAML frontmatter： │
│ - name：技能唯一标识，openclaw 用 name 去区分不同技能 │
│ - description：技能的"触发器"！分析用户输入匹配 description │
│ 关键词，判断用户想做什么，匹配成功之后自动加载技能 │
│ description 写得好，技能触发才准确！这是技能能否被正确 │
│ 调用的关键！ │
│ │
│ 用途：匹配用户消息，决定是否触发技能 │
│ 其他文件：完全不加载！ │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 阶段 2: 技能被触发后（按需加载） │
│ ───────────────────────────────────────────────────── │
│ 加载 SKILL.md 正文（Markdown 部分） │
│ 用途：了解如何执行技能 │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 阶段 3: 执行技能时（按需读取/执行） │
│ ───────────────────────────────────────────────────── │
│ 根据需要： │
│ - 执行 scripts/ 中的脚本 │
│ - 读取 references/ 中的文档 │
│ - 使用 assets/ 中的资源 │
│ - 运行 hooks/ 中的钩子 │
└─────────────────────────────────────────────────────────┘
### 2.2 加载时机表
| 时机 | 触发条件 | 加载内容 |
|------|----------|----------|
| Gateway 启动 | `openclaw gateway start` | 所有已安装技能 |
| 会话创建 | 新 agent 会话 | 技能列表 + SKILL.md 内容 |
| 技能安装 | `openclaw skills install <name>` | 新技能立即加载 |
| 热重载 | 技能文件变更 | 可选（需配置） |
### 2.3 举例说明
**非必选文件的用途：**
| 文件/目录 | 何时使用 | 谁使用 |
|-----------|----------|--------|
| scripts/ | 技能触发后，需要执行代码时 | Agent 执行或调用 |
| references/ | 技能触发后，需要查文档时 | Agent 读取参考 |
| assets/ | 技能触发后，需要模板/资源时 | Agent 使用或输出 |
| hooks/ | 技能加载/完成时 | 自动触发 |
| _meta.json | 几乎不用，仅元数据展示 | 可选信息 |
| .clawhub/ | 发布技能到 ClawHub 时 | 包管理器使用 |
**场景 1：用户说"今天天气怎么样？"**
1. OpenClaw 扫描所有技能的 SKILL.md frontmatter
→ 匹配到 `weather` 技能的 `description` 包含"天气"
→ 触发 `weather` 技能
2. 加载 `weather/SKILL.md` 正文
→ 读到"使用 curl wttr.in 查询天气"
3. Agent 执行指令
→ 直接运行 `curl` 命令
→ 不需要 `scripts/`（因为没有脚本）
→ 不需要 `references/`（因为很简单）
→ 不需要 `assets/`
**场景 2：用户说"生成视频"**
1. OpenClaw 匹配到 `video-generator` 技能
→ 触发技能
2. 加载 `video-generator/SKILL.md` 正文
→ 读到"执行 scripts/generate.js"
3. Agent 执行指令
→ 运行 `node scripts/generate.js` ← 使用 `scripts/`
→ 脚本保存结果到 `scripts/results/` ← 使用 `results/`
→ 不需要 `references/`（因为逻辑在脚本里）
→ 不需要 `assets/`（因为没有模板）
**场景 3：用户说"帮我写个 React 组件"**
1. OpenClaw 匹配到 `react-component-builder` 技能
→ 触发技能
2. 加载 `SKILL.md` 正文
→ 读到"使用 assets/templates/component.jsx 模板"
→ 读到"参考 references/react-patterns.md"
3. Agent 执行
→ 读取 `assets/templates/component.jsx` ← 使用 `assets/`
→ 参考 `references/react-patterns.md` ← 使用 `references/`
→ 生成代码给用户
> **核心原则**：非必选文件是技能功能的扩展，不是加载机制的必需。技能越复杂，越可能需要这些文件；简单技能可以只有 `SKILL.md` 就够了！
---
## 三、技能匹配机制
### 3.1 如何知道用哪个技能
OpenClaw 使用 **语义匹配** 而非精确匹配：
- 基于 `description` 字段进行关键词匹配
- 支持模糊匹配和同义词识别
- 匹配优先级：精确匹配 > 语义匹配 > 关键词匹配
### 3.2 编写优秀的 description
`description` 是技能的"触发器"，写得好坏直接影响技能能否被正确调用：
**✅ 好的写法：**
```yaml
description: 天气查询技能，支持全球城市，返回温度、湿度、风力等信息
❌ 差的写法：
description: 一个技能 # 太模糊，无法匹配
建议：
- 包含核心功能关键词
- 列举常见触发场景
- 保持简洁但信息完整
3.3 调试技巧
如果技能没有被触发：
- 检查
name是否与目录名一致 - 检查
description是否包含足够的关键词 - 查看 Gateway 日志确认加载状态
- 尝试重启 Gateway 强制重新加载
四、最佳实践
4.1 命名规范
- 目录名和
name使用小写 + 连字符（如video-generator） - 避免使用空格、大写字母、特殊字符
- 名称应清晰表达技能功能
4.2 文件组织
- 简单技能：只保留
SKILL.md - 复杂技能：按需添加
scripts/、references/、assets/ - 保持目录结构清晰，便于维护
4.3 性能优化
description尽量精简，减少匹配开销- 大文件放在
assets/，按需加载 - 避免在启动时加载不必要的资源
五、总结
OpenClaw 技能系统的核心设计理念：
- 最小化必需文件 - 只有
SKILL.md是必需的 - 按需加载 - 只在需要时加载相关资源
- 语义匹配 - 基于
description智能匹配用户意图 - 灵活扩展 - 支持脚本、文档、模板、钩子等多种扩展方式
掌握这些机制，你就可以轻松开发出自己的 OpenClaw 技能，让 AI 助手更强大！
参考资料
作者：妙思 🐈⬛
发布日期：2026-03-09
标签：OpenClaw AI 技能开发 自动化 Agent
小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用
更多推荐
6
0- 0
已为社区贡献2条内容
所有评论(0)