本页是 OpenClaw 插件开发的快速入门教程。从创建 package.json + manifest 开始，实现工具注册，到 ClawHub 发布和安装，全流程覆盖。也包含 Channel 插件、Provider 插件的跳转链接，以及 Beta 版本测试指南。

构建 OpenClaw 插件

插件用于扩展 OpenClaw 的能力：渠道、模型 Provider、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索、Agent 工具或任意组合。

你不需要把插件提交到 OpenClaw 仓库。发布到 ClawHub 或 npm，用户用 openclaw plugins install <package-name> 安装即可。OpenClaw 会先查 ClawHub，找不到再查 npm。

前置条件

• Node >= 22 和包管理器（npm 或 pnpm）
• 熟悉 TypeScript（ESM）
• 仓库内插件：需要 clone 仓库并执行 pnpm install

选择插件类型

类型	说明	详细指南
Channel 插件	接入消息平台（Discord、IRC 等）	Channel 插件
Provider 插件	接入模型 Provider（LLM、代理或自定义端点）	Provider 插件
工具/Hook 插件	注册 Agent 工具、事件 Hook 或服务	见下文

快速入门：工具插件

这个示例创建一个注册 Agent 工具的最简插件。

步骤 1：创建包和 manifest

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（每个插件必须有）：

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

步骤 2：编写入口文件

// 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 用于非 Channel 插件。Channel 插件用 defineChannelPluginEntry。

步骤 3：测试和发布

外部插件（发布到 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

仓库内插件（自动发现）：放到内置插件工作区树下。

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

插件能力完整清单

能力	注册方法	详细指南
文本推理（LLM）	api.registerProvider(...)	Provider 插件
渠道/消息	api.registerChannel(...)	Channel 插件
语音（TTS/STT）	api.registerSpeechProvider(...)	Provider 插件#步骤5
实时转录	api.registerRealtimeTranscriptionProvider(...)	Provider 插件#步骤5
实时语音	api.registerRealtimeVoiceProvider(...)	Provider 插件#步骤5
媒体理解	api.registerMediaUnderstandingProvider(...)	Provider 插件#步骤5
图像生成	api.registerImageGenerationProvider(...)	Provider 插件#步骤5
音乐生成	api.registerMusicGenerationProvider(...)	Provider 插件#步骤5
视频生成	api.registerVideoGenerationProvider(...)	Provider 插件#步骤5
网页抓取	api.registerWebFetchProvider(...)	Provider 插件#步骤5
网页搜索	api.registerWebSearchProvider(...)	Provider 插件#步骤5
Agent 工具	api.registerTool(...)	见下文
自定义命令	api.registerCommand(...)	入口文件
事件 Hook	api.registerHook(...)	入口文件
HTTP 路由	api.registerHttpRoute(...)	架构参考
CLI 子命令	api.registerCli(...)	入口文件

注册 Agent 工具

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

  // 可选工具 — 用户需将其加入白名单
  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"] },
}

注意：

• 工具名不能与 core 工具冲突（冲突时被跳过）
• 有副作用或额外二进制依赖的工具使用 optional: true
• 用户可将插件 id 加入 tools.allow 来启用该插件的所有工具

Hook 守卫语义

• before_tool_call: { block: true } → 终止，阻止低优先级处理器
• before_tool_call: { requireApproval: true } → 暂停执行，通过 exec 审批叠加层/Telegram 按钮/Discord 交互或 /approve 命令提示用户审批
• before_install: { block: true } → 终止
• message_sending: { cancel: true } → 终止

导入规范

始终从 openclaw/plugin-sdk/<subpath> 子路径导入：

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

// 错误：整体根 barrel（已废弃，将被移除）
import { ... } from "openclaw/plugin-sdk";

发布前检查清单

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

Beta 版本测试

1. 关注 openclaw/openclaw releases，订阅 Watch > Releases。Beta 标签格式：v2026.3.N-beta.1
2. Beta 标签出现后立即针对该版本测试你的插件。稳定版发布前的窗口期通常只有几小时
3. 测试完成后在 Discord plugin-forum 频道你的插件线程中发布 all good 或报告损坏内容
4. 如有问题，开或更新标题为 Beta blocker: <plugin-name> - <summary> 的 issue，并打上 beta-blocker 标签
5. 开 PR 标题为 fix(<plugin-id>): beta blocker - <summary> 并在 PR 和 Discord 线程中链接 issue

相关文档

• 插件内部架构 — 深度架构解析
• SDK 概览 — Plugin SDK 参考
• Manifest 规范 — 插件 manifest 格式
• Channel 插件 — 构建渠道插件
• Provider 插件 — 构建模型 Provider 插件

常见问题

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

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

Q: 插件开发完后如何在本地测试而不发布？

A: 将插件目录放到工作区或用 openclaw plugins install ./my-plugin-dir 从本地路径安装。可用 openclaw plugins inspect my-plugin 确认注册状态。

Q: 可选工具和必选工具的区别是什么，我该如何选择？

A: 必选工具始终对 Agent 可用；可选工具需用户主动在配置 tools.allow 中开启。有副作用（如发送消息、执行命令）、依赖外部二进制或功能较窄的工具，建议设为可选，让用户自主决定是否启用。