跳转至

加载管道和注册表

发现、安全门控、清单优先元数据、插件缓存边界,以及核心读取的注册表。属于插件架构内部机制指南的一部分。

加载流水线

启动时,OpenClaw 大致执行以下操作:

  1. 发现候选插件根目录
  2. 读取原生或兼容的捆绑清单和包元数据
  3. 拒绝不安全候选项
  4. 规范化插件配置(plugins.enabled、allow、deny、entries、 slots、load.paths)
  5. 为每个候选项决定启用状态
  6. 加载已启用的原生模块:内置捆绑模块使用原生加载器;第三方本地源码 TypeScript 使用紧急 Jiti 回退
  7. 调用原生 register(api) 钩子,并将注册项收集到插件注册表
  8. 将注册表暴露给命令/运行时表面

原生插件导入会在链接插件的异步模块图之前,同步评估每个请求的 SDK 入口。这使得 CommonJS 捆绑包可以在并发通道启动期间 require() 同一个 SDK 入口,而不会看到未完成的 ESM 模块。未使用的 SDK 入口保持未加载状态。

捆绑通道入口和通道元数据模块使用共享的缓存模块加载器。它在评估前准备 SDK 别名,并负责原生到源码的回退;通道适配器不会通过另一个加载器重试失败的评估。

安全门控在运行时执行之前运行。发现阶段在以下情况下阻止候选项:

  • 其解析后的入口逃逸出插件根目录
  • 其路径(或其根目录)对所有用户可写
  • 对于非捆绑插件,路径所有者与当前 uid(或 root)不匹配

在 Windows 上,插件根目录可能位于目录联接之下,包括 Node 版本管理器前缀。在打开入口之前,根别名会按目录身份解析并验证;文件仍必须位于该根目录内。

对所有用户可写的捆绑目录会先尝试就地 chmod 修复(npm/全局安装可能以 0777 提供包目录),然后门控再检查;对于捆绑来源,完全跳过所有权检查。

被阻止的候选项在已知插件 id 时,仍会在输出的诊断中携带该插件 id(包括从否则被拒绝的目录中的清单解析出的 id),因此引用该 id 的配置会看到一个与路径安全警告关联的被阻止插件,而不是无关的“未知插件”错误。

清单优先行为

清单是控制平面的事实来源。OpenClaw 使用它来:

  • 识别插件
  • 发现已声明的通道/技能/配置模式或捆绑能力
  • 验证 plugins.entries.<id>.config
  • 增强 Control UI 标签/占位符
  • 显示安装/目录元数据
  • 在不加载插件运行时的情况下保留低成本的激活和设置描述符

对于原生插件,运行时模块是数据平面部分。它注册实际行为,例如钩子、工具、命令或提供者流程。

可选的清单 activation 和 setup 块保留在控制平面。它们是仅用于激活规划和设置发现的元数据描述符;它们不会替代运行时注册、register(...) 或 setupEntry。实时激活消费者使用清单激活元数据,在更广泛的注册表物化之前缩小插件加载范围:

  • CLI 加载缩小到拥有所请求主命令的插件
  • 通道设置/插件解析缩小到拥有所请求通道 id 的插件
  • 显式提供者设置/运行时解析缩小到拥有所请求提供者 id 的插件
  • 代理运行时规划缩小到在 activation.onAgentHarnesses 中声明所选嵌入式 harness 运行时 id 的插件
  • 启动插件选择会添加其 activation.onConfigPaths 条目在配置中存在且已启用的插件
  • Gateway 启动规划使用 activation.onStartup 进行显式启动导入;没有启动元数据的插件仅通过更窄的激活触发器加载

激活规划器同时为现有调用方暴露仅 id API,并为诊断暴露 plan API。plan 条目报告插件被选择的原因,将显式 activation.* 提示与清单所有权回退区分开:

原因(来自 activation.* 提示) 原因(来自清单所有权)
activation-agent-harness-hint —
activation-capability-hint —
activation-channel-hint manifest-channel-owner (channels)
activation-command-hint manifest-cli-command-owner (cliCommands), manifest-command-alias (commandAliases)
activation-provider-hint manifest-provider-owner (providers), manifest-setup-provider-owner (setup.providers)
activation-route-hint —
—(钩子触发没有提示变体) manifest-hook-owner (hooks), manifest-tool-contract (contracts.tools)

这种原因划分是兼容性边界:现有插件元数据继续可用,同时新代码可以检测宽泛提示或回退行为,而不改变运行时加载语义。

请求时的运行时预加载即使请求宽泛的 all 范围,仍会从配置、启动规划、已配置通道、插槽和自动启用规则推导显式的有效插件 id 集合(src/plugins/effective-plugin-ids.ts 中的 resolveEffectivePluginIds)。如果推导出的集合为空,OpenClaw 会保持范围为空,而不是扩大到每个可发现的插件。

设置发现优先使用描述符拥有的 id(例如 setup.providers 和 setup.cliBackends)来缩小候选插件,然后才回退到 setup-api,用于仍需要设置时运行时钩子的插件。提供者设置列表使用清单 providerAuthChoices、描述符派生的设置选项和安装目录元数据,而不加载提供者运行时。显式 setup.requiresRuntime: false 是仅描述符的截止点;省略 requiresRuntime 会保留旧版 setup-api 回退以兼容。如果多个已发现插件声称同一个规范化设置提供者或 CLI 后端 id,设置查找会拒绝模糊的所有者,而不是依赖发现顺序。当设置运行时执行时,注册表诊断会拒绝未声明的提供者和 CLI 后端注册。CLI 后端描述符也会报告缺失的运行时注册;提供者描述符可以保持仅元数据,同时设置模块贡献其他设置钩子。

插件缓存边界

一个 PluginCache 拥有某个保留缓存代的插件事实。 CLI 预检和启动会逐步填充同一个缓存;后续访问仅填充尚未获取的事实。其不可变元数据快照组合了已安装索引、清单、所有者映射,以及来自每个已配置 agent 工作区的可用发现事实。已禁用的插件仍保留在清单中,因此后续启用无需再次发现。来自不同工作区来源的冲突插件 ID 仍会被拒绝。

运行时读取器使用这个 PluginMetadataSnapshot、一个派生的 PluginLookUpTable,或一个显式清单注册表。插件作用域是内存中的投影;常规查找、账户变更和运行工作区变更不会触发文件系统扫描、stat/realpath 新鲜度轮询、清单重读或哈希计算。插件生命周期操作会在其自身的缓存代中准备新的元数据。账户健康状况和认证状态不属于不可变软件包清单的一部分。

原生 SDK 别名解析会在同一缓存代中保留每个导入文件的规范路径、根成员关系和别名目标。别名注册或替换会清除这些结果,元数据失效也会清除;重复导入不会重复执行文件系统规范化或包含检查。

同一缓存代会为已安装索引作用域查找、编译后的模型匹配模式、解析后的安装记录投影和清单指纹每个不可变索引仅准备一次。可变管理索引保持未缓存。查找方法和安装记录结果仍由调用方拥有;启用和信任根据当前操作的策略评估,而不是存储在这些事实中。

在保留缓存代之外,重用已加载插件要求所选 ID、来源、根、入口点和工件选择输入一致。加载器会在已加载所有者上记录源/构建选择和任何已执行的 setup 条目。显式清单和发现来源选择(包括已接纳的 sidecar)也参与加载器缓存键。原始发现在主动重用前还需要匹配的加载身份,因为其清单胜出者尚未确定。保留缓存代仍具有权威性,包括空选择。源/构建视图只有在加载器在保留偏好下将它们解析到同一执行根和入口时,才可共享同一所有者。仅路径名称或匹配的入口词干不足以确立所有权。运行时重用和加载共享现有生命周期拥有的工件事实和最终执行步骤,包括已执行的 setup 条目。发现和工件身份保留其选定路径。

有界的已加载所有者查找在未指定偏好时保留所有者的工件策略。会检查显式偏好;精确加载器请求应用完整缓存身份和冷加载默认值。

已完成的注册表会同时缓存在其原始请求和已解析的清单选择下。重用这些已准备的清单不会重复插件注册。两个键共享现有有界缓存,并在注册表退役或加载缓存清除时移除。验证、完整注册和 CLI 元数据加载具有独立的缓存条目;验证某个模块不能满足后续对其注册信息的请求。

出站通道引导会在所选插件缓存和元数据范围内记住成功和不可用的发送器。清单替换或元数据失效允许重新尝试;同一范围内的重复投递会重用结果,而不会重试失败的注册。请求范围的通道所有者仍优先于进程根引导结果。载荷准备在其处理器上携带所选发送器的指令策略,因此一个批次在解析和应用通道转换之前只解析一次其插件。

提供者查找首先使用显式调用方工作区,然后使用其元数据快照记录的工作区,包括显式共享根作用域。只有没有工作区字段的窄化元数据视图会继承活动工作区。注册表现有的加载上下文保留其工作区,因此来自其他工作区的请求或活动注册表不能替换已准备的选择。

提供者钩子共享规范的提供者注册表选择。已声明的提供者保留其名称,而提供者触发的辅助项仍会在其旁边激活。必需的加载所有者和符合条件的钩子接收器在该选择中分别捕获。已声明的提供者所有者在重用前需要匹配的物理记录和提供者注册;仅激活辅助项可能没有提供者行,但需要一次成功完成的运行时注册过程。仅 setup 过程无法证明其运行时贡献已完成。没有静态所有者的引用仅在请求范围内选择其匹配的运行时别名。已加载别名可以标识要重新加载的所有者,但只有所选注册表的当前注册决定别名接收器。仅加载的故障转移检查永远不会发现或激活插件。当它使用注册表拥有的元数据时,调用方的发现和策略输入必须与记录的指纹匹配。加载器只捕获一次规范化注册输入,包括配对的源配置;后续元数据更新保留该记录。常规查找仅当这些输入匹配时重用回调;保留缓存代保持权威性。模型引用解析从注册表或保留请求范围读取相同的已声明所有者事实,因此失败的已声明提供者不能被其他提供者的钩子别名替换。

提供者认证别名与快照一起规范化并建立索引。查找使用当前工作区信任配置在这些已准备的候选项中选择;它们不缓存信任决策或凭据。提供部分清单视图的调用方保持每次调用时新的投影,而不是共享可变元数据。

显式安装、更新、注册表刷新和 doctor 操作使用同一缓存类型的隔离缓存代,并在其生命周期租约之后获取。它们可以检查已更改的文件并重建持久化的已安装索引。实时清单替换属于 Gateway 插件生命周期:plugins.refresh 准备并应用新缓存代,然后返回其运行时回执,其中 restartRequired: false,即使被动配置重载被禁用也是如此。独立的注册表或 doctor 修复本身不能证明 Gateway 已应用修复后的文件;需要时使用 plugin Reload。

共享缓存拥有已检查的文件内容、解析后的包和清单数据、捆绑的 MCP/LSP/设置文件、插件技能路径、发现路径、已安装索引投影、编译后的模型策略、SDK 别名、产物位置以及惰性模块导出。缺失的文件和产物也是事实:它们会保持缺失,直到新的代次。发现、注册表组装和索引哈希复用相同的已检查字节,而不是在每个阶段重新打开文件。

实际代码导入在首次执行前保留其边界和文件身份检查。同意检查在已等待的批准之后使用一次新的检查,因此已更改的产物不能继承针对旧能力的批准。插件缓存会释放失败的加载,但 Node 会在进程生命周期内保留失败的原生 ESM 求值;重启账户无法修复该模块图。成功的导入会在消费者之间共享。

文档和 Web 内容提取在每次请求时从当前元数据作用域中选择回调。共享的配置对象并不会使两个清单可互换;插件缓存仍会复用它们的模块导出。公共产物适配器在提供程序选择和模块加载中都携带显式环境,包括所选配置文件的捆绑发现策略。当选择提供清单所有者时,产物从该所有者的根和入口解析,保留源覆盖和保留的模块实例。

捆绑提供程序策略查找在元数据缓存中保留其已解析表面,包括缺失。重复的模型引用规范化复用该表面,而不会再次解析产物候选项。该记忆化条目遵循所选注册表的发布版本和捆绑目录选择;注册和未发布的注册表保持未缓存。新的代次或显式元数据失效会再次解析该表面,并且受管表面保留其实例的准入检查。

CLI 调用拥有一个操作缓存,跨越配置读取、输出元数据、命令所有权、嵌套注册和操作。独立注册使用其调用方的活动代次。配置验证覆盖每个工作区;执行使用原始选定的工作区快照,或者在未证明工作区所有者时使用共享根。精确的配置/源身份和修订检查为保留的注册器设置边界。准备在 Commander 操作之前关闭,而其缓存作用域持续到操作完成,以支持延迟导入。更改的包文件需要新的操作;更改激活输入不会使兼容的包事实失效。SDK 别名映射在首次别名或转换器需求下,在其捕获的主机和权限作用域中准备。状态注册使用一个轻量外观,完整运行时稍后采用它;只有注册表代理授予存储访问。配置读取只在实际写入开始时导入写入器。

已注册的服务、钩子、工具、会话 MCP 覆盖、生成的技能链接发布和激活状态仍由运行时拥有。 活动注册表固定其选定的产物绑定,因此源模块和构建模块无法拆分其注册。原生 ESM 模块生命周期仍遵循 Node 的模块加载器。由清单派生的问题,例如“哪个插件拥有此提供程序?”,使用元数据快照而不执行插件代码。持久化的已安装索引属于管理和启动;它不是运行时读取器的新鲜度信号。

注册表模型

已加载的插件不会直接修改随机的核心全局变量。它们注册到一个中央插件注册表(src/plugins/registry-types.ts 中的 PluginRegistry),该注册表跟踪插件记录(身份、来源、起源、状态、诊断)以及每种能力的数组:工具、旧版钩子和类型化钩子、通道、提供程序、网关 RPC 处理程序、HTTP 路由、CLI 注册器、后台服务、插件拥有的命令,以及数十个其他类型化提供程序族(语音、嵌入、图像/视频/音乐生成、Web 获取/搜索、代理框架、会话操作等)。

核心功能随后从该注册表读取,而不是直接与插件模块通信。这使加载保持单向:

  • 插件模块 -> 注册表注册
  • 核心运行时 -> 注册表消费

这种分离对可维护性很重要。它意味着大多数核心表面只需要一个集成点:“读取注册表”,而不是“为每个插件模块设置特例”。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw