Skip to main content

​
构建插件

插件通过新功能扩展 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

注册代理工具、事件钩子或服务 —— 继续阅读下方内容

​
快速开始：工具插件

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

Create the package and manifest

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"]
  }
}
每个插件都需要一个清单，即使没有配置。请参阅 Manifest 了解完整架构。
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 用于非渠道插件。对于渠道，请使用 defineChannelPluginEntry — 参见 渠道插件。 有关完整的入口点选项，请参阅 入口点。
3

测试并发布

外部插件： 发布到 ClawHub 或 npm，然后安装：
openclaw plugins install @myorg/openclaw-my-plugin
OpenClaw 会首先检查 ClawHub，然后回退到 npm。仓库内插件： 放置于 extensions/ 之下 — 会自动被发现。
pnpm test -- extensions/my-plugin/

​
插件功能

单个插件可以通过 api 对象注册任意数量的功能：
功能注册方法详细指南
文本推理 (LLM)api.registerProvider(...)提供商插件
渠道 / 消息传递api.registerChannel(...)渠道插件
语音 (TTS/STT)api.registerSpeechProvider(...)提供商插件
媒体理解api.registerMediaUnderstandingProvider(...)提供商插件
图像生成api.registerImageGenerationProvider(...)提供商插件
网络搜索api.registerWebSearchProvider(...)提供商插件
代理工具api.registerTool(...)下方
自定义命令api.registerCommand(...)入口点
事件钩子api.registerHook(...)入口点
HTTP 路由api.registerHttpRoute(...)内部原理
CLI 子命令api.registerCli(...)入口点
有关完整的注册 API，请参阅 SDK 概览。 需要记住的钩子守卫语义：
  • before_tool_call: { block: true } 是终止的，并停止低优先级的处理程序。
  • before_tool_call: { block: false } 被视为未作决定。
  • message_sending: { cancel: true } 是终止的，并停止低优先级的处理程序。
  • message_sending { cancel: false } 被视为未作决定。
有关详细信息，请参阅 SDK Overview hook decision semantics。

​
注册代理工具

工具是 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/<subpath> 路径导入： 
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 Overview。 在插件内部，使用本地桶文件（api.ts、runtime-api.ts）进行内部导入——切勿通过其 SDK 路径导入您自己的插件。

​
提交前检查清单

package. 具有正确的 openclaw 元数据
openclaw.plugin. 清单存在且有效
入口点使用 defineChannelPluginEntry 或 definePluginEntry
所有导入都使用特定的 plugin-sdk/<subpath> 路径
内部导入使用本地模块，而不是 SDK 自导入
测试通过 (pnpm test -- extensions/my-plugin/)
pnpm check 通过（仓库内插件）

​
后续步骤

渠道插件

构建消息渠道插件

Provider Plugins

构建模型提供商插件

SDK Overview

导入映射和注册API参考

Runtime Helpers

通过 api.runtime 进行 TTS、搜索、子代理

Testing

测试工具和模式

Plugin Manifest

完整清单架构参考
本页面源自 openclaw/openclaw，由 BeaversLab 翻译，遵循 MIT 协议 发布。
Last modified on March 27, 2026