构建插件

插件在无需更改核心代码的情况下扩展 OpenClaw。插件可以添加消息传递渠道、模型提供商、本地 CLI 后端、代理工具、钩子、媒体提供商或其它由插件拥有的功能。

您无需将外部插件添加到 OpenClaw 代码库。将包发布到 ClawHub，用户即可通过以下方式安装：

openclaw plugins install clawhub:<package-name>

在启动切换期间，裸包规范仍然从 npm 安装。当您需要 ClawHub 解析时，请使用 clawhub: 前缀。

要求

使用 Node 22.19 或更新版本，以及包管理器，例如 npm 或 pnpm。
熟悉 TypeScript ESM 模块。
对于代码库内捆绑插件工作，请克隆代码库并运行 pnpm install。源码检出插件开发仅支持 pnpm，因为 OpenClaw 从 extensions/* 工作区包加载捆绑插件。

选择插件形态

渠道插件

将 OpenClaw 连接到消息传递平台。

提供商插件

添加模型、媒体、搜索、获取、语音或实时提供商。

CLI 后端插件

通过 CLI 模型回退运行本地 AI OpenClaw。

工具插件

注册代理工具。

快速开始

通过注册一个必需的代理工具来构建一个最小工具插件。这是最短的有用插件形态，并展示了包、清单、入口点和本地验证。

创建包元数据

{
  "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",
  "contracts": {
    "tools": ["my_tool"]
  },
  "activation": {
    "onStartup": true
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

已发布的外部插件应将运行时入口指向构建后的 JavaScript 文件。有关完整的入口点契约，请参阅 SDK 入口点。

每个插件都需要一个清单，即使它没有配置。运行时工具必须出现在 contracts.toolsOpenClaw 中，以便 OpenClaw 可以在不急切加载每个插件运行时的情况下发现所有权。有意识地设置 activation.onStartupGateway(网关) 。此示例在 Gateway 启动时开始。

有关每个清单字段，请参阅插件清单。

注册工具

import { Type } from "typebox";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

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

对于非渠道插件，请使用 definePluginEntry。渠道插件使用 defineChannelPluginEntry。

测试运行时

对于已安装或外部插件，检查加载的运行时：

openclaw plugins inspect my-plugin --runtime --json
```CLI

如果插件注册了 CLI 命令，请运行该命令。例如，
演示命令应该有一个执行证明，例如
`openclaw demo-plugin ping`OpenClaw。

对于此仓库中的捆绑插件，OpenClaw 从 `extensions/*` 工作区发现源代码检出
插件包。运行最接近的针对性
测试：

```bash
pnpm test -- extensions/my-plugin/
pnpm check

发布

发布前验证包：

clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
```ClawHub

规范的 ClawHub 代码片段位于 `docs/snippets/plugin-publish/`。

Install
通过 ClawHub 安装已发布的软件包：
Terminal window
```
openclaw plugins install clawhub:your-org/your-plugin
```

注册工具

工具可以是必需的或可选的。必需的工具在插件启用时始终可用。可选工具需要用户选择加入。

register(api) {
  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 },
  );
}

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

{
  "contracts": {
    "tools": ["workflow_tool"]
  },
  "toolMetadata": {
    "workflow_tool": {
      "optional": true
    }
  }
}

用户通过 tools.allow 选择加入：

{
  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for all tools from one plugin
}

对副作用、不常见的二进制文件或不应默认公开的功能使用可选工具。工具名称不得与核心工具冲突；冲突将被跳过并在插件诊断中报告。格式错误的注册（包括没有 parameters 的工具描述符）也会以相同方式被跳过和报告。已注册的工具是类型化函数，模型在通过策略和允许列表检查后可以调用它们。

工具工厂接收运行时提供的上下文对象。当工具需要记录、显示或适应当前轮次的活跃模型时，请使用 ctx.activeModel。该对象可以包含 provider、modelId 和 modelRefOpenClaw。将其视为信息性的运行时元数据，而不是针对本地操作员、已安装的插件代码或修改后的 OpenClaw 运行时的安全边界。敏感的本地工具仍应要求显式的插件或操作员选择加入，并在活跃模型元数据缺失或不适用时自动失效。

清单声明所有权和发现；执行仍然调用实时注册的工具实现。保持 toolMetadata.<tool>.optional: true 与 api.registerTool(..., { optional: true })OpenClaw 一致，以便 OpenClaw 可以避免加载该插件运行时，直到工具被明确加入允许列表。

导入约定

从专注的 SDK 子路径导入：

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

不要从已弃用的根桶导入：

import { definePluginEntry } from "openclaw/plugin-sdk";

在你的插件包中，使用本地桶文件（barrel files）如 api.ts 和 runtime-api.ts 进行内部导入。不要通过 SDK 路径导入你自己的插件。特定于提供商的辅助工具应保留在提供商包中，除非该接缝真正通用。

自定义 Gateway(网关) RPC 方法是一个高级入口点。请将它们保留在特定于插件的前缀上；核心管理命名空间（如 Gateway(网关)RPCconfig.*、 exec.approvals.*、operator.admin.*、wizard.* 和 update.*）保持保留状态并解析为 operator.admin。 openclaw/plugin-sdk/gateway-method-runtime 桥接层保留用于声明 contracts.gatewayMethodDispatch: ["authenticated-request"] 的插件 HTTP 路由。

有关完整的导入映射，请参阅 Plugin SDK overview。

提交前检查清单

针对 Beta 版本进行测试

关注 openclaw/openclaw 上的 GitHub 发布标签，并通过 Watch > Releases 订阅。 Beta 标签看起来像 v2026.3.N-beta.1OpenClaw。你也可以开启官方 OpenClaw X 账号 @openclaw 的通知以获取发布公告。
Beta 标签一出现，请立即针对该标签测试你的插件。稳定版发布前的窗口期通常只有几个小时。
在 plugin-forum Discord 渠道的插件主题中发布帖文，测试 all good 或损坏的内容。如果您还没有主题，请创建一个。
如果出现问题，请打开或更新一个标题为 Beta blocker: <plugin-name> - <summary> 的问题并应用 beta-blocker 标签。将问题链接放在您的主题中。
向 main 开启一个标题为 fix(<plugin-id>): beta blocker - <summary> 的 PR，并在 PR 和您的 Discord 主题中链接该问题。贡献者无法标记 PR，因此标题是维护者和自动化工具在 PR 端的信号。带有 PR 的阻碍项会被合并；没有 PR 的阻碍项可能仍会发布。维护者会在测试期间关注这些主题。
沉默即代表通过。如果您错过了窗口，您的修复可能会在下一个周期落地。