构建插件

插件可为 OpenClaw 扩展新能力：渠道、模型提供商、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索、智能体工具，或这些能力的任意组合。你不需要将你的插件添加到 OpenClaw 仓库中。发布到 ClawHub 或 npm，用户即可通过 openclaw plugins install <package-name> 安装。OpenClaw 会优先尝试 ClawHub，并在需要时自动回退到 npm。

前置条件

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

你要构建哪种插件？

渠道插件

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

提供商插件

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

工具 / hook 插件

注册智能体工具、事件 hook 或服务 —— 继续阅读下文

如果某个渠道插件是可选的，并且在新手引导/设置运行时可能尚未安装，请使用 openclaw/plugin-sdk/channel-setup 中的 createOptionalChannelSetupSurface(...)。它会生成一个设置适配器 + 向导组合，用于提示安装要求，并在插件安装完成前对真实配置写入进行失败关闭保护。

快速开始：工具插件

本教程将创建一个用于注册智能体工具的最小插件。渠道插件和提供商插件有各自的专用指南，见上方链接。

创建包和清单

{
  "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"
    }
  }
}

每个插件都需要一个清单，即使没有配置也是如此。完整 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: "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 用于非渠道插件。对于渠道，请使用 defineChannelPluginEntry —— 参见渠道插件。如需了解完整的入口点选项，请参见入口点。

测试并发布

外部插件： 通过 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 这样的裸包规范，OpenClaw 也会在 npm 之前先检查 ClawHub。仓库内插件： 放在内置插件工作区树下 —— 会自动发现。

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

插件能力

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

能力	注册方法	详细指南
文本推理（LLM）	`api.registerProvider(...)`	提供商插件
CLI 推理后端	`api.registerCliBackend(...)`	CLI 后端
渠道 / 消息	`api.registerChannel(...)`	渠道插件
语音（TTS/STT）	`api.registerSpeechProvider(...)`	提供商插件
实时转录	`api.registerRealtimeTranscriptionProvider(...)`	提供商插件
实时语音	`api.registerRealtimeVoiceProvider(...)`	提供商插件
媒体理解	`api.registerMediaUnderstandingProvider(...)`	提供商插件
图像生成	`api.registerImageGenerationProvider(...)`	提供商插件
音乐生成	`api.registerMusicGenerationProvider(...)`	提供商插件
视频生成	`api.registerVideoGenerationProvider(...)`	提供商插件
网页抓取	`api.registerWebFetchProvider(...)`	提供商插件
网页搜索	`api.registerWebSearchProvider(...)`	提供商插件
智能体工具	`api.registerTool(...)`	下文
自定义命令	`api.registerCommand(...)`	入口点
事件 hook	`api.registerHook(...)`	入口点
HTTP 路由	`api.registerHttpRoute(...)`	内部机制
CLI 子命令	`api.registerCli(...)`	入口点

完整注册 API 请参见 SDK 概览。如果你的插件注册了自定义 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 } 会暂停智能体执行，并通过 exec 审批覆盖层、Telegram 按钮、Discord 交互，或任意渠道上的 /approve 命令提示用户批准。
before_install：{ block: true } 为终止结果，并会阻止更低优先级的处理器继续执行。
before_install：{ block: false } 会被视为未作决定。
message_sending：{ cancel: true } 为终止结果，并会阻止更低优先级的处理器继续执行。
message_sending：{ cancel: false } 会被视为未作决定。

/approve 命令会同时处理 exec 审批和插件审批，并带有有界回退：当找不到某个 exec 审批 ID 时，OpenClaw 会用同一个 ID 通过插件审批再次尝试。插件审批转发可通过配置中的 approvals.plugin 独立设置。如果自定义审批流程需要检测这一相同的有界回退场景，优先使用 openclaw/plugin-sdk/error-runtime 中的 isApprovalNotFoundError，而不要手动匹配审批过期字符串。详情请参见 SDK 概览中的 hook 决策语义。

注册智能体工具

工具是 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 }] };
    },
  });

  // 可选工具 —— 用户必须添加到 allowlist
  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 路径导入你自己的插件。对于提供商插件，除非该扩展点确实具有通用性，否则请将提供商特定的辅助函数保留在这些包根级 barrel 中。当前内置示例包括：

Anthropic：Claude 流包装器以及 service_tier / beta 辅助函数
OpenAI：提供商构建器、默认模型辅助函数、实时提供商
OpenRouter：提供商构建器以及新手引导/配置辅助函数

如果某个辅助函数只在一个内置提供商包内部有用，请将其保留在该包根级扩展点上，而不是将其提升到 openclaw/plugin-sdk/* 中。一些生成的 openclaw/plugin-sdk/<bundled-id> 辅助扩展点仍然存在，用于内置插件维护和兼容性，例如 plugin-sdk/feishu-setup 或 plugin-sdk/zalo-setup。请将这些视为保留接口，而不是新第三方插件的默认模式。

提交前检查清单

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 标签一出现，就尽快用它测试你的插件。稳定版发布前的窗口通常只有几个小时。
测试后，在 Discord 的 plugin-forum 渠道中你插件对应的线程里发布 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 测试期间关注这些线程。
没有消息就表示一切正常。如果你错过了这个窗口，你的修复很可能会在下一个周期落地。

下一步

渠道插件

构建一个消息渠道插件

提供商插件

构建一个模型提供商插件

SDK 概览

导入映射和注册 API 参考

运行时辅助工具

通过 api.runtime 使用 TTS、搜索、子智能体

测试

测试工具和模式

插件清单

完整清单 schema 参考

Overview

First steps

Guides

构建插件

构建插件

前置条件

你要构建哪种插件？

渠道插件

提供商插件

工具 / hook 插件

快速开始：工具插件

插件能力

注册智能体工具

导入约定

提交前检查清单

Beta 版本测试

下一步

渠道插件

提供商插件

SDK 概览

运行时辅助工具

测试

插件清单

相关内容

Overview

First steps

Guides

​构建插件

​前置条件

​你要构建哪种插件？

渠道插件

提供商插件

工具 / hook 插件

​快速开始：工具插件

​插件能力

​注册智能体工具

​导入约定

​提交前检查清单

​Beta 版本测试

​下一步

渠道插件

提供商插件

SDK 概览

运行时辅助工具

测试

插件清单

​相关内容

构建插件

前置条件

你要构建哪种插件？

快速开始：工具插件

插件能力

注册智能体工具

导入约定

提交前检查清单

Beta 版本测试

下一步

相关内容