插件清单

Plugin Manifest（插件清单）定义了 OpenClaw 插件的元数据、类型、导出约定与生命周期。每个插件都必须在 package.json 中声明 openclaw 字段以被网关正确识别。

package.json 要求

一个合规的 OpenClaw 插件 package.json 最小结构：

{
  "name": "@openclaw/my-plugin",
  "version": "1.0.0",
  "description": "我的 OpenClaw 插件",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "openclaw": {
    "type": "tool",
    "displayName": "我的工具插件",
    "minGatewayVersion": "0.5.0",
    "permissions": ["network", "file-read"]
  },
  "keywords": ["openclaw", "openclaw-plugin"],
  "license": "MIT"
}

清单字段详解

openclaw 节点字段

字段	类型	必填	说明
type	string	✅	插件类型：channel、tool、hook
displayName	string	✅	显示名称
minGatewayVersion	string	❌	最低网关版本要求
permissions	string[]	❌	所需权限列表
configSchema	object	❌	配置项 JSON Schema
multiInstance	boolean	❌	是否支持多实例（默认 false）

权限声明

声明 permissions 可以让用户在安装时了解插件的能力范围。常见权限：network、file-read、file-write、exec。

插件类型

Channel（渠道插件）

import { ChannelPlugin } from '@openclaw/sdk'

const plugin: ChannelPlugin = {
  type: 'channel',
  name: 'my-channel',

  async onMessage(message, context) {
    // 处理来自渠道的消息
  },

  async sendMessage(to, content, context) {
    // 向渠道发送消息
  }
}

export default plugin

Tool（工具插件）

import { ToolPlugin } from '@openclaw/sdk'

const plugin: ToolPlugin = {
  type: 'tool',
  tools: [
    {
      name: 'my_tool',
      description: '工具描述',
      parameters: { /* JSON Schema */ },
      handler: async (params, ctx) => {
        return { result: 'done' }
      }
    }
  ]
}

export default plugin

Hook（钩子插件）

import { HookPlugin } from '@openclaw/sdk'

const plugin: HookPlugin = {
  type: 'hook',
  hooks: {
    'message:before': async (message, ctx) => {
      // 消息处理前的拦截逻辑
      return message
    },
    'message:after': async (response, ctx) => {
      // 消息处理后的后处理逻辑
    }
  }
}

export default plugin

导出约定

导出规则

插件必须使用 默认导出（export default）。网关不会识别命名导出。

// ✅ 正确
export default plugin

// ❌ 错误
export { plugin }

生命周期钩子

插件可实现以下生命周期方法：

钩子	触发时机	用途
onLoad	插件被加载时	初始化资源、建立连接
onReady	网关就绪后	执行启动后逻辑
onUnload	插件被卸载时	清理资源、关闭连接
onConfigChange	配置变更时	热更新配置

export default {
  type: 'tool',
  async onLoad(config, gateway) {
    console.log('插件加载完成')
  },
  async onUnload() {
    console.log('插件已卸载，资源已释放')
  }
}

本地测试

链接本地插件

openclaw plugins link ./my-plugin

运行测试

cd my-plugin
npm test

调试模式启动网关

openclaw start --debug --plugin-dev ./my-plugin

发布到 npm

# 构建
npm run build

# 登录 npm
npm login

# 发布
npm publish --access public

发布检查清单

发布前确认：✅ 版本号已更新 ✅ openclaw 字段完整 ✅ 包含 README ✅ 测试通过