构建插件

插件通过新增能力来扩展 OpenClaw：channels、模型提供方、 speech、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索、agent 工具，或这些能力的任意组合。你不需要将你的插件添加到 OpenClaw 仓库中。发布到 ClawHub，用户可通过 openclaw plugins install clawhub:<package-name> 安装。在发布切换期间，裸包说明仍然会从 npm 安装。

前提条件

Node >= 22 和一个包管理器（npm 或 pnpm）
熟悉 TypeScript（ESM）
对于仓库内插件：已克隆仓库并执行 pnpm install。源码检出方式的插件开发仅支持 pnpm，因为 OpenClaw 会从 extensions/* 工作区包中加载已捆绑的插件。

这是什么类型的插件？

Channel 插件

将 OpenClaw 连接到一个消息平台（Discord、IRC 等）

Provider 插件

添加一个模型提供方（LLM、代理或自定义端点）

工具 / hook 插件

对于在 onboarding/setup 运行时不能保证已安装的 channel 插件，请使用来自 openclaw/plugin-sdk/channel-setup 的 createOptionalChannelSetupSurface(...)。它会生成一个 setup adapter + wizard 对，声明安装要求，并在真实的配置写入前保持关闭，直到插件已安装。

快速开始：工具插件

本教程将创建一个最小插件，用于注册一个 agent 工具。Channel 和 provider 插件有上面链接的专门指南。

创建包和清单

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "compat": {
      "pluginApi": ">=2026.3.24-beta.2",
      "minGatewayVersion": "2026.3.24-beta.2"
    },
    "build": {
      "openclawVersion": "2026.3.24-beta.2",
      "pluginSdkVersion": "2026.3.24-beta.2"
    }
  }
}

每个插件都需要一个清单，即使没有配置也是如此。运行时注册的工具必须列在 contracts.tools 中，这样 OpenClaw 才能在不加载每个插件运行时的情况下发现其所属插件。插件也应明确声明 activation.onStartup。本示例将其设为 true。完整 schema 请参见 Manifest。规范的 ClawHub 发布片段位于 docs/snippets/plugin-publish/ 中。

编写入口点

// 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: "为 OpenClaw 添加一个自定义工具",
  register(api) {
    api.registerTool({
      name: "my_tool",
      description: "执行某件事",
      parameters: Type.Object({ input: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: `Got: ${params.input}` }] };
      },
    });
  },
});

definePluginEntry 用于非 channel 插件。对于 channels，请使用 defineChannelPluginEntry — 参见 Channel Plugins。关于完整的入口点选项，请参见 Entry Points。

测试并发布

外部插件： 使用 ClawHub 验证并发布，然后安装：

clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
openclaw plugins install clawhub:@myorg/openclaw-my-plugin

像 @myorg/openclaw-my-plugin 这样的裸包说明会在发布切换期间从 npm 安装。当你想使用 ClawHub 解析时，请使用 clawhub:。仓库内插件： 放置在捆绑插件工作区树下 — 会自动被发现。

pnpm test -- <bundled-plugin-root>/my-plugin/

插件能力

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

能力	注册方法	详细指南
文本推理（LLM）	`api.registerProvider(...)`	Provider Plugins
CLI 推理后端	`api.registerCliBackend(...)`	CLI Backends
Channel / 消息	`api.registerChannel(...)`	Channel Plugins
Speech（TTS/STT）	`api.registerSpeechProvider(...)`	Provider Plugins
实时转录	`api.registerRealtimeTranscriptionProvider(...)`	Provider Plugins
实时语音	`api.registerRealtimeVoiceProvider(...)`	Provider Plugins
媒体理解	`api.registerMediaUnderstandingProvider(...)`	Provider Plugins
图像生成	`api.registerImageGenerationProvider(...)`	Provider Plugins
音乐生成	`api.registerMusicGenerationProvider(...)`	Provider Plugins
视频生成	`api.registerVideoGenerationProvider(...)`	Provider Plugins
网页抓取	`api.registerWebFetchProvider(...)`	Provider Plugins
网页搜索	`api.registerWebSearchProvider(...)`	Provider Plugins
工具结果中间件	`api.registerAgentToolResultMiddleware(...)`	SDK Overview
Agent 工具	`api.registerTool(...)`	下方
自定义命令	`api.registerCommand(...)`	Entry Points
插件 hooks	`api.on(...)`	Plugin hooks
内部事件 hooks	`api.registerHook(...)`	Entry Points
HTTP 路由	`api.registerHttpRoute(...)`	Internals
CLI 子命令	`api.registerCli(...)`	Entry Points

关于完整的注册 API，请参见 SDK Overview。捆绑插件在需要模型看到输出之前先进行异步工具结果重写时，可以使用 api.registerAgentToolResultMiddleware(...)。请在 contracts.agentToolResultMiddleware 中声明目标运行时，例如 ["pi", "codex"]。这是一个受信任的捆绑插件接入点；除非 OpenClaw 为此能力增加明确的信任策略，否则外部插件应优先使用常规的 OpenClaw 插件 hooks。如果你的插件注册自定义 gateway RPC 方法，请将它们放在插件专用前缀下。核心管理命名空间（config.*、exec.approvals.*、wizard.*、update.*）保持保留状态，并且始终解析为 operator.admin，即使某个插件要求更窄的作用域也是如此。需要记住的 hook 守卫语义：

before_tool_call：{ block: true } 是终止性的，并会停止更低优先级的处理器。
before_tool_call：{ block: false } 被视为没有决定。
before_tool_call：{ requireApproval: true } 会暂停 agent 执行，并通过 exec approval 覆盖层、Telegram 按钮、Discord 交互，或任何 channel 上的 /approve 命令来提示用户批准。
before_install：{ block: true } 是终止性的，并会停止更低优先级的处理器。
before_install：{ block: false } 被视为没有决定。
message_sending：{ cancel: true } 是终止性的，并会停止更低优先级的处理器。
message_sending：{ cancel: false } 被视为没有决定。
message_received：当你需要入站 thread/topic 路由时，优先使用类型化的 threadId 字段。将 metadata 保留给 channel 特定的额外信息。
message_sending：优先使用类型化的 replyToId / threadId 路由字段，而不是 channel 特定的 metadata 键。

/approve 命令同时处理 exec 和插件批准，并带有有限回退：当找不到某个 exec approval id 时，OpenClaw 会通过插件批准重试同一个 id。插件批准转发可以通过配置中的 approvals.plugin 单独配置。如果自定义批准管道需要检测同样的有限回退情况，请优先使用 openclaw/plugin-sdk/error-runtime 中的 isApprovalNotFoundError，而不是手动匹配 approval-expiry 字符串。更多示例和 hook 参考请参见 Plugin hooks。

注册 agent 工具

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

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

  // 可选工具 — 用户必须添加到允许列表
  api.registerTool(
    {
      name: "workflow_tool",
      description: "运行一个工作流",
      parameters: Type.Object({ pipeline: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.pipeline }] };
      },
    },
    { optional: true },
  );
}

通过 api.registerTool(...) 注册的每个工具也必须在插件清单中声明：

{
  "contracts": {
    "tools": ["my_tool", "workflow_tool"]
  }
}

OpenClaw 会捕获并缓存已注册工具中经过验证的描述符，因此插件无需在清单中重复 description 或 schema 数据。该清单契约仅声明归属和发现；执行时仍会调用实时注册的工具实现。用户可在配置中启用可选工具：

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

工具名称不得与核心工具冲突（冲突项会被跳过）
注册对象格式不正确的工具（包括缺少 parameters）会被跳过，并在插件诊断中报告，而不会破坏 agent 运行
对有副作用或额外二进制依赖的工具使用 optional: true
用户可以通过将插件 id 添加到 tools.allow 来启用某个插件中的所有工具

注册 CLI 命令

插件可以使用 api.registerCli 添加根级 openclaw 命令组。请为每个顶层命令根提供 descriptors，这样 OpenClaw 就能在不急于加载每个插件运行时的情况下显示并路由该命令。

register(api) {
  api.registerCli(
    ({ program }) => {
      const demo = program
        .command("demo-plugin")
        .description("运行 demo 插件命令");

      demo
        .command("ping")
        .description("检查该插件 CLI 是否可执行")
        .action(() => {
          console.log("demo-plugin:pong");
        });
    },
    {
      descriptors: [
        {
          name: "demo-plugin",
          description: "运行 demo 插件命令",
          hasSubcommands: true,
        },
      ],
    },
  );
}

安装后，验证运行时注册并执行该命令：

openclaw plugins inspect demo-plugin --runtime --json
openclaw demo-plugin ping

导入约定

始终从聚焦的 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 路径导入你自己的插件。对于 provider 插件，除非接口确实是通用的，否则请将 provider 特定的辅助工具保留在这些包根的 barrel 文件中。当前内置的示例包括：

Anthropic：Claude 流包装器以及 service_tier / beta 辅助工具
OpenAI：provider 构建器、默认模型辅助工具、实时 provider
OpenRouter：provider 构建器以及 boot/config 辅助工具

如果某个辅助工具只在一个内置 provider 包内部有用，请将它保留在该包根级别的导出面上，而不是将其提升到 openclaw/plugin-sdk/* 中。一些生成的 openclaw/plugin-sdk/<bundled-id> 辅助导出面仍然存在，用于在其文档说明所有者用法时维护内置插件。请将这些视为保留接口，而不是新第三方插件的默认模式。

提交前检查清单

package.json 具有正确的 openclaw 元数据

openclaw.plugin.json 清单文件存在且有效

入口点使用 defineChannelPluginEntry 或 definePluginEntry

所有导入都使用聚焦的 plugin-sdk/<subpath> 路径

内部导入使用本地模块，而不是 SDK 自导入

测试通过（pnpm test -- <bundled-plugin-root>/my-plugin/）

pnpm check 通过（适用于仓库内插件）

Beta 版本测试

关注 openclaw/openclaw 上的 GitHub 发布标签，并通过 Watch > Releases 订阅。Beta 标签看起来像 v2026.3.N-beta.1。你也可以为 OpenClaw 官方 X 账号 @openclaw 启用通知，以便及时获知发布公告。
一旦出现 beta 标签，立即用它测试你的插件。正式版发布前的窗口通常只有几个小时。
测试完成后，在你插件的 plugin-forum Discord 主题中回复 all good，或说明出现了什么问题。如果你还没有主题，请创建一个。
如果存在问题，请创建或更新一个标题为 Beta blocker: <plugin-name> - <summary> 的 issue，并添加 beta-blocker 标签。将该 issue 链接放到你的主题中。
针对 main 创建一个标题为 fix(<plugin-id>): beta blocker - <summary> 的 PR，并在 PR 和你的 Discord 主题中都附上 issue 链接。贡献者不能给 PR 添加标签，因此标题是维护者和自动化识别 PR 侧信号的方式。有 PR 的 blocker 会被合并；没有 PR 的 blocker 仍然可能随版本发布。维护者会在 beta 测试期间关注这些主题。
沉默即表示通过。如果你错过了这个窗口，你的修复很可能会在下一个周期才落地。

后续步骤

Channel 插件

构建消息通道插件

Provider 插件

构建模型 provider 插件

SDK 概览

导入映射和注册 API 参考

运行时辅助工具

通过 api.runtime 使用 TTS、搜索和子代理

测试

测试工具和模式

插件清单

完整的清单 schema 参考

另请参阅

插件架构 — 深入了解内部架构
SDK 概览 — 插件 SDK 参考
清单 — 插件清单格式
Channel 插件 — 构建通道插件
Provider 插件 — 构建 provider 插件

概览

插件

技能

自动化与任务

工具

智能体协作

前提条件

这是什么类型的插件？

Channel 插件

Provider 插件

工具 / hook 插件

快速开始：工具插件

插件能力

注册 agent 工具

注册 CLI 命令

导入约定

提交前检查清单

Beta 版本测试

后续步骤

Channel 插件

Provider 插件

SDK 概览

运行时辅助工具

测试

插件清单

另请参阅

概览

插件

技能

自动化与任务

工具

智能体协作

Documentation Index

​前提条件

​这是什么类型的插件？

Channel 插件

Provider 插件

工具 / hook 插件

​快速开始：工具插件

​插件能力

​注册 agent 工具

​注册 CLI 命令

​导入约定

​提交前检查清单

​Beta 版本测试

​后续步骤

Channel 插件

Provider 插件

SDK 概览

运行时辅助工具

测试

插件清单

​另请参阅

前提条件

这是什么类型的插件？

快速开始：工具插件

插件能力

注册 agent 工具

注册 CLI 命令

导入约定

提交前检查清单

Beta 版本测试

后续步骤

另请参阅