插件运行时网关和节点

从插件代码到达网关和配对节点，以及长期网关服务接收的事件。 Plugin 运行时助手 参考的一部分。

服务调度

向 apiVersion: 2 注册服务，以在其启动和停止上下文中要求主机拥有的 PluginServiceSchedulerV1 功能：

api.registerService({  id: "catalog-refresh",  apiVersion: 2,  start({ scheduler }) {    scheduler.schedule({      id: "refresh",      delayMs: 0,      everyMs: 60_000,      run: () => refreshCatalog({ signal: scheduler.signal }),    });  },});

命名这些合约时，从 openclaw/plugin-sdk/plugin-entry 导入 OpenClawPluginServiceV2、OpenClawPluginServiceContextV2 和 PluginServiceSchedulerV1。现有的 OpenClawPluginService 和 OpenClawPluginServiceContext 类型保持源兼容；他们的调度程序字段是可选的。网关为两个服务版本提供调度程序。

schedule 接受绝对 atMs 或相对 delayMs。作业 ID 属于一个作用域：调度相同的 ID 会替换其挂起的调度，而其他服务和子作用域可以独立使用相同的 ID。 mode: "earliest" 保留较早的待决截止日期。 everyMs 在回调结束并合并错过的周期后安排下一次运行；回调必须返回其异步工作，以便退休可以加入其中。错误由主机调度程序报告。返回的句柄的 cancel() 会阻止将来的调度，并且 stop() 还会等待该作业的运行回调。

使用 scheduler.scope() 可以缩短连接或观察者寿命。其beginClose()关闭准入，中止其信号，并取消挂起的工作； await stop()也加入跑步工作和所有后​​代。关闭孩子并不能阻止其父母或兄弟姐妹。关闭服务会关闭其所有子作用域。保留了schedule和scope函数在关闭后抛出。不要等待作用域的 stop() 来自其自身正在运行的回调之一。

主机首先关闭调度准入并发出取消信号，然后调用服务的停止挂钩。退休等待着那个钩子和预定的工作。插件保留重新连接策略、套接字、观察者、持久冲洗排序和交付托管的所有权。停止传输并按照所有者所需的顺序刷新挂起的交付，然后在关闭该工作使用的资源之前加入其子范围。将生命周期信号传递给支持取消的操作，并在返回之前完成已允许的写入。调度不会创建持久作业，也不会更改存储的配置或状态；更新不需要状态迁移。

通道网关适配器选择使用 apiVersion: 2。他们的 startAccount 和 stopAccount 回调接收 ChannelGatewayContextV2，包括所需的帐户调度程序。从 openclaw/plugin-sdk/channel-contract 导入该上下文和 ChannelGatewayAdapterV2。现有的版本 1 适配器保留可选的调度程序字段并继续保持不变。主机为两个版本提供相同的功能，并在注销帐户之前加入计划的工作。捆绑插件定时器迁移可以独立采用它。

ChannelPlugin<Account, Probe, Audit> 和 createChatChannelPlugin 默认为版本 1 网关适配器，保留现有声明和手动调用。对于版本 2 适配器，使用 ChannelPlugin<Account, Probe, Audit, 2> 或第四个 createChatChannelPlugin 类型参数。内联 api.registerChannel 注册从适配器的 apiVersion 推断回调上下文。

较旧的参数合约不接受调度程序的已发布工厂在其版本 1 适配器中使用 openclaw/plugin-sdk/runtime 中的 resolvePluginServiceScheduler，然后委托给其版本 2 实现。解析器接受显式句柄或借用当前绑定的服务、帐户或可执行文件 CLI 生命周期。它拒绝丢失或关闭的所有者，并且从不创建根调度程序。新工厂明确需要句柄。

CLI 回调保留其命令注册时捕获的调度所有者。定时回调在同一个插件实例中运行，无需继承发起请求或操作员权限。为运行时提供服务的命令必须保持挂起状态，直到该运行时关闭；从操作返回可以让可执行文件退出并在释放插件之前加入其调度程序。

一次性诊断导出器借用现有的 CLI SDK 主机调度程序。当在没有该主机的情况下启用导出时，启动会报告明显的错误；代理命令报告诊断失败并继续。导出器关闭仅取消其服务范围，使 CLI 调度程序可用于其他工作。

网关和节点命名空间

Session 资源方法

插件可以在注册附加网关方法时声明 sessionAccess：

api.registerGatewayMethod("my-plugin.session.open", handleOpen, {  scope: "operator.write",  sessionAccess: { mode: "write", allowOwnSessionScope: true, requiredTool: "my_tool" },});

这需要当前经过身份验证的配置文件、现有的规范化顶级 sessionKey 以及（如果提供）其匹配的 agentId。广泛的作家保留会话的共享规则。 allowOwnSessionScope 另外承认 operator.sessions.write 仅用于呼叫者自己的会话。 requiredTool 检查共享有效会话工具策略和允许的代理运行的工具限制。代理呼叫者只能进行自己的对话。目前资源工具策略准入不支持锁定模型选择。

处理程序接收 sessionAccessAuthority。在等待准备之前和之后以及效果之前立即致电 assertCurrent()。当处理程序完成时，路由器关闭此调用句柄；以后不能重复使用它来采用新资源。

在处理程序期间使用 retain() 来获取 signal、assertCurrent() 和 release() 的原始人访问借用，例如用于交互式查看器。对于由独立授权的协作者共享的资源，请使用 retainSession()。第二次借用仅检查确切的会话化身和存储生成；它不授权操作。每个操作仍然需要自己的 person/run 入场。正常的行进度会保留两个生命周期；重置、删除或物理存储替换会使会话借用无效。释放启动失败、更换和服务清理时的所有借用。

sandboxRequired 描述了承认的 session/role 约束。消费者必须提供合规的后端或报告其后端不受支持。此元数据不会将网关托管的进程变成沙箱。

对于工具演示，openclaw/plugin-sdk/agent-harness-runtime 中的 readGatewayToolOperatorScopes() 在检查该权限后返回当前承认的操作员范围的副本。对于没有操作员捕获的 system/local 调用，它返回 undefined。它不授予权限；所选网关方法仍授权该请求。

人员访问生命周期

api.registerGatewayAccessPolicy({ authorize }) 在经过身份验证的人员准入中添加了插件拥有的访问要求。回调接收当前配置和主要配置文件的 ID、电子邮件别名、可选的已验证 githubAccountIds 以及分配的角色。账户ID来自现有身份所有者；显示登录名和公共电子邮件不会建立该绑定。网关从该人的有效角色和该插件的ID解析出requiredByRole；角色绑定策略使用该事实，而不是从默认角色名称推断绑定。当保单不管辖该人时，请返回 undefined。否则返回{ assertCurrent, signal }；当不存在所需的访问权限时拒绝入场。

命名网关角色可以将 accessPolicyPlugin 设置为您的插件 ID。该角色需要您注册策略的当前权限，包括插件无法加载或其清单不可用时。返回 undefined 不满足显式角色绑定。没有绑定的角色保留其现有的策略行为，并且网关所有者保持独立。

断言必须在执行操作之前立即检查原始访问源。当该源过期或被撤销（包括插件服务关闭）时中止其信号。如果稍后创建授权，已结束的源必须保持结束状态。更新可以扩展不间断的源。将源保留在其现有生命周期所有者中，并在接受人员访问之前对其进行初始化。

返回本机 AbortSignal。注册保留本机取消和清理，同时保留绑定到插件实例的断言和可调用中止原因值。插件退役也会结束捕获的访问。

网关将返回的权限绑定到原始人，并通过 WebSocket 和 HTTP 请求以及通过链接通道发送方允许的命令携带它。链接的管理员必须满足相同的角色绑定人员策略，包括在等待的命令准备之后。撤销已承认的授权将终止该命令的权力；替代补助金仅适用于新入学。显式配置的命令所有者保留其独立权限。普通传输断开与撤销不同。政策必须保留独立的员工访问权；它不能从会话的创建者、显示名称或沙箱状态推断请求者的权限。共享秘密系统权限仍然处于个人策略之外。

持久人员访问授权

支持延迟共享发布的策略在其访问权限上返回稳定的 UUID 作为 grantId 并实现 resume({ config, profile, requiredByRole, grantId })。网关记录插件 ID 和原始拨款参考以及接受的请求者和范围上限；它不会保留权限回调、信号、凭据或电子邮件别名。

网关还保留该人的原始电子邮件绑定的不透明生命周期 ID。将原始别名移动到另一个配置文件会终止该发布权限，即使稍后恢复了该别名。显示对准入后添加的别名的编辑和更改会保留原始绑定。插件的授权 UUID 保持独立检查；这些身份事实无法取代它。

resume 必须检查确切的原始拨款，即使此人当前的角色本来可以豁免。在其保持活动状态时返回其当前权限，并仅在授权明确结束、不存在或替换时返回 undefined。当服务正在启动或其状态不可用时抛出，因此恢复会保留挂起的请求，而不是将不可读的授权视为已撤销。仅当续订在旧授权到期之前提交时，才可以保留 UUID；过期或撤销后重新邀请必须使用新的UUID。

恢复授予后，恢复保留其权限并在效果之前调用 assertCurrent，而不是再次恢复。其他策略仍会检查每个断言的新适用性，包括对插件拥有状态的更改。

没有持久拨款支持的政策仍然管辖实时入场。他们的非保密权限无法转换为可重新启动的共享发布请求。共享出版物目前支持一项原始管理拨款；无法从该单个引用推断出多个依赖关系。新适用的政策还需要新的出版物准入。

if (await api.runtime.gateway.isAvailable()) {  const result = await api.runtime.gateway.request<{ callId: string }>(    "voicecall.start",    { to: "+15550001234", mode: "conversation" },    { timeoutMs: 60_000 },  );}

const controller = new AbortController();const { nodes } = await api.runtime.nodes.list({ connected: true }); const result = await api.runtime.nodes.invoke({  nodeId: "mac-studio",  command: "my-plugin.command",  params: { action: "start" },  timeoutMs: 30000,  signal: controller.signal,});

const controller = new AbortController();const channel = await api.runtime.nodes.openDuplex({  nodeId: "paired-node",  command: "my-plugin.image-bridge",  params: { format: "png" },  timeoutMs: 30000,  maxMessageBytes: 4 * 1024 * 1024,  signal: controller.signal,}); const unsubscribe = channel.onMessage((message: Uint8Array) => {  console.log("Received one complete binary message:", message.byteLength);}); try {  await channel.send(Uint8Array.of(1, 2, 3));  const result = await channel.closed;} finally {  unsubscribe();  channel.close();}

api.registerNodeHostCommand({  command: "my-plugin.image-bridge",  duplex: true,  async handle(_paramsJSON, io) {    if (!io?.frames) {      throw new Error("Framed node command I/O is unavailable.");    }     const frames = io.frames;    return await new Promise<string>((resolve, reject) => {      frames.onMessage((message) => {        void frames.send(message).then(() => resolve('{"ok":true}'), reject);      });      io.signal.addEventListener(        "abort",        () => reject(new Error("Node command was canceled.")),        { once: true },      );    });  },});

Gateway 服务事件

网关托管服务可以使用 ctx.invokeNode?.() 作为自己注册的节点命令。这使用服务的标识，因此只读文档请求可以获取远程文件，而无需授予其调用者 operator.write 的权限。使用该能力前请先授权公开操作。 Node 配对、命令授予和插件路径策略仍然适用。该功能不接受调用者选择的范围，并在服务停止或其网关关闭时停止接受工作。普通api.runtime.nodes.invoke保持其调用者的权限。

ctx.openNodeDuplex?.() 为使用 duplex: true 或 duplex: "optional" 注册的服务自己的命令打开相同的帧二进制传输。使用与invokeNode相同的节点策略和服务生命周期；调用者无法选择身份或范围。可选的 assertCurrent 回调在分派和每帧之前添加当前操作的活动性检查。关闭服务会取消打开的通道。

网关托管服务还接收 ctx.getCron?.()，用于网关挂钩已可用的调度程序操作：list、add、update、remove 和 removeStaleJobFamily。非网关服务主机省略此 getter。

当前的服务句柄还公开 enqueueRun(id, mode) 用于服务拥有的工作。它使用具有服务实时权限的正常 cron 准入队列，独立于完整的代理工具调用者。使用 "if-enabled" 请求立即运行而不覆盖禁用的作业。当服务停止或调度程序被替换时，保留的句柄仍然会拒绝，包括在等待准入时。较旧的主机上不存在此可选方法；它没有调用者范围的后备。

当前的服务句柄还为插件拥有的自动化事件源公开 readEventSources() 和 runEvent(id, input)。源命名空间绑定到服务的插件ID；插件无法选择另一个源所有者。快照包含 jobId、sourceIdentity、enabled 和源 options，而不是凭据或创建者权限。 runEvent 采用不可变的事件信封和现有的入口声明令牌。它返回带有运行收据的 transferred，当 busy/paused/stopped 时返回 pending，对于已停用的源返回 invalidated。主机在准入期间重新检查源生成，并自动将声明传输到运行。不要将待处理事件标记为完成或将忙碌结果转变为执行确认。这些可选功能没有直接代理后备。

对于 MCP- 支持的源，ctx.mcpEvents?.prepareSource({ jobId, sourceIdentity, serverName }) 解析持久的创建者和配置的 MCP 帐户。该作业必须属于调用插件的事件源命名空间，并在 options.server 中引用该服务器。此功能可用于外部插件以及捆绑的适配器；调用者无法提供主体或凭据。每个 Webhook 绑定保留一个准备好的句柄。它公开不透明的 account/principal ID、revalidate()、assertCurrent()、有界配置文件请求、unsubscribe(signal) 和 dispose()。在接受回调或分派排队事件之前等待 revalidate()，然后将其同步电流源断言传递到授权入口和 runEvent。重新验证会读取规范凭证所有者，包括其他进程更改，并刷新良性 policy/session 更改，而无需替换句柄。成功的凭证刷新可保留授权生命周期；注销、终端授权丢失、更换则不会。请求在同一生命周期内获取新的解析器凭据并固定 MCP 端点。即使解析器重用其授予 ID，更改的已解析 URL 也会停用绑定，而不是重定向续订或清理。

第一次订阅尝试捕获一个确切的 Webhook 身份和有限的清理权限，即使其远程结果未知。续订必须使用该身份。 unsubscribe(signal) 关闭订阅准入，等待其正在进行的请求，并仅清理捕获的身份。清理可以在良性重新验证和源删除后继续存在，但无法借用替换凭证生命周期或在重新启动后从持久绑定事实中恢复。清理完毕后处理手柄；否则，有限远程租约必须到期。

请求者连接解析器接收这些使用者的 requireLiveAuthority: true。返回 authority 观测值以及 url 和 headers，以及非秘密 authorizationId、assertCurrent()、异步 revalidate() 和 dispose()。 ID 必须能够承受刷新和重新启动，但在断开连接或更换后会发生变化，即使同一请求者重新连接也是如此。断言必须属于凭证所有者，而不是已解析标头的快照。处置释放的是观察结果，而不是账户。使用错误代码 MCP_AUTHORIZATION_RETIRED 表示已知的生命周期损失，使用 MCP_AUTHORIZATION_UNAVAILABLE 表示暂时无法建立权限。临时失败会保留未完成的工作而不承认它。已停用的绑定不得重新获得以后的授权。仅凭证解析器仍然支持普通工具，但无法授权持久事件。缺少主机支持是明显的能力差距，而不是使用操作员或共享凭证后备的权限。

使用 版本 2 服务调度 进行订阅续订和退避。保持期限可从拥有的持久状态重建；协议维护不得创建第二个调度程序或调用模型。

当前网关服务句柄还提供await cron.isEnabled()来观察是否启用了自动调度，包括OPENCLAW_SKIP_CRON覆盖。它仅返回一个布尔值，而不返回存储元数据或改变作业的权限。对于较旧的主机实现，该方法在公共类型中是可选的；它的缺失意味着未知、未启用或禁用。当旧主机不存在时，支持旧主机的消费者可以保留之前的协调行为。禁用调度不会禁用作业 CRUD 或所需的插件清理。

服务清理保留所属插件的清理上下文，因此 stop() 可以在普通呼叫准入关闭后释放资源。保留该启动尝试获取的资源和取消订阅函数，并释放这些确切的句柄。清理失败并不意味着本机资源已终止；请参阅 插件生命周期和清理。

使用服务的 start() 和 stop() 方法来拥有定期调节。它们运行用于服务或插件替换以及网关启动和关闭；对于受影响的插件，完整插件替换还运行 gateway_stop 和 gateway_start。仅服务配置重新加载不会重播这些挂钩。每个返回的调度程序句柄都属于一个服务生命周期和一个调度程序实例。一旦服务开始关闭或调度程序被替换，调用（包括排队写入）就会被拒绝。在服务保持活动状态时再次调用 ctx.getCron() 以获取替换调度程序。

服务可以声明 reload: { configPrefixes: ["myConfig.service"] } 以及 id、start 和 stop。提交匹配的配置更改后，网关将停止该服务并使用新的 ctx.config 再次调用 start(ctx)。仅替换声明匹配前缀的已加载服务；重叠的所有者全部刷新。现有的同等或更窄的重启或无操作策略仍然优先。每个启动都会收到一个新的功能租赁和运行状况报告者。 Stop必须在解决之前释放资源；失败的替换清理或启动会触发网关恢复。完整的插件替换包含这些服务的重新启动。停止钩子在该尝试的原始开始稳定后运行。更换截止日期可以结束调用者的等待并撤销服务能力，同时保留最终的清理工作。

值得信赖的官方诊断出口商服务也可以收到 ctx.internalDiagnostics.getRuntimeIdentity?.()。它返回托管进程的实际 processInstanceId 和可选加载的 buildId，没有文件系统查找或 RPC。在服务启动时捕获；保留的吸气剂在服务租约被撤销后抛出。不提供此可选功能的主机会使运行时身份不可用。此诊断事实不会授予权限或识别服务重新加载时期。

他们的 ctx.internalDiagnostics.onEvent(listener, filter?, options?) 订阅提供事件、信任元数据和冻结的私有数据对象。仅需要事件和元数据的导出器可以传递 { includePrivateData: false } 作为第三个注册参数，以跳过私有负载副本并接收冻结的空对象。这保留了事件过滤器、仅可信交付和服务租赁清理。私有数据默认保持启用状态；较旧的主机忽略可选参数并保留其现有的复制行为。

使用 api.registerService(...) 注册的长期运行服务，在进程运行 Gateway 广播器时会收到一个进程本地的 ctx.gatewayEvents facade；在没有广播器的运行时中，该字段不存在，因此请进行特性检测并保留回退方案（例如粗粒度轮询）。使用 onSessionsChanged(...) 在 Gateway 广播 sessions.changed 通知后作出响应：

let unsubscribeSessionsChanged: (() => void) | undefined; api.registerService({  id: "session-index",  start(ctx) {    unsubscribeSessionsChanged = ctx.gatewayEvents?.onSessionsChanged((event) => {      // event: { sessionKey, agentId?, label?, displayName?, reason?, phase? }      // refreshSession is your plugin's own handler, not an SDK export.      refreshSession(event.sessionKey);    });  },  stop() {    unsubscribeSessionsChanged?.();    unsubscribeSessionsChanged = undefined;  },});

该处理程序在网关进程中运行，并且不添加网关协议订阅。保留返回的取消订阅函数并在服务清理期间调用它。有效负载是一个轻量级的变更通知；当插件需要完整的当前会话条目时，等待 api.runtime.agent.session.getSessionEntryAsync(...)。在插件的事件处理程序中处理异步刷新失败。同步 getSessionEntry 兼容性方法已弃用至 2026 年 12 月 31 日；请参阅 会话读取器迁移 。

OpenClaw 每次启动尝试最多调用服务的 stop() 一次，包括启动失败之前替换超时的情况。启动失败回滚和关闭共享相同的清理结果；记录清理失败，而不是在该尝试中重试。

如果更换失败，网关可以再次调用start()来恢复之前的服务。重新创建 stop() 释放的资源并重置每次启动标志，以便工具和后台工作在回滚后仍然可用。

由于返回或等待的 Promise 导致的服务启动失败会自动记录。有意在后台启动所需工作的服务必须通过其世代绑定的运行状况报告器报告稍后的故障和恢复：

// startIndexWorker and stopIndexWorker are your plugin's own background-work// helpers, not SDK exports.api.registerService({  id: "index-worker",  start(ctx) {    void startIndexWorker().then(      () => ctx.serviceHealth?.clearFailure(),      (error) => ctx.serviceHealth?.reportFailure(error),    );  },  stop() {    stopIndexWorker();  },});

当服务停止或其插件注册表生成被替换时，报告器将被撤销，因此来自旧生成的后期回调无法覆盖当前的运行状况。当服务不可用时，更愿意返回启动承诺，直到承诺解决为止；仅将报告器用于拥有自己的停止路径的故意非阻塞工作。