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

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

---
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}℃，湿度${data.main.humidity}%`;
  } catch (error) {
    return `查询失败：${error.message}，请检查城市名或 API 密钥`;
  }
});

代码说明：

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

第四步：配置环境变量

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

WEATHER_API_KEY=你的密钥

第五步：加载插件并测试

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

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

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

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

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

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

2. 插件优化小技巧

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

3. 插件发布（可选）

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

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

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

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

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

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

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

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