自定义技能开发

本文将教你如何创建、测试和发布自己的 OpenClaw 技能，让你的 AI 助手获得独特的能力。

什么是自定义技能？

自定义技能是你自己创建的扩展模块，可以让 OpenClaw 执行特定的任务。你可以：

封装常用操作为技能
集成内部 API 或服务
创建团队专属工具
分享给社区帮助他人

技能结构

一个技能就是一个包含 SKILL.md 文件的文件夹：

my-skill/
├── SKILL.md          # 技能定义文件（必需）
├── README.md         # 说明文档（可选）
├── config.json       # 配置文件（可选）
└── scripts/          # 脚本文件（可选）
    └── helper.sh

SKILL.md 格式

SKILL.md 是技能的核心文件，包含 YAML 前置信息和指令内容：

---
name: my-custom-skill
description: 我的自定义技能，用于执行特定任务
tags: [automation, productivity]
user-invocable: true
---

# My Custom Skill

这个技能可以帮助你...

## 使用方法

当用户请求执行某项任务时，AI 应该：

1. 首先确认用户的需求
2. 执行相关操作
3. 返回结果

## 注意事项

- 确保有足够的权限
- 处理可能的错误情况

创建第一个技能

步骤 1：创建技能目录

# 创建技能文件夹
mkdir -p ~/.openclaw/skills/hello-world

# 进入目录
cd ~/.openclaw/skills/hello-world

步骤 2：创建 SKILL.md

---
name: hello-world
description: 一个简单的打招呼技能
tags: [demo, beginner]
user-invocable: true
---

# Hello World 技能

这是一个入门示例技能。

## 功能

当用户说"打招呼"时，友好地问候用户。

## 指令

- 询问用户的姓名
- 用友好的语气问候
- 可以添加一些有趣的问候语

步骤 3：测试技能

重启 OpenClaw 会话，然后测试：

用户：打个招呼
AI：你好！我是你的 AI 助手，很高兴见到你！请问你叫什么名字？

进阶：带配置的技能

添加环境变量

---
name: my-api-tool
description: 调用自定义 API 的工具
metadata:
  openclaw:
    requires:
      env: ["MY_API_KEY"]
    primaryEnv: "MY_API_KEY"
---

# My API Tool

这个技能用于调用内部 API。

## 配置

需要在 ~/.openclaw/openclaw.json 中配置：

{
  "skills": {
    "entries": {
      "my-api-tool": {
        "enabled": true,
        "apiKey": "YOUR_API_KEY"
      }
    }
  }
}

## 使用

当用户请求调用 API 时...

进阶：带脚本的技能

创建包含执行脚本的技能：

---
name: backup-tool
description: 自动备份工具
metadata:
  openclaw:
    requires:
      bins: ["rsync"]
---

# Backup Tool

自动备份指定目录。

## 用法

当用户请求备份时：

1. 确认要备份的目录
2. 确认备份目标位置
3. 执行备份命令：

```bash
rsync -av --progress /source/ /destination/
```

4. 报告备份结果

技能配置选项

YAML 前置字段

字段	说明	必需
name	技能唯一标识	✅
description	技能描述	✅
tags	标签列表	❌
user-invocable	是否支持斜杠命令	❌
metadata	元数据配置	❌

metadata.openclaw 配置

字段	说明
requires.bins	需要的命令行工具
requires.env	需要的环境变量
requires.config	需要的配置项
primaryEnv	主要 API Key 环境变量
emoji	技能图标
homepage	技能主页 URL

发布到 ClawHub

1. 登录 ClawHub

clawhub login

2. 发布技能

clawhub publish ./my-skill   --slug my-skill   --name "My Skill"   --version 1.0.0   --tags latest   --changelog "首次发布"

3. 更新技能

# 修改后更新版本
clawhub publish ./my-skill   --slug my-skill   --version 1.1.0   --changelog "添加新功能"

技能开发最佳实践

1. 清晰的描述

让 AI 和用户都能理解技能的用途。

2. 详细的指令

在 SKILL.md 中提供清晰的步骤说明。

3. 错误处理

考虑各种可能的错误情况并提供处理方案。

4. 安全考虑

不要在技能中硬编码敏感信息。

5. 版本管理

使用语义化版本号（semver）。

调试技巧

1. 查看日志

openclaw logs --follow

2. 测试技能加载

openclaw skills list

3. 检查配置

openclaw doctor

常见问题

Q: 技能没有被加载？

检查：

SKILL.md 格式是否正确
文件位置是否正确
前置 YAML 是否有效

Q: 如何调试技能？

查看 OpenClaw 日志，确认技能加载状态。

Q: 技能冲突怎么办？

技能按优先级加载：工作区 > 本地 > 内置。可以重命名技能避免冲突。

Q: 如何删除已发布的技能？

clawhub delete --slug my-skill --yes

示例：实用技能模板

API 调用技能

---
name: api-caller
description: 通用 API 调用工具
metadata:
  openclaw:
    requires:
      env: ["API_ENDPOINT", "API_KEY"]
    primaryEnv: "API_KEY"
---

# API Caller

调用 REST API 并返回结果。

## 用法

1. 确认要调用的端点
2. 确认请求方法和参数
3. 执行请求并返回响应

文件处理技能

---
name: file-processor
description: 批量文件处理工具
---

# File Processor

批量处理文件。

## 支持的操作

- 格式转换
- 重命名
- 压缩/解压
- 内容替换