本页内容
本页内容
插件内部
插件内部
这里是 OpenClaw 插件系统的深度架构参考。如需实用指南,请从下面的专题页面开始。
用于添加、启用和排查插件的终端用户指南。
使用最小可运行 manifest 的第一个插件教程。
构建一个消息频道插件。
构建一个模型提供者插件。
导入映射和注册 API 参考。
公共能力模型
功能是 OpenClaw 内的公共 native 插件 模型。本机插件可以注册一种或多种功能类型:
| 能力 | 注册方法 | 示例插件 |
|---|---|---|
| 文本推理 | api.registerProvider(...) |
anthropic, openai |
| CLI 推理后端 | api.registerCliBackend(...) |
anthropic, openai |
| 嵌入 | api.registerEmbeddingProvider(...) |
提供商自有的向量插件 |
| 语音 | api.registerSpeechProvider(...) |
elevenlabs, microsoft |
| 实时转录 | api.registerRealtimeTranscriptionProvider(...) |
openai |
| 实时语音 | api.registerRealtimeVoiceProvider(...) |
google, openai |
| 媒体理解 | api.registerMediaUnderstandingProvider(...) |
google, openai |
| 转录来源 | api.registerTranscriptSourceProvider(...) |
discord, google-meet, teams-meetings, zoom-meetings |
| 图像生成 | api.registerImageGenerationProvider(...) |
fal, google, openai |
| 音乐生成 | api.registerMusicGenerationProvider(...) |
fal, google, minimax |
| 视频生成 | api.registerVideoGenerationProvider(...) |
fal, google, qwen |
| 网页抓取 | api.registerWebFetchProvider(...) |
firecrawl |
| 网页搜索 | api.registerWebSearchProvider(...) |
brave, firecrawl, google |
| 频道 / 消息传递 | api.registerChannel(...) |
matrix, msteams |
| 网关发现 | api.registerGatewayDiscoveryService(...) |
bonjour |
| 迁移 | api.registerMigrationProvider(...) |
migrate-claude, migrate-hermes |
外部兼容性立场
该功能模型现已登陆核心并由 bundled/native 插件使用,但外部插件兼容性仍然需要比“它是导出的,因此它被冻结”更严格的标准
| 插件情况 | 指导 |
|---|---|
| 现有外部插件 | 保持基于 hook 的集成可工作;这是兼容性基线。 |
| 新 bundled/native 插件 | 优先选择显式功能注册,而不是特定于供应商的访问或新的仅钩子设计。 |
| 采用能力注册的外部插件 | 允许,但除非文档标记为稳定,否则将能力相关的辅助表面视为会演进。 |
能力注册是预期方向。在迁移期间,旧式 hooks 仍是外部插件最安全的不破坏路径。已导出的辅助子路径并不都等价——应优先选择狭窄、文档化的契约,而不是偶然导出的辅助函数。
插件形态
OpenClaw 会根据插件实际的注册行为(而不仅仅是静态元数据)将每个已加载插件归类为某种形态:
普通能力
注册恰好一种能力类型(例如一个仅提供者插件,如 arcee 或 chutes)。
混合能力
注册多种能力类型(例如 openai 同时拥有文本推理、语音、媒体理解和图像生成)。
仅钩子
只注册 hooks(类型化或自定义),不注册能力、工具、命令或服务。
无能力
注册工具、命令、服务或路由,但不注册能力。
使用 openclaw plugins inspect <id> 查看插件的形态和能力拆分。详情请参见 CLI 参考。
兼容性信号
openclaw doctor、openclaw plugins inspect <id>、openclaw status --all 和 openclaw plugins doctor 会显示这些兼容性提示:
| Signal | 含义 |
|---|---|
| 配置有效 | 配置解析正常,且插件解析成功 |
| 仅 hook(信息) | 插件只注册 hooks;这是一条受支持的路径,但尚未迁移到能力注册 |
| 已弃用的 memory-embedding API(警告) | 非捆绑插件使用旧的、特定于 memory 的嵌入提供者 API,而不是 registerEmbeddingProvider |
| 严重错误 | 配置无效或插件加载失败 |
今天 advisory/warn 信号都不会破坏您的插件。这些信号也出现在 openclaw status --all 和 openclaw plugins doctor 中。
架构概览
OpenClaw 的插件系统有四层:
清单+发现
OpenClaw 会从配置路径、workspace 根目录、全局插件根目录以及捆绑插件中查找候选插件。发现流程会优先读取原生 openclaw.plugin.json 清单以及受支持的 bundle 清单。
启用+验证
核心会决定发现的插件是启用、禁用、阻止,还是被选中用于某个独占槽位,例如 memory。
运行时加载
本机 OpenClaw 插件在进程内加载并将功能注册到中央注册表中。托管实例通过 Node 加载 JavaScript 并在需要时编译 TypeScript 源。兼容的包被标准化为注册表记录,而无需导入运行时代码。
表面消耗
OpenClaw 的其余部分读取注册表,以暴露工具、频道、提供者设置、hooks、HTTP 路由、CLI 命令和服务。
就插件 CLI 而言,根命令发现分为两个阶段:
- 解析时元数据来自
registerCli(..., { descriptors: [...] }) - 真正的插件 CLI 模块可以保持懒加载,并在首次调用时注册
这样既能将插件拥有的 CLI 代码保留在插件内部,又能让 OpenClaw 在解析前预留根命令名。
重要的设计边界是:
- manifest/config 验证应该从 manifest/schema 元数据 进行,而不执行插件代码
- 原生能力发现可能会加载受信任的插件入口代码,以构建一个不激活的注册表快照
- 原生运行时行为来自插件模块的
register(api)路径,并且api.registrationMode === "full"
该拆分允许 OpenClaw 验证配置,解释 missing/disabled 插件,并在完整运行时激活之前构建 UI/schema 提示。
回滚贡献后,失败的注册在插件诊断中仍然可见。这些记录不会进入执行范围或阻止健康的插件和核心上下文引擎准入;装载机仍然拥有其清理工作。
网关启动和重新加载屈服于插件注册之间的事件循环,以便运行状况探测和现有请求可以运行。注册顺序不变,网关仅在完整生成准备好后才发布注册表。每个插件的模块评估和register()保持同步;插件应该将昂贵的工作推迟到异步服务生命周期,或者在第一次异步使用时加载仅执行的模块。在准备就绪之前注册可调用的钩子,即使它们的实现是延迟加载的。
llama.cpp 插件遵循此分割进行设置、服务器管理、嵌入、图像描述和流式传输。注册会立即公开其功能并嵌入索引身份;相应的异步操作在第一次使用时加载其实现。
网络服务发现尊重精确准备的一代,包括空选择。当它覆盖选定的提供者时,它会重用普通的请求拥有的注册表;否则,空结果需要完整的检查清单清单。部分功能回调保留未声明的提供者的发现。准备好的 cron 运行和 Doctor 工具构建不会仅仅为了检查是否配置了网络搜索而再次注册相同的插件。 Doctor 将特定于提供者的模式规范化保留在其选定的工具生成之外。
插件元数据快照和查找表
一个 PluginCache 在第一个插件元数据访问时启动,包括网关启动之前的 CLI 预检,并在需要元数据和工件时逐渐填充。 Gateway 初创公司保留了该所有者并构建了其不可变的 PluginMetadataSnapshot。该快照包括来自所有配置的代理工作区的插件元数据,包括禁用的插件,并保留源优先级和工作区出处。它存储已安装的插件索引、清单注册表、清单诊断、所有者映射和插件 ID 规范器。包内容和延迟加载的模块导出属于同一缓存的其他类型化视图,而不是快照本身。
插件感知配置验证、启动自动启用和网关插件引导程序会使用该快照,而不是独立重建 manifest/index 元数据。 PluginLookUpTable 源自同一快照,并添加了当前运行时配置的启动插件计划。
在 POSIX 上,成功检查的条目打开还会将其规范路径发布到元数据缓存。对于普通元数据路径,发现会解析每个父目录一次并将其重用于非符号链接子目录。这些路径事实一直持续到所有者使元数据无效为止;符号链接保留文件系统解析,实际文件打开保留其描述符绑定的安全检查。 Windows 保留单独的路径解析,因为准入可以返回受信任的根别名而不是本机拼写。
当规则或默认值需要时,异步配置验证会请求元数据。仅核心设置不会加载插件清单;成功的 config get 使用插件、通道和代理配置之外的核心编辑提示,构建仅用于缺失路径诊断的 JSON 架构。代理配置使提供者模型参数架构不受插件影响。本机目录隐私首选项仍会收到其插件架构检查。
当需要元数据时,准备通过共享状态读取工作程序一起读取机器拥有的捆绑发现策略和安装的索引。元数据和所有权租赁读取仅加载其处理程序;通用命令注册表保持延迟。稍后读取会重用插件缓存,直到其所有者刷新它。私有检查快照保留自己的策略事实,而不替换实时进程缓存。
冷承诺元数据准备保留一个只读子级,用于快照分配、复制和停用。该子进程内部的共享状态工作线程承认源并读取私有字节。它在子进程退出其快照之前退出,使 SQL 远离 CLI 线程,而不将单独的读取器加载到 CLI 进程中。源文件保持不变。现有的准备快照、实时本机读取器和架构维护范围保留其现有的读取和所有权路径。需要同步服务的读者保留其传输和清理合同。
通道设置目录保留请求的工作空间和加载路径范围,包括原始插件影子,因此信任过滤可以选择适当的已安装替代方案。
启动后,运行时读取器会重用该清单,而无需文件系统发现、清单重读或新鲜度检查。狭窄的插件选择是同一清单的内存视图。更改帐户或代理的运行工作区不会使其失效。显式插件生命周期操作会在将其发布到正在运行的网关之前准备用于安装、更新、删除、源或清单编辑以及发现根更改的新清单。
插件清单响应在安装运行状况诊断和目录呈现之间共享准备好的启用和包所有权事实。这些事实属于一个同步响应准备,在托管目录加载之后和可选类别加载之前;维护业务仍在准备自己当前的所有权检查。
在代理解析的工作区之外运行,重用代理准备好的插件生成,而不是再次加载插件。当引导工作区解析为该代理的解析工作区时,根后台运行(包括技能研讨会审查和独立的 cron 作业)符合资格。在网关中,每个其他运行工作区也符合资格,因为它解析为相同的启动清单。它们的执行目录和文件系统限制保留在任务根目录中,包括在压缩期间。没有该共享清单的主机(例如在另一个工作区中直接运行 CLI)将保留其自己的工作区范围生成。
工具解析将准备好的生成记录为禁用或失败的插件(例如,选定内存插槽之外的内存插件)视为已确定的结果,并且不会在每轮中再次加载它们。
插件重新加载在异步元数据准备后协调配置观察器事件。未更改的源事件不会取消操作;新的写入或更改的配置、安装记录或源所有权仍然会取代它。
普通插件源捕获使用独立文件,包括通过别名到达的副本。在具有写时复制支持的文件系统上,这些捕获可以共享存储而不共享文件标识,从而减少大型插件的数据写入。捕获期间运行文件遏制和收据验证;稍后的源编辑将在下次重新加载时生效,而不是使现有快照失效。
旧版会话密钥迁移会选择在检查通道存在之前声明该功能的插件。已经符合迁移政策资格的所有者不需要进行渠道存在检查。范围选择仅检查其通道所有者的持久凭据,因此不相关的身份验证模块在 Doctor 修复期间保持卸载状态。此凭证范围不限制基于环境的存在信号:缺少插件的配置通道仍会产生安装和恢复提示。
提供者引用所有权针对每个不可变清单注册表编制索引一次,包括运行时 auth/catalog 别名和 CLI 后端回退。查找共享冻结的所有者列表;更新或缩小的注册表拥有自己的索引,而保留代则保留其原始所有权事实。
模型 ID 规范化策略是针对每个快照或缩小的视图准备的。模型选择、目录和运行时标准化将这一观点向前推进,而不是从其插件列表中重建策略。配置突变仅针对创作的提供者目录模型 ID 获取这些策略;通用代理模型引用不需要插件清单。空视图仍然具有权威性,并且无法从更广泛的流程快照继承策略。
舰队模型运行时准备为每个构建捕获一个不可变的配置和创作源视图。插件参数处理、激活指纹和代理查找跨代理重复使用那些捕获的事实。动态模型挂钩仍然接收每个代理的目录、工作区和模型注册表。准备工作由代理之间的事件循环决定,因此网关请求可以在大型机群构建期间运行;配置刷新创建一个新的捕获。现有安装无需更改配置或迁移。
该快照和查找表让重复的启动决策保持在快速路径上:
- 频道所有权
- 启动插件规划
- 启动插件 id
- 提供者和 CLI 后端所有权
- 设置提供者、命令别名、模型目录提供者以及 manifest 契约所有权
- 插件配置 schema 和频道配置 schema 验证
- 启动时自动启用决策
启动和热替换共享一个准备好的注册表发布者以及所有配置的代理工作区中的相同清单。重新加载会保留工作区来源,因此当另一个插件发生更改时,不会替换未更改的链接插件。替换会保留未更改的插件实例,并在耗尽受影响的服务和通道之前验证候选元数据。保留实例保留其原始注册和 api 对象;它不会再次注册。插件范围的运行时功能(例如 api.runtime.llm.complete)在每次调用开始时选择已提交的插件清单,因此保留的上下文引擎仍然可以在替换另一个插件后启动新的完成,包括恢复先前回合上下文的工作。在等效元数据或设置中重新排序对象键不会取代注册;更改的值、有序列表和显式重新加载请求仍然有效。它在注册其替换之前停止并处理先前的注册,然后一起发布运行时方法和元数据。连接的客户端在发布后刷新其插件功能。如果在发布和清理成功之前替换失败,恢复寄存器将使用新的资源所有权捕获先前的代码和配置。发布后的失败会报告已提交的生成。插件运行时导入仍然是惰性的;保留元数据不会激活每个已发现的插件。
仅当保留其确切的通道注册时,持久最终通道回复才能在无关的重新加载后使用接纳网关的当前注册表。切换还需要不变的通道设置、共享通道默认值和拥有插件设置。通道可以为可以更改外部配置的凭据添加发送者准备:Telegram 检查其解析的机器人凭据并将其固定以用于最终发送,因此更改的令牌文件内容、环境令牌和 SecretRef 值无法选择另一个机器人。没有发送方准备的通道会使用未更改的后继配置进行交付。新的或替换的通道注册、更改的设置以及关闭网关仍然被阻止。这永远不会回退到另一个网关或重试可能已经到达提供商的发送。
准备好的模型替换门保留新的运行,而已经承认的运行则使用其原始回调完成。普通静止在资源替换之前关闭插件准入;对于保留的工作没有单独的保留栏。详细的准备情况和日志报告保留的工作数量和耗尽期限;最终的 RPC 收据报告申请和任何排水通知。从实例自己的活动回调重新加载或借用同一实例的实时轮流在准备期间会失败,以避免等待自身。闲置的准备好的出版物和封闭的转弯范围不会阻止更换。与仍然开放的回合租约相匹配的嵌套静态模型获取在检查替换门之前借用该回合的原始生成,因此该回合可以在外部重新加载耗尽它时完成。借用无法更改代理、工作区、配置或选定的插件所有者。显式实时目录发现仍然遵循普通的准入和刷新。没有匹配轮租的回调和消费者仍然无法等待自己的重新加载,包括外部 --wait 请求。任意嵌套的跨插件依赖链是尽力而为;如果这样的链无法解决,则取消 --wait 或重新启动。
启用交付的请求者延续在其初始运行时获取被拒绝,并以失败的形式完成,并使用普通的最终交付作为失败通知。重新加载后重试之前请检查对话和日志。取消或撤销的工作无法发送此通知;较早执行后的拒绝保留其现有的错误路径。
虽然承认工作耗尽,但普通模型目录、身份验证状态和聊天元数据读取继续使用活动发布。目录刷新工作、下载的目录采用和新的执行仍在等待。当资源替换开始时,已发布的事实将失效;承认的工作超时可以使这些事实保持可用而无需重建它们。未完成的初创出版物仍遵循其现有的取消和恢复路径。
保留工作和飞行中通话共享 60 秒的停靠前预算。保留运行在普通呼叫准入结束之前完成。然后现有的调用就会解决,同时发布的元数据仍然可读。 Sidecar 在剩余的有限消费者耗尽之前释放其能力消费者;内存拆卸保留其确切退休提供程序实例的清理权限,直到原始清理解决。仅在切换之后替换才会停止服务和通道。闲置服务和通道托管随后将由其所有者停止。如果工作没有完成,重载失败一次,恢复准入,并清除重载状态;上一代插件仍在使用。截止日期不会取消代理运行或允许处理未完成的写入。该工作完成后重试 openclaw plugins reload <id>,或明确选择 --wait 等待承认的工作解决。显式等待属于其请求连接:Ctrl+C 或断开连接取消预发布等待并运行相同的回滚。取消永远不会处理已承认的工作、绕过清理或撤销已提交的出版物。服务关闭和恢复保留其有限的期限。成功发布会记录所应用的替换并发出 plugins.changed。
提供程序或工具插件加载失败仍记录在其运行时生成中。它使该插件不可用,而不取代使用健康插件的生成或阻止模型。使用 openclaw plugins inspect <id> --runtime --json 检查失败的所有者。使用 openclaw doctor --fix 进行支持的安装修复,或修复插件代码中报告的问题,然后通过管理网关 API 请求 plugins.reload 加载修复的插件。
只读模型验证、有效工具清单和隔离模型检查在需要可执行提供程序或harness挂钩时会获取自己的注册。并发调用者共享准备好的生成,其生命周期处理程序在最终借用者和任何未完成的准备或目录工作解决之后运行。当回调仍在运行时,取消不会关闭注册。进程关闭会在加入其剩余工作和处置之前撤销这些注册表视图。仅需要元数据的目录读取不会获取这些可执行注册。有效的工具清单仅准备已配置和会话选择的模型事实,包括从启用的提供商捕获的目录;它不会刷新完整的模型目录。会话选择不会更改配置的模型选择器。
每个插件服务启动尝试都会拥有一次清理操作,包括失败的启动。热替换会在五秒的期限内观察候选者的启动和服务清理。候选启动失败拒绝替换。替换已加载的插件需要成功清理,然后另一个注册才能获取其资源;因此,挂起的清理或清理错误可能会拒绝替换并阻止自动恢复。待处理的启动会保留其资源,直到其完成且一站式操作解决为止。插件删除可以报告延迟清理;网关关闭会在释放插件资源之前加入该工作。当物理清理完成时,处置会停止新注册的呼叫。服务清理不会仅仅因为观察者超时而被第二次调用。如果命令目录刷新也停止了未更改的通道,则失败的替换将恢复这些健康的注册,同时失败的插件仍处于隔离状态。
在发布之前失败的替换会自动尝试恢复以前的代码和配置。如果其通道已停止,恢复会观察挂起的服务清理并确认工作一次,最长持续 60 秒。它的观察有一个独立的网关拥有的取消信号,因此断开连接的重新加载请求者无法中断恢复。只有服务停止观察者超时才有资格进行此等待;通道停止故障、被拒绝的服务清理和失败的候选清理仍然会阻止恢复。此次等待与最初的服务停止承诺相结合,包括共享停止期限已满的服务。清理和工作成功解决后,恢复会处理旧的注册,使用新的资源所有权注册其捕获的代码,并重新启动其通道。手动停止的帐户保持停止状态。超时永远不会授予另一个未完成写入资源的注册所有权,并且重试不会重复服务停止或资源处置。未提交的故障也会尝试根据以前的配置重新发布准备好的模型运行时,即使插件恢复失败或无法安全运行,除非网关正在关闭。
对于发布后失败的仅插件替换,网关会尝试重新发布模型目录并根据提交的配置和插件生成回复调度。原始插件故障仍然可见,包括通道准备失败。如果模型发布也失败,操作会报告这两个失败,并要求操作员重试插件重新加载或重新启动网关。关闭或更换网关会取消此恢复;未完成的运行时工作的混合配置更改保留其现有的重新启动恢复。
当恢复无法安全完成时,操作将视为失败并释放其通道重新加载暂停。通道运行状况读取保留捕获的帐户事实,而无需调用不可用的插件代码;健康的注册可以正常重启。详细的准备情况报告 failing: ["plugin-reload"] 以及受影响的插件 ID 和可操作的恢复原因,而不是留下不确定的“重新加载”状态。在承认的工作和挂起的清理解决后重试 openclaw plugins reload <id>,或重新启动网关。永久清理失败仍然会阻止其他注册获取这些资源。
稍后的重新加载可以在挂起的清理成功完成后重试,而无需再次从已处理的实例中捕获代码。如果在服务或通道停止之后但在处理开始之前排空失败,则停顿的注册将保留其原始加载程序以供下一次重新加载的恢复捕获;当恢复失败时,普通插件调用保持关闭状态。被拒绝的替换和失败的恢复注册保留相同的清理屏障。恢复保留现有错误记录作为诊断,而不执行其代码。它永远不会用当前的包文件来替换其捕获的源已被释放的已停用的注册。
丢失捕获的源文件会产生替换警告,而不是阻止新的插件加载。恢复快照必须包含之前捕获的所有输入,包括伴随文件。如果替换失败,则恢复仅恢复具有可用捕获代码的插件;它不会用更改的已安装文件替换丢失的快照。现有的调用消耗和资源清理要求仍然适用。
网关关闭还会在初始宽限期后加入实际的利用、MCP、LSP、嵌入和媒体清理。清除活动注册表时,插件主机清理可以在超时后前进到稍后的挂钩,但注册表重置和共享数据库关闭会等待其实际完成。这些等待保留了清理资源;它们不会恢复已停用插件的运行时权限。
关闭会在等待配置重新加载完成之前关闭准入。这些重新加载仍然可以推迟现有消费者进行的清理工作。最终网关关闭会释放这些使用者,加入保留的清理,并在另一个网关启动之前报告其故障。
网关配置重新加载和启动元数据持久性使用进程绑定的插件生命周期租约。强制停止后,下一个进程可以回收其记录的同主机进程身份已被证明已死亡的租约。包安装租约保留其到期保护,因为安装程序子进程的寿命可能比其父进程长。竞争的租约会记录其持有者并在等待时观察到到期情况;在启动之前,没有进程标识的旧租约必须仍然过期才能安全地刷新插件索引。这使用现有的状态架构并且不需要更新迁移。
可执行文件CLIcleanup 报告每个超过五秒的处理程序,并继续进行稍后的清理,而不取消挂起的工作。在macOS和Node的系统CA支持启用,命令完成后自动退出等待此挂起的清理完成。显式命令退出请求和更新退出看门狗保留其有限行为。
独立插件和 Codex 监督 MCP stdio 服务通过接受的工具工作、工具清理和嵌套的 SDK 提供程序查找来保留其发现的注册。终端关闭会在释放这些注册并等待其资源处置程序之前取消并加入处理程序。传输关闭和注册处置失败到达服务调用者。使用提供的工具创建的编程服务器将这些资源留给调用者;关闭并重新连接同一服务器不会丢弃它们。
热注册表发布不等待退役主机清理;在重置共享状态之前,终端关闭还会加入早期注册表替换已启动的清理操作。激活和回滚仅适用于其捕获的注册表版本。由生命周期回调取代的激活会报告错误。
缓存规则记录在 Plugin 架构内部 中:网关保留一代缓存,而显式管理操作使用同一缓存的隔离代。网关元数据没有挂钟 TTL。
安装、更新、注册表刷新和医生流程可能会读取新的包元数据以验证其更改。单独的管理快照或已安装索引写入不会替换正在运行的网关的清单:网关生命周期所有者必须准备并发布它。运行时流使用其选择的快照或查找表,而不是回退到冷管理路径。
Runtime实例和源生命周期
推理验证对运行时的 source/build 首选项选择的工件进行指纹识别,包括显式捆绑源覆盖。加载未更改的插件会保留该证据;更改其选定的运行时文件会使它失效。
托管运行时实例拥有其模块结果、注册的可调用对象和运行时存储槽。非捆绑实例还拥有捕获的源工件。创建实例时,包插件会捕获其包输入。独立文件捕获其条目和静态已知输入,而无需复制周围的工作空间。捆绑的运行时和设置模块,包括 TypeScript 源条目,共享主机的代码标识;每个库存仍然拥有其注册的回调和清理。加载编辑后的捆绑代码需要重新启动网关;当安装加载编译输出时首先重建。
Doctor 在其维护阶段保留未执行的源快照。每个阶段都允许带有私有模块文件的新回调实例,并在释放其生命周期租约之前解决其清理问题。快照在整个操作中重复使用;在 Doctor 运行之间编辑插件源,而不是在阶段之间编辑插件源。下一次调用将捕获当前文件和依赖项。当医生完成时,保留的源监护权结束,包括在诊断过程退出之前。这不会更改正在运行的网关的清单或需要安装迁移。
条件包别名保留其包元数据,而本机 Node 条件(包括 module-sync)从捕获的元数据中选择目标。源检查使用相同的同步模块条件,而不评估插件代码。捕获的源保留了编写的导入和 require 调用之间的差异,因此 Bun 的编译器分辨率预览在第一次调用之前不会获取延迟依赖项。对于被捕获的一代来说,丢失的选定目标仍然不存在。没有导出映射的旧包也承认其现有的主条目或索引条目,而不执行未选择的代码。本机条目重复使用下面记录的入场信息。在执行之前捕获所选包的剩余主体。依赖关系链接保留现有的嵌套安装位置。安装在包旁边的依赖项在捕获中仍然是同级,包括通过相对文件系统路径读取其本机资产的可选平台包。其他祖先依赖项链接在捕获的包根目录处。 Capture 不会在各个源文件旁边添加 node_modules,因此本机插件加载器仍然可以找到其包根及其构建资产。
本机工件通过其所属的包目录被允许,保留二进制文件的包相对路径和声明的伴随库依赖项。没有承认的包根目录的工件保留其包含目录。安装程序拥有的目录使用硬链接或现有的保留目录引用;通过插件安全检查检查的文件保留独立的副本。可变源树为每个承认的身份保留一个私有目录快照,通过就地编辑保留旧的二进制文件和伴随字节。该命名空间中的文件是在入场时准备的;模块执行仍然按需。注册共享准入事实而不共享其运行时权限。托管 npm 插件支持在另一个文件系统上捕获存储,包括 tmpfs 挂载和通过符号链接到达的 npm 根。保留的本机目录根据所选主机的解析包根验证准入插件的 OpenClaw 对等体。提升的本机依赖项不需要自己的主机链接,但它解析的任何主机都必须匹配。对等路径、已解析目标和选定主机的名称不匹配;使用该主机运行 openclaw doctor --fix,然后重新加载受影响的插件。加载器记录该插件的失败并继续加载不相关的插件。私人医生检查将其本地入院事实与运营商的状态分开。临时捕获复制本机包及其同伴,因此检查更新演练永远不会向其私有数据添加硬链接。检查结束后,它们的临时捕获永远不会延迟写入已安装的索引;普通的延迟写入保留其原始状态目录。当本机包共享依赖项时,即使文件系统的 ctime 尚未提前,准入也只会协调其自己的硬链接的身份。在升级之前,会根据已安装的字节检查记录的摘要,包括之前捕获为独立副本的同伴。未改变的同伴在Doctor和reload期间仍然有效;源内容检查仍然拒绝编辑。当文件符号链接不可用时,仅当其目录保留每个捕获的同伴和选定的主机 SDK 时,一代才可以使用硬链接。否则该插件会报告加载错误,要求文件符号链接支持;更新将继续执行现有的插件失败警告行为。在捕获中,准入会检查每个不可变名称空间和伴随目录映射一次,即使父本机目录和子本机目录在同一位置重叠,也会解析每个成员一次。准备更多模块会重用这些事实并检查新承认的展示位置。替换捕获、主机选择和恢复副本会再次验证,因此 Doctor 和 Gateway 准备工作可以避免重复行走,而无需重用另一个捕获的判决。现有的已安装索引 SQLite 有效负载记录目录成员资格、设备、inode、模式、大小、mtime 和 ctime 身份、SHA-256 摘要和初始生成收据。不变的热启动重用了这些事实。添加、删除或更改同伴需要再次入场。如果记录的捕获目录丢失,则新的准入会读取已安装的包,而不会提升丢失的捕获的身份。这也适用于使用较旧更新程序的更新后 Doctor。仅 Ctime 的不确定性通过有界重新哈希来解决,包括其 inode 另一个捕获保留或释放的普通伴随文件。传统的重新加载收据保留其帧原始字节值,因此更改的收据仍然需要流式传输其本机有效负载。只读检查在以后的结算过程中永远不会发布其本地承认。延迟发布保留原始数据库权限和状态目录。 Doctor 的私有检查将捕获的代码保留在配置文件限定的临时存储中,因此删除其数据库快照无法删除仍在进程中加载的映像。完全丢失的退役捕获可以从其安装的源重建;保留的或部分存在的命名空间中丢失的文件仍然会出现加载错误。身份重用无法检测保留每个记录的身份字段的编辑。已认可的本机名称空间之外的源代码将被单独捕获和验证。已发布的本机捕获可以在普通的暂存清理中幸存下来。医生维护会删除未引用的捕获,同时保留已安装的索引引用、暖代和实时所有者。系统临时回退捕获的范围仅限于其状态目录;所有权未知的捕获将被保留。
在获取插件生命周期租约之前,网关空闲清理会检查捕获目录和 npm 保留标记。空扫描不会进行共享状态写入,并使网关的元数据缓存完好无损。当存在候选者时,清理会使用私有操作范围的缓存和一个新的安装索引有效负载来进行安装记录和本机接收保护。无效的收据仍然保留捕获,并且每次删除都会保留其实时租赁和托管检查。私有缓存在租约释放之前被处置。这些尽最大努力的扫描不会冻结文件系统:检查后创建或停用的工件仍保留用于以后的清理尝试。调度和删除标准不变。
每个捕获的生成都链接选定的主机 openclaw 包,因此从其模块启动的工作进程和子进程可以解析主机 SDK。该链接不依赖于主线程的模块挂钩,并在恢复期间重新创建。导入已解析的 SDK 文件 URL 和绝对路径保持相同的主机标识;它们不会创建主机包或其运行时块的选择性副本。即使活动插件缓存更改后,延迟的 SDK 导入和 import.meta.resolve() 也会保留该代的选定源或构建主机。快照清理和更新源检查不会通过这些链接下降到主机包中。
在现有运行时、设置或可执行文件发现检查接纳条目后,其实例将按需捕获导入的共享文件和依赖模块。相对、绝对和文件-URL 导入使用捕获的文件; TypeScript 依赖项在其自己的包范围内编译。元数据和安装检查仍然受到限制,并且不获取可执行的共享输入。
可执行加载可以通过单独捕获其选定的模块来遵循共享模块链接。冷源快照仍然拒绝插件根目录之外的链接,因此延迟安装批次和安装摘要结算需要将这些输入打包为依赖项。此模块加载路径不会捕获插件根目录外部链接的非模块资源。
首次请求的 import() 或 require() 可以观察后续的源编辑;捕获的元数据和条目字节保持不变。初始源摘要涵盖了创建时捕获;后面的输入扩展了显式源电流检查,而不更改该摘要。无效的可选包元数据仅在选择时才会失败。模块获取使用实例的当前许可,并且处置关闭进一步的获取。运行时和设置停用使用现有的五秒实例关闭预算。如果调用、保留的消费者或清理超出该预算,逻辑退休将返回强制退休诊断,其中包含仍在运行的调用和消费者计数。普通调用权限关闭,迟到的成功结果将被拒绝。物理清理以异步方式继续:捕获的文件和模块解析器将保留,直到调用、使用者和清理尾部实际解决为止。显式保留的消费者保留其承认的轮次和清理权限,直到其主机关闭或释放它。发布后其回调和迟到结果被拒绝。共享的可写状态在其清理完成之前保持所有权;后期清理失败仍然是资源切换的失败。 Web 提供商描述符保留其注册身份;运行时投影将它们的工厂和返回的工具绑定到所选的插件实例。同步源检查和失败捕获在返回之前仍会清理。
默认源在 <stateDir>/tmp/plugin-captures/<instanceId>/captures/ 下实时捕获,随机实例 ID 和一个 owner.sqlite 令牌持有其本机生命周期租约。网关元数据及其源捕获保留相同的进程本地实例;并发 CLI 进程拥有一个单独的实例。释放一个捕获不能停用另一捕获或仍在运行的元数据所有者。网关元数据为其调度程序提供每小时清理的功能;可执行文件 CLI 通过其调用范围命令自己进行维护。单独捕获源并不会创建计时器。清理不会保留第一个命令的调用上下文。当状态目录位于插件的源目录内时,托管 tmp/plugin-captures 子树将从源快照中排除。恢复仍然可以从该子树中加载保留的源包。
可执行的 CLI 命令在成功和失败时通过现有调用资源范围淘汰其插件库存。 Gateway 发布所采用的库存随着 Gateway 元数据的停用而保留。在进程退出时,捕获所有者同步收回持有该进程保管权的任何剩余实例,包括显式退出和 CLI-handled 信号。强制终止仍然依赖于启动回收。插件清理拥有这个捕获子树;回收会在废弃令牌之前删除捕获的有效负载,因此部分删除仍然可以重试。令牌在其目录被删除之前关闭,包括在 Windows 上。
当前进程中映射的本机库通过进程退出保留其捕获和令牌,即使在删除其 JavaScript 模块缓存条目后也是如此。清理在该捕获生命周期内记录 retained-by-loaded-module 一次,而不是尝试取消链接加载的 Windows 图像。未更改的本机包标识在重新加载时继续共享保留的有效负载。当初始化抛出时,本机加载尝试也会保留其捕获:本机映像可以在初始化错误后保持映射。
在加载运行时插件之前,启动会尝试在独占维护所有权下进行收据感知清理。它可以立即回收已退役、未锁定的实例,包括保留到上一个进程退出之前保留的未发布的本机有效负载。已安装索引仍引用的已发布本机有效负载仍然可用。如果另一个进程拥有国家所有权,则这种机会主义清理会默默地跳过,而不要求操作员停止健康的网关。其他维护或清理失败会产生警告并继续启动;观察性阅读不会影响捕获的内容。
每小时清理也会检查这个拥有的子树。实例在一小时后变得符合资格。仅凭年龄并不能授权删除:对于带有代币的实例,清理还必须获取现有代币的专有本机租约以证明释放的托管权。这在进程终止或重新启动后没有 PID 或启动命名空间记录时起作用,并为已发送的 owner.sqlite 标记保留相同的清理合同。清理会在删除之前重新检查目录和令牌身份。实时租约、不可读的条目、符号链接和无效令牌会保留文件。仅在完整的过程和开放文件普查证明不活动,然后成功进行重命名检查后,才会回收因分配中断或较旧的部分清理而没有令牌的老化实例。分配在创建有效负载之前创建令牌,而处置则在其令牌之前删除有效负载。令牌属于其捕获实例;捕获不会创建全局协调数据库。删除仍然是异步的和建议性的。该子树被排除在状态备份之外,因为其捕获的包字节是可重构的。
在需要源捕获之前,元数据保留不会创建目录。如果状态目录无法接受捕获,则加载将回退到隔离的系统临时实例并报告警告。正常处理仍然会删除该实例;自动清理不会扫描不相关的系统临时根。没有总磁盘配额,活动实例可以合法地超过一小时的清理宽限期。如果在实例仍保留托管权时删除其有效负载目录,则下一次捕获将在同一租约下重新创建该目录。这不会恢复以前删除的捕获文件或重新创建丢失的所有权目录。
启动和每小时清理还会回收选定状态临时目录和当前系统临时目录中的无令牌 openclaw-plugin-build-* 和 openclaw-model-catalog-* 根。根必须超过一小时并且没有托管令牌。在 macOS 和 Linux 上,清理会在重命名之前重新检查每个旧根是否属于当前 UID,即使在特权运行中也保留其他用户的捕获。现场 OpenClaw 生产者保留无令牌根。在 Linux 上,清理还会检查进程文件描述符、工作目录和映射文件,包括不是 OpenClaw 进程的持有者。只有在没有持有人的情况下进行完整的人口普查才允许移除。受限的 procfs 挂载(hidepid 限制或 subset=pid)会保留根,并发出 restricted-procfs 警告。不可读或不完整的检查会保留根,并在每次扫描时发出一个警告并说明原因;清理会在稍后的扫描中重试,而不会中断加载或更新。没有完整的开放文件检查的平台(包括 macOS 和 Windows)保留无令牌根。具有托管代币的托管实例继续在所有平台上使用其本机租约。单独的重命名检查永远不会确定不活动。
年长的openclaw-plugin-build-*系统临时目录中的目录没有所有者记录来证明其生产者是否还活着。医生报告无令牌openclaw-plugin-build-*和openclaw-model-catalog-*状态临时目录下的根目录,~/.openclaw/tmp即使选择另一个状态目录,当前系统临时目录,/tmp on POSIX主机和记录的托管服务TMPDIR地点。它会删除重复的目录别名并报告每个捕获的路径和常规文件大小,而无需跟踪捕获内的链接。目录根包括所有嵌套的openclaw-plugin-build-*树木报告的尺寸和移除收据。
openclaw doctor --fix 仅在 Doctor 负责网关维护且完整的主机进程普查未发现其他 OpenClaw 生产者时收回这些遗留根。该规则在每次删除之前重新检查这两个条件,并打印一份收据,列出已删除的路径及其大小。活着的兄弟姐妹、无法进行人口普查或缺少维护权限都会将捕获物留在原处并附上解释性消息。在当前进程中创建或更改的捕获和带有令牌的捕获保持不变。 Linux 和 macOS 在检查进程时保留本机参数边界。 macOS还可以通过内核可执行路径和有效的Apple平台签名来识别另一个用户下的本机系统服务;其他实时进程不可用的参数会使清理工作因某种原因而被阻止。在没有完整进程普查的主机上(包括 Windows 和公认的容器环境),Doctor 会报告遗留捕获,但会跳过它们的删除。对于共享主机临时目录的容器,请在停止 OpenClaw 容器后在主机上运行维护。 Doctor 的维护修复仍然与运行时回收分开:其更广泛的库存包括当前运行时不使用的旧服务临时位置。现代捕获保留了托管令牌清理功能。
配置的网关代理在每个插件清单生命周期共享一个模型目录工作器。代理和认证事实属于每个任务;插件注册和捕获的源保留在共享清单中。提供自己环境的独立主机为该环境保留一个独立的目录工作人员。提供程序发现条目在加载时使用确切选定的运行时实例的捕获源,因此发现不会创建同一插件包的第二个副本。独立发现保留其自己的设置生命周期。每个工作线程都会保留每个加载器工作区的当前插件注册上下文,由具有匹配配置、环境和插件清单的代理共享。交替未更改的工作空间重用其捕获的源;替换一个工作区不会驱逐另一个工作区。在该工作线程中,未更改的已安装本机 ESM 条目会保留一个模块评估,并跨配置修订为每个工作区捕获 URL。在原始一代发布后,其捕获和编译的 TypeScript 帮助程序仍然可用于延迟导入。每一代仍然拥有其注册和解析挂钩;已发布的世代无法使用替换世代的 API 来注册提供程序。不同的工作空间保留单独的模块。 Node 保留每个本机模块直到工人退休,因此新安装的路径或工作区仍会添加常驻模块。当工作进程重新启动时,将拾取已安装的源替换;显式恢复保留其单独的源保管权。 CommonJS 捕获和处置不变。代理凭据和配置的模型事实随每个请求一起传送;目录作业不会重建代理工作区。 Discovery 重用该上下文已获取的注册。第一个目录请求一起准备代理的已知配置和凭据提供程序的注册;只有请求的提供者运行目录挂钩。新观察到的所有者扩展了这种背景,但没有放弃早期的所有者。承认的工作解决后,替换将释放它们。本机准入在 180 秒目录刷新截止时间之外运行,因此慢速文件系统不会重复丢弃并重新捕获同一包。每个经过验证的本机名称空间成员都会推进一个计数器,除非活动插件发生更改,否则每秒最多通过现有工作任务通道转发一次。当计数器前进时,家长允许继续入场。 180 秒没有进展后,它会记录命名插件和本机参考验证阶段的失败,并关闭工作程序,而不自动重新捕获该清单。重新加载插件或重新启动网关以重试。父探测和排队请求保持受限;提供商发现在准入后开始其自己的 180 秒截止日期。库存报废和停工仍然导致工人关闭。成功进行物理清理后,退役的插件实例会释放其注册表引用,同时保留撤销。本机模块导出不再通过实例所有权保留已处置的注册表,并且过时的调用仍然被拒绝。待处理或失败的清理保留其保管权。成功处理的注册会保留其插件缓存。
目录观察是被动的。库存请求可以要求目录所有者续订过期的提供程序,同时返回其接受的行。聊天元数据和会话投影仅观察发布,因此刷新无法通过其自己的通知自行安排。选定的本机模型发现具有独立的采购所有者,并且不等待提供商库存更新。两位所有者在发布前将他们的结果与最新接受的对应结果合并。目录工作线程使用 512 MiB V8 老一代限制,而不是继承网关的堆预算。主隔离初始化后,启动会清除 V8 的进程范围堆覆盖,因此显式堆标志仍会调整网关的大小,而工作线程限制仍然有效。显式 V8 标志冻结或矛盾标志检查可防止此重置并发出警告。本机和外部分配超出了工作人员限制。当网关目录工作器发生故障时,网关会记录一条警告并说明原因,并将 status 中的故障计数为 workerPools.modelCatalog.workerFailures。除了停止的本机准入之外,故障还会在新工作线程上重新发布受影响的代理目录。
目录和身份验证刷新任务带有主机准备的 Claw 同意来源。工作线程配置重建和提供程序导入使用这些事实,而无需打开或复制共享状态数据库。主机配置发布和 Doctor 保留其现有的出处刷新和工件保留检查路径;存储的数据、模式和 update/rollback 行为保持不变。
凭证持久性会在凭证发现之前发布新的共享存储所有权。登录和显式身份验证刷新会加入凭证所有者的发布,而不是为相同的更改创建另一个目录生成。
模型目录工作人员将捕获的插件文件保存在同一托管捕获实例下的工作人员拥有的目录中,并由其生产者保留保管权。父进程在该工作进程退出后删除所有剩余的捕获,包括取消和崩溃。当工作进程运行时,文件仍然可用,并且退休一个工作进程不会删除另一代的捕获。如果整个网关被杀死,现有的每小时清理只有在可以获得现有令牌的独占本机租约时才会回收废弃的实例。相同的规则适用于已发货的 SQLite 标记,并在重新启动后起作用。年龄本身永远不会释放捕获。取消会在worker退出后释放计算能力;终端关闭也会等待文件清理。失败的文件删除将报告为清理警告。
单独加载元数据不会执行每个插件,并且注册保持同步。同步加载的 TypeScript 条目及其同步 TypeScript 导入保留 Jiti 的 CommonJS 编译行为,包括 .mts 和 .mtsx 条目。 Node 评估捕获的输出。让顶级等待远离同步入口点;通过生命周期回调或稍后的动态导入启动异步工作。
动态 TypeScript 导入保留异步 CommonJS 执行,包括顶级等待和 module.exports,而从本机 JavaScript 加载的源遵循 Node 的模块格式。第一次评估修复了实例的模式;单独解析一个模块并不能对其进行评估。源 import.meta.resolve 保留了 Jiti 的可选父级 URL 和分辨率选项,包括自定义条件和 try。单参数解析器使用源目录和包范围。当仅存在 helper.ts 时,捕获本地 TypeScript 导入(例如 ./helper.js)的重用解析状态,避免重复解析器设置和基于异常的文件探测。现有的 JavaScript 和 Jiti 的替代文件名优先级保持不变。解析器状态随其捕获而释放;新捕获独立选择当前源输入。从捕获的源加载的条目保留其实例的评估失败,而不是通过另一个加载器重试。核心提供的 JavaScript 和在捕获的插件实例外部加载的库保持其现有的 native/Jiti 加载行为。
主机插件 SDK 始终保留在主机的本机模块图中,包括当 Jiti 编译插件条目时。 SDK 别名使用解析的文件系统路径,因此符号链接签出无法创建另一个主机所有者。运行主机选择源或内置的SDK模块;插件的文件扩展名不会选择第二个 SDK 图表。源主机需要本机 TypeScript 加载器,例如存储库的工具预加载。无法本地加载的 SDK 会失败,而不是由插件变压器再次评估。插件重新加载可能会创建插件私有代码的新实例,而现有插件和替换插件共享主机 SDK 身份和权限。
捕获的包还保留指向所选主机安装的链接,以便子工作程序和进程可以导入其公共 SDK。这些单独的隔离使用安装的正常包导出;它们不继承父级的源别名或权限。捕获处理会删除链接,而不是主机包。
托管 TypeScript 文件名元数据(import.meta.url、import.meta.filename、import.meta.dirname、__filename 和 __dirname)标识捕获的源,以便相关资产读取保留在该代内。 Node 从单独的目录执行编译后的JavaScript;其模块 URL 和 CommonJS 缓存键可能与源文件名不同。
Node通过Module.registerHooks拥有插件解析;即使 Module.registerHooks 存在,Bun 也会保留其 native/Jiti 加载器和 Bun.plugin 解析器。
Bun 使用其 native/Jiti 加载器,为每个托管实例提供单独捕获的源工件。 Reload 准备新的 TypeScript 条目和帮助程序,而现有使用者保留其旧实例。处置会删除该实例捕获的缓存记录和文件,而不驱逐其替换实例或主机 SDK。原生导入和 Jiti 导入保留其各自的包装条件。
Bun 需要本地包 import/export 目标在本机解析之前存在。因此,选择性捕获在评估之前获取与这些声明匹配的现有文件,包括条件分支和通配符目标。未选择的源仍然是原始字节;不评估其代码和 TypeScript 配置。这比Node的需求驱动捕获在启动时可以读取更多的文件。其他延期进口仍通过实例当前的准入在首次使用时获取来源;已经准备好的模块无需新购。选择依赖项的包导入将其保留的文件一起提升,包括预取条目的物理别名。延迟 require 调用的编译器预览在调用执行之前不会获取嵌套依赖项主体。 Bun 保留内置包导入目标及其本机验证的所有权。
使用 Jiti 的 TypeScript 路径设置时,请在插件处于活动状态时保留原始 tsconfig 文件和配置依赖项可用。加载的模块保留其选择的路径映射;以前未访问的模块可能会在首次使用时读取这些配置文件。新加载的实例选择当前路径设置。在 Windows 上,显式和相对 tsconfig 路径仍然解析来自实例捕获源的托管导入,包括编辑源文件后的延迟导入。
注册表退役会撤销与物理资源释放分开的托管执行。取得的检查可以释放其执行权限,而借款人仍持有底层注册资源;最后的物理索赔拥有其处置权,包括在释放请求结束后仍然可用的清理工作范围。裸 SDK 提供程序结果保留其自己的实例使用者,因此它们的回调仍然可用,直到拥有的 SDK 主机关闭。该主机在释放消费者和资源之前加入承认的回调工作;解除检查仍然可以防止新的借款。网关关闭会保留共享依赖项,直到仍然需要它们的所有者加入为止。这些所有权规则不会使本机插件成为沙箱或自动关闭插件创建的资源。请参阅 Plugin 生命周期和 cleanup 了解插件作者的清理合约。
已承认的代理轮流通过已接受的提交和引擎处置来保留其原始上下文引擎。重新加载可以在该回合完成时报告延迟清理。启动引擎处理会立即关闭其正常回调;发动机的清理工作仍归公司所有,直到问题解决为止。
激活规划
激活规划属于控制平面。调用方可以在加载更广泛的运行时注册表之前,询问哪些插件与某个具体命令、提供者、频道、路由、agent harness 或能力相关。
规划器保持当前 manifest 行为兼容:
activation.*字段是显式的规划器提示providers、channels、commandAliases、setup.providers、contracts.tools和 hooks 仍然是 manifest 所有权回退- 仅 ids 的规划器 API 对现有调用方保持可用
- plan API 会报告原因标签,以便诊断能够区分显式提示和所有权回退
频道插件和共享消息工具
频道插件不需要注册单独的 send/edit/react 工具来进行正常的聊天操作。 OpenClaw 在核心中保留了一个共享的 message 工具,通道插件拥有其背后特定于通道的发现和执行。
当前边界是:
- core拥有共享的
message工具主机、快速接线、session/thread记账、执行调度 - 频道插件拥有作用域内的动作发现、能力发现以及任何频道特定的 schema 片段
- 频道插件拥有提供者特定的会话对话语法,例如对话 ids 如何编码线程 ids,或如何从父对话继承
- 频道插件通过其动作适配器执行最终动作
对于频道插件,SDK 表面是 ChannelMessageActionAdapter.describeMessageTool(...)。这个统一的发现调用让插件能够将其可见动作、能力和 schema 贡献一起返回,从而避免这些部分彼此偏离。
消息动作名称使用一种有意设计为封闭且由核心拥有的词汇,以便每种传输方式都能呈现每个动作。插件只能通过核心 PR 添加动作名称;运行时注册是明确不受支持的。
当特定于通道的消息工具参数携带媒体源(例如本地路径或远程媒体 URL)时,插件还应从 describeMessageTool(...) 返回 mediaSourceParams。 Core 使用该显式列表来应用沙箱路径规范化和出站媒体访问提示,而无需对插件拥有的参数名称进行硬编码。更喜欢那里的动作范围的地图,而不是一个通道范围的平面列表,因此仅配置文件的媒体参数不会在 send 等不相关的动作上得到规范化。
核心会在该发现步骤中传入运行时作用域。重要字段包括:
accountIdcurrentChannelIdchatType(入方向路由建立时为direct、group或channel)currentThreadTscurrentMessageIdsessionKeysessionIdagentId- 可信的入站
requesterSenderId
这对于上下文相关的插件很重要。通道可以根据活动帐户、当前 room/thread/message、权威对话类型或可信请求者身份来隐藏或公开消息操作,而无需在核心 message 工具中硬编码特定于通道的分支。将 chatType 视为当前入站路由提供的发现范围,而不是从不透明的通道 id 再次推断的范围;当该路由未建立会话类型时,它不存在。
这就是为什么嵌入式运行器路由更改仍然是插件工作的原因:运行器负责将当前 chat/session 身份转发到插件发现边界,以便共享 message 工具公开当前回合的正确通道拥有的表面。
对于频道拥有的执行辅助工具,频道插件应将执行运行时保留在其自身的插件模块中。核心不再在 src/agents/tools 下拥有 Discord、Slack、Telegram 或 WhatsApp 的消息动作运行时。我们不会发布单独的 plugin-sdk/*-action-runtime 子路径,这些插件应直接从其自有模块中导入本地运行时代码。
一般来说,相同的边界适用于提供者命名的 SDK 接口:核心不应为 Discord、Signal、Slack、WhatsApp 或类似插件导入特定于通道的便利桶。如果核心需要某种行为,则可以使用捆绑插件自己的 api.ts / runtime-api.ts 桶,或者将需求提升为共享 SDK 中的狭窄通用功能。
捆绑插件遵循相同的规则。捆绑插件的 runtime-api.ts 不应重新导出其自己品牌的 openclaw/plugin-sdk/<plugin-id> 外观。这些品牌外观仍然是针对外部插件和较老消费者的兼容性垫片,但捆绑插件应使用本地导出以及狭窄的通用 SDK 子路径,例如 openclaw/plugin-sdk/channel-policy、openclaw/plugin-sdk/runtime-store 或 openclaw/plugin-sdk/webhook-ingress。新代码不应添加特定于插件 ID 的 SDK 外观,除非现有外部集成的兼容性边界需要它。
针对 poll,存在两条执行路径:
outbound.sendPoll是适用于符合通用 poll 模型的频道的共享基线actions.handleAction("poll")是适用于频道特定 poll 语义或额外 poll 参数的首选路径
现在,核心会在插件 poll 分发拒绝该动作之后,再推迟共享 poll 解析,因此插件拥有的 poll 处理器可以接受频道特定的 poll 字段,而不会先被通用 poll 解析器阻挡。
完整启动顺序请参见 插件架构内部。
能力所有权模型
OpenClaw 将原生插件视为 公司 或 功能 的所有权边界,而不是把各种互不相关的集成杂糅在一起的“杂物袋”。
这意味着:
- a 公司插件通常应该拥有该公司的所有 OpenClaw- 表面
- 功能插件通常应拥有其引入的完整功能表面
- 通道应消费共享的核心能力,而不是临时性地重新实现提供方行为
供应商多功能
google 拥有文本推理、CLI 后端、嵌入、语音、实时语音、媒体理解、image/music/video 生成和网络搜索。 openai 拥有文本推理、嵌入、语音、实时转录、实时语音、媒体理解、图像生成。 minimax 拥有文本推理加媒体理解、语音、image/music/video 生成和网络搜索。
供应商单一能力
arcee 和 chutes 仅拥有文本推理;microsoft 仅拥有语音。厂商插件可以一直保持这种窄范围,直到它需要覆盖该厂商更多的表面。
功能插件
voice-call 拥有通话传输、工具、CLI、路由以及 Twilio 媒体流桥接,但它消费共享的语音、实时转录和实时语音能力,而不是直接导入厂商插件。
期望的最终状态是:
- a 供应商的 OpenClaw-face 位于一个插件中,即使它跨越文本模型、语音、图像和视频
- 其他厂商可以针对自己的功能做同样的事情
- 通道不关心哪个厂商插件拥有提供方;它们消费 core 暴露的共享能力契约
这一区分非常关键:
- plugin = 所有权边界
- capability = 可由多个插件实现或消费的核心契约
因此,如果 OpenClaw 添加视频等新域,第一个问题不是“哪个提供商应该对视频处理进行硬编码?”第一个问题是“核心视频能力合约是什么?”一旦该合同存在,供应商插件就可以对其进行注册,并且 channel/feature 插件可以使用它。
如果该能力还不存在,通常正确的做法是:
定义能力
在 core 中定义缺失的能力。
通过SDK暴露
以类型安全的方式通过插件 API/runtime 暴露它。
电线消费者
根据该功能连接 channels/features。
供应商实施
让厂商插件注册实现。
这样既能保持所有权明确,又能避免依赖单一厂商或一次性插件专用代码路径的 core 行为。
能力分层
在决定代码应该放在哪里时,可以使用这个心智模型:
核心能力层
共享编排、策略、回退、配置合并规则、交付语义以及类型化契约。
供应商插件层
供应商特定的 API、身份验证、模型目录、语音合成、图像生成、视频后端、使用端点。
Channel/feature 插件层
Discord/Slack/voice-call/etc. 集成,消耗核心功能并将其呈现在表面上。
例如,TTS 遵循这样的结构:
- core 拥有回复时 TTS 策略、回退顺序、偏好设置和通道交付
elevenlabs、google、microsoft和openai拥有合成实现voice-call消费电信 TTS 运行时辅助工具
未来的能力也应优先采用同样的模式。
多能力公司插件示例
从外部看,公司插件应该是内聚的。如果 OpenClaw 对模型、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取和网页搜索拥有共享契约,那么某个厂商可以在一个地方拥有它的全部表面:
重要的不是这些辅助函数的准确名称,而是这种形态:
- 一个插件拥有厂商表面
- core 仍然拥有能力契约
- 提供方请求转换和 HTTP 辅助工具保留在厂商插件中
- 通道和功能插件消费
api.runtime.*辅助工具,而不是厂商代码 - 契约测试可以断言插件注册了它声称拥有的能力
能力示例:视频理解
OpenClaw 已经将 image/audio/video 理解视为一种共享能力。相同的所有权模型也适用于此:
核心定义合约
core 定义媒体理解契约。
供应商插件注册
厂商插件按需注册 describeImage、transcribeAudio 和 describeVideo。
消费者使用共享行为
通道和功能插件消费共享的 core 行为,而不是直接连接到厂商代码。
这样可以避免把某个提供方的视频假设写进 core。插件拥有厂商表面;core 拥有能力契约和回退行为。
视频生成已经使用了相同的顺序:core 拥有类型化的能力契约和运行时辅助工具,而厂商插件围绕它注册 api.registerVideoGenerationProvider(...) 实现。
需要具体的部署清单吗?请参阅 添加功能 。
契约与约束
插件 API 表面被有意设计为类型化并集中在 OpenClawPluginApi 中。该契约定义了插件可用的注册点,以及插件可以依赖的运行时辅助工具。
这之所以重要,是因为:
- 插件作者获得了一个稳定的内部标准
- core 可以拒绝重复所有权,例如两个插件注册相同的 provider id
- 启动时可以针对格式错误的注册提供可执行的诊断信息
- 契约测试可以强制执行打包插件的所有权并防止悄然漂移
有两层约束:
运行时注册强制执行
插件注册表会在插件加载时校验注册。示例:重复的 provider id、重复的 speech provider id 以及格式错误的注册会生成插件诊断,而不是未定义行为。
合同测试
在测试运行期间,会将打包插件捕获到契约注册表中,以便 OpenClaw 能明确断言所有权。当前这用于模型提供方、语音提供方、网页搜索提供方以及打包注册所有权。
实际效果是 OpenClaw 预先知道哪个插件拥有哪个表面。这使得核心和通道可以协同工作,因为所有权是声明的、类型化的和可测试的,而不是隐式的。
契约中应该包含什么
好合同
- 类型化
- 小而精
- 面向特定能力
- 由 core 拥有
- 可被多个插件复用
- 由 channels/features 消耗,无需供应商知识
不良合同
- 将厂商特定策略隐藏在 core 中
- 绕过注册表的一次性插件逃逸口
- 通道代码直接进入厂商实现
- 不属于
OpenClawPluginApi或api.runtime的临时运行时对象
拿不准时,就提高抽象层级:先定义能力,再让插件接入它。
技能预览
Control UI 可以预览已声明的插件技能,而无需安装或执行它。打开预览会读取其文件清单,并且仅读取条目 SKILL.md 正文。选择另一个文件按需读取该正文;导航从不预取同级内容。在加载选定文件时,文件树保持可用,并且可以就地重试失败的读取。
目录读取保持固定到选定的包版本,并验证库存的路径、大小和 SHA-256 哈希值。安装的读取保留在已解析的插件根目录中,拒绝不安全的链接,并拒绝更改的插件版本。两个路径都保留文件计数、树深度、每个文件和聚合捆绑包限制。总计限制适用于库存,而不是选择订单。
加载的主体和挂起的读取属于一个开放的预览和网关连接。关闭、重新打开、离开或重新连接都会停用该缓存。迟到的文件响应可以填充其自己的缓存条目,但无法更改所选文件。新的选定文件请求重新验证库存;仅重复使用已加载的实体。就地编辑的已安装文件在重新打开时可见。
执行模型
原生 OpenClaw 插件和网关在同一进程内运行。它们未进行沙箱隔离。已加载的原生插件与核心代码共享相同的进程级信任边界。
默认情况下,兼容捆绑包更安全,因为 OpenClaw 当前将它们视为 metadata/content 包。在当前版本中,这主要意味着捆绑技能。
对非捆绑插件使用允许列表和显式 install/load 路径。将工作区插件视为开发时代码,而不是生产默认值。
对于捆绑的工作区包名称,请将插件 id 与 npm 名称绑定:默认使用 @openclaw/<id>,或者在包有意暴露更窄的插件角色时,使用经批准的类型后缀,例如 -provider、-plugin、-speech、-sandbox 或 -media-understanding。
导出边界
OpenClaw 导出的是能力,而不是实现便利性。
保持能力注册为公开。裁剪非契约型的辅助导出:
- 打包插件特定的辅助子路径
- 不打算作为公共 API 的运行时管道子路径
- 供应商特定的便利辅助工具
- setup/onboarding 帮助程序是实现细节
预留的内置插件辅助子路径已从生成的 SDK 导出映射中移除。将所有者特定的辅助工具保留在所属插件包中;仅将可复用的宿主行为提升为通用 SDK 契约,例如 plugin-sdk/gateway-runtime、plugin-sdk/security-runtime 以及注入的插件 API 能力。
内部实现与参考
关于加载管道、注册表模型、提供方运行时钩子、Gateway HTTP 路由、消息工具模式、通道目标解析、提供方目录、上下文引擎插件,以及添加新能力的指南,请参见 插件架构内部。
相关内容
- 构建插件
- 插件清单
- 插件 SDK 设置
- 上下文引擎
- Plugin Runtime -
api.runtime帮助程序插件调用