构建插件

插件通过新功能扩展 OpenClaw：频道、模型提供商、语音、图像生成、网络搜索、代理工具或其任意组合。

您无需将插件添加到 OpenClaw 代码库中。发布到 ClawHub 或 npm，用户即可使用 openclaw plugins install <package-name> 进行安装。OpenClaw 会优先尝试 ClawHub，然后自动回退到 npm。

先决条件

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

哪种类型的插件？

Channel plugin

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

Provider plugin

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

Tool / hook plugin

快速开始：工具插件

本演练将创建一个注册代理工具的最小化插件。频道和提供商插件有上方链接的专门指南。

Create the package and manifest

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

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

每个插件都需要一个清单，即使没有配置。请参阅

Manifest 以了解完整的架构。标准的 ClawHub 发布代码片段位于 docs/snippets/plugin-publish/ 中。

Write the entry point

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 — 请参阅 Channel Plugins。有关入口点的完整选项，请参阅 Entry Points。

Test and publish
外部插件： 使用 ClawHub 验证并发布，然后安装：
Terminal window
```
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
openclaw plugins install clawhub:@myorg/openclaw-my-plugin
```
OpenClaw 也会在 npm 之前检查 ClawHub，对于像 @myorg/openclaw-my-plugin 这样的裸包规范。

代码库内插件： 放置在捆绑插件工作区树下 — 自动发现。
Terminal window
```
pnpm test --
```
/my-plugin/ ```

插件功能

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

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

有关完整的注册 API，请参阅 SDK 概述。

需要注意的钩子守卫语义：

before_tool_call：{ block: true } 是终止性的，会停止较低优先级的处理程序。
before_tool_call：{ block: false } 被视为未做出决定。
before_tool_call：{ requireApproval: true } 暂停代理执行，并通过执行批准覆盖层、Telegram 按钮、Discord 交互或任何渠道上的 /approve 命令提示用户批准。
before_install：{ block: true } 是终止性的，会停止较低优先级的处理程序。
before_install：{ block: false } 被视为未做出决定。
message_sending：{ cancel: true } 是终止性的，会停止较低优先级的处理程序。
message_sending：{ cancel: false } 被视为未做出决定。

/approve 命令可处理执行和插件批准，并具有自动回退功能。插件批准转发可以通过配置中的 approvals.plugin 单独配置。

有关详细信息，请参阅 SDK 概述钩子决策语义。

注册代理工具

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

register(api) {
  // Required tool — always available
  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 }] };
    },
  });

  // Optional tool — user must add to 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/

` 路径导入：

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

// Wrong: monolithic root (deprecated, will be removed)
import { ... } from "openclaw/plugin-sdk";

有关完整子路径参考，请参阅 SDK 概述。

在插件内部，请使用本地桶文件（api.ts，runtime-api.ts）进行内部导入 —— 切勿通过其 SDK 路径导入您自己的插件。

提交前检查清单

Beta 版本测试

请关注 openclaw/openclaw 上的 GitHub 发布标签，并通过 Watch > Releases 进行订阅。Beta 标签类似于 v2026.3.N-beta.1。您也可以开启官方 OpenClaw X 账号 @openclaw 的通知以获取发布公告。
Beta 标签出现后，请立即针对该版本测试您的插件。在正式版发布前的窗口期通常只有几个小时。
测试完成后，在 plugin-forum Discord 频道中您的插件主题帖内发布 all good 或遇到的问题。如果您还没有主题帖，请创建一个。
如果出现问题，请创建或更新一个标题为 `Beta blocker:

的 issue，并应用beta-blocker标签。将 issue 链接放入您的主题帖中。 5. 向main提交一个标题为fix(

): beta blocker -

` 的 PR，并在 PR 和您的 Discord 主题帖中链接该 issue。贡献者无法标记 PR，因此标题是维护者和自动化程序在 PR 端的信号。带有 PR 的阻碍性修复会被合并；没有 PR 的阻碍性修复可能会直接发布。维护者会在 Beta 测试期间关注这些主题帖。 6. 没有消息就是好消息。如果您错过了窗口期，您的修复可能会在下一个周期落地。