基础设施注册
用于 hooks、Gateway HTTP 路由和 RPC 方法、CLI 条目以及后台服务的注册器,外加这些接口面所依赖的 SDK 辅助函数。属于 Plugin SDK 概览 的一部分。
基础设施¶
| Method | What it registers |
|---|---|
api.registerHook(events, handler, opts?) |
事件钩子 |
api.registerHttpRoute(params) |
Gateway HTTP 端点 |
api.registerGatewayMethod(name, handler, opts?) |
Gateway RPC 方法 |
api.registerGatewayDiscoveryService(service) |
本地 Gateway 发现广播器 |
api.registerCli(registrar, opts?) |
CLI 子命令 |
api.registerNodeCliFeature(registrar, opts?) |
openclaw nodes 下的 Node 功能 CLI |
api.registerService(service) |
后台服务 |
api.registerInteractiveHandler(registration) |
交互式处理器 |
api.registerAgentToolResultMiddleware(...) |
运行时工具结果中间件 |
api.registerMemoryPromptSupplement(builder) |
附加的内存相关提示部分 |
api.registerMemoryPromptPreparation(prepare) |
内存相关提示部分的异步准备 |
api.registerMemoryCorpusSupplement(adapter) |
附加的内存搜索/读取语料库 |
api.registerHostedMediaResolver(resolver) |
浏览器风格托管媒体 URL 的解析器 |
api.registerMcpServerConnectionResolver(...) |
针对静态服务器名称的按请求方 MCP 传输(url/headers) |
api.registerTextTransforms(transforms) |
插件拥有的提示/消息兼容性文本重写 |
api.registerConfigMigration(migrate) |
在插件运行时加载前运行的轻量级配置迁移 |
api.registerMigrationProvider(provider) |
openclaw migrate 的导入器 |
api.registerAutoEnableProbe(probe) |
可自动启用此插件的配置检查 |
api.registerReload(registration) |
用于重载处理的 restart/hot/noop 配置前缀策略 |
api.registerNodeInvokePolicy(policy) |
节点调用命令的允许列表/审批策略 |
api.registerSecurityAuditCollector(collector) |
openclaw security audit 的发现收集器 |
Gateway 方法默认使用 profileAccess: "required",因此在插件分发之前,已认证 profile 验证会失败关闭。仅对于经过审计且既不读取也不修改持久用户或会话状态的方法,才设置 profileAccess: "independent"。Operator scope 仍然是独立的授权要求。
只读方法可以通过注册选项选择加入 WebSocket 响应共享:
shareKey(caller, params)、shareInvalidationEvents 和 shareMaxAgeMs。
当请求无法共享时返回 null。键必须包含所有调用方和参数依赖,包括身份、scopes、capabilities、agent 以及账户选择。成功结果在发布后必须不可变。分发器会检查每个调用方的权限,并且只共享结果和序列化后的 payload;错误不会被缓存。列出的广播会使待处理和已完成条目失效。默认绝对上限为一秒,宿主将其上限设为五秒。Gateway 在所有方法中最多保留 16 个响应,每个最多 1 MiB,并在其方法注册表被替换时清除它们。过期和失效会释放等待的调用方,使其执行自己的读取,而不是反复加入已退役的工作。
仅当方法的授权完全由分发覆盖时才选择加入;执行额外调用方特定授权或嵌套请求的处理器必须保持请求本地。对于变更、订阅和连接绑定 provider,请省略这些选项。
文件监视容量错误¶
getFileWatchCapacityCode(error) 来自 openclaw/plugin-sdk/file-access-runtime,
对于原生 watch 失败返回 EMFILE、ENFILE 或 ENOSPC,对于其他错误返回 undefined。它要求 syscall: "watch",因为 watcher 库可能通过同一错误事件转发目录扫描错误。在 watcher 生命周期所有者中使用该结果,以停止原生重试并选择现有的刷新路径。
文件系统观察与 worker 通知¶
resolveFsObservationMode(env?) 和 resolveFsObservationIntervalMs(env?) 来自
openclaw/plugin-sdk/file-access-runtime,共享宿主保留的
CHOKIDAR_* 环境契约。
从同一 SDK 入口点使用 admitObservationRoot、watch 及其类型,
包括 ObservationRoot、WatchOptions 和 WatchSubscription。这些
操作共享宿主的 fs-safe 实例;插件单独的依赖副本无法观察这些 Roots。
将解析后的模式和 pollIntervalMs 传递给 watch,以便
自动回退保留轮询间隔。将解析、稳定、重试和索引保留在消费者中。使用 fs-safe 时,通过
health.failure.operation === "watch" 和 health.failure.code === "watch-limit" 对原生 watch 容量进行分类;
getFileWatchCapacityCode 保留其现有的 Node watch 错误契约。
对于同版本观察工作器,createFileWatchNotifier(output, onFailure)
来自同一 SDK 入口点,通过借用的可写流发送 JSON 行。
调用 send("change" | "unavailable" | "available") 以进行失效和
可用性更新。它会合并待处理通知,保持一个写入在
途,并在输出失败或意外关闭时调用 onFailure。等待
close() 以停止接受通知,并在退役工作器前等待已接受的写入完成;流仍由调用方拥有。它承载当前
观察状态,而不是文件系统事件的完整历史。
流式文件验证¶
sha256File(pathOrHandle, { maxBytes, signal }) from
openclaw/plugin-sdk/file-access-runtime 返回 { bytes, digest },而无需
将整个文件加载到内存中。它读取到 EOF,并拒绝
增长超过字节限制的文件。借用的句柄保持在其原始偏移处打开;调用方拥有准入和关闭。路径输入拒绝最终符号链接,
并关闭其拥有的句柄。取消会在拒绝之前结束待处理工作。
可选的原生辅助函数在 JavaScript 事件循环之外进行哈希;回退
使用有界缓冲区。两条路径都不提供并发写入的快照。
浏览器生命周期清理¶
closeTrackedBrowserTabsForSessions from openclaw/plugin-sdk/browser-maintenance
接受一个可选的 prepareCurrent(): Promise<boolean> 检查,在插件
激活之后、每次新的清理认领之前执行。返回 false 会跳过新的认领;
现有的 isCurrent() 回调在已等待的准备之后仍保持为同步所有者检查。宿主提供的 sessionEntryCurrent 检查使用当前会话事实限制原生认领和
认领前状态写入;它不授予存储访问权限。
提供 sessionEntryCurrent 还要求 prepareCurrent,它会在
进程本地标签页获取清理预留之前检查它们。未配对的检查会在
标签页清理开始前被拒绝并给出警告。
官方插件通过 openclaw/plugin-sdk/plugin-state-runtime 共享 SessionEntryCurrentPreparation 和
SessionEntryCurrentCheck 类型。
一旦标签页被认领,关闭和退役该标签页会在其捕获的
Browser 权限下完成,即使清理调用方随后发生变化。
工件通过 supportsSessionEntryCurrent: true 声明此契约。
针对较旧工件的受保护清理会保持标签页不变并报告更新警告;仅使用现有同步守卫的调用方仍受支持。
SQLite 写入准入¶
runSqliteImmediateTransaction(db, prepare, options?) from
openclaw/plugin-sdk/sqlite-runtime 等待写入准入而不阻塞
事件循环。当另一个写入者持有数据库时,其异步 prepare 函数可能运行多次。保持准备可重复:在其中读取并规划,
然后返回一个 同步 事务回调。在写入前,在该回调内重新验证当前所有者和行谓词。
从准备返回 undefined 会跳过写入,并将辅助函数解析为 undefined,即使另一个写入者仍处于活动状态。否则,辅助函数
解析为事务回调的结果。它会拒绝已激活的事务,或拒绝留下打开事务的准备。一旦获准,回调只运行一次;回调和提交失败永远不会重放。
准入重试使用连接现有的 busy_timeout;这不是准备或事务执行的总截止时间。options 提供与
runSqliteImmediateTransactionSync 相同的事务诊断。保持数据库句柄及其所属操作存活,直到返回的 Promise 结束。
回调和 SQLite 调用仍在调用方线程上同步运行。
对于重复的固定查询,prepareSqliteQuerySync(db, build) 只编译一次其
Kysely 形状,并在每次调用时绑定新参数。当启用时,它使用常规
同步执行器和连接的有界语句缓存。
将预编译函数与其数据库所有者一起保留,并在关闭连接时丢弃它;事务回调必须保持同步。
工作器任务准入¶
WorkerTaskPool from openclaw/plugin-sdk/process-runtime 支持为捆绑和单独发布的官方插件提供可复用
计算工作器。
在这些工作器内部,从 openclaw/plugin-sdk/worker-task-server 导入 serveWorkerTasks 和
WorkerTaskControl 类型,以避免加载宿主进程和池运行时。两条路径使用相同的任务协议。
共享实现位于私有 @openclaw/worker-runtime
工作区包中。插件继续使用这些公共 SDK 入口点;OpenClaw 的
宿主适配器向同一调度器提供工作器创建、资源清理和进程核算。
process-runtime 中较旧的服务导出仍保留给已发布的官方
插件。捆绑工作器使用 worker-task-server;只有在受支持的官方插件版本已迁移到具有此子路径的宿主后,才移除较旧的导出。
每个池默认有 128 个未完成任务和 256 MiB 的报告输入字节,
包括排队、准备中和运行中的任务。在构造池时设置 maxPendingTasks 和
maxPendingBytes,以选择不同的正数限制。
使用 run(input, { inputBytes }) 报告已知的保留输入,包括由输入工厂捕获的缓冲区。省略 inputBytes 计为零;此核算
不测量序列化负载大小、解码数据、结果或工作器堆。
容量耗尽会在准备或执行该输入之前,以 WorkerTaskError.code = "overloaded"
拒绝 run()。已接受的工作在单工作器池内保持有序。将拒绝的操作报告为不成功;不要用空结果替代,也不要用同步执行绕过限制。
已接受的工作结束后,同一池再次接受新工作。调用方可以在压力消退且其原始权限和截止时间重新验证后重试被拒绝的操作;池不会自动重试。
对于无状态计算,sharedCompute: true 还会与同一 isolate 中参与池共享一个聚合的 128 个任务 / 256 MiB 准入预算以及 CPU 执行容量。专用有序池保留其自身的执行容量,并仍然执行各自的准入限制。
对于等待主机响应的交互式任务,队列压力可以通过 yieldSignal 请求协作式检查点,以便排队的工作能够运行。主机操作保留其自身生命周期。内部 openclaw.worker.task 诊断信息会包含 hostWaitMs,与现有计时字段并列;主机等待包含在 runMs 中,而不是额外加到它上面。该字段是诊断数据,不是公开配置选项。
任务的 timeoutMs 包含主机回调。超时会中止回调的 signal 并退役 Worker;主机响应可以缩短剩余截止时间,但不能续期它。已经强制执行单独的、感知审批的主机截止时间的所有者,可以设置 hostTimeout: "owner",以在主机回调期间暂停池时钟,并在响应中提供其剩余预算。已接受的主机效果仍需要其所有者的结算和清理回执。请将回调信号转发到排队的读取、写入、锁和网络请求中;仅在 await 之后检查它会使已取消的工作留在队列中。主机等待超时会发出 WORKER_HOST_CALLBACK_TIMEOUT,并附带回调的操作名称(字符串请求或其 kind/type 字段),但不记录其负载。没有标签的请求会改为标识其 Worker 入口点。
通过 workerOptions 传入静态 Node.js Worker 设置。对于每个 Worker 的设置,prepareWorker() 在每次 Worker 创建尝试时运行一次,并返回 { options, temporaryDirectory? }。其 options 会浅覆盖 workerOptions:诸如 env、workerData 和 resourceLimits 等属性会替换整个静态属性,而不是合并嵌套值。
返回的 temporaryDirectory 会将新分配的临时目录移交给池。如果准备过程在返回前失败,则由准备过程负责清理。池只在该 Worker 退出后删除目录,包括启动失败或取消的情况,并报告删除失败,但不会替换任务结果。Worker 退出会释放执行容量;close() 还会等待待处理的文件清理。请将持久数据以及从 Worker 外部借用的文件保留在该目录之外。
当原生终止失败时,池会保留该 Worker 的输入托管和执行容量。retryFailedRetirements() 只重试这些失败的退役操作,并等待原生退出和待处理的文件清理,而不会中断健康任务或等待它们完成。它不会重放失败的工作,也不会关闭池。正在关闭的所有者必须停止新的准入,排空健康任务,并以 close() 结束。
serveWorkerTasks 提供第三个处理程序参数 WorkerTaskControl。在每个必须在 Worker 终止前完成的有界原生操作周围,使用 await control.runNativeSection(() => nativeOperation())。该围栏还会等待返回的 Promise,适用于具有异步入口点的原生库。请将无关的工作和渲染保留在围栏之外;不要为整个文档或主机请求设置围栏。在页面或其他工作单元之间调用 control.throwIfCancelled(),以便取消不会启动另一个原生操作。
取消、截止时间、池关闭和 Worker 退役会原子地关闭原生区段准入。未设置围栏的 Worker 会立即终止;设置了围栏的 Worker 在其当前原生操作完成且 Worker 退出之前,仍会占用准入和执行容量。截止时间会请求取消;它无法安全地中断卡住的原生调用。因此,原生区段必须具有有界输入,并且不得等待网络、用户输入或无界工作。
SQLite Worker 存储¶
使用来自 openclaw/plugin-sdk/sqlite-runtime 的 openSqliteWorkerStore<Operations>,将某个功能的 SQLite 生命周期移出应用程序事件循环。从主应用程序线程调用它,并传入 { moduleUrl, databasePath, input }。Operations 将每个领域操作映射到其 { input, output } 类型;store.execute({ type, input }, { signal }?) 返回对应的输出 Promise。主机目前会拒绝来自其他应用程序 Worker 的调用,这些调用需要一个共享的主机代理连接。
此首个主机仅支持基于文件系统的数据库。空路径、SQLite URI、:memory: 以及 OpenClaw 保留的隐身数据库基名会在规范化或 Worker 准入之前被拒绝。内存和隐身的所有权仍待定;这些定位符绝不能成为磁盘文件名。
静态本地 moduleUrl 标识一个受信任的功能模块,该模块导出 createSqliteWorkerBackend(input, { databasePath })。其工厂负责数据库打开和模式设置;其同步 execute(command) 负责查询和事务。close() 可以等待事务之外的清理;主机会保留该 actor,直到该清理完成。请将原生句柄、WAL 维护和预编译语句保留在该后端内部。跨边界发送可序列化的领域命令和结果,绝不发送 SQL 字符串、回调或 Kysely 构建器。使用 openclaw.build.workerEntries 声明私有构建入口,并从加载器的 api.runtimeSource 事实推导其位置。
当获取必须保留数据库缺失状态时,传入 existingOnly: true。当文件不存在且没有活动 actor 保留该路径时,该调用返回 undefined,而不会启动 Worker 或调用工厂。冷启动的现有打开需要模块显式导出 openExistingSqliteWorkerBackend(input, { databasePath })。主机绝不会替换普通创建工厂。现有工厂必须使用 SQLite 的原生只读或现有文件打开模式,并验证当前模式,而不创建或迁移它。先进行文件系统存在性检查,再使用普通的缺失则创建打开方式,并不满足此契约。
主机在分发现有工厂之前,以及返回 store 之前,都会检查物理身份。准入后如果消失或被替换,获取将被拒绝。当仅现有客户端和普通客户端的模块及初始化输入匹配时,它们共享同一个物理 actor;更改打开意图不会重新运行工厂,也不会创建另一个连接。领域命令仍然拥有写权限以及后续任何模式初始化。仅现有获取不会为后续命令提供只读能力。
中止信号会移除仍在队列中的操作。一旦分发,操作会保留其结果或失败;取消并不能证明回滚。close() 会拒绝新工作并排空该客户端已接受的操作。最后一个客户端也会关闭其数据库后端;最后一个后端会释放其 worker。worker 丢失或无法序列化已完成操作的结果时,可能以 code: "outcome-unknown" 拒绝。该操作可能已经提交:在决定下一步操作之前,请检查权威状态。主机永远不会自动重试写入。
异步的 execute 返回会违反命令契约。主机在报告 outcome-unknown 之前会退役并等待该 worker 结束;当已完成回复无法解码时,也会这样做。清理失败会保留其原始错误,同时 worker 被排空。
进程级主机按需启动,并根据可用 CPU 使用两个到八个共享 Node worker。Bun 最多使用 64 个专用 worker,直到其原生 SQLite 关闭修复发布。主机允许 64 个正在打开或存活的 store 客户端(包括共享同一数据库的客户端)、每个 worker 128 个未完成操作,以及所有 worker 上 256 MiB 的排队和保留输入。仅计数溢出会在其 worker 上按 FIFO 顺序等待最多十秒;独立 worker 保留其自身的请求容量。字节、消息和 store 限制会立即以 code: "overloaded" 拒绝。每个输入消息限制为 32 MiB。较大的 execute 输入以 8 MiB 块到达;后端在完整命令通过验证后运行一次。工厂初始化输入仍为单个有界消息。
保留最多 64 MiB 序列化输入的命令可以排队,其完整字节长度会在结算前计入。较大的命令必须立即在空闲 worker 上启动,并带有预留的 32 MiB 传输窗口;否则它会在分发前以 overloaded 拒绝。
总预算限制的是已准入的队列字节和预留传输窗口,而不是活动超大命令或结果所持有的完整值。一旦暂存开始,现有的分发后取消和排空规则即适用。
不超过 64 MiB 的结果使用内联回复;较大的结果会以有界的 8 MiB 块传输其完整序列化值。调用方仍需在内存中物化完整结果,并且原始操作在传输验证和清理期间保持所有权。同一数据库的操作共享其连接所有者,并按顺序执行。没有只读副本或 worker 池配置选项。
计算 worker 入口点¶
对于插件拥有的 worker,请从同一 SDK 子路径向 resolveRuntimeWorkerUrl 传递 package: { name, distWorkerPath }。使用插件的 package.json 名称以及相对于其 dist 目录的 worker 路径。该描述符随后支持捆绑安装和独立安装,包括重命名的安装目录。在 openclaw.build.workerEntries 中声明 worker 的源入口,以便包构建输出它。
Webhook 请求体拒绝¶
对于有界请求体读取,请使用来自 openclaw/plugin-sdk/webhook-request-guards 的 readWebhookBodyOrReject 或 readJsonWebhookBodyOrReject。当结果为 { ok: false } 时返回;该辅助函数负责错误响应和连接清理。请求体字节限制和读取超时与传输清理保持独立。
对于响应优先的请求体读取之后的自定义错误表示,请等待 sendHttpRequestRejection(req, res, statusCode, body, contentType?),而不是调用 res.end() 并销毁请求。它会保留安全头,构造完整的错误,然后在 Node 和 Node 兼容的 Bun HTTP 传输上关闭写入侧,同时保持应用程序请求体读取器暂停。Node 的请求背压会限制剩余输入缓冲;清理最多允许一秒,而不是另一个请求体读取超时。对端断开、格式错误的 HTTP 或清理预算耗尽都可能阻止投递。已提交的响应会被关闭,而不会追加替代错误或完成部分成功的请求体。
在这些传输上,拒绝会发出响应 close,而不发出 finish。
将 close 用于终端清理或选定错误的诊断;它不能证明投递。将成功响应活动保留在 finish 上,并加上调用方的成功状态检查,以便中止的请求无法报告健康活动。
旧版 Bun HTTP 传输使用原生响应完成,因为其原始套接字操作不会刷新 HTTP 响应。OpenClaw 检测由 Bun 的 Node 兼容性重构引入的原生 HTTP destroySoon 实现,而不是依赖不同 canary 构建共享的版本标签。较新 Bun 上排队的 HEAD 拒绝会等待响应套接字分配,包括没有 HTTP 响应完成诊断的构建。旧版 Bun 仍可能在大型未完成上传期间报告客户端连接重置,即使已经投递了完整错误。
网关 HTTP 请求在每条连接上按顺序运行,包括其响应生命周期。正在关闭的连接无法再接收后续请求或升级。排队请求会施加输入背压,直到较早的响应完成;有限管道按顺序排空。对于并发请求,请使用单独的连接。将由 beginWebhookRequestPipelineOrReject 返回的释放钩子放在 finally 中;该钩子会在释放进行中的槽位之前保留任何选定的拒绝清理。
Webhook 传输可以通过 openclaw/plugin-sdk/webhook-ingress 中的 registerPluginHttpRoute 注册其处理器。网关拥有监听器、连接接入、请求作用域和路由租约交接;渠道负责其签名验证和有界请求体读取。
对于内置回调设置和 Doctor 指导,来自私有 openclaw/plugin-sdk/gateway-config-runtime 门面的 classifyGatewayProbePath(pathname) 可识别网关检查路径,而无需加载 webhook 执行代码。该门面不属于第三方 SDK。请先通过 new URL(rawPath, "http://localhost").pathname 规范化回调输入。结果 live、ready 和 startup 标识网关端口上由检查拥有的确切路径;请选择不同的 webhook 路径。结果 namespace 和 outside 不标识确切的检查路由。同一私有门面还导出 resolvePluginRoutePathContext 和 isProtectedPluginRoutePathFromContext,用于规范的受保护路径检查。如果回调位于受保护命名空间下,请在将外部回调或反向代理迁移到网关端口之前选择渠道的安全默认路径。在该迁移期间,旧版监听器仍可继续提供其旧路径。
对于随附的渠道监听器,注册可包含 legacyListener: { port, host? }。网关通过同一插件分发机制转发指向该端点的请求,保留原始套接字、URL、请求体和响应头。处理器负责路径和方法拒绝,包括未知路径。核心 HTTP 端点绝不会暴露在兼容端口上。旧版监听器要求 auth: "plugin":渠道继续对其旧回调路径进行身份验证,包括 /api/channels 下的路径。网关端口保持其受保护路径的身份验证策略。此例外仅适用于在兼容端口上收到的请求;它不授予任何网关操作员作用域,也不会免除渠道签名检查或工作准入。getWebhookLegacyListener(req) 返回其冻结的已配置 { port, host? } 端点;对于普通网关请求返回 undefined;请求头无法设置它。当旧端口曾用于区分共享同一路径和密钥的账户时,请在签名解析之前按此端点过滤账户目标。普通网关请求仍需要无歧义的账户路径或认证身份。
可选的注册元数据 health: { path, contentType? } 保留随附的确切原始健康检查目标:对于普通 HTTP 方法返回 200 ok,遵循 Node 的 HEAD 行为,并且仅包含可选的 Content-Type。它仅适用于旧版端口,包括在路由交接期间,并且不会暴露网关检查详细信息。旧版端口保留原生 Node 的 Expect 头处理、Upgrade 回退、请求头限制和超时默认值。可以通过 timeouts: { headers, request, socket }(以毫秒为单位)保留随附的超时配置。这些是插件注册契约,而非新的操作员配置。
渠道负责有效的监听器解析:仅为显式 legacyWebhook 端点对象注册旧版监听器。省略设置或设为 false 时选择仅网关入口。为运行时路由和 Doctor 指导解析同一端点。插件拥有的 Doctor 契约可以通过 openclaw/plugin-sdk/runtime-doctor-migrations 中的 createLegacyWebhookListenerDoctorContract 进行组合,以在正常的备份配置写入过程中保留作者指定的端口和继承的绑定地址。显式旧版主机若未指定端口,则使用渠道随附的默认端口。当 Doctor 移除已退役键时,规范的 false 设置仍具有权威性。
要退役历史默认值,可以从现有配置 Doctor 模块及其 config-doctor-api 和 doctor-contract-api 入口点导出辅助函数的静态 historicalWebhookListener 属性。这个 { channelId, port, host? } 对象复用辅助函数的历史默认值。
主机验证渠道属于该插件、端口是 1 到 65535 的整数,并且显式主机非空。仅当作者指定的监听器设置先前暗示渠道激活时,才将工厂选项 preserveAuthoredActivation: true 设为 true。返回的静态声明携带此标志;主机在先前的操作和完成检查之后、添加隐式固定之前保留激活。规范化器本身不得启用渠道。在清单中保留 doctorContract.configRepair: true。从现有 normalizeCompatibilityConfig 结果中返回 historicalWebhookAccountIds,使用插件的账户和传输所有者来选择符合条件的账户。空数组表示检查已完成且没有符合条件的账户;undefined 数组条目选择无账户的渠道根。当当前进程无法决定依赖环境的资格时返回 null。仅当契约未实现时才省略该字段。主机负责先前的操作检测、固定创建和完成;规范化器仅返回资格,而不打开监听器或创建隐式端点。
保留的主机配置 Doctor 工件还暴露 normalizeHistoricalWebhookConfig。它复用仅监听器迁移,并返回其配置更改、警告和 historicalWebhookAccountIds,而不会应用无关的兼容性修复。在更新预演期间,主机可对安装被推迟的缺失插件使用此操作。选定的已安装或自定义所有者仍遮蔽主机工件,并且此操作不会完成被推迟的插件检查。外部插件不需要实现此主机回退。
自动固定属于现有账户,包括 accounts.default,因此之后添加的账户不会继承它们。Doctor 在通过 meta.migrations.webhookListeners 持久化固定之前会备份配置。该标记记录每个已完成通道的确切插入路径,对于全新安装则为 true。在保留此标记的同时移除固定,不会在后续的 Doctor 运行或更新中重新创建它。有关只读配置行为,请参阅 webhook 迁移。
在 runConfigSequence().infoNotes 中返回常规的监听器指导,以便 Doctor 将其标记为信息。将可操作的配置问题保留在 warningNotes 中;changeNotes 描述已应用的修复。
共享同一路由的账户租约可以保留各自的端点。仅由重启交接保留的端点返回可重试的 503 响应;具有活动持有者的端点继续处理请求。同一地址上的活动持有者优先于保留的交接。
共享同一端点的活动注册必须声明相同的健康与超时配置;冲突的注册会被拒绝,且不会更改监听器。绑定失败会发出警告,而不会禁用 Gateway 路由。在运维人员更改提供商回调或反向代理以指向 Gateway 端口后,插件可以停止注册兼容性端点。
退役一个端点会停止新连接,同时已准入的响应继续完成。Gateway 在完全关闭之前将这些正在关闭的套接字保留在其传输所有权下,并在完全关闭时关闭它们;通道在销毁前保留自己的响应排空顺序。
拥有自己的 createServer 准入的通道 webhook 监听器使用来自 openclaw/plugin-sdk/webhook-request-guards 的 runHttpConnectionRequest(req, run, res?) 对每个连接进行串行化。将 ServerResponse 作为第三个参数传入:共享所有者会等待响应完成(finish 或 close)后才准入该连接的下一个请求,因此感知关闭的拒绝——其清理工作可能在一秒内销毁套接字——永远不会超过先前排队的确认。省略响应参数会在当前响应完成之前释放下一个请求,从而失去该保证;仅在共享连接上不写入响应的分发场景中省略它。已准入的工作始终会完成;排队的工作在关闭后绝不会被分发,正在关闭的连接也无法准入后续请求。
确认后 webhook 工作¶
在处理完成之前确认请求的 webhook 路由必须将该分离的工作移至其自身受跟踪的准入根上:
import { runDetachedWebhookWork } from "openclaw/plugin-sdk/webhook-request-guards";
// processWebhookEvent, event, and runtime are your plugin's own handler, payload, and logger.
void runDetachedWebhookWork(() => processWebhookEvent(event)).catch((error) => {
runtime.error?.(`webhook dispatch failed: ${String(error)}`);
});
在 HTTP 请求仍然处于准入状态时,同步调用 runDetachedWebhookWork(...)。该辅助函数会立即保留一个独立的根,然后在下一个微任务中启动回调,以便请求处理器可以先写入其确认。返回的 promise 采用回调的结果;调用者仍负责处理拒绝。这使确认后的排队工作保持被接受,并让重启或暂停的排空等待它。在返回前等待所有处理完成的处理器不需要此辅助函数。
请求者作用域的 MCP 连接¶
在 mcp.servers、原生插件的 mcpServers 清单字段或捆绑包清单中保持 MCP 服务器身份静态(名称、工具过滤器)。可以选择注册一个连接解析器,以便每个受信任的消息请求者获得自己的传输:
api.registerMcpServerConnectionResolver({
serverName: "user-email",
resolve: async (ctx) => {
// ctx.requesterSenderId is host-trusted; never invent sender identity here.
// lookupUserToken is your plugin's own credential-store lookup, not an SDK export.
const token = await lookupUserToken(ctx.requesterSenderId);
if (!token) {
return null; // omit this server for the current run
}
return {
url: "https://mcp.example.com/email",
headers: { Authorization: `Bearer ${token}` },
};
},
});
契约说明:
- 解析器上下文仅携带受信任的主机身份(
requesterSenderId、可选的agentAccountId/messageChannel)。未来的受信任字段(例如 cron/子代理用户上下文)可以通过附加方式添加。 - 一个插件拥有一个服务器名称:来自另一个插件对同一
serverName的重复registerMcpServerConnectionResolver会被拒绝并给出错误诊断(首次注册优先),因此连接所有权永远不会依赖于插件加载顺序。 - 工具名称取自完整声明的服务器集合,因此部分解析永远不会在请求者之间或轮次之间改变安全的服务器名称。核心不会验证不同的请求者端点是否提供相同的工具模式;解析器必须将每个请求者指向同一逻辑服务,否则工具模式(以及提示缓存稳定性)会在不同请求者之间产生分歧。
- 没有受信任
requesterSenderId的运行(cron、子代理、心跳、公共网关)永远不会物化请求者作用域的服务器。没有共享的回退连接。 resolve的每个服务器限制为 10 秒;超时或抛出异常会在该运行中省略该服务器,而不会导致静态 MCP 失败。- 已解析的连接每个请求者最多每 5 分钟重新验证一次:轮换会使用新凭证重建传输,
null结果会撤销它(即使会话进行中,缓存的运行时也会被销毁)。因此,被撤销或轮换的凭证最多可继续使用 5 分钟。 - 已解析的
headers永远不会被记录或持久化;核心仅保留一个临时的内存键控摘要(进程本地 HMAC)来检测凭证轮换,并将已解析的标头/URL 凭证值注册到日志/调试捕获的脱敏注册表中。 - 请求者作用域的服务器不会生成 MCP 应用视图:视图的生命周期超过请求者认证的运行,并且网关视图边界没有请求者身份,因此这些服务器的应用预览保持故障关闭状态。工具结果不受影响。
- 没有解析器的静态服务器保持现有的会话作用域生命周期。
- Harness 交付规则: 请求者作用域的服务器永远不会进入 harness 原生的 MCP 客户端配置(Codex 线程
mcp_servers、CLI-c mcp_servers=…或任何其他会话共享的 MCP 投影)。Harness 改为将它们作为运行作用域的工具交付: - 嵌入式运行器:会话 MCP 运行时 + 捆绑工具(静态 + 作用域)。
- Codex 应用服务器:通过
materializeRequesterScopedMcpToolsForHarnessRun提供动态工具(仅作用域;静态服务器保留在 Codex 的原生 MCP 客户端上)。 - 作用域工具的规范在会话中首次成功解析后保持会话稳定,因此共享线程的 harness(Codex)在发送者变更时不会轮换线程。在任何请求者解析之前,不会公布任何作用域规范。
- 共享线程 harness 上未经认证的请求者仍然可以看到已公布的作用域工具;调用其中一个会为该请求者返回一个干净的未连接工具错误。OpenClaw 永远不会回退到另一个请求者的凭证。
Memory prompt 补充构建器会接收可选的 agentId、agentSessionKey 和 sandboxed 上下文。Memory 语料补充 search 和 get 调用会接收可选的 agentId 和 sandboxed 上下文。具有智能体自有存储的插件应在每次调用时解析该存储,而不是在注册期间捕获一个全局路径。如果在多智能体操作中需要 agent id 但缺失,应失败关闭,而不是选择任意智能体。
当 prompt 文本依赖于异步插件状态时,使用 registerMemoryPromptPreparation(...)。该回调在每次完整智能体 prompt 之前运行一次,并接收与同步 Memory prompt 构建器相同的 tool、agent、session 和 sandbox 上下文。在加载持久化状态之前,验证当前存储所有者实例,然后仅返回该次运行的行。OpenClaw 会冻结这些行,并将不可变结果交给同步 prompt 组装。将持久化、原子替换和所有者移除时的删除保留在所属插件内部;不要从 prompt 构建器轮询或读取文件。
Telegram 交互式处理器可以返回 { submitText },以便在处理器成功后将文本路由到 Telegram 的正常入站智能体路径。当入站策略跳过文本或处理失败时,OpenClaw 会保留回调按钮,以便用户在阻塞条件变化后重试。此结果字段是 Telegram 特有的;其他渠道保留其自身的交互式结果契约。
Doctor 插件状态修复¶
PluginDoctorStateMigrationContext.repairPluginStateEntries(namespace, replacements) 在离线 after-session-repair 阶段可用。每个替换包含来自 readPluginStateEntriesInKeyRange 的精确 PluginDoctorRawStateEntry 观察,以及一个 JSON 兼容的 value。空的读取前缀会以每页最多 512 行的方式扫描命名空间。宿主绑定插件身份和状态位置;插件从不提供数据库路径或 SQL。
宿主会冻结每个批次,验证包含原始行字节的备份,并在当前维护权限下比较完整观察,然后由一个事务替换它们的值。键、创建时间戳和过期时间保持不变。任何已更改的行或数据库代际都会拒绝整个批次。插件在其 Doctor 契约中保留格式解释,并将凭据绑定和运行时生命周期决策留给其现有所有者。较旧的宿主可以省略此可选修复能力。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw