42-OpenClaw插件开发:从入门到发布

引言

OpenClaw 的插件系统让每个人都可以扩展它的能力。你可以用插件添加新的工具、渠道、甚至全新的 AI 模型。但很多人在开发过程中会遇到各种坑——权限问题、签名验证失败、发布流程不清晰…

今天，我们从零开始，手把手教你开发并发布一个 OpenClaw 插件。

正文

插件架构概述

OpenClaw 插件本质是一个独立的功能包，包含：

my-plugin/
├── plugin.json          # 插件元数据
├── src/
│   ├── index.ts         # 入口文件
│   ├── tools/           # 工具定义
│   ├── handlers/        # 事件处理器
│   └── schemas/         # 数据结构
├── package.json
└── README.md

插件通过 manifest 声明自己的能力：

// plugin.json
{
  "name": "weather-plugin",
  "version": "1.0.0",
  "description": "天气查询插件",
  "author": "your-name",

  "permissions": ["network", "storage"],

  "tools": [
    {
      "name": "get_weather",
      "description": "查询指定城市的天气",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "城市名称"
          }
        },
        "required": ["city"]
      }
    }
  ],

  "channels": ["feishu", "wechat"],
  "apis": ["wttr.in"]
}

开发环境搭建

# 1. 安装插件开发脚手架
npm install -g @openclaw/create-plugin

# 2. 创建新插件
openclaw plugin create weather-plugin

# 3. 目录结构
cd weather-plugin
npm install

# 4. 启动开发模式（热重载）
openclaw plugin dev

# 5. 测试插件
openclaw plugin test

实现插件逻辑

// src/index.ts
import { Plugin, PluginContext } from '@openclaw/sdk'

// 定义工具实现
const getWeatherTool = {
  name: 'get_weather',
  description: '查询指定城市的天气',

  async execute(params: { city: string }, context: PluginContext) {
    const { city } = params

    // 调用天气 API
    const response = await fetch(`https://wttr.in/${encodeURIComponent(city)}?format=j1`)
    const data = await response.json()

    const current = data.current_condition[0]

    return {
      city,
      temperature: current.temp_C + '°C',
      weather: current.weatherDesc[0].value,
      humidity: current.humidity + '%',
      wind: current.windspeedKmph + ' km/h',
      feelsLike: current.FeelsLikeC + '°C'
    }
  }
}

// 定义事件处理器
const eventHandlers = {
  'message:received': async (message, context) => {
    // 自动回复天气（当用户问"北京天气"时）
    const match = message.text.match(/(\S+)天气/)
    if (match) {
      const city = match[1]
      const weather = await getWeatherTool.execute({ city }, context)

      await context.reply(`🌤️ ${city}当前天气：
温度：${weather.temperature}
天气：${weather.weather}
湿度：${weather.humidity}
风速：${weather.wind}
体感温度：${weather.feelsLike}`)
    }
  }
}

// 导出插件
export default new Plugin({
  name: 'weather-plugin',
  version: '1.0.0',

  tools: [getWeatherTool],
  handlers: eventHandlers,

  // 生命周期钩子
  async onInstall(context: PluginContext) {
    console.log('天气插件已安装')
  },

  async onUninstall(context: PluginContext) {
    console.log('天气插件已卸载')
  }
})

配置与调试

# openclaw.yml
plugins:
  weather-plugin:
    enabled: true
    config:
      default_city: "北京"
      temperature_unit: "celsius"  # celsius / fahrenheit
    debug: true  # 开启调试日志

开发过程中查看调试日志：

# 实时查看插件日志
openclaw logs --plugin weather-plugin --follow

# 查看特定错误
openclaw logs --plugin weather-plugin --level error

# 测试工具调用
openclaw plugin test weather-plugin --tool get_weather --params '{"city":"上海"}'

发布插件到市场

# 1. 确保通过所有测试
openclaw plugin test weather-plugin

# 2. 登录账号
openclaw login

# 3. 构建发布版本
openclaw plugin build weather-plugin

# 4. 发布到插件市场
openclaw plugin publish weather-plugin --tag latest

# 5. 设置版本（语义化版本）
openclaw plugin publish weather-plugin --version 1.0.0 --tag beta

发布后填写市场信息：

// marketplace.json
{
  "title": "🌤️ 天气查询插件",
  "short_description": "一句话查询任意城市天气",
  "screenshots": [
    "https://example.com/screenshot1.png"
  ],
  "categories": ["utility", "lifestyle"],
  "keywords": ["weather", "天气", "forecast"]
}

总结

插件开发四步走：

1. 创建项目：openclaw plugin create

2. 编写逻辑：实现 tools 和 handlers

3. 本地调试：openclaw plugin dev + openclaw logs

4. 发布上线：openclaw plugin build && publish