OpenClaw Extensions 目录边界规范:插件公共契约、导入限制与边界扩展流程

原创2026-10-15 10:38:111,828 阅读
文章标签:人工智能大模型AI 应用后端LLM 网关即时通讯AI Agent插件系统本地部署MCP Clients

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.ts and ./runtime-api.ts.

内置插件的生产代码只允许两类导入来源:

  1. openclaw/plugin-sdk/* 公共子路径(例如 openclaw/plugin-sdk/telegram 对应仓库内 src/plugin-sdk/telegram.ts 门面文件);
  2. 本插件包内的本地 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's src/**.

四条禁令,分别封住四类“伸手进内部”的捷径:

  • 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.json and the package openclaw block 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 through api.ts and, if needed, a matching src/plugin-sdk/<id>.ts facade.

插件包内的默认可见性是 private:实现目录(src/)、引导文件(如 onboard.ts)和其他本地 helper 都不构成对外承诺。要让某个符号被外部使用,必须走显式的“提升”流程:

  1. 先在 api.ts(或 runtime-api.ts)中导出该符号;
  2. 如需要,再在 src/plugin-sdk/ 下创建对应的 <id>.ts 门面文件(例如 src/plugin-sdk/telegram.ts 就是对 ./telegram-core.js、./telegram-runtime.js 的 export * 聚合);
  3. 同时登记进 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.ts first instead of letting them deep-import extension internals.

这条规则约束的是依赖方向的反向流量:当核心代码(或核心测试)想复用某个内置插件里的工具函数时,核心不允许直接 deep-import 插件的 src/**。正确做法是先把该符号从插件的 api.ts 导出,再(按 3.5 的流程)经由 SDK 门面被核心使用。这样既保持了插件包根的封闭性,也让“核心依赖了哪些内置插件能力”在 barrel 文件中一览无余。

4. 如何扩展边界(Expanding The Boundary)

文档最后一节给出三条扩展守则,对应插件 API 演进的完整操作流程:

  1. 只加不挖(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 后,边界测试仍然保持全绿。

  2. 新接缝必须向后兼容且带版本意识

    Keep new plugin-facing seams backwards-compatible and versioned. Third-party plugins consume this surface.

    从源码结构看,SDK 表面同时存在 core.ts 与 compat.ts 这类兼容层文件,印证了仓库在维护一个需要长期兼容的公开面。任何新增/修改子路径的行为都要按“第三方插件也在用”的假设来做兼容设计。

  3. 一次变更,四处同步

    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 为仓库内真实样例):

  1. 实现留在包内:extensions/bluebubbles/src/group-policy.ts(私有);
  2. 经 barrel 导出:bluebubbles/api.ts 与 bluebubbles/runtime-api.ts 均 export { resolveBlueBubblesGroupRequireMention } from "./src/group-policy.js";
  3. 核心/其他插件一律通过 openclaw/plugin-sdk/bluebubbles 这类子路径导入,而不是 extensions/bluebubbles/src/group-policy.ts;
  4. 元数据侧保持 bluebubbles/openclaw.plugin.json 的 id/channels/configSchema 与 bluebubbles/package.json openclaw 块中的 install、渠道展示信息一致,保证不执行代码即可完成发现与校验;
  5. 若新增 SDK 子路径或具名导出,则同步更新 plugin-sdk-entrypoints.json、package.json exports、门面文件与契约测试,并跑边界清单确认三种模式(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.json exports(当前 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 元数据仍然自洽。

登录后查看全文
openclaw-zero-token