第 28 章 · 扩展与插件

“OpenClaw 的核心是开放。这一章介绍如何扩展 OpenClaw 的能力——安装插件、编写扩展、集成外部服务。”

28.1 插件系统概述

什么是插件？

插件（Plugin）是扩展 OpenClaw 核心功能的代码模块。

与 Skill 不同：

• Skill：教 AI 如何做某事（知识层面）
• Plugin：给 AI 提供新工具（能力层面）

插件类型

28.2 安装插件

从 ClawHub 安装

openclaw plugins install weather-api

从 GitHub 安装

openclaw plugins install github:user/repo

从本地安装

openclaw plugins install ./my-plugin

查看已安装插件

openclaw plugins list

输出：

Name         | Version | Type    | Status-------------|---------|---------|--------weather-api  | 1.2.0   | tool    | enableddiscord      | 2.0.0   | channel | enabledlocal-model  | 0.5.0   | model   | disabled

28.3 插件配置

启用/禁用插件

openclaw plugins enable weather-apiopenclaw plugins disable local-model

配置插件参数

{  plugins: {    entries: {      "weather-api": {        enabled: true,        config: {          apiKey: process.env.WEATHER_API_KEY,          defaultLocation: "Beijing"        }      }    }  }}

28.4 MCP 协议插件

什么是 MCP？

MCP（Model Context Protocol）是 Anthropic 提出的工具协议标准。

MCP 插件让 OpenClaw 可以使用 MCP 兼容的工具集。

安装 MCP 插件

openclaw plugins install mcp-playwright

配置 MCP

{  mcp: {    servers: {      "playwright": {        command: "npx",        args: ["-y", "@anthropic/mcp-server-playwright"],        env: {          HEADLESS: "true"        }      }    }  }}

使用 MCP 工具

MCP 工具会自动出现在 AI 的工具列表中：

帮我打开 https://example.com 并截图

AI 会调用 MCP 提供的 playwright 工具。

28.5 开发工具插件

插件结构

my-plugin/├── manifest.json   # 插件元数据├── index.js        # 主入口└── tools/│   ├── tool1.js    # 工具实现│   └── tool2.js

manifest.json

{"name":"my-plugin","version":"1.0.0","type":"tool","description":"我的自定义工具插件","tools":[{"name":"my_tool","description":"我的工具描述","parameters":{"param1":{"type":"string","description":"参数1"}}}]}

index.js

exportdefaultfunctionregisterTools(pluginContext) {  pluginContext.registerTool('my_tool', {description: '我的工具描述',parameters: {param1: { type: 'string', description: '参数1' }    },handler: async (params) => {// 工具实现return { result: 'success' };    }  });}

28.6 开发渠道插件

渠道插件结构

exportdefaultclassMyChannel {constructor(config) {this.config = config;  }// 连接到渠道asyncconnect() {// WebSocket 连接、Bot 登录等  }// 发送消息asyncsend(to, message) {// 发送到渠道  }// 接收消息（回调）onMessage(callback) {// 注册消息回调  }// 断开连接asyncdisconnect() {// 清理资源  }}

注册渠道

{  channels: {    myChannel: {      plugin: "my-channel-plugin",      enabled: true,      config: {        apiKey: "xxx"      }    }  }}

28.7 开发模型插件

模型插件结构

exportdefaultclassMyModel {constructor(config) {this.config = config;  }// 调用模型asyncgenerate(messages, options) {// 调用你的模型 APIconst response = awaitfetch('https://my-model-api.com/generate', {method: 'POST',body: JSON.stringify({ messages, options })    });return response.json();  }// 模型信息getModelInfo() {return {name: 'my-model',capabilities: ['text', 'vision']    };  }}

注册模型

{  models: {    providers: {      myProvider: {        plugin: "my-model-plugin",        models: {          "my-model": {            alias: "custom/my-model"          }        }      }    }  }}

28.8 发布插件

准备发布

1. 编写完整文档
2. 测试各种场景
3. 添加版本号和变更日志

发布到 ClawHub

openclaw plugins publish my-plugin

发布到 npm

npm publish openclaw-plugin-my-plugin

28.9 常用插件推荐

工具类

渠道类

MCP 类

28.10 扩展开发最佳实践

1. 遵循接口规范

确保插件遵循 OpenClaw 的插件接口规范。

2. 提供清晰的错误处理

handler: async (params) => {try {// 操作return { success: true, result: data };  } catch (error) {return { success: false, error: error.message };  }}

3. 添加配置验证

constructor(config) {if (!config.apiKey) {thrownewError('apiKey is required');  }this.config = config;}

4. 编写测试

// test.jsimportMyPluginfrom'./index.js';const plugin = newMyPlugin({ apiKey: 'test' });const result = await plugin.handler({ param1: 'test' });assert(result.success);

📝 本章小结

• 插件扩展 OpenClaw 的核心能力
• 类型：工具、渠道、模型、Hook、MCP
• 安装：ClawHub、GitHub、本地
• 开发：遵循接口规范、错误处理、配置验证
• 发布：ClawHub、npm