OpenClaw养虾插件清单与使用指南

在OpenClaw生态中，插件是扩展其核心能力的关键。而这一切的起点，都始于一份清晰、规范的插件清单（Plugin Manifest）。这份清单定义了插件的身份、能力和行为准则，确保网关能够正确识别、加载并与之交互。今天，我们就来深入拆解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字段，它是网关识别插件的唯一标识。

清单字段详解

让我们聚焦于openclaw节点下的各个字段，它们共同勾勒出插件的轮廓。

openclaw 节点字段

其中，permissions字段的声明尤为重要。它相当于插件的“能力说明书”，让用户在安装前就能清晰了解插件会访问哪些系统资源，例如网络（network）、文件读取（file-read）、文件写入（file-write）或执行命令（exec）。这是一种建立信任的良好实践。

插件类型

OpenClaw插件主要分为三种类型，每种都有其特定的接口和用途。

Channel（渠道插件）

这类插件负责与外部消息平台（如微信、钉钉、Slack）对接，处理消息的接收与发送。其基本结构如下：

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（工具插件）

工具插件用于扩展AI模型的能力，使其能够调用外部API或执行特定任务。一个工具插件可以包含多个工具：

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 }

生命周期钩子

为了让插件能够优雅地管理资源，OpenClaw SDK提供了一系列生命周期钩子。实现这些方法可以让插件在加载、就绪、卸载等关键时刻执行相应操作。

一个简单的实现示例：

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

本地测试

在发布之前，充分的本地测试至关重要。OpenClaw CLI提供了便捷的链接命令，允许你将本地开发的插件目录链接到网关中进行实时调试：

openclaw plugins link ./my-plugin

执行此命令后，以调试模式启动网关，即可加载并测试你的本地插件。

发布到 npm

当插件开发测试完毕，就可以准备发布到npm仓库，供他人使用了。流程非常标准：

# 构建生产代码
npm run build

# 登录 npm 账户
npm login

# 发布包（公开）
npm publish --access public

在点击发布按钮前，建议对照以下清单做最后确认：

• ✅ package.json中的版本号已按语义化版本规范更新。
• ✅ openclaw字段完整且正确。
• ✅ 项目包含清晰的README文档。
• ✅ 所有测试用例均已通过。

遵循上述规范，你就能构建出结构清晰、行为可靠、易于分发的OpenClaw插件，从而为整个生态贡献你的独特能力。