快速入门

插件在不修改核心的情况下扩展 OpenClaw。插件可以添加消息通道、模型提供商、本地 CLI 后端、智能体工具、钩子、媒体提供商或其他插件自有能力。

你不需要将外部插件添加到 OpenClaw 仓库。将包发布到 ClawHub，用户通过以下方式安装：

openclaw plugins install clawhub:<package-name>

裸包规范会从 npm 安装。当你希望使用 ClawHub 解析时，使用 clawhub: 前缀。

需求¶

• 所有插件 API 均为实验性。 固定你的 OpenClaw 宿主版本，并测试你声明兼容的每个版本。
• Node 24.16+ 或 Node 26.1+，以及 npm 或 pnpm。
• TypeScript ESM 模块。
• 对于仓库内捆绑插件工作，克隆仓库并运行 pnpm install。 源码检出插件开发仅支持 pnpm，因为 OpenClaw 从 extensions/* 工作区包中发现捆绑插件。

选择插件形态¶

通道插件

将 OpenClaw 连接到消息平台。

提供商插件

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

CLI 后端插件

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

工具插件

注册智能体工具。

功能插件

构建类型化操作、原生页面以及 Control UI 替换。

快速入门¶

通过注册一个必需的智能体工具来构建一个最小工具插件。这是最短的实用插件形态，涵盖包、清单、入口点和本地验证。

1. 创建包元数据

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "typebox": "1.3.34"
  },
  "peerDependencies": {
    "openclaw": ">=2026.3.24-beta.2"
  },
  "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",
  "categories": ["other"],
  "contracts": {
    "tools": ["my_tool"]
  },
  "activation": {
    "onStartup": true
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

2. 注册工具

```typescript index.ts 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() }), outputSchema: Type.Object( { input: Type.String() }, { additionalProperties: false }, ), async execute(_id, params) { const details = { input: params.input }; return { content: [{ type: "text", text: Got: ${params.input} }], details, }; }, }); }, });

非通道插件使用 `definePluginEntry`。通道插件则改用 `openclaw/plugin-sdk/core` 中的 `defineChannelPluginEntry`。

**3. 测试运行时**

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

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

如果插件注册了 CLI 命令，也运行该命令并确认输出，例如 openclaw demo-plugin ping。

对于本仓库中的捆绑插件，OpenClaw 会从 extensions/* 工作区发现源码检出插件包。运行最接近的目标测试：

pnpm test extensions/my-plugin/
pnpm check

4. 测试包安装

在发布可打包的插件之前，测试用户将获得相同的安装形态。首先添加一个构建步骤，将 openclaw.extensions 等运行时入口指向已构建的 JavaScript，例如 ./dist/index.js，并确保 npm pack 包含该 dist/ 输出。TypeScript 源入口仅用于源码检出和本地开发路径。

插件构建可以使用 TypeScript 7。OpenClaw 加载输出的 JavaScript；本地 TypeScript 源入口使用 OpenClaw 的运行时转换器，并且不要求插件安装 TypeScript 编译器。

然后打包插件，并使用 npm-pack: 安装 tarball：

npm pack --pack-destination /tmp
openclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --force
openclaw plugins inspect my-plugin --runtime --json

npm-pack: 使用 OpenClaw 为每个插件管理的 npm 项目，因此可以捕获源码检出测试可能隐藏的运行时依赖错误。它验证的是包和依赖结构，而不是与目录关联的官方信任。运行时导入必须位于 dependencies 或 optionalDependencies 中；仅保留在 devDependencies 中的依赖项不会为受管理的运行时项目安装。

不要将原始归档/路径安装作为官方或特权插件行为的最终证明。原始源码对于本地调试很有用，但它们不能证明与 npm 或 ClawHub 安装相同的依赖路径。如果你的插件依赖于受信任的官方插件状态，请通过目录支持的官方安装或记录官方信任的已发布包路径添加第二项证明。有关安装根目录和依赖项所有权详情，请参阅插件依赖解析。

5. 发布

发布使用独立的 clawhub CLI。请先安装并登录，然后在发布前验证包：

npm i -g clawhub
clawhub login
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin

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

6. 安装

通过 ClawHub 安装已发布的包：

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

添加插件美术资源¶

提供 assets/icon.png 用于在目录、设置和安装卡片中展示插件身份。为聊天中的紧凑工具调用使用单独的 assets/activity.svg 单色图标。在浅色和深色主题下以 16 px 检查活动形状；避免在标记后方使用填充方块。

一个活动图标即可覆盖整个插件。仅当工具需要不同形状时，才添加 assets/activity/<tool-name>.svg，并使用其确切的 tools.effective ID。将这些资源包含在已发布的包中，并使用 npm pack --dry-run 验证其存在。有关支持的 SVG 几何形状、尺寸限制和回退行为，请参阅活动图标契约。

注册工具¶

工具可以是必需的或可选的。当插件启用时，必需工具始终可用。可选工具在 OpenClaw 加载所属插件运行时之前需要用户明确选择加入。

工具工厂会收到受信任的运行时上下文，包括 deliveryContext、在可用时用于当前平台会话的 nativeChannelId，以及 requesterSenderId。工厂可以使用 toolContext.delivery?.send({ text, mediaUrl }) 向当前会话发送文本或媒体。该属性在活跃频道轮次之外不可用，或者当频道使用 Gateway 拥有的投递时不可用。OpenClaw 会绑定路由、账户、线程和媒体访问策略；该能力在轮次结束时过期。

register(api) {
  api.registerTool(
    (toolContext) => ({
      name: "workflow_tool",
      description: "Run a workflow",
      parameters: Type.Object({ pipeline: Type.String() }),
      outputSchema: Type.Object(
        { pipeline: Type.String() },
        { additionalProperties: false },
      ),
      async execute(_id, params) {
        await toolContext.delivery?.send({
          text: `Workflow started: ${params.pipeline}`,
        });
        return {
          content: [{ type: "text", text: params.pipeline }],
          details: { pipeline: params.pipeline },
        };
      },
    }),
    { name: "workflow_tool", optional: true },
  );
}

outputSchema 是可选的。它描述 Code Mode 和 Tool Search 使用的结构化 details 值。目录调用会在执行前拒绝无效模式，并在工具钩子之后验证最终值。对于没有稳定 JSON 结果的工具，请省略它。有关完整契约，请参阅工具插件。

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

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

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

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

可选工具控制工具是否暴露给模型。当工具或钩子应在模型选择之后、操作运行之前请求批准时，请使用插件权限请求。

toolMetadata.<tool>.profiles 将插件工具添加到命名的内置配置文件允许列表。例如，"profiles": ["coding", "messaging"] 会在这些配置文件中暴露它，而无需添加核心目录条目。显式操作员允许列表和拒绝规则仍然具有权威性。

对于副作用、不寻常的二进制文件或不应默认暴露的能力，请使用可选工具。工具名称不得与核心工具名称冲突；冲突会被跳过并在插件诊断中报告。格式错误的注册也会以相同方式跳过并报告：缺少非空 name、非函数 execute，或没有 parameters 对象的工具描述符。

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

清单声明所有权和发现；执行仍然调用实时注册的工具实现。保持 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 文件（如 api.ts 和 runtime-api.ts）进行内部导入。不要通过 SDK 路径导入你自己的插件。除非该扩展点确实通用，否则特定于提供商的辅助函数应保留在提供商包中。

自定义 Gateway RPC 方法是一个高级入口点。将它们保留在插件特定的前缀下；核心管理命名空间（如 config.*、 exec.approvals.*、operator.admin.*、wizard.* 和 update.*）保持保留，并解析到 operator.admin。 openclaw/plugin-sdk/gateway-method-runtime 桥接保留给经过身份验证的插件 HTTP 路由以及声明 contracts.gatewayMethodDispatch: ["authenticated-request"] 的已注册 RPC 处理器。嵌套 RPC 分发保留原始经过身份验证的客户端、实时权限 检查和请求拥有的取消信号。它仍然检查目标方法所需的 scopes，并在变更提交边界重新检查调用者权限； 契约从不提供合成客户端或额外 scopes。

对于完整的导入映射，请参阅 插件 SDK 概览。

OpenClaw SDK 兼容性字段带有 TypeScript @deprecated 注释， 编辑器会将其显示为迁移警告。要在构建时强制执行它们， 请启用类型感知规则，例如 @typescript-eslint/no-deprecated。 Oxlint 不是类型感知的，因此无法强制执行这些注释。

提交前检查清单¶

针对 Beta 版本进行测试¶

1. 关注 openclaw/openclaw 发布（Watch > Releases）。Beta 标签看起来像 v2026.3.N-beta.1。你也可以在 X 上关注 @openclaw 获取发布公告。
2. 一旦 beta 标签出现，立即针对该 beta 标签测试你的插件。稳定版之前的窗口通常只有几个小时。
3. 测试后，在 plugin-forum Discord 频道中你的插件线程中发帖（discord.gg/clawd），说明 all good 或什么坏了。如果你还没有线程，请创建一个。
4. 如果出现问题，打开或更新一个标题为 Beta blocker: <plugin-name> - <summary> 的问题，并应用 beta-blocker 标签。在你的线程中链接该问题。
5. 向 main 打开一个标题为 fix(<plugin-id>): beta blocker - <summary> 的 PR，并在 PR 和你的 Discord 线程中链接该问题。贡献者无法为 PR 添加标签，因此标题是维护者和自动化在 PR 侧的信号。带有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题可能仍会发布。
6. 沉默意味着通过。错过窗口通常意味着你的修复会在下一个周期落地。

后续步骤¶

通道插件

构建消息通道插件

提供商插件

构建模型提供商插件

CLI 后端插件

注册本地 AI CLI 后端

SDK 概览

导入映射和注册 API 参考

运行时辅助函数

通过 api.runtime 使用 TTS、搜索和子代理

测试

测试工具和模式

插件清单

完整清单模式参考

相关¶

• 插件钩子
• 插件架构
• 插件架构内部
• 插件 SDK 子路径
• 管理插件