当前位置：首页 > news >正文

15、OpenClaw 自定义插件开发完整指南（2026最新版）

news 2026/5/6 6:27:52

OpenClaw 采用"核心极简、扩展按需"的插件化架构，插件是扩展其能力的标准方式。你可以通过插件添加AI工具、聊天命令、HTTP接口、消息通道、生命周期钩子等功能，适用于v2026.3.8+版本。

文章目录

- 一、前置准备
- 二、你的第一个插件：Hello World
- - 步骤1：创建插件目录结构
  - 步骤2：创建插件清单文件（必填）
  - 步骤3：创建插件入口文件
  - 步骤4：安装并启用插件
  - 步骤5：测试插件
- 三、插件核心能力详解
- - 1. 注册AI工具（Tools）
  - 2. 注册斜杠命令（Commands）
  - 3. 注册HTTP路由
  - 4. 注册生命周期钩子（Hooks）
  - 5. 注册CLI命令
- 四、插件开发进阶
- - 1. 使用TypeScript开发
  - 2. 插件配置与环境变量
  - 3. 插件间通信
  - 4. 调试插件
- 五、插件打包与发布
- - 1. 本地打包
  - 2. 发布到npm
  - 3. 安装已发布的插件
- 六、最佳实践
- 七、常见问题

一、前置准备

环境要求
- Node.js 22+（必须）
- OpenClaw 最新版本：npm install -g openclaw@latest
- 确保Gateway正在运行：openclaw gateway status
插件位置选择
- 全局插件（推荐）：~/.openclaw/extensions/（所有工作区可用）
- 工作区插件：./.openclaw/extensions/（仅当前项目可用）
- 开发中插件：任意路径（通过plugins.load.paths配置）

二、你的第一个插件：Hello World

步骤1：创建插件目录结构

# 创建全局插件目录mkdir-p~/.openclaw/extensions/hello-worldcd~/.openclaw/extensions/hello-world

步骤2：创建插件清单文件（必填）

创建openclaw.plugin.json，这是插件的"身份证"，OpenClaw在加载代码前会先读取此文件：

{"id":"hello-world","version":"1.0.0","name":"Hello World","description":"我的第一个OpenClaw插件","main":"./index.js","configSchema":{"type":"object","additionalProperties":false,"properties":{"greeting":{"type":"string","default":"Hello","description":"默认问候语"}}}}

步骤3：创建插件入口文件

创建index.js，实现插件的核心功能：

// 导入类型定义（可选但推荐）import{Type}from"@sinclair/typebox";// 插件入口函数，接收OpenClaw API对象exportdefaultfunctionregister(api){// 1. 注册一个AI工具（Agent可自动调用）api.registerTool({name:"say_hello",description:"向用户发送问候语",parameters:Type.Object({name:Type.String({description:"要问候的人的名字"})}),asyncexecute(_id,params){// 获取插件配置constconfig=api.getConfig();return{content:[{type:"text",text:`${config.greeting},${params.name}! 来自Hello World插件`}]};}});// 2. 注册一个斜杠命令（无需AI即可执行）api.registerCommand({name:"hello",description: