龙虾文档

主题

技能开发指南 ​

概述 ​

技能（Skill）是 OpenClaw 的核心扩展机制。每个技能本质上是一个以 SKILL.md 为核心的目录，定义了 Agent 在特定场景下应该如何使用工具。本指南教你从零开发自己的技能。

最小技能 ​

一个技能只需要一个 SKILL.md 文件：

bash
mkdir -p ~/.openclaw/workspace/skills/hello-world
markdown
<!-- ~/.openclaw/workspace/skills/hello-world/SKILL.md -->
---
name: hello-world
description: 一个简单的问候技能
version: 1.0.0
---

# Hello World

当用户打招呼时，用热情友好的方式回复，并告诉他今天是星期几。

保存后，Agent 会自动加载这个技能——无需重启。

SKILL.md 格式 ​

YAML Frontmatter ​

文件顶部 --- 包裹的部分是元数据：

yaml
---
name: weather                  # 必填：技能名称（小写、连字符）
description: 查询全球天气预报    # 必填：触发条件（AI 据此判断何时使用）
version: 1.2.0                 # 必填：语义化版本号
author: your-name              # 可选：作者
requirements:                  # 可选：系统依赖
  - curl
  - jq
metadata:
  openclaw:
    requires:
      env:                     # 所需环境变量
        - WEATHER_API_KEY
      bins:                    # 所需系统命令
        - curl
---

description 很关键

description 决定了 AI 何时调用这个技能。写得越具体，触发越精准。例如：

  • ❌ "天气相关" — 太模糊
  • ✅ "查询指定城市的实时天气和未来 7 天预报" — 精准

Markdown 指令 ​

Frontmatter 之后的 Markdown 内容是给 AI 的「操作手册」：

markdown
# Weather Skill

## 使用场景
当用户询问天气、温度、是否需要带伞等问题时触发。

## 操作步骤
1. 从用户消息中提取城市名称
2. 使用 curl 调用天气 API：
   ```bash
   curl -s "https://api.weatherapi.com/v1/forecast.json?key=$WEATHER_API_KEY&q={city}&days=3&lang=zh"
  1. 解析返回的 JSON 数据
  2. 以友好的格式展示天气信息

输出格式 ​

  • 城市名称 + 当前温度
  • 天气状况描述
  • 未来 3 天概览
  • 是否需要带伞/防晒的建议

注意事项 ​

  • 如果城市名称不明确，先确认
  • API 返回错误时，告知用户稍后重试

## 目录结构

完整的技能目录结构：

```text
my-skill/
├── SKILL.md          # 必须 — 技能定义文件
├── scripts/          # 可选 — 辅助脚本
│   ├── setup.sh      #   安装依赖
│   └── query.js      #   API 调用脚本
├── templates/        # 可选 — 提示词模板
│   └── report.hbs
└── README.md         # 可选 — 使用说明

脚本引用 ​

在 SKILL.md 中可以引用技能目录下的脚本，使用 {baseDir} 占位符：

markdown
执行以下命令查询天气：
```bash
node {baseDir}/scripts/query.js --city "{city}"

`{baseDir}` 会在运行时自动替换为技能的实际目录路径。

## 环境变量配置

敏感信息通过环境变量传递，**不要硬编码**：

```bash
# 方式一：全局环境变量
openclaw config set env.WEATHER_API_KEY "your-api-key"

# 方式二：技能级配置
# 在 openclaw.json 中
json
{
  "skills": {
    "weather": {
      "api_key": "your-api-key",
      "default_city": "Beijing"
    }
  }
}

开发流程 ​

1. 创建技能 ​

bash
# 在工作区创建（最高优先级）
mkdir -p ~/.openclaw/workspace/skills/my-skill

# 或在用户级创建
mkdir -p ~/.openclaw/skills/my-skill

2. 编写 SKILL.md ​

参考上面的格式示例。

3. 验证 ​

bash
# 检查技能格式
openclaw skills check

# 查看已加载的技能
openclaw skills list

4. 测试 ​

直接在对话中测试：

text
你：帮我查一下北京天气

Agent：[触发 weather 技能]
正在查询北京天气...
北京今天晴，25°C，空气质量良好...

5. 调试 ​

如果技能没有被触发：

  1. 检查 description 是否足够描述触发场景
  2. 检查日志：openclaw logs --follow
  3. 确认技能在列表中：openclaw skills list
  4. 确认环境变量已配置

实战案例：Tavily 搜索 ​

以社区热门技能 tavily-search 为例：

markdown
---
name: tavily-search
description: 使用 Tavily API 进行 Agent 优化的网络搜索
version: 2.1.0
metadata:
  openclaw:
    requires:
      env:
        - TAVILY_API_KEY
      bins:
        - node
---

# Tavily Search

## 何时使用
当用户需要搜索网络信息、查找最新新闻、验证事实时使用。

## 搜索方式
执行以下脚本进行搜索：
```bash
node {baseDir}/scripts/search.js --query "{search_query}" --max-results 5

结果处理 ​

  1. 按相关性排序展示搜索结果
  2. 提供来源链接
  3. 综合多个结果给出简明答案
  4. 如结果不满意，可调整搜索关键词重试

## 性能注意事项

| 活跃技能数量 | 影响 | 建议 |
|-------------|------|------|
| 1-5 个 | 几乎无影响 | 正常使用 |
| 5-10 个 | 上下文略增 | 日常使用推荐上限 |
| 10-20 个 | 明显增加 Token 消耗 | 按需启用 |
| 20+ 个 | 严重影响性能 | 应避免 |

每次对话会在启动时「快照」当前活跃技能，采用懒加载——脚本仅在被触发时才执行。

## 安全提醒

::: danger 技能安全
2026 年 2 月的审计发现，约 12% 的 ClawHub 技能存在恶意行为或安全漏洞。开发和安装技能时请注意：

1. **先安装 `skill-vetter`** — 安全审查工具
2. **不要在脚本中硬编码密钥**
3. **审查第三方技能的 scripts/ 目录**
4. **优先使用高星标、高下载量的技能**
:::

## 发布到 ClawHub

```bash
# 1. 登录
openclaw clawhub login

# 2. 发布
openclaw clawhub publish ./my-skill

发布前检查清单：

  • [ ] SKILL.md 包含完整的 frontmatter（name、description、version）
  • [ ] 添加了 README.md 说明使用方法
  • [ ] 不包含任何敏感信息
  • [ ] 脚本中有适当的错误处理
  • [ ] 在本地测试通过

基于 MIT 协议发布

© 2025-2026 longxia.best — OpenClaw 中文社区 · GitHub