本页提供 OpenClaw 插件开发的完整快速入门。从创建包元数据和 manifest 开始，到注册工具、发布到 ClawHub、测试验证，全流程覆盖。也包含 Channel 插件、Provider 插件等不同插件形状的选择指南，以及 Beta 版本的测试要求和发布前检查清单。核心命令：openclaw plugins install clawhub:<package-name>。

OpenClaw 插件开发：工具、Channel、Provider 插件构建指南

插件用于扩展 OpenClaw 的能力：消息渠道、模型 Provider、本地 CLI 后端、Agent 工具、Hook、媒体 Provider 或其他自定义能力。你不需要把插件提交到 OpenClaw 仓库——发布到 ClawHub 后，用户直接用以下命令安装即可：

openclaw plugins install clawhub:<package-name>

不指定 clawhub: 前缀时，启动过渡期仍会尝试从 npm 安装。使用 clawhub: 前缀则强制走 ClawHub 解析。

前置条件

• Node 22.19 或更新，以及 npm 或 pnpm 包管理器。
• 熟悉 TypeScript ESM 模块。
• 对于仓库内绑定的插件开发，需要克隆仓库并运行 pnpm install。源码签出的插件开发只能用 pnpm，因为 OpenClaw 从 extensions/* 工作区包加载绑定插件。

选择插件形状

• Channel 插件：连接 OpenClaw 到消息平台。→ Channel 插件文档
• Provider 插件：添加模型、媒体、搜索、抓取、语音或实时 Provider。→ Provider 插件文档
• CLI 后端插件：通过 OpenClaw 模型回退运行本地 AI CLI。→ CLI 后端插件文档
• Tool 插件：注册 Agent 工具。→ Tool 插件文档

快速入门：最小工具插件

以下步骤创建一个注册一个 Agent 工具的最简插件，包含包元数据、manifest、入口文件和本地验证。

1. 创建包元数据

package.json：

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

openclaw.plugin.json（每个插件必须有一个 manifest，即使没有配置也需要）：

{
  "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 入口点 获取完整的入口点约定。在 manifest 中，contracts.tools 声明了工具所有权，以便 OpenClaw 无需立即加载每个插件运行时即可发现。activation.onStartup 需有意设置，此处示例设置在 Gateway 启动时激活。完整 manifest 字段见 Plugin manifest。

2. 注册工具

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}` }],
        };
      },
    });
  },
});

非 Channel 插件使用 definePluginEntry，Channel 插件使用 defineChannelPluginEntry。

3. 测试运行时

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

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

如果插件注册了 CLI 命令，也运行那个命令。例如，demo 命令应有执行证明 openclaw demo-plugin ping。

对于仓库内的绑定插件，OpenClaw 从 extensions/* 工作区自动发现源码签出的插件包。运行针对性测试：

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

4. 发布

发布前验证包：

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

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

5. 安装

通过 ClawHub 安装已发布的包：

openclaw plugins install clawhub:your-org/your-plugin

注册 Agent 工具

工具可以是必选（插件启用后始终可用）或可选（需用户选择启用）。

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(...) 注册的工具也必须在插件 manifest 中声明：

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

用户通过 tools.allow 选择启用：

{
  tools: { allow: ["workflow_tool"] } // 或 ["my-plugin"] 启用该插件的所有工具
}

• 可选工具适用于有副作用、依赖不常见二进制或不应默认暴露的能力。
• 工具名不能与核心工具冲突；冲突会被跳过并在插件诊断中报告。
• 格式错误的注册（如缺少 parameters 的工具描述符）也会被跳过并报告。
• 注册的工具是模型可调用的类型化函数，经过策略和允许列表检查后执行。
• 工具工厂接收运行时提供的上下文对象。使用 ctx.activeModel 获取当前轮次的活跃模型信息，包含 provider、modelId 和 modelRef。将其视为运行时元数据，而非安全边界。敏感本地工具仍需要显式的插件或操作员同意，并在活跃模型元数据缺失或不合适时失败。

manifest 用于声明所有权和发现；执行时仍调用实时注册的工具实现。保持 toolMetadata.<tool>.optional: true 与 api.registerTool(..., { optional: true }) 一致，以便 OpenClaw 在工具被显式允许之前避免加载该插件运行时。

导入规范

从聚焦的 SDK 子路径导入：

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

不要从已废弃的根 barrel 导入：

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

在你的插件包内，使用本地 barrel 文件（例如 api.ts、runtime-api.ts）进行内部导入。不要通过 SDK 路径导入自己的插件。Provider 特定的辅助函数应留在 Provider 包内，除非接口确实通用。

自定义 Gateway RPC 方法是高级入口点，应放在插件特定的前缀下；核心管理命名空间如 config.*、exec.approvals.*、operator.admin.*、wizard.*、update.* 保留并解析为 operator.admin。openclaw/plugin-sdk/gateway-method-runtime 桥接器保留给声明 contracts.gatewayMethodDispatch: ["authenticated-request"] 的插件 HTTP 路由。

完整导入映射见 Plugin SDK 概览。

发布前检查清单

• [ ] package.json 有正确的 openclaw 元数据
• [ ] openclaw.plugin.json manifest 存在且有效
• [ ] 入口点使用 defineChannelPluginEntry 或 definePluginEntry
• [ ] 所有导入使用聚焦的 plugin-sdk/<subpath> 路径
• [ ] 内部导入使用本地模块，而非 SDK 自导入
• [ ] 测试通过（pnpm test -- <bundled-plugin-root>/my-plugin/）
• [ ] pnpm check 通过（仓库内插件）

针对 Beta 版本测试

1. 关注 openclaw/openclaw releases，并订阅 Watch > Releases。Beta 标签格式如 v2026.3.N-beta.1。也可关注官方 X 账号 @openclaw 获取发布公告。
2. Beta 标签出现后立即针对该版本测试你的插件。稳定版发布前的窗口期通常只有几小时。
3. 在 Discord plugin-forum 频道的插件线程中发布测试结果：all good 或报告损坏内容。若没有线程，新建一个。
4. 若出现问题，打开或更新一个标题为 Beta blocker: &lt;plugin-name&gt; - <summary> 的 issue，并打上 beta-blocker 标签。在 Discord 线程中放置 issue 链接。
5. 提交 PR 到 main，标题为 fix(&lt;plugin-id&gt;): beta blocker - <summary>，并在 PR 和 Discord 线程中链接 issue。贡献者无法打标签，标题是维护者和自动化工具的 PR 侧信号。有 PR 的阻塞项会合并；没有的可能会随下一个周期发布。
6. 沉默表示一切正常。如果错过窗口，你的修复可能会在下一个周期落地。

下一步

• Channel 插件 — 构建消息渠道插件
• Provider 插件 — 构建模型 Provider 插件
• CLI 后端插件 — 注册本地 AI CLI 后端
• SDK 概览 — 导入映射和注册 API 参考
• 运行时辅助 — TTS、搜索、子智能体通过 api.runtime
• 测试 — 测试工具和模式
• Plugin manifest — 完整 manifest 模式参考

相关

• 插件 Hook
• 插件架构

常见问题

如何选择插件类型？Channel、Provider、Tool 有什么区别？

Channel 插件用于接入消息平台（如 Discord、IRC），Provider 插件用于接入模型/媒体/搜索等外部服务，Tool 插件用于注册 Agent 可调用的工具函数。如果你的插件只提供 Agent 工具，选 Tool 插件；如果要添加消息渠道，选 Channel 插件；如果要让 OpenClaw 能访问某个模型或媒体服务，选 Provider 插件。

是否需要先把插件提交到 OpenClaw 仓库才能让用户安装？

不需要。发布到 ClawHub（clawhub package publish）或 npm 后，用户直接 openclaw plugins install <package-name> 安装即可。OpenClaw 会自动优先查 ClawHub。

开发完成后如何在本地测试而不发布？

对于外部插件，可用 openclaw plugins install ./my-plugin-dir 从本地路径安装。之后用 openclaw plugins inspect my-plugin 确认注册状态。对于仓库内插件，放入 extensions/* 工作区后直接运行 pnpm test -- extensions/my-plugin/。