快速入门
插件在不更改核心的情况下扩展 OpenClaw。插件可以添加消息渠道、模型提供者、本地 CLI 后端、代理工具、钩子、媒体提供者或其他由插件拥有的能力。
你无需将外部插件添加到 OpenClaw 仓库。将包发布到 ClawHub,用户通过以下命令安装:
裸包规范从 npm 安装。当需要 ClawHub 解析时,使用 clawhub: 前缀。
要求¶
- 所有插件 API 均为实验性。请锁定你的 OpenClaw 主机版本,并测试你声明兼容的每个版本。
- Node 24.16+ 或 Node 26.1+,以及
npm或pnpm。 - TypeScript ESM 模块。
- 对于仓库内捆绑的插件开发,克隆仓库并运行
pnpm install。源码检出插件开发仅限 pnpm,因为 OpenClaw 从extensions/*工作区包中发现捆绑插件。
选择插件形态¶
将 OpenClaw 连接到消息平台。
添加模型、媒体、搜索、获取、语音或实时提供者。
通过 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
}
}
已发布的外部插件应将运行时入口指向构建后的 JavaScript 文件。有关完整入口点契约,请参阅 SDK 入口点。
为插件的主要用户用途选择一个目录类别。此通用示例使用 other;日历插件会使用 scheduling,编码助手会使用 developer-tools,代理执行后端会使用 agent-runtimes。
每个插件都需要清单,即使没有配置也是如此。运行时工具必须出现在 contracts.tools 中,以便 OpenClaw 无需急切加载每个插件运行时即可发现所有权。请有意地设置 activation.onStartup;此示例在 Gateway 启动时加载。
受主机信任的插件表面同样受清单门控,并且对已安装的插件需要显式声明:api.registerAgentToolResultMiddleware(...) 需要每个目标运行时列在 contracts.agentToolResultMiddleware 中,api.registerTrustedToolPolicy(...) 需要每个策略 ID 位于 contracts.trustedToolPolicies 中。这些声明使安装时检查与运行时注册保持一致。
有关每个清单字段,请参阅插件清单。
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/* 工作区中发现源码检出插件包。运行最接近的定向测试:
4. 测试包安装
在发布可打包插件之前,请测试用户将获得的相同安装形态。首先添加构建步骤,将运行时入口(如 openclaw.extensions)指向构建后的 JavaScript(如 ./dist/index.js),并确保 npm pack 包含该 dist/ 输出。TypeScript 源码入口仅用于源码检出和本地开发路径。
插件构建可以使用 TypeScript 7。OpenClaw 会加载生成的 JavaScript;本地 TypeScript 源码入口使用 OpenClaw 的运行时转换器,不需要插件安装 TypeScript 编译器。
然后打包插件,并使用 npm-pack: 安装压缩包:
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 安装已发布的包:
添加插件美术资源¶
在目录、设置和安装卡片中随附 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 选择加入:
可选工具控制工具是否暴露给模型。当工具或钩子需要在模型选择之后、动作执行之前请求批准时,请使用插件权限请求。
toolMetadata.<tool>.profiles 将插件工具添加到指定的内置配置文件白名单中。例如,"profiles": ["coding", "messaging"] 会在这些配置文件中暴露该工具,而无需添加核心目录条目。操作员的显式白名单和拒绝规则仍然具有权威性。
对于副作用、不常见的二进制文件或默认不应暴露的能力,请使用可选工具。工具名称不得与核心工具名称冲突;冲突项会被跳过并在插件诊断中报告。格式错误的注册会被跳过并以同样方式报告:缺少非空 name、execute 不是函数,或工具描述符没有 parameters 对象。
工具工厂接收运行时提供的上下文对象。当工具需要记录、显示或适应当前轮次的活动模型时,请使用 ctx.activeModel;它可以包含 provider、modelId 和 modelRef。请将其视为信息性运行时元数据,而不是针对本地操作员、已安装插件代码或修改过的 OpenClaw 运行时的安全边界。敏感的本地工具仍应要求插件或操作员明确选择加入,并在活动模型元数据缺失或不合适时默认拒绝(fail closed)。
清单声明所有权和发现方式;执行时仍会调用实时注册的工具实现。保持 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 路径导入你自己的插件。除非该接缝确实通用,否则特定于 Provider 的辅助函数应保留在 provider 包中。
自定义 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 不是类型感知的,因此无法强制执行这些注解。
提交前检查清单¶
Success
package.json 具有正确的 openclaw 元数据
Success
openclaw.plugin.json 清单存在且有效
Success
入口点使用 defineChannelPluginEntry 或 definePluginEntry
Success
所有导入都使用聚焦的 plugin-sdk/<subpath> 路径
Success
内部导入使用本地模块,而不是 SDK 自导入
Success
测试通过(pnpm test extensions/my-plugin/)
Success
pnpm check 通过(仓库内插件)
针对 beta 版本测试¶
- 关注 openclaw/openclaw 发布(
Watch>Releases)。Beta 标签形如v2026.3.N-beta.1。你也可以在 X 上关注 @openclaw 获取发布公告。 - 一旦 beta 标签出现,立即针对该 beta 标签测试你的插件。稳定版之前的窗口通常只有几个小时。
- 测试后,在
plugin-forumDiscord 频道中你的插件线程中发帖(discord.gg/clawd),说明all good或哪里出了问题。如果你还没有线程,请创建一个。 - 如果出现问题,打开或更新一个标题为
Beta blocker: <plugin-name> - <summary>的 issue,并应用beta-blocker标签。在你的线程中链接该 issue。 - 向
main打开一个标题为fix(<plugin-id>): beta blocker - <summary>的 PR,并在 PR 和你的 Discord 线程中链接该 issue。贡献者无法给 PR 打标签,因此标题是维护者和自动化在 PR 侧的信号。带有 PR 的 blocker 会被合并;没有 PR 的 blocker 可能仍会发布。 - 沉默意味着通过。错过窗口通常意味着你的修复会在下一个周期落地。
后续步骤¶
构建消息通道插件
构建模型 provider 插件
注册本地 AI CLI 后端
导入映射和注册 API 参考
通过 api.runtime 使用 TTS、搜索、子代理
测试工具和模式
完整清单模式参考
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw