OpenClaw Skills 完全指南：如何自建AI技能扩展

Skills
, , , ,

OpenClaw Skills

引言：AI的「外挂大脑」

OpenClaw 的强大之处不仅在于它能连接各种工具和服务，更在于其高度可扩展的 Skills（技能）系统。如果说 AI 模型是大脑，那么 Skills 就是为这个大脑安装的「外挂模块」——每个技能都教会 AI 如何完成特定的任务。

本文将详细介绍如何在 OpenClaw 上创建自定义 Skills，从基础概念到实战开发，带你掌握这一强大功能。

什么是 OpenClaw Skill？

一个 Skill 本质上是一个包含以下内容的目录：

1
2
3
4
weather-checker/
├── SKILL.md          # 技能定义文件（核心）
└── scripts/
    └── get_weather.sh # 可选的辅助脚本

技能的核心：SKILL.md

SKILL.md 文件由两部分组成：

  1. YAML Frontmatter（元数据）：定义技能的基本信息和配置
  2. Markdown 指令：教导 AI 如何使用该技能

技能结构深度解析

1. 基础元数据（必需）

1
2
3
4
---
name: weather-checker
description: 检查指定城市的天气状况，使用 wttr.in 服务
---
  • name：技能的唯一标识符（小写，使用连字符）
  • description：简短描述，AI 会根据这个描述决定何时使用该技能

2. 高级元数据（可选）

1
2
3
4
5
6
7
8
9
10
metadata:
  {
    "openclaw": {
      "requires": {
        "bins": ["curl"],      # 需要 curl 命令
        "env": []              # 需要的环境变量
      },
      "os": ["darwin", "linux"] # 支持的操作系统
    }
  }

条件过滤（Gating）：OpenClaw 在加载技能时会检查这些条件，只有满足所有条件时，技能才会被激活。

3. 技能指令部分

在元数据之后，使用 Markdown 格式编写技能指令：

1
2
3
4
5
6
7
8
9
10
# 天气检查技能

使用 `curl` 命令通过 wttr.in 服务获取指定城市的天气信息。

## 使用方法

当用户询问天气时，使用以下命令：

```bash
curl -s "https://wttr.in/Taipei?format=3"

参数说明

  • format=3: 简洁的单行格式
  • lang=zh: 使用中文显示
1
2
3
4
5
6
7
8
9
10

## 实战：创建 weather-checker 技能

让我们一步步创建一个实用的天气检查技能。

### 步骤 1：创建技能目录

```bash
# 在 workspace 中创建技能目录
mkdir -p ~/.openclaw/workspace/skills/weather-checker/scripts

步骤 2：编写 SKILL.md

创建 skills/weather-checker/SKILL.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
---
name: weather-checker
description: 检查指定城市的天气状况，使用 wttr.in 服务
metadata:
  {
    "openclaw": {
      "requires": {
        "bins": ["curl"]
      }
    }
  }
---

# 天气检查技能

## 核心功能
使用 wttr.in 服务获取全球城市的实时天气信息。

## 基础用法
```bash
# 简洁格式
curl -s "https://wttr.in/Taipei?format=3"

# 中文详细报告
curl -s "https://wttr.in/Taipei?lang=zh"

高级用法

1
2
# 使用脚本获取天气
bash {baseDir}/scripts/get_weather.sh "Tokyo" "zh"

可用参数

  • ?format=3: 单行简洁格式
  • ?lang=zh: 中文界面
  • ?2: 显示未来2天预报
  • ?u: 使用英制单位
1
2
3
4
5
6
7
8
9
10
11
12
13
14

**关键技巧**：使用 `{baseDir}` 占位符引用技能目录的绝对路径。

### 步骤 3：添加辅助脚本

创建 `skills/weather-checker/scripts/get_weather.sh`：

```bash
#!/bin/bash
CITY="${1:-Taipei}"
LANG="${2:-zh}"

echo "查询 $CITY 的天气..."
curl -s "https://wttr.in/$CITY?lang=$LANG" | head -20

设置执行权限：

1
chmod +x skills/weather-checker/scripts/get_weather.sh

步骤 4：测试技能

重启 OpenClaw Gateway 或刷新技能：

1
2
3
4
5
# 重启 Gateway
openclaw gateway restart

# 或发送刷新指令
echo "刷新技能" | openclaw agent

现在你可以问 AI：「台北天气怎么样？」AI 会自动使用 weather-checker 技能来回答。

高级功能详解

1. 环境变量注入

在技能配置中注入环境变量：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// ~/.openclaw/openclaw.json
{
  "skills": {
    "entries": {
      "weather-checker": {
        "enabled": true,
        "env": {
          "DEFAULT_CITY": "Taipei",
          "WEATHER_API": "wttr.in"
        }
      }
    }
  }
}

2. API Key 管理

对于需要 API 密钥的技能：

1
2
3
4
5
6
7
8
9
metadata:
  {
    "openclaw": {
      "requires": {
        "env": ["OPENWEATHER_API_KEY"]
      },
      "primaryEnv": "OPENWEATHER_API_KEY"
    }
  }

然后在配置中提供密钥：

1
2
3
4
5
6
7
8
9
{
  "skills": {
    "entries": {
      "weather-checker": {
        "apiKey": "your_api_key_here"
      }
    }
  }
}

3. 操作系统限制

限制技能只能在特定平台运行：

1
2
3
4
5
6
7
8
9
metadata:
  {
    "openclaw": {
      "os": ["darwin"],  # 仅 macOS
      "requires": {
        "bins": ["say"]  # 需要 macOS 的 say 命令
      }
    }
  }

4. 技能优先级控制

1
2
3
4
5
6
7
8
---
name: my-skill
description: 我的技能
user-invocable: true           # 用户可通过斜杠命令调用
disable-model-invocation: false # 允许 AI 自动调用
command-dispatch: tool         # 直接调用工具（绕过 AI）
command-tool: exec             # 调用的工具名称
---

技能存放位置与优先级

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

  1. Workspace Skills (~/.openclaw/workspace/skills/)

    • 最高优先级
    • 适合项目特定的技能

  2. Managed Skills (~/.openclaw/skills/)

    • 系统级共享技能
    • 所有 agent 都可使用

  3. Bundled Skills (OpenClaw 内置)

    • 最低优先级
    • 系统预装技能

名称冲突时：Workspace 的技能会覆盖其他位置的同名技能。

使用 ClawHub 共享技能

ClawHub 是 OpenClaw 的官方技能市场（https://clawhub.com）。

发布技能到 ClawHub

  1. 确保技能目录结构正确
  2. 添加完整的文档
  3. 使用 clawhub CLI 发布：
1
2
3
4
5
6
7
8
# 登录 ClawHub
clawhub login

# 发布技能
clawhub publish skills/weather-checker

# 更新技能
clawhub publish skills/weather-checker --bump-version

从 ClawHub 安装技能

1
2
3
4
5
6
7
8
# 搜索技能
clawhub search weather

# 安装技能
clawhub install weather-checker

# 更新所有技能
clawhub update --all

最佳实践与安全建议

🛡️ 安全第一

  1. 谨慎使用 exec 工具：避免执行未经验证的用户输入
  2. 沙箱环境：对于高风险操作，使用沙箱环境
  3. 权限最小化：只授予必要的文件系统权限
  4. 输入验证：始终验证用户提供的参数

📝 编写高质量技能

  1. 清晰的描述：让 AI 准确理解何时使用该技能
  2. 完整的示例：提供多种使用场景的示例
  3. 错误处理：说明可能出现的错误和解决方法
  4. 依赖声明：在 metadata 中明确声明所有依赖

🔧 调试技巧

1
2
3
4
5
6
7
8
# 查看已加载的技能
openclaw skills list

# 检查特定技能的 eligibility
openclaw skills check weather-checker

# 查看技能加载日志
tail -f ~/.openclaw/logs/gateway.log | grep -i skill

实战案例：创建高级技能

案例：GitHub 项目管理技能

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
---
name: github-manager
description: 管理 GitHub 仓库、Issue 和 Pull Request
metadata:
  {
    "openclaw": {
      "requires": {
        "bins": ["gh"],
        "env": ["GITHUB_TOKEN"]
      },
      "install": [
        {
          "id": "brew",
          "kind": "brew",
          "formula": "gh",
          "bins": ["gh"],
          "label": "Install GitHub CLI via Homebrew"
        }
      ]
    }
  }
---

# GitHub 管理技能

## 核心功能
- 创建和管理 Issue
- 审查和合并 Pull Request
- 查看 CI/CD 状态
- 管理仓库设置

## 常用命令
```bash
# 列出 Issue
gh issue list --state open

# 创建 Pull Request
gh pr create --title "功能更新" --body "详细描述"

# 查看 CI 状态
gh run list --limit 5

自动化工作流

1
2
# 自动 rebase 并合并
gh pr merge 123 --rebase --auto

技能生命周期管理

版本控制

1
2
3
4
5
6
7
8
9
---
name: my-skill
version: 1.2.0
description: 我的技能 v1.2.0
changelog:
  - 1.2.0: 添加新功能 X
  - 1.1.0: 修复安全性问题
  - 1.0.0: 初始版本
---

向后兼容性

  • 保持 API 稳定
  • 使用版本号区分重大变更
  • 提供迁移指南

总结：成为 OpenClaw 技能大师

通过本文，你已经掌握了：

  1. 技能基础：理解 SKILL.md 的结构和组成
  2. 实战开发：创建完整的 weather-checker 技能
  3. 高级特性：使用 metadata 进行条件过滤和配置
  4. 技能管理：理解存放位置、优先级和 ClawHub
  5. 最佳实践：编写安全、高效的技能

下一步学习方向

  1. 集成外部 API：创建调用 REST API 的技能
  2. 文件处理技能：处理 PDF、图片、视频等文件
  3. 数据库技能：连接和操作数据库
  4. 自动化工作流：创建多步骤自动化技能

资源推荐

附录：完整示例技能

你可以在以下位置找到本文创建的完整示例：

  • ~/.openclaw/workspace/skills/weather-checker/
  • 或从 GitHub 获取：[示例仓库链接]

开始创造吧！ 每个你创建的技能都是对 AI 能力的扩展，也是对你工作流程的优化。

有问题或想要分享你的技能？欢迎在评论区交流！