OpenClaw 自定义 Skill 开发：从入门到实战

在前两篇文章中，我们学习了如何安装技能和组合技能创建工作流。但有时候，现有的技能无法满足你的特殊需求，这时就需要自己开发一个自定义 Skill。本文将详细介绍如何从零开始开发一个 OpenClaw 技能。

为什么需要自定义 Skill？

尽管 ClawHub 上有丰富的技能可供选择，但在以下场景下你需要自己开发技能：

特定业务需求：你的业务有独特的流程和逻辑
内部系统集成：需要连接公司内部的工具和服务
定制化功能：需要特定的功能组合
复用代码：将常用的脚本封装成可复用的技能

Skill 的基本结构

一个标准的 OpenClaw Skill 包含以下文件：

my-skill/
├── SKILL.md          # 技能定义文件（必需）
├── README.md          # 说明文档（可选）
├── run.sh             # 执行脚本（可选）
├── config.yaml        # 配置文件（可选）
└── scripts/           # 辅助脚本目录
    └── helper.sh

SKILL.md 文件结构

SKILL.md 是技能的核心文件，定义了技能的元信息和工具：

# My Skill

_技能描述：这是一个示例技能，用于..._

## 工具

本技能提供以下工具：

### say-hello

说 hello。

**参数：**
- name: 名字
  type: string
  required: true
  description: 要问候的名字

## 示例

\`\`\`bash
# 调用示例
openclaw skill run my-skill --tool say-hello --param name "张三"
\`\`\`

实战：创建一个天气预报技能

让我们通过一个完整的示例来学习开发技能。我们将创建一个天气预报技能。

步骤 1：创建技能目录

mkdir -p weather-skill
cd weather-skill

步骤 2：编写 SKILL.md

# Weather Skill

_获取指定城市的天气信息_

## 工具

### get-weather

获取指定城市的当前天气。

**参数：**
- location: 城市名称
  type: string
  required: true
  description: 要查询的城市

**返回：**
- 天气状况
- 温度
- 湿度
- 风速

## 示例

\`\`\`bash
# 查询北京天气
weather-skill get-weather --location 北京
\`\`\`

步骤 3：实现技能逻辑

创建 run.sh 脚本：

#!/bin/bash

# 天气技能实现
# 使用 wttr.in 免费天气 API

TOOL=$1
shift

case $TOOL in
    get-weather)
        LOCATION=$1
        curl -s "wttr.in/${LOCATION}?format=j1"
        ;;
    *)
        echo "Unknown tool: $TOOL"
        exit 1
        ;;
esac

赋予执行权限：

chmod +x run.sh

步骤 4：测试技能

./run.sh get-weather 北京

步骤 5：安装到 OpenClaw

cp -r weather-skill ~/.openclaw/skills/

Skill 的高级特性

配置管理

使用 YAML 配置文件来管理技能配置：

# config.yaml
api:
  key: ${WEATHER_API_KEY}
  endpoint: "https://api.weather.com"
  
defaults:
  location: "北京"
  units: "metric"

cache:
  enabled: true
  ttl: 3600

在脚本中读取配置：

# 读取配置
CONFIG_FILE="$(dirname "$0")/config.yaml"

# 使用 yq 读取配置
API_KEY=$(yq eval '.api.key' "$CONFIG_FILE")
DEFAULT_LOCATION=$(yq eval '.defaults.location' "$CONFIG_FILE")

依赖管理

如果技能需要外部依赖，在 SKILL.md 中声明：

## 依赖

- curl (用于 HTTP 请求)
- jq (用于 JSON 解析)
- yq (用于 YAML 配置)

## 安装依赖

\`\`\`bash
# macOS
brew install curl jq yq

# Ubuntu/Debian
sudo apt-get install curl jq
pip install yq
\`\`\`

错误处理

添加完善的错误处理：

#!/bin/bash

set -e

TOOL=$1
shift

error() {
    echo "Error: $1" >&2
    exit 1
}

case $TOOL in
    get-weather)
        LOCATION=$1
        [ -z "$LOCATION" ] && error "Location is required"
        
        RESULT=$(curl -s "wttr.in/${LOCATION}?format=j1" 2>&1)
        [ $? -ne 0 ] && error "Failed to fetch weather data"
        
        echo "$RESULT"
        ;;
esac

日志记录

添加日志功能便于调试：

#!/bin/bash

LOG_FILE="${HOME}/.openclaw/logs/weather-skill.log"

log() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" >> "$LOG_FILE"
}

log "Tool called: $TOOL"

发布技能到 ClawHub

开发完成后，你可以将技能发布到 ClawHub 与社区分享：

准备发布

添加 LICENSE 文件
完善 README.md
确保代码质量

发布命令

# 登录 ClawHub
clawhub login

# 进入技能目录
cd my-skill

# 发布
clawhub publish \
  --name "Weather Skill" \
  --slug weather-skill \
  --version 1.0.0 \
  --category utility \
  --changelog "Initial release"

技能开发最佳实践

代码规范

单一职责：每个技能只完成一个功能
清晰命名：工具名和参数名要语义化
完善文档：SKILL.md 要详细清晰

性能优化

缓存结果：对于重复查询，添加缓存
超时控制：设置合理的请求超时
并行处理：独立任务使用并行执行

安全考虑

敏感信息：使用环境变量而非硬编码
输入验证：验证所有用户输入
最小权限：只请求必要的权限

测试覆盖

单元测试：测试核心函数
集成测试：测试与外部服务交互
端到端测试：测试完整流程

常见问题排查

技能不被识别

检查 SKILL.md 格式是否正确
确认技能目录在正确位置
查看 OpenClaw 日志

工具调用失败

检查脚本是否有执行权限
验证依赖是否已安装
查看错误日志

性能问题

添加缓存减少重复请求
优化脚本逻辑
检查网络延迟

总结

通过本文，你应该已经掌握了开发自定义 OpenClaw 技能的全流程：

理解 Skill 的基本结构
能够创建完整的技能项目
掌握配置管理、错误处理等高级特性
了解如何发布和分享技能

下一篇文章我们将介绍「Webhook 集成」，教你如何让 OpenClaw 与外部系统实时交互。敬请期待！

相关链接：