OpenClaw 插件开发指南：为 AI 数字员工添加新技能

一、先搞懂：OpenClaw 是什么？

OpenClaw 是能动手的 AI 数字员工——它有大脑（大模型）、有手脚（技能插件），能自己执行任务：查天气、发邮件、操作浏览器、管理文件，甚至帮你写代码、做自动化。

它的核心亮点就是技能乐高化：不用改底层代码，像拼乐高一样，写个插件就能给 AI 加新技能，零编程基础也能快速上手。

简单说：OpenClaw = AI 大脑 + 技能插件生态，插件就是 AI 的'超能力'，咱们今天就教你亲手造这个超能力！

二、开发前必看：环境准备

先把基础环境搭好，所有命令都是官方最新稳定版，复制就能用。

1. 系统要求

操作系统：Windows（WSL2）/macOS/Linux
Node.js ≥ 22（官方强制要求，低版本会报错）
网络：能正常访问 GitHub（插件开发需要拉取官方模板）

2. 一键安装 OpenClaw

macOS/Linux 终端执行：

curl -fsSL https://openclaw.ai/install.sh | bash

Windows PowerShell 执行：

iwr -useb https://openclaw.ai/install.ps1 | iex

安装完成后，执行初始化命令：

openclaw onboard --install-daemon

3. 验证环境

输入 openclaw doctor，出现All checks passed就说明环境没问题，准备开干！

三、核心原理：OpenClaw 插件为啥叫'技能乐高'？

先别着急写代码，搞懂原理，后面开发事半功倍。

OpenClaw 的插件（官方叫Skill 技能），遵循AgentSkills 兼容规范，结构超级简单，就像乐高积木：

一个文件夹：插件的家，名字就是技能名
一个 SKILL.md 文件：插件的'身份证'，写清楚功能、参数、依赖
（可选）执行脚本：实现具体功能，支持 JS/Python/Shell

官方把技能分三类，咱们新手先学本地自定义技能，最安全、最容易落地：

捆绑技能：官方自带，不用改
托管技能：全局共享，所有 AI 数字员工都能用
工作区技能：项目专属，优先级最高（咱们就写这个）

加载优先级：工作区技能 > 托管技能 > 捆绑技能，不用担心冲突，改起来超方便。

打个比方：AI 数字员工是'外卖员'，插件就是'外卖箱里的工具'——你想让他送鲜花，就加个'鲜花配送插件'；想让他送文件，就加个'文件传输插件'，不用重新造一个外卖员。

四、实战开始：30 分钟写第一个插件（查天气技能）

咱们直接上手，做一个自然语言查天气的插件，用户说'帮我查北京明天的天气'，AI 就能自动返回结果，全程零难度。

第一步：创建插件文件夹

找到你的 OpenClaw 工作区，新建文件夹路径：

你的工作区/skills/weather-query

skills是官方规定的技能目录，必须放在这里，AI 才能识别。

第二步：写插件'身份证'——SKILL.md

这是插件最重要的文件，官方规定格式，复制下面的代码，改改文字就能用：

---
name: weather-query
description: 自然语言查询城市天气，支持今日/明日/近 3 天
metadata: {"openclaw":{"emoji":"🌤️","requires":{"env":["WEATHER_API_KEY"],"os":["darwin","linux","win32"]}}}
user-invocable: true
---
# 天气查询技能
## 功能说明
支持用户用自然语言查询任意城市的天气，自动解析城市名和时间，调用公共天气接口返回结果。
## 使用方法
用户直接说：
- 帮我查上海今天的天气
- 北京明天会下雨吗
- 广州近 3 天天气怎么样
## 实现逻辑
1. 从用户指令提取**城市**和**时间**
2. 加载天气 API 密钥
3. 调用接口获取数据
4. 格式化结果返回给用户

重点解释：

name：插件唯一名称，不能重复
description：插件功能描述，AI 靠这个识别什么时候调用
metadata：官方配置，指定插件图标、依赖的环境变量（天气 API 密钥）
user-invocable: true：允许用户直接调用，设为 false 只能 AI 自动调用

第三步：写功能实现脚本（index.js）

在 weather-query 文件夹里新建 index.js，这是插件的'核心大脑'，代码真实可运行，来自官方插件模板：

// 导入 OpenClaw 官方工具库（原生支持，无需额外安装）
const { tool, parseUserIntent } = require('openclaw-sdk');

// 注册天气查询工具
tool.register('weather-query', async (params) => {
  try {
    // 解析用户指令：提取城市和时间
    const { city, time = '今日' } = parseUserIntent(params.content, {
      city: { type: 'city', required: true },
      time: { type: 'enum', options: ['今日', '明日', '近 3 天'] }
    });

    // 从环境变量获取 API 密钥（官方推荐，安全不泄露）
    const apiKey = process.env.WEATHER_API_KEY;
    if (!apiKey) {
      return '请先在环境变量配置 WEATHER_API_KEY';
    }

    // 调用天气接口（合规公共接口，无风控风险）
    const response = await fetch(`https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=${apiKey}&units=metric&lang=zh_cn`);
    const data = await response.json();

    // 格式化返回结果
    return `🌤️ ${city}${time}天气：${data.weather[0].description}，温度${data.main.temp}℃，湿度%`;
  }  (error) {
     ;
  }
});

代码说明：

用的是 OpenClaw 官方 SDK，原生支持，不是第三方桥接，稳定不报错
环境变量存密钥，符合官方安全规范，不会泄露信息
用的是公共天气接口，合规可访问，无封号风险

第四步：配置环境变量

在工作区的 .env 文件里添加天气 API 密钥（去天气官网免费申请）：

WEATHER_API_KEY=你的密钥

第五步：加载插件并测试

重启 OpenClaw 网关：openclaw restart
打开 AI 对话界面，输入：帮我查北京明天的天气
秒出天气结果，插件开发完成！

全程算下来，也就 20 多分钟，真正的零基础上手。

五、进阶技巧：让你的插件更专业

写完基础插件，再加点小技巧，直接变身资深开发者。

1. 插件安全规范（官方强制要求）

密钥必须存在环境变量，绝对不能写在代码里
第三方接口必须用 HTTPS，禁止 HTTP 明文传输
不随意获取用户本地文件，遵循沙箱机制
社区插件要经过代码审计，官方认证插件更安全

2. 插件优化小技巧

给插件加 emoji：在 metadata 里配置，界面更美观
支持多系统：metadata 里添加 os 配置，Windows/mac/Linux 都能用
错误处理：加 try/catch，给用户友好提示，别报一堆英文
自动刷新：开启技能监视器，改完代码不用重启，自动生效

3. 插件发布（可选）

如果想分享给别人用，可上传到 ClawdHub（OpenClaw 官方技能市场），按照官方模板提交，审核通过后就能被全球开发者使用。

六、避坑指南：新手最容易踩的 5 个坑

插件放错位置：必须放在工作区/skills 目录，否则 AI 识别不到
Node.js 版本太低：必须≥22，低版本直接报错，别侥幸
密钥写在代码里：违规又危险，一定要用环境变量
插件名称重复：优先级高的插件会覆盖低优先级的，改个唯一名字
没重启网关：改完配置不重启，插件不生效，记得重启

七、写在最后：AI 插件开发，真的没那么难

很多新手觉得 AI 开发要懂高数、会复杂编程，其实完全不是。

OpenClaw 的技能乐高化生态，就是把复杂的底层逻辑封装好，咱们只需要关心'给 AI 加什么技能'，不用管底层怎么运行。

不管你是编程专业的大学生，还是刚入行的初级程序员，都能快速上手。一个简单的插件，就是你踏入 AI 开发的第一步。

AI 时代，能给 AI'造技能'的人，永远不缺机会。赶紧动手，写出你的第一个 AI 插件吧！

OpenClaw 插件开发指南：为 AI 数字员工添加新技能