14、OpenClaw（龙虾助手）Skill 开发完整规范（2026最新版）

最新推荐文章于 2026-07-23 09:38:07 发布

原创

最新推荐文章于 2026-07-23 09:38:07 发布 · 1.1k 阅读

AI 时代程序员必备技能

Codex、Claude Code、Cursor、Hermes Agent、OpenClaw等工程化实战专栏，讲透 AI 如何接管脏活累活

一键订阅

OpenClaw Skill 是扩展 AI 助手能力的核心机制，通过标准化的开发规范，你可以将任何业务逻辑接入 OpenClaw，打造完全符合需求的智能体。本指南基于 OpenClaw v2026.4.20+ 版本编写，覆盖声明式 Skill和原生代码 Skill两种开发模式，以及安全、测试、发布全流程规范。

文章目录

一、基础概念与类型

1.1 什么是 Skill

Skill 是 OpenClaw 的功能扩展单元，本质上是一组标准化的指令和代码，告诉 AI 智能体：

什么时候应该调用这个技能
调用时需要哪些参数
具体的执行步骤是什么
如何处理返回结果

核心区别：

Tool（工具）：AI 的手脚（文件读写、Shell 执行、网络请求等基础能力）
Skill（技能）：加载在工具上的具体业务逻辑（搜索、查天气、文档处理等）

1.2 Skill 类型与适用场景

类型	开发难度	功能上限	适用场景	示例
声明式 Skill（SKILL.md）	极低（无需代码）	中	简单流程、工具组合、提示词封装	天气查询、视频总结、文件格式转换
原生代码 Skill（JS/TS/Python）	中	极高	复杂逻辑、API 集成、高性能计算	数据库操作、图像处理、自动化工作流
MCP 兼容 Skill	中	极高	跨生态复用、第三方服务集成	飞书/微信对接、云服务操作

1.3 Skill 加载优先级（从高到低）

工作区 Skill：~/.openclaw/workspace/skills/（当前工作区专属）
托管 Skill：~/.openclaw/skills/（通过 ClawHub 安装的共享 Skill）
内置 Skill：随 OpenClaw 分发（官方维护，自动更新）

二、开发环境准备

2.1 系统要求

OpenClaw 版本 ≥ v2026.3.7
Node.js 版本 ≥ 22.x（原生代码 Skill 必需）
npm/yarn/pnpm 包管理器
代码编辑器（推荐 VS Code）

2.2 开发工具安装

# 安装 OpenClaw CLI（已安装可跳过）
npm install -g openclaw@latest

# 验证安装
openclaw --version

# 创建新技能项目（推荐使用脚手架）
openclaw skill init my-first-skill
cd my-first-skill

三、标准项目结构

3.1 声明式 Skill（最简结构）

my-simple-skill/
└── SKILL.md          # 唯一必需文件，包含元数据和执行指令

3.2 原生代码 Skill（完整结构）

my-code-skill/
├── SKILL.md          # 技能元数据和 AI 调用说明（必需）
├── manifest.json     # 权限声明和配置定义（v2026.4+ 必需）
├── package.json      # Node.js 依赖和脚本
├── index.ts          # 核心逻辑入口（JS/TS/Python）
├── src/              # 源代码目录
│   ├── utils.ts      # 工具函数
│   └── api.ts        # API 调用封装
├── tests/            # 测试用例
│   ├── unit.test.ts  # 单元测试
│   └── integration.test.ts # 集成测试
├── assets/           # 静态资源（图片、配置文件等）
└── README.md         # 用户文档

四、配置文件规范

4.1 SKILL.md 核心配置（所有 Skill 必需）

SKILL.md 是技能的"身份证"，AI 智能体只通过这个文件判断是否调用技能，必须严格遵循格式。

标准格式

---
name: weather-query
description: 当用户询问某个城市的天气、温度、气象情况时触发。调用 wttr.in API 返回简短天气摘要。
author: your-name
version: 1.0.0
license: MIT
homepage: https://github.com/your-name/weather-query
user-invocable: true
disable-model-invocation: false
metadata:
{
  "openclaw": {
    "emoji": "🌤️",
    "os": ["darwin", "linux", "win32"],
    "requires": {
      "bins": ["curl"],
      "env": ["WEATHER_API_KEY"],
      "config": ["units"]
    },
    "primaryEnv": "WEATHER_API_KEY"
  }
}
---

# 天气查询技能

## 触发条件
当用户询问以下内容时调用此技能：
- 某个城市的天气
- 温度、湿度、风力等气象信息
- 未来几天的天气预报

## 执行步骤
1. 从用户消息中提取城市名称
2. 如果城市名不明确（如"老家"、"这里"），先向用户确认
3. 执行以下命令获取天气数据：
   ```bash
   curl -s "https://wttr.in/${CITY}?format=3&lang=zh"

解析输出结果，用友好的自然语言回复用户

示例

用户：北京今天天气怎么样？
回复：北京今天晴，气温 15~25℃，微风。

错误处理

如果网络请求失败，提示"天气查询失败，请稍后再试"
如果城市不存在，提示"未找到该城市的天气信息"


#### 关键字段说明
- **name**：技能唯一标识，只能包含小写字母、数字和连字符
- **description**：**最重要的字段**，AI 完全依靠这个字段判断是否调用技能。必须清晰说明触发场景和功能
- **user-invocable**：是否可通过斜杠命令手动调用（默认 true）
- **disable-model-invocation**：是否从模型提示词中排除（默认 false）
- **metadata.openclaw.os**：支持的操作系统（darwin=macOS, linux, win32=Windows）
- **metadata.openclaw.requires**：技能运行所需的依赖和环境变量

### 4.2 manifest.json 权限声明（v2026.4+ 必需）
从 v2026.4 版本开始，所有原生代码 Skill 必须声明所需权限，否则会被沙箱限制。

```json
{
  "name": "my-code-skill",
  "version": "1.0.0",
  "permissions": {
    "fs": {
      "read": ["~/.openclaw/skills/my-code-skill/**", "/tmp/**"],
      "write": ["~/.openclaw/skills/my-code-skill/cache/**"]
    },
    "network": {
      "allow": ["api.example.com", "cdn.example.com"]
    },
    "tools": ["exec", "read", "write"],
    "env": ["MY_SKILL_API_KEY"]
  },
  "config": {
    "units": {
      "type": "string",
      "default": "metric",
      "description": "温度单位（metric/imperial）"
    }
  }
}

权限说明

fs：文件系统权限，必须明确声明可读写的目录
network：网络权限，必须明确声明可访问的域名
tools：可使用的内置工具（exec=执行命令, read=读文件, write=写文件）
env：可访问的环境变量

4.3 package.json 配置

{
   
   
  "name": "my-code-skill",
  "version": "1.0.0",
  "main": "index.ts",
  "dependencies": {
   
   
    "axios": "^1.6.0"
  },
  "devDependencies": {
   
   
    "@types/node": "^20.0.0",
    "typescript": "^5.0.0"
  },
  "scripts": {
   
   
    "build": "tsc",
    "test"