跳转至

网关与节点

从插件代码访问 Gateway 和已配对节点,以及长生命周期 Gateway 服务接收到的事件。属于 插件运行时辅助功能 参考的一部分。

服务调度

使用 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 类型仍保持源码兼容;它们的 scheduler 字段是可选的。Gateway 会为两种服务版本提供 scheduler。

schedule 接受绝对时间 atMs 或相对延迟 delayMs。任务 ID 属于一个作用域:调度相同 ID 会替换其待处理的分发,而其他服务和子作用域可以独立使用相同 ID。mode: "earliest" 保留较早的待处理截止时间。everyMs 会在回调完成后调度下一次运行,并合并错过的周期;回调必须返回其异步工作,以便退役流程可以等待它。错误由宿主 scheduler 报告。返回句柄的 cancel() 会阻止后续分发,stop() 还会等待该任务正在运行的回调。

对于较短的连接或 watcher 生命周期,使用 scheduler.scope()。其 beginClose() 会关闭准入、中止其 signal 并取消待处理工作;await stop() 还会等待正在运行的工作以及所有后代。关闭子作用域不会停止其父作用域或同级作用域。关闭服务会关闭其所有子作用域。保留的 schedule 和 scope 函数在关闭后会抛出异常。不要从作用域自身正在运行的回调中等待该作用域的 stop()。

宿主会先关闭调度准入并发出取消信号,然后调用服务的 stop 钩子。退役流程会同时等待该钩子和已调度的工作。插件保留对重连策略、socket、watcher、持久化刷新顺序和投递保管的所有权。按所有者要求的顺序停止传输并刷新待处理投递,然后在该工作使用的资源关闭前等待其子作用域。将生命周期 signal 传递给支持取消的操作,并在返回前完成已准入的写入。调度不会创建持久化任务,也不会更改已存储的配置或状态;更新不需要状态迁移。

Channel Gateway 适配器通过 apiVersion: 2 选择加入。它们的 startAccount 和 stopAccount 回调会接收 ChannelGatewayContextV2,其中包含必需的账户 scheduler。从 openclaw/plugin-sdk/channel-contract 导入该上下文和 ChannelGatewayAdapterV2。现有版本 1 适配器保留可选的 scheduler 字段,并继续按原样工作。宿主会为两种版本提供相同能力,并在退役账户前等待已调度的工作。捆绑的插件计时器迁移可以独立采用它。

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

其旧参数契约不接受 scheduler 的已发布工厂,应在版本 1 适配器中使用来自 openclaw/plugin-sdk/runtime 的 resolvePluginServiceScheduler,然后委托给其版本 2 实现。解析器接受显式句柄,或借用当前绑定的服务、账户或可执行 CLI 生命周期。它会拒绝缺失或已关闭的所有者,并且从不创建根 scheduler。新工厂需要显式提供句柄。

CLI 回调会保留其命令注册时捕获的调度所有者。定时回调在同一插件实例中运行,不会继承发起请求或操作员权限。服务于某个运行时的命令必须保持待处理状态,直到该运行时关闭;从 action 返回后,可执行文件可以退役并等待其 scheduler,然后再释放插件。

一次性诊断导出器会借用现有 CLI SDK 宿主 scheduler。当启用导出但没有该宿主时,启动会报告一个清晰的错误;agent 命令会报告诊断失败并继续。导出器关闭只会退役其服务作用域,使 CLI scheduler 仍可供其他工作使用。

Gateway 与节点命名空间

会话资源方法

插件在注册增量 Gateway 方法时可以声明 sessionAccess:

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

这需要当前已认证 profile、一个已存在的规范顶层 sessionKey,以及(如果提供)与之匹配的 agentId。广泛写入者保留会话的共享规则。allowOwnSessionScope 仅对调用者自己的会话额外允许 operator.sessions.write。requiredTool 会检查规范的有效会话工具策略以及已准入 agent 运行的工具限制。Agent 调用者绑定到其自己的会话。目前,资源工具策略准入不支持锁定模型选择。

处理器会接收 sessionAccessAuthority。在等待的准备前后以及产生副作用前立即调用 assertCurrent()。路由器会在处理器结束时关闭此调用句柄;之后不能重用它来采用新资源。

在处理器期间使用 retain(),可获得原始人员访问借用,包含 signal、assertCurrent() 和 release(),例如用于交互式查看器。对于由独立授权协作者共享的资源,使用 retainSession()。第二次借用只检查确切的会话实例和存储代际;它不授权操作。每个操作仍需要其自身的人员/运行准入。常规行进度会保留两种生命周期;重置、删除或物理存储替换会使会话借用失效。在启动失败、替换和服务清理时释放所有借用。

sandboxRequired 描述已准入会话/角色约束。消费者必须提供合规后端,或报告其后端不受支持。此元数据不会将 Gateway 托管进程变为沙箱。

对于工具展示,来自 openclaw/plugin-sdk/agent-harness-runtime 的 readGatewayToolOperatorScopes() 在检查该权限后,返回当前已准入操作者作用域的副本。对于没有操作者捕获的系统/本地调用,它返回 undefined。它不授予权限;所选 Gateway 方法仍会对请求进行授权。

人员访问生命周期

api.registerGatewayAccessPolicy({ authorize }) 向已认证人员准入添加插件拥有的访问要求。回调接收当前配置以及规范资料 ID、邮箱别名、可选的已验证 githubAccountIds 和分配的角色。账户 ID 来自现有身份所有者;显示登录名和公开邮箱不会建立该绑定。Gateway 根据该人员的有效角色和本插件 ID 解析 requiredByRole;角色绑定策略使用该事实,而不是从默认角色名称推断绑定。当策略不适用于该人员时返回 undefined。否则返回 { assertCurrent, signal };当所需访问缺失时拒绝准入。

命名 Gateway 角色可将 accessPolicyPlugin 设置为你的插件 ID。该角色要求来自你已注册策略的当前权限,包括插件无法加载或其清单不可用的情况。返回 undefined 不能满足显式角色绑定。没有该绑定的角色保留其现有策略行为,并且 Gateway 所有者保持独立。

断言必须在操作前立即检查原始访问源。当该源过期或被撤销时中止其信号,包括插件服务关闭。如果后续创建授权,已结束的源必须保持结束状态。续期可以延长未中断的源。将源保留在其现有生命周期所有者中,并在接受人员访问之前初始化它。

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

Gateway 将返回的权限绑定到原始人员,并使其随 WebSocket 和 HTTP 请求传递,以及随为关联通道发送者准入的命令传递。关联管理员必须满足相同的角色绑定人员策略,包括在等待的命令准备之后。撤销已准入的授权会结束该命令的权限;替代授权仅适用于新准入。显式配置的命令所有者保留其独立权限。普通传输断开不同于撤销。策略必须保留独立员工访问;它不得从会话创建者、显示名称或沙箱状态推断请求人员的权限。共享密钥系统权限仍位于人员策略之外。

持久人员访问授权

支持延迟共享发布的策略在其访问权限上返回稳定 UUID 作为 grantId,并实现 resume({ config, profile, requiredByRole, grantId })。Gateway 将插件 ID 和此原始授权引用与已接受请求者及作用域上限一起记录;它不持久化权限回调、信号、凭据或邮箱别名。

Gateway 还保留该人员原始邮箱绑定的不透明生命周期 ID。将原始别名移至另一资料会结束该发布权限,即使该别名后来恢复。显示编辑以及对准入后添加的别名的更改保留原始绑定。插件的授权 UUID 仍会被独立检查;这些身份事实不能替代它。

resume 必须检查该确切的原始授权,即使该人员的当前角色本可豁免。在其保持有效时返回其当前权限,并且仅在授权明确结束、缺失或被替换时返回 undefined。在服务启动中或其状态不可用时抛出异常,以便恢复保留待处理请求,而不是将不可读授权视为已撤销。续期只有在旧授权过期前提交时才能保留 UUID;过期或撤销后的重新邀请必须使用新的 UUID。

没有持久授权支持的策略仍会治理实时准入。其未分类权限不能转换为可重启的共享发布请求。共享发布当前支持一个原始治理授权;不能从该单一引用推断多个依赖。新适用的策略也需要新的发布准入。

api.runtime.gateway

在进程内调用另一个 Gateway 方法,同时保留当前插件的可信运行时身份。这适用于捆绑或受信任的官方插件,它们组合插件拥有的 Gateway 能力,而无需打开回环 WebSocket 连接。

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

请求使用 operator.write 作用域,并且不授予管理员作用域。来自任意外部插件的调用会被拒绝。失败的方法会抛出 GatewayClientRequestError,保留结构化 details、重试元数据以及 Gateway 错误代码,用于恢复流程。对于也可在独立代理进程中运行的工具,在选择此路径之前使用 isAvailable()。

await api.runtime.gateway.openPluginPanel({ panelId, sessionKey, agentId }) 在请求的 Control UI 中打开此插件已注册的原生会话面板。与任意 request 不同,这一受限能力也可用于用户安装插件。宿主绑定插件 ID,保留调用者现有的 operator.write 权限,并仅针对请求当前操作或代理轮次的浏览器。在插件退役、调用者撤销或请求者断开连接后,它会拒绝;会话密钥绝不会选择他人的浏览器。{ ok: true } 确认命令已投递,而非插件异步文档加载完成。必须启用原生 UI,并且插件必须注册指定名称的面板。

await api.runtime.gateway.readSessionFacts({ sessionKeys }) 最多读取 40 个会话,并返回类型化的 { sessions, warnings? } 数据。每个会话包括其 key、identity、agent、有界脱敏标题和消息预览、运行状态(active、idle 或 failed)、可选观察者摘要(health、headline、assessment、revision)、拉取请求编号和状态、归档状态以及最后活动时间。消息预览上限为 400 个字符。pullRequestsUnavailable 区分未知 PR 状态与已确认的空列表。此生命周期绑定的读取复用 Gateway 的会话投影和上下文绑定的 PR 快照所有者,保留当前调用方权限和会话可见性,并省略隐身会话。它返回准备好的事实,无需等待 Git 或转录增强;在增强待处理期间,预览可能缺失。缺失的 PR 快照会在后台刷新。使用 api.runtime.gateway.subscribeSessionChanges 在事实变化时重新读取受影响的 sessionKey,并在完成后调用返回的取消订阅函数。仅类别变化会携带 factsInvalidated: "category";不使用会话类别的投影可以忽略它们。未变化的事实无需基于年龄的重试。保留的句柄在其所有者关闭后拒绝;无需新的 SDK barrel 导出。

api.runtime.gateway.withSessionFacts(select, async (snapshot) => result) 通过相同的会话列表过滤所有者选择不可变事实,无分页。选择支持 agent、archive、automation、activity 和 person 过滤器,包括 people 维度。未变化的会话事实跨读取保留对象同一性;revision 随所选内容或其活动或重试截止时间变化。符合条件的人类读取者会收到一个稳定的不透明 scope,用于其查询以及当前 viewer、profile、access、configuration 和 redaction 事实。其他调用方收到 undefined。scope 不是权限:宿主会在回调完成后重新检查调用方,包括已等待的插件工作。仅在此回调内消费复用的结果。

所选行包括 isMain。失败的获取批次保留已授权的 roster 字段,并带有 unavailable 原因;插件可以显示相同会话身份和 redactionRevision 的先前事实。当该 revision 变化时,丢弃在旧策略下准备的保留文本。缺失或不再可见的会话会被省略;missingSessionKeys 标识当前事实被省略的所选 roster 条目,因此消费者可以弃用其回退事实。所选 PR 事实从 60 秒到 15 分钟重试,保留带有 pullRequestsStale: true 的最后确认列表,并在生命周期替换或成功读取时重置。当脱敏规则变化时,宿主会省略保留的 PR 标题,直到新的源文本可用,同时保留已确认状态和重试截止时间。activityExpiresAt 和 retryAt 描述下一个相关截止时间;不会创建轮询定时器。在将事实适配到另一个公共响应契约时,移除这些仅用于选择的字段。

await api.runtime.gateway.resolveGitHubAccount({ login, signal? }) 使用 Gateway 配置的 GitHub API 凭据将公共 GitHub 登录名解析为 { accountId, login },不进行匿名重试。捆绑和受信任的官方插件使用现有的 users.list / operator.read 权限;调用方、插件和 Gateway 必须保持活动。查找失败返回 { error },包含现有 GitHub statusCode(404 未找到、429 速率限制、502 上游或网络故障)、安全的 message、可选的绝对 retryAtMs 以及 credentialConfigured。取消和权限失败会拒绝。该可选能力在旧宿主上不存在;应要求更新,而不是实现私有查找。传输层拥有超时和身份验证。

await api.runtime.gateway.withUserProfileIdentity({ profileId, emails, githubAccountIds }, run) 在现有 users.list / operator.read 权限下,为最多 500 个所选 email 别名准备规范 profile 的原始绑定生命周期。可选 githubAccountIds 将最多 500 个正的安全数值 account ID 绑定到同一规范 profile。回调接收一个同步 assertCurrent() 函数。将其与操作自身的授权组合,用于 store 的最终提交守卫以及分发外部变更之前。它读取由 profile 所有者发布的当前事实,而不在调用线程上查询 SQLite。将别名移走再移回、合并所选 profile、未完成的 profile 变更或关闭调用方会使检查失效。所选 account ID 必须保持为该 profile 的已验证成员。未选择的 email 绑定可以独立变化。准备在回调完成后释放,之后保留的断言会拒绝。此能力检查所选身份;它不授予执行操作或回滚已被外部接受的变更的权限。

api.runtime.nodes
从 Gateway 加载的插件代码或插件 CLI 命令中列出已连接节点并调用 node-host 命令。当插件拥有配对设备上的本地工作时使用此功能,例如另一台 Mac 上的浏览器或音频桥接。

```typescript
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,
});
```

当调用方可以被取消时,将 agent 工具或请求的 `AbortSignal` 作为 `signal` 传递。Gateway 加载的调用会将取消转发到配对节点;node-host 命令处理程序会将其作为 `context.signal` 接收,以便停止进行中的请求并释放本地资源。省略 `signal` 的现有调用保留其先前行为。

Gateway 加载的插件可以通过 nodes.openDuplex(...) 打开到已注册 node-host 命令的连接范围二进制通道:

    ```typescript
    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();
    }
    ```

    `openDuplex` 接受与 `nodes.invoke` 相同的节点、命令、参数、超时、幂等键、会话键、调用方信号和请求的作用域,外加可选的 `maxMessageBytes` 和 `maxOutstandingDeliveryBytes` 限制。单条消息限制默认为 100 MiB,可以降低,但绝不能超过 100 MiB。`maxOutstandingDeliveryBytes` 限制那些异步监听器回调尚未完成的完整消息的总大小;它默认为 `maxMessageBytes`,不能小于该限制,且不能超过 100 MiB。如果协议可以在最大尺寸响应之后发送有界的异步通知,则可以请求更大的未决投递预算,而无需提高单条消息上限。OpenClaw 将每条二进制消息拆分为有序的 8 KiB 有效载荷片段,以符合现有的 16 KiB 传输帧限制;调用方始终发送和接收完整的 `Uint8Array` 消息。并发发送会保留消息边界。

    在 `openDuplex` 解析后立即注册该通道的唯一消息监听器。在注册监听器之前,OpenClaw 最多缓冲八条完整消息且总计 1 MiB;超过任一限制都会关闭调用。取消订阅回调会移除该监听器。监听器可以返回 `Promise<void>`;抛出的错误或被拒绝的 promise、调用方中止、`close()`、节点断开、配对变更、插件重新加载或退役,或 Gateway 关闭都会关闭通道并取消未完成的节点工作。节点命令成功完成和 `channel.closed` 会等待已在进行中的异步消息监听器。`close()` 是幂等的,且在关闭后保留的通道方法会拒绝。`channel.closed` 会以成功的命令结果解析,或以节点、授权、传输或取消错误拒绝。通道无法重连,也无法在节点断开后存活。

    节点插件声明 `duplex: true`,并通过可选的帧式命令 I/O 能力注册消息监听器。当同一命令也支持一元调用时,使用 `duplex: "optional"`;它仍会在不支持 duplex 的节点上宣告。请通过显式请求参数选择二进制行为,而不是仅根据 I/O 是否存在来选择:

    ```typescript
    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 },
          );
        });
      },
    });
    ```

    在发送之前注册 `frames.onMessage(...)`:节点只有在监听器存在后才会宣告帧式就绪,并且 `openDuplex` 只有在命令分发和帧式就绪都完成后才会解析。这可防止输入在插件能够消费之前到达。现有的原始 `emitChunk` 和 `onInput` 辅助函数仍可用于终端式命令。

    使用 `openclaw/plugin-sdk/node-host` 中 `runNodePtyCommand` 的交互式命令可以传入一个 `assertCurrent` 回调,用于已准备的源权限。PTY 所有者会在异步原生加载之后、启动之前立即重新检查该回调和调用的中止信号。

    `openDuplex` 仅对当前受信任的进程内 Gateway 插件运行时可用。插件 CLI 运行时会以可操作的错误拒绝它;没有远程轮询或本地回退。每次调用都会使用与 `nodes.invoke` 相同的配对、已声明命令允许列表、插件策略、审批、授权和连接所有权检查。

    当节点向代理暴露插件或 MCP 支持的工具时,`nodes.list(...)` 会包含每个已连接节点宣告的 `nodePluginTools` 描述符。这些描述符是实时连接状态:当节点断开时,Gateway 会移除它们,并且节点可以在本地插件/MCP 清单变化后使用 `node.pluginTools.update` 替换它们。

    在 Gateway 内部,此运行时是进程内的。在插件 CLI 命令中,它通过 RPC 调用已配置的 Gateway,因此诸如 `openclaw googlemeet recover-tab` 之类的命令可以从终端检查已配对的节点。节点命令仍会经过正常的 Gateway 节点配对、命令允许列表、插件 node-invoke 策略和节点本地命令处理。

当为已准入的运行启用执行身份审计时,这些 Gateway 门禁会显示为强制执行的决策回执。成功的节点结果仅用于归因。如果策略在未调用其提供的 invokeNode 回调的情况下返回,则动作状态未知;返回成功的插件结果并不能证明节点动作已经发生。

暴露节点托管代理工具的插件可以为默认应加入允许列表的非危险命令设置 agentTool.defaultPlatforms。当操作员必须通过 gateway.nodes.commands.allow 显式选择加入时,应省略该设置。危险的节点托管命令应使用 api.registerNodeInvokePolicy(...) 注册节点调用策略;该策略在 Gateway 中于命令允许列表检查之后、命令转发到节点之前运行,因此直接 node.invoke 调用、节点托管插件工具以及更高层级的插件工具共享同一强制执行路径。

节点调用策略会接收所选节点通告的 commands 和可选的 caps。使用这些事实来要求受支持的命令行为,然后通过提供的 invokeNode 回调进行分发;该回调在转发命令前会重新验证当前连接和配对。

allow-always 仍保持为一次策略决策,除非节点调用策略显式声明 standingApproval: { kind: "placement", scope: "<capability>" }。该选择加入仅允许对同一当前受管 placement、节点配对、环境所有者、工作区和语义能力范围内的某个高风险命令进行后续启动,最长 30 天,并且绝不跨越 Gateway 重启。对于其审批有意覆盖后续参数变更的能力,请使用稳定的、不含内容的范围。当已批准的目标或其他请求参数必须保持精确时,不要选择加入。

节点命令可以声明 prepare(context) 用于异步原生启动。节点宿主初始化会在发布初始清单或连接到 Gateway 之前等待它;插件注册本身保持同步。共享的准备回调在每个节点注册表初始化时运行一次,而不是每次调用或重连时运行。可选提供者在预期的准备失败时应保持已知的不可用状态,并让 isAvailable 扣留其命令;抛出异常会中止节点启动。使用 watchAvailability 处理后续可用性变化,使用 onDisconnect 处理执行清理。watchAvailability 返回的清理回调可以返回一个 Promise。节点关闭会等待该回调并报告清理失败。

Warning

可选的 scopes 字段会为调用请求 Gateway 操作员范围。OpenClaw 仅对捆绑插件和受信任的官方插件安装遵循该字段;来自其他插件的请求不会提升调用权限。当 openDuplex 在已认证的 Gateway 请求内运行时,其有效范围绝不会超过该已认证调用者的实际范围,即使受信任插件请求了更强的范围。在没有已认证入站客户端时,适用现有的受信任插件范围行为。仅当受信任插件必须使用更严格的 Gateway 范围(例如 operator.admin)调用节点命令时,才使用请求的范围。

Gateway 服务事件

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

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

Gateway 托管服务还会接收 ctx.getCron?.(),用于 Gateway 钩子已经可用的调度器操作:list、add、update、remove 和 removeStaleJobFamily。非 Gateway 服务宿主会省略此获取器。

当前服务句柄还暴露 enqueueRun(id, mode) 用于服务拥有的工作。它使用普通的 cron 准入队列,并带有服务的实时权限,独立于已完成的代理工具调用者。使用 "if-enabled" 可请求立即运行,而不会覆盖已禁用的作业。保留的句柄在服务停止或调度器被替换时仍会拒绝,包括在等待准入期间。此可选方法在较旧的宿主上不存在;它没有调用者范围的回退。

当前 Gateway 服务句柄还提供 await cron.isEnabled(),用于观察是否启用了自动调度,包括 OPENCLAW_SKIP_CRON 覆盖。它只返回一个布尔值,而不是存储元数据或修改作业的权限。该方法在面向较旧宿主实现的公共类型中是可选的;其缺失表示未知,而不是已启用或已禁用。支持较旧宿主的消费者在缺失时可以保持其先前的协调行为。禁用调度不会禁用作业 CRUD 或必需的插件清理。

服务清理会保留所属插件的清理上下文,以便 stop() 可以在普通调用准入关闭后释放资源。保留该启动尝试获取的资源取消订阅函数,并释放这些精确的句柄。清理失败并不意味着原生资源已被终止;参见插件生命周期与清理。

使用服务的 start() 和 stop() 方法来负责周期性协调。 它们会在服务或插件替换以及 Gateway 启动和关闭时运行; 完整插件替换还会为受影响的插件运行 gateway_stop 和 gateway_start。 仅服务配置重载不会重放这些钩子。 每个返回的调度器句柄属于一个服务生命周期和一个调度器实例。 调用(包括排队写入)会在服务关闭开始或该调度器被替换后拒绝。 在服务仍保持活动状态时,再次调用 ctx.getCron() 以获取替换后的调度器。

服务可以与其 id、start 和 stop 一起声明 reload: { configPrefixes: ["myConfig.service"] }。 在匹配的配置变更提交后,Gateway 会停止该服务,并使用新的 ctx.config 再次调用 start(ctx)。 只有声明了匹配前缀的已加载服务会被替换;重叠的所有者都会刷新。 现有的相等或更窄的重启或空操作策略仍然优先。 每次启动都会获得新的能力租约和健康报告器。 停止必须在解析前释放资源;替换清理或启动失败会触发 Gateway 恢复。 完整插件替换涵盖这些服务重启。 停止钩子在该次尝试的原始启动结束后运行。 替换截止时间可以结束调用方的等待并撤销服务能力,同时最终清理仍由所有者负责。

受信任的官方诊断导出器服务还可以接收 ctx.internalDiagnostics.getRuntimeIdentity?.()。 它返回宿主进程的规范 processInstanceId 和可选的已加载 buildId,无需文件系统查找或 RPC。 在服务启动期间捕获它;保留的 getter 会在服务租约被撤销后抛出异常。 未提供此可选能力的宿主会使运行时身份不可用。 此诊断事实不会授予权限,也不会标识服务重载纪元。

它们的 ctx.internalDiagnostics.onEvent(listener, filter?, options?) 订阅 会传递事件、信任元数据和冻结的私有数据对象。 只需要事件和元数据的导出器可以将 { includePrivateData: false } 作为第三个注册参数传递, 以跳过私有负载副本,并改为接收一个冻结的空对象。 这会保留事件过滤器、仅限受信任的投递以及服务租约清理。 私有数据默认保持启用;较旧的宿主会忽略该可选参数,并保留其现有复制行为。

通过 api.registerService(...) 注册的长生命周期服务,在进程运行 Gateway 广播器时, 会接收一个进程本地的 ctx.gatewayEvents 外观;在没有广播器的运行时中,该字段不存在, 因此请进行特性检测并保留回退方案(例如粗略轮询)。 在 Gateway 广播 sessions.changed 通知后,使用 onSessionsChanged(...) 作出响应:

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;
  },
});

该处理程序在 Gateway 进程中运行,并且不会添加 Gateway 协议订阅。 保留返回的取消订阅函数,并在服务清理期间调用它。 负载是一个轻量级变更通知;当插件需要完整的当前会话条目时, 使用 api.runtime.agent.session.getSessionEntry(...)。

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

如果替换失败,Gateway 可能会再次调用先前服务的 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();
  },
});

当服务停止或其插件注册表代次被替换时,报告器会被撤销, 因此来自旧代次的迟到回调无法覆盖当前健康状态。 当服务在该 promise 结束前不可用时,优先返回启动 promise; 仅将报告器用于有意非阻塞且拥有自身停止路径的工作。

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