OpenClaw Extensions 目录边界规范:插件公共契约、导入限制与边界扩展流程
OpenClaw Extensions 目录边界规范:插件公共契约、导入限制与边界扩展流程
本文基于 OpenClaw 仓库中 extensions/CLAUDE.md 的完整内容展开,讲清楚 extensions/ 目录中内置插件必须遵守的“插件边界”契约:公开入口(Plugin SDK 子路径与本地 barrel 文件)、六条硬性导入规则、openclaw.plugin.json 元数据要求,以及如何安全地扩展插件对外接口。读完本篇,你将能够判断一份 extension 代码是否越界、如何把一个内部 helper 正确地“提升”为公共 API,以及为什么仓库要用清单(inventory)测试来机械地强制这些规则。
1. extensions 目录的定位:把内置插件当第三方插件看待
extensions/ 目录存放的是 OpenClaw 的内置(bundled)插件,包括渠道插件(telegram、discord、slack、whatsapp、signal、matrix 等)、模型 Provider 插件(openai、deepseek、openrouter、ollama 等)以及搜索、语音、记忆等能力插件。当前仓库中该目录包含约 90 个插件包(每个包一个独立子目录,如 bluebubbles、brave、telegram)。
extensions/CLAUDE.md(与 extensions/AGENTS.md 内容一致)开篇给出整份规范的核心立场:
This directory contains bundled plugins. Treat it as the same boundary that third-party plugins see.
(该目录包含内置插件。请把它当作第三方插件所看到的同一边界来对待。)
这句话是整个边界的“宪法”:内置插件不是“自己人”,不允许因为它们住在 monorepo 里就随意 import 核心内部代码。这样做的收益是双重的——
- 核心(
src/)可以按“只有插件 SDK 公共面是稳定的”这一前提演进,不必为每个内置插件的内部实现兜底; - 第三方插件与内置插件面对完全相同的 API 表面,任何在内置插件上跑通的集成方式都天然对外可复现。
2. 公共契约(Public Contracts)由什么构成
文档把插件能依赖的“公共契约”拆成两类:文档(Docs)与定义文件(Definition files)。
2.1 插件系统文档
- docs/plugins/manifest.md:插件清单
openclaw.plugin.json与 JSON Schema 校验要求,当前仓库中实际存在、可直接查阅; - 文档还列出了一组插件体系文档:
docs/plugins/building-plugins.md、docs/plugins/architecture.md、docs/plugins/sdk-overview.md、docs/plugins/sdk-entrypoints.md、docs/plugins/sdk-runtime.md、docs/plugins/sdk-channel-plugins.md、docs/plugins/sdk-provider-plugins.md。这些是规范声明的公开文档面(注意:在当前仓库快照中docs/plugins/目录下实际只包含 manifest.md、community.md、agent-tools.md、voice-call.md、zalouser.md 等少数文件,其余文档属于规范引用的目标文档面)。
2.2 定义文件(Definition files)
真正以代码形式承载契约的是这几个文件:
| 文件 | 作用(结合源码可确认) |
|---|---|
| src/plugin-sdk/plugin-entry.ts | 插件入口定义,导出 OpenClawPluginApi、OpenClawPluginDefinition、ProviderAuthMethod 等核心类型,是插件注册 API 的“类型总表” |
| src/plugin-sdk/core.ts | 渠道插件核心类型面,转出 ChannelPlugin、ChannelOutboundAdapter、ChannelPairingAdapter 等适配器类型 |
| src/plugin-sdk/provider-entry.ts | Provider 插件入口,提供 SingleProviderPluginOptions、单 Provider API Key 认证(createProviderApiKeyAuthMethod)等便捷定义 |
| src/plugin-sdk/channel-contract.ts | 纯渠道契约类型(ChannelAccountSnapshot、ChannelThreadingContext 等),供插件实现与测试共用 |
| scripts/lib/plugin-sdk-entrypoints.json | 机器可读的 SDK 子路径清单,列出 index、core、channel-runtime、telegram、discord 等全部可公开导入的子路径 |
| package.json | exports 字段把上述子路径逐个映射为 openclaw/plugin-sdk/* 包导出,是 Node 解析层面上的最终契约 |
从 package.json 的 exports 字段可以确认,openclaw/plugin-sdk/* 目前共暴露了 252 个子路径,覆盖 core、runtime、channel-runtime、各渠道门面(telegram、discord、slack、signal、whatsapp 等)以及各类 *-runtime 模块。scripts/lib/plugin-sdk-entrypoints.json 与这份 exports 共同构成“哪些子路径是公开的”这一事实来源。
此外还有一个重要的代码生成机制:scripts/lib/plugin-sdk-facades.mjs 中定义了 GENERATED_PLUGIN_SDK_FACADES 清单,声明“哪些 extension 的 api.ts 会被提升为 SDK 子路径、各自导出哪些具名符号”。例如它声明 amazon-bedrock 子路径的源码是 ../../extensions/amazon-bedrock/api.js,并逐一列出 discoverBedrockModels、resolveBedrockConfigApiKey 等允许导出的符号。这印证了规范中的一条关键原则:公开面是白名单式的,不是目录级的。
3. 边界规则(Boundary Rules)逐条解析
文档的“Boundary Rules”小节给出 6 条硬性规则,下面逐条说明其含义与在仓库中的实际形态。
3.1 规则一:只能从 Plugin SDK 子路径和本地 barrel 导入
Extension production code should import from
openclaw/plugin-sdk/*and its own local barrels such as./api.tsand./runtime-api.ts.
内置插件的生产代码只允许两类导入来源:
openclaw/plugin-sdk/*公共子路径(例如openclaw/plugin-sdk/telegram对应仓库内 src/plugin-sdk/telegram.ts 门面文件);- 本插件包内的本地 barrel 文件,约定命名为
./api.ts与./runtime-api.ts。
以 bluebubbles 插件为例,它正是这个约定的标准样板:
- bluebubbles/api.ts:对外 barrel,导出
bluebubblesPlugin以及resolveBlueBubblesGroupRequireMention、isAllowedBlueBubblesSender等符号; - bluebubbles/runtime-api.ts:运行时 barrel,仅把
src/group-policy.js中的策略函数转出口; - 两个 barrel 都只是
export ... from "./src/..."的重导出,真正的实现留在包内。
3.2 规则二:禁止导入核心内部与其他插件内部
Do not import core internals from
src/**,src/channels/**,src/plugin-sdk-internal/**, or another extension'ssrc/**.
四条禁令,分别封住四类“伸手进内部”的捷径:
src/**:核心业务实现;src/channels/**:渠道层内部(注意这与公开面src/plugin-sdk/channel-contract.ts的区分——契约类型是公开的,渠道实现不是);src/plugin-sdk-internal/**:SDK 内部实现区;- 其他扩展的
src/**:禁止插件 A 直接依赖插件 B 的内部文件。
这一条不是靠约定自觉遵守的,仓库有专门的机器校验:根目录测试 extension-plugin-sdk-boundary.test.ts 调用边界清单脚本 scripts/check-extension-plugin-sdk-boundary.mjs,以三种模式做全仓扫描——
src-outside-plugin-sdk:extension 中指向 plugin-sdk 之外的src/**的导入,断言清单必须为空;plugin-sdk-internal:指向src/plugin-sdk-internal/**的导入,断言为空;relative-outside-package:使用相对路径逃出当前插件包根的导入,断言为空。
测试还要求清单输出是稳定排序的(按 file/line/kind/specifier/resolvedPath/reason 排序),并支持 --json 输出。从源码结构看,这是一种典型的“drift 即失败”(drift-as-failure)守护:任何一次违规导入都会让清单非空、测试立即变红,不需要人工 Code Review 逐行盯。
3.3 规则三:禁止相对导入逃出插件包根
Do not use relative imports that escape the current extension package root.
这条与 3.2 的最后一条互为表里,但从“相对路径”角度再堵一次:不允许 ../../telegram/src/... 这类跨包相对导入。插件包(如 extensions/bluebubbles/)是一个导入封闭单元,跨包引用必须走命名空间(openclaw/plugin-sdk/*),从而保证依赖关系在包管理器与解析层面上清晰可见。
3.4 规则四:元数据必须保持准确,做到“不执行代码也能发现与配置”
Keep plugin metadata accurate in
openclaw.plugin.jsonand the packageopenclawblock so discovery and setup work without executing plugin code.
每个插件根目录都必须有一份 openclaw.plugin.json,同时 package.json 中的 openclaw 块携带安装与选择信息。两者必须一致且准确,因为核心在发现(discovery)与配置校验(setup/validation)阶段不加载插件模块。
- docs/plugins/manifest.md 明确:缺少或损坏的 manifest 会被当作插件错误并阻塞配置校验;未知
channels.*键、未知plugins.entries.<id>等都是硬错误。必填字段只有两个:id与内联configSchema(哪怕是空 schema{ "type": "object", "additionalProperties": false, "properties": {} }也必须给); - 仓库内的实例可以直接对照:bluebubbles/openclaw.plugin.json 声明了
"id": "bluebubbles"、"channels": <a href="https://link.gitcode.com/i/669e91a98b91810cd9d5f00fa779fc81" target="_blank">"bluebubbles"]与空 schema;[extensions/openclaw.plugin.json 是askonce插件的 manifest; - 而 bluebubbles/package.json 的
openclaw块则携带了extensions: ["./index.ts"]、setupEntry、渠道展示信息(label、docsPath、blurb、preferOver等)以及install段(npmSpec、localPath、minHostVersion)。
这套“manifest 先行、代码后行”的设计意味着:openclaw plugins 相关的发现、启用/禁用、配置校验全部基于元数据完成,插件代码只在真正运行该能力时才被加载。
3.5 规则五:src/**、onboard.ts 等一律视为私有
Treat files like
src/**,onboard.ts, and other local helpers as private unless you intentionally promote them throughapi.tsand, if needed, a matchingsrc/plugin-sdk/<id>.tsfacade.
插件包内的默认可见性是 private:实现目录(src/)、引导文件(如 onboard.ts)和其他本地 helper 都不构成对外承诺。要让某个符号被外部使用,必须走显式的“提升”流程:
- 先在
api.ts(或runtime-api.ts)中导出该符号; - 如需要,再在 src/plugin-sdk/ 下创建对应的
<id>.ts门面文件(例如 src/plugin-sdk/telegram.ts 就是对./telegram-core.js、./telegram-runtime.js的export *聚合); - 同时登记进
scripts/lib/plugin-sdk-entrypoints.json与 package.json 的exports,使openclaw/plugin-sdk/<id>可被解析。
src/plugin-sdk/ 目录本身就是这个流程的产物:目录中既有通用运行时(runtime.ts、channel-runtime.ts、provider-setup.ts),也有按插件 id 命名的大量单插件门面(telegram.ts、slack.ts、discord.ts、signal.ts、whatsapp.ts、zalo.ts……),每个文件对应 plugin-sdk-entrypoints.json 中的一个子路径。
3.6 规则六:核心需要内置插件的 helper 时,先过 api.ts
If core or core tests need a bundled plugin helper, export it from
api.tsfirst instead of letting them deep-import extension internals.
这条规则约束的是依赖方向的反向流量:当核心代码(或核心测试)想复用某个内置插件里的工具函数时,核心不允许直接 deep-import 插件的 src/**。正确做法是先把该符号从插件的 api.ts 导出,再(按 3.5 的流程)经由 SDK 门面被核心使用。这样既保持了插件包根的封闭性,也让“核心依赖了哪些内置插件能力”在 barrel 文件中一览无余。
4. 如何扩展边界(Expanding The Boundary)
文档最后一节给出三条扩展守则,对应插件 API 演进的完整操作流程:
-
只加不挖(additive, not invasive)
If an extension needs a new seam, add a typed Plugin SDK subpath or additive export instead of reaching into core.
需要新的“接缝(seam)”时,正确动作是给 Plugin SDK 新增一个带类型的子路径,或追加导出一个已有子路径上的符号,而不是伸手进核心。对照 3.2 的清单测试:新子路径加入
plugin-sdk-entrypoints.json和exports后,边界测试仍然保持全绿。 -
新接缝必须向后兼容且带版本意识
Keep new plugin-facing seams backwards-compatible and versioned. Third-party plugins consume this surface.
从源码结构看,SDK 表面同时存在
core.ts与compat.ts这类兼容层文件,印证了仓库在维护一个需要长期兼容的公开面。任何新增/修改子路径的行为都要按“第三方插件也在用”的假设来做兼容设计。 -
一次变更,四处同步
When intentionally expanding the contract, update the docs, exported subpath list, package exports, and API/contract checks in the same change.
有意扩大契约时,同一次提交里要同时更新:文档、导出的子路径清单(scripts/lib/plugin-sdk-entrypoints.json)、package.json 的
exports、以及 API/契约检查(如plugin-entry.test.ts、subpaths.test.ts、package-contract-guardrails.test.ts、plugin-entry-guardrails.test.ts 这一组契约测试,以及 scripts/lib/plugin-sdk-facades.mjs 中声明的具名导出白名单)。缺少任何一环,契约测试或清单脚本就会暴露出不一致。
5. 把规范落到实操:一次“符号提升”的完整走查
综合上面各节,把一个内置插件里的函数变成公共 API 的标准路径是(以 bluebubbles 的 resolveBlueBubblesGroupRequireMention 为仓库内真实样例):
- 实现留在包内:
extensions/bluebubbles/src/group-policy.ts(私有); - 经 barrel 导出:bluebubbles/api.ts 与 bluebubbles/runtime-api.ts 均
export { resolveBlueBubblesGroupRequireMention } from "./src/group-policy.js"; - 核心/其他插件一律通过
openclaw/plugin-sdk/bluebubbles这类子路径导入,而不是extensions/bluebubbles/src/group-policy.ts; - 元数据侧保持 bluebubbles/openclaw.plugin.json 的
id/channels/configSchema与 bluebubbles/package.jsonopenclaw块中的install、渠道展示信息一致,保证不执行代码即可完成发现与校验; - 若新增 SDK 子路径或具名导出,则同步更新
plugin-sdk-entrypoints.json、package.jsonexports、门面文件与契约测试,并跑边界清单确认三种模式(src-outside-plugin-sdk/plugin-sdk-internal/relative-outside-package)仍为空。
6. 小结
extensions/是内置插件目录,其代码必须与第三方插件一样,只站在 Plugin SDK 公共面之上;- 公开契约 = 插件文档面 +
src/plugin-sdk/plugin-entry.ts/core.ts/provider-entry.ts/channel-contract.ts+plugin-sdk-entrypoints.json+package.jsonexports(当前 252 个plugin-sdk/*子路径); - 六条边界规则的核心是:只准
openclaw/plugin-sdk/*与本地api.ts/runtime-api.ts两类导入源、包根封闭、manifest 元数据先行、默认私有、反向依赖先过 barrel; - 规则由 extension-plugin-sdk-boundary.test.ts 的清单式测试机械化强制,违反即测试失败;
- 扩展边界必须 additive、向后兼容,且文档、子路径清单、exports、契约检查四处同改。
对于在 OpenClaw 中开发内置插件或评估第三方插件的开发者,这份边界规范给出了明确的合规检查清单:先问“这个导入是否落在 openclaw/plugin-sdk/* 或本包 barrel 内”,再问“这个符号是否经过了 api.ts 提升”,最后确认 openclaw.plugin.json 与 package.json 元数据仍然自洽。