从零开发一个 OpenClaw Skill 技能插件

2026-01-29 · 6 分钟技能插件

概述

OpenClaw 的技能插件（Skill）系统让你可以为 AI 助手扩展自定义能力。每个技能本质上是一个包含 SKILL.md 文件的目录，通过 YAML 前置元数据定义行为。

技能目录结构

一个典型的技能插件目录如下：

my-weather-skill/
├── SKILL.md          # 必需：技能定义文件
├── tools/
│   └── get_weather.sh
└── prompts/
    └── weather_prompt.md

编写 SKILL.md

SKILL.md 是技能的核心定义文件，顶部使用 YAML frontmatter 声明元数据：

---
name: weather-lookup
description: 查询全球城市的实时天气信息
homepage: https://github.com/example/weather-skill
user-invocable: true
disable-model-invocation: false
command-dispatch: weather
---

# 天气查询技能

当用户询问天气相关问题时，使用 get_weather 工具获取实时数据。

## 使用方式
用户可以直接说"查一下北京天气"来触发此技能。

YAML 字段详解

字段	必需	说明
`name`	是	技能唯一标识符
`description`	是	技能功能描述
`homepage`	否	项目主页链接
`user-invocable`	否	用户是否可以直接调用（默认 true）
`disable-model-invocation`	否	禁止模型自动调用（默认 false）
`command-dispatch`	否	绑定的命令关键词

技能加载优先级

OpenClaw 按以下优先级加载同名技能：

工作区技能（workspace）：项目目录下的 .openclaw/skills/
托管技能（hosted）：~/.openclaw/skills/
内置技能（built-in）：OpenClaw 自带技能

高优先级的技能会覆盖低优先级的同名技能。

门控条件（requires）

使用 requires 字段声明技能的运行前置条件：

---
name: docker-manager
description: Docker 容器管理技能
requires:
  bins:
    - docker
    - docker-compose
  env:
    - DOCKER_HOST
  config:
    - channels.discord.enabled
---

bins：检查系统中是否安装了指定命令行工具
env：检查是否定义了指定环境变量
config：检查 OpenClaw 配置中是否存在指定字段

不满足条件的技能会被自动禁用，不会出现在可用技能列表中。

skills.entries 配置

在主配置中通过 skills.entries 为技能注入 API 密钥和环境变量：

// ~/.openclaw/openclaw.json
{
  "skills": {
    "entries": {
      "weather-lookup": {
        "env": {
          "WEATHER_API_KEY": "${WEATHER_API_KEY}"
        }
      },
      "translator": {
        "env": {
          "DEEPL_AUTH_KEY": "${DEEPL_AUTH_KEY}"
        }
      }
    }
  }
}

这种方式确保敏感凭据不会硬编码在技能文件中。

发布到 ClawHub

ClawHub 是 OpenClaw 的官方技能注册中心，提供便捷的分发管理：

# 安装远程技能
clawhub install weather-lookup

# 更新已安装的技能
clawhub update weather-lookup

# 同步所有已安装技能到最新版本
clawhub sync

发布自己的技能

# 在技能目录下初始化发布配置
cd my-weather-skill
clawhub init

# 发布到 ClawHub
clawhub publish

安全注意事项

安装第三方技能时请注意以下安全风险：

审查 SKILL.md 内容：确认技能请求的权限合理
检查 requires 声明：了解技能需要访问哪些系统资源
限制环境变量暴露：仅通过 skills.entries 注入必要的变量
优先使用官方或知名开发者的技能

// 可以全局禁用未审核的技能
{
  "skills": {
    "trustLevel": "verified-only"
  }
}

完整开发示例

以下是一个简单的"系统信息查询"技能的完整代码：

---
name: sysinfo
description: 查询当前系统的硬件和软件信息
user-invocable: true
requires:
  bins:
    - uname
---

# 系统信息查询

当用户询问系统信息时，执行以下命令获取数据：
- `uname -a` 获取内核信息
- `df -h` 获取磁盘使用情况
- `free -h` 获取内存使用情况

将结果以清晰的表格形式呈现给用户。

故障排查

技能未出现在可用列表中？

检查 requires 条件是否全部满足
确认技能目录在正确的加载路径下

技能加载但未被调用？

确认 disable-model-invocation 未设置为 true
检查 command-dispatch 关键词是否与用户输入匹配