插件开发

插件为 OpenClaw 扩展新能力：频道（channel）、模型提供商、语音、图像生成、网络搜索、Agent 工具，或任意组合。

无需将插件添加到 OpenClaw 仓库。发布到 ClawHub 或 npm，用户通过 openclaw plugins install <package-name> 安装即可。OpenClaw 会先尝试 ClawHub，自动回退到 npm。

前置条件

• Node >= 22 以及包管理器（npm 或 pnpm）
• 熟悉 TypeScript（ESM）
• 仓库内插件：已克隆仓库并完成 pnpm install

我需要什么类型的插件？

插件类型	说明	详细指南
Channel 插件	将 OpenClaw 接入消息平台（Discord、IRC 等）	Channel 插件
Provider 插件	添加模型提供商（LLM、代理或自定义端点）	Provider 插件
工具/Hook 插件	注册 Agent 工具、事件 hook 或服务	继续阅读下文

快速入门：工具插件

本教程创建一个注册 Agent 工具的最小插件。Channel 和 Provider 插件有专属指南，见上表链接。

第一步：创建包和清单

// package.json
{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"]
  }
}

// openclaw.plugin.json
{
  "id": "my-plugin",
  "name": "My Plugin",
  "description": "Adds a custom tool to OpenClaw",
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

每个插件都需要一个清单，即使没有配置也一样。完整 schema 参见 插件清单。

第二步：编写入口点

// index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Adds a custom tool to OpenClaw",
  register(api) {
    api.registerTool({
      name: "my_tool",
      description: "Do a thing",
      parameters: Type.Object({ input: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: `Got: ${params.input}` }] };
      },
    });
  },
});

definePluginEntry 适用于非 channel 插件。对于 channel，使用 defineChannelPluginEntry——参见 Channel 插件。完整入口点选项参见 入口点。

第三步：测试和发布

外部插件： 发布到 ClawHub 或 npm，然后安装：

openclaw plugins install @myorg/openclaw-my-plugin

OpenClaw 先检查 ClawHub，然后回退到 npm。

仓库内插件： 放在 extensions/ 目录下——自动被发现。

pnpm test -- extensions/my-plugin/

插件能力

单个插件可以通过 api 对象注册任意数量的能力：

能力	注册方法	详细指南
文本推理（LLM）	api.registerProvider(...)	Provider 插件
CLI 推理后端	api.registerCliBackend(...)	CLI 后端
Channel / 消息	api.registerChannel(...)	Channel 插件
语音（TTS/STT）	api.registerSpeechProvider(...)	Provider 插件
媒体理解	api.registerMediaUnderstandingProvider(...)	Provider 插件
图像生成	api.registerImageGenerationProvider(...)	Provider 插件
网络搜索	api.registerWebSearchProvider(...)	Provider 插件
Agent 工具	api.registerTool(...)	见下文
自定义命令	api.registerCommand(...)	入口点
事件 Hook	api.registerHook(...)	入口点
HTTP 路由	api.registerHttpRoute(...)	内部架构
CLI 子命令	api.registerCli(...)	入口点

完整注册 API 参见 SDK 概览。

Hook 守卫语义注意事项：

• before_tool_call：{ block: true } 是终止性的，会阻止低优先级处理程序
• before_tool_call：{ block: false } 视为无决策
• message_sending：{ cancel: true } 是终止性的，会阻止低优先级处理程序
• message_sending：{ cancel: false } 视为无决策

详见 SDK 概览 Hook 决策语义。

注册 Agent 工具

工具是 LLM 可以调用的类型化函数。可以是必需的（始终可用）或可选的（用户选择启用）：

register(api) {
  // 必需工具——始终可用
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({ input: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });

  // 可选工具——用户必须加入允许列表
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Run a workflow",
      parameters: Type.Object({ pipeline: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.pipeline }] };
      },
    },
    { optional: true },
  );
}

用户在配置中启用可选工具：

{
  tools: { allow: ["workflow_tool"] },
}

• 工具名不得与核心工具冲突（冲突会被跳过）
• 有副作用或需要额外二进制文件的工具使用 optional: true
• 用户可以将插件 id 添加到 tools.allow 来启用该插件的所有工具

导入约定

始终从专注的 openclaw/plugin-sdk/<subpath> 路径导入：

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";

// 错误：整体根导入（已废弃，将被移除）
import { ... } from "openclaw/plugin-sdk";

完整子路径参考见 SDK 概览。

在插件内部，对内部导入使用本地 barrel 文件（api.ts、runtime-api.ts）——永远不要通过 SDK 路径导入自己的插件。

提交前检查清单

• package.json 包含正确的 openclaw 元数据
• openclaw.plugin.json 清单存在且有效
• 入口点使用 defineChannelPluginEntry 或 definePluginEntry
• 所有导入使用专注的 plugin-sdk/<subpath> 路径
• 内部导入使用本地模块，不通过 SDK 自导入
• 测试通过（pnpm test -- extensions/my-plugin/）
• pnpm check 通过（仓库内插件）

Beta 版本测试

1. 在 openclaw/openclaw 关注 GitHub 发布标签，订阅 Watch > Releases。Beta 标签形如 v2026.3.N-beta.1。也可以开启官方 OpenClaw X 账号 @openclaw 的通知。
2. Beta 标签出现后立即针对它测试你的插件。稳定版发布前的窗口通常只有几个小时。
3. 测试完成后，在 Discord plugin-forum 频道的插件线程中发布 all good 或描述出现的问题。如果还没有线程，创建一个。
4. 如果出现问题，打开或更新标题为 Beta blocker: <plugin-name> - <summary> 的 issue 并添加 beta-blocker 标签。将 issue 链接放在你的线程中。
5. 打开标题为 fix(<plugin-id>): beta blocker - <summary> 的 PR 并在 PR 和 Discord 线程中链接 issue。贡献者无法给 PR 打标签，所以标题是维护者和自动化的 PR 侧信号。有 PR 的阻塞问题会被合并；没有 PR 的可能直接发布。维护者在 Beta 测试期间会关注这些线程。
6. 沉默代表绿色。如果错过了窗口，你的修复可能在下个周期落地。

下一步

• Channel 插件 —— 构建消息频道插件
• Provider 插件 —— 构建模型提供商插件
• SDK 概览 —— 导入映射和注册 API 参考
• 运行时辅助函数 —— 通过 api.runtime 使用 TTS、搜索、子 agent
• 测试 —— 测试工具和模式
• 插件清单 —— 完整清单 schema 参考