运行时辅助函数

在 "full"、"discovery"、"tool-discovery" 和 "setup-runtime" 注册期间可用的实时 api.runtime 对象参考。在 "cli-metadata" 和 "setup-only" 注册期间，运行时能力被有意设为不可用：访问其中任意一项会抛出指明插件和模式的错误。将运行时访问延迟到 register() 之外，或者对于根 CLI 命令，在插件清单中声明 cliCommands。使用运行时辅助函数，而不是直接导入宿主内部实现。

通道插件

针对通道插件，在上下文中使用这些辅助函数的分步指南。

提供商插件

针对提供商插件，在上下文中使用这些辅助函数的分步指南。

register(api) {
  const runtime = api.runtime;
}

api.runtime.version 是当前 OpenClaw 产品版本，来源于共享版本解析器，因此插件看到的值与 CLI 报告的相同。

各页面涵盖的内容¶

• 配置与实用工具 — 运行时配置的读取和写入，以及共享的进程、错误和模型选择器实用工具。
• 代理与会话 — 代理身份、目录、会话存储、转录和沙箱权限。
• 模型辅助函数 — 宿主拥有的补全、模型选择策略和提供商身份验证解析。
• 后台工作 — 钩住代理轮次、子代理运行以及原生 harness 完成投递。
• 网关与节点 — 进程内 Gateway 请求、配对节点调用和 Gateway 服务事件。
• 媒体辅助函数 — 语音、媒体理解、图像/视频/音乐生成、网络搜索和媒体实用工具。
• 状态与系统 — 配置快照、基于 SQLite 的插件状态、系统实用工具、事件和日志记录。
• 通道辅助函数 — 用于分块、路由、配对、媒体和提及的通道特定运行时辅助函数组。

运行时命名空间¶

每个 api.runtime 命名空间及其文档页面。

存储运行时引用¶

使用 createPluginRuntimeStore 存储运行时引用，以便在 register 回调之外使用：

1. 创建存储

import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";

const store = createPluginRuntimeStore<PluginRuntime>({
  pluginId: "my-plugin",
  errorMessage: "my-plugin runtime not initialized",
});

2. 接入入口点

import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

// `myPlugin` is your own `ChannelPlugin` object and `store` is the store
// created in the previous step; neither is an SDK export.
export default defineChannelPluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Example",
  plugin: myPlugin,
  setRuntime: store.setRuntime,
});

3. 从其他文件访问

export function getRuntime() {
  return store.getRuntime(); // throws if not initialized
}

export function tryGetRuntime() {
  return store.tryGetRuntime(); // returns null if not initialized
}

插件生命周期与清理¶

受管插件实例拥有其已注册的可调用对象、运行时存储槽位，以及已加载的源码代次。退役该实例会阻止通过其受管句柄发起新调用。已准入的调用和流在处置前有有限机会完成；保留旧函数并不会使其成为当前运行时句柄。

由已准入轮次选定的上下文引擎，在该轮次提交和引擎处置期间仍保持归属。替换已启用的插件时，会等待这些消费者关闭后再注册其继任者。禁用或移除插件时，可以将其清理报告为延迟；开始引擎处置会关闭常规引擎回调，同时清理继续完成。

替换会先验证元数据和配置，然后停止服务和通道，排空已准入的工作，运行 gateway_stop，并在调用新注册之前处置旧实例。发布前失败会触发自动恢复，通过以先前配置注册捕获的先前代码；已停止的实例不被假定为可重启。插件不能从自身活动调用中同步替换自己：该操作会在关闭前拒绝，并可在该调用结束后重试。无法在其预算内完成的清理可能会阻止安全替换或恢复。未受影响的实例保持活动，Gateway 进程继续运行。

受管实例暴露 api.lifecycle.signal 和 api.lifecycle.onDispose(cleanup)。当处置到达显式清理时，信号会中止。onDispose 接受同步或异步回调，并返回一个用于注销该回调的函数。回调只运行一次，按注册的逆序，在共享清理预算内运行。抛出异常或未完成的回调会被记录为清理失败，同时仍会尝试剩余清理。这些字段在 SDK 类型中是可选的，因为没有受管实例的 API 宿主可能会省略它们；在依赖实例清理之前，请对它们进行特性检测。现有的 api.lifecycle.registerRuntimeLifecycle(...) 契约仍可用于插件拥有的宿主状态。

清理是尽力而为的。插件必须在 onDispose 或其服务的 stop() 方法中显式释放自己的定时器、监听器、套接字、监视器和子进程。OpenClaw 不会拦截这些原生资源，也不会证明在受管退役完成时它们已停止。原生插件仍然是受信任的进程内代码。普通数据和原生字节缓冲区保留其正常身份；生命周期围栏适用于受管可调用接口，而不是插件可以保留的每个对象。

除了取消定时器外，还要释放已存储的句柄。在 Node 中，已取消的定时器对象仍可能保留其创建时的异步上下文：

clearInterval(timer);
timer = undefined;

这对原生 ESM 插件中的模块级状态很重要：替换后，Node 可能仍会保留已求值的模块。移除捕获的文件并关闭其受管回调，并不会卸载该原生模块或清除其变量。在清理中丢弃对已停止资源和其他可处置状态的引用。

插件返回的不透明值可以直接传回，或放在仅包含数据的记录和数组中。调用方拥有的带有方法或访问器的对象会原样传递，包括其中的任何句柄。

createPluginRuntimeStore 从调用它的受管实例解析其槽位。准备另一个实例不会覆盖该实例的运行时。在受管实例作用域之外的调用保留存储现有的独立行为。由 Gateway 承载的代理轮次会借用准入 Gateway 当前注册表中的工具注册，因此工厂和执行共享其服务初始化了运行时的实例。采用要求相同的插件源、配置、非空声明工具名称集合以及可选性。它保留发现中的工具成员资格和顺序。如果没有明确的准入 Gateway 所有者，轮次将保留其发现注册。

返回裸结果的 SDK 辅助函数会保留其资源，直到拥有宿主关闭。调用方无需处置这些结果；参见 已准备的简单补全。

内存运行时替换¶

内存运行时可以实现 prepareReload({ retireRuntime, retiringEmbeddingProviders })，并返回 drain() 和 resume()。准备会同步隔离受影响的管理器获取，包括延迟和回退工作。应匹配确切获取的适配器对象，而不是提供者 ID。排空会在尝试关闭受影响的管理器之前，将其从复用中移除。它可以返回 { errors } 来报告清理失败。恢复会在取消后重新开放准入，或者在运行时被保留时于发布后重新开放准入，即使旧清理仍未完成。正在退役的管理器不得将迟到结果发布到替换管理器的缓存中。

准备未使用的运行时必须使其管理器引擎保持未加载。对于没有此钩子的运行时，如果运行时或嵌入适配器退役，OpenClaw 会在提供时调用现有的 closeAllMemorySearchManagers 方法。这会尽力关闭该运行时的所有管理器；它无法识别依赖的管理器，也无法阻止并发管理器获取。

浏览器会议状态所有权¶

MeetingPlatformAdapter.createStatusCallSource 接受可选的 liveOwnershipSource：一个在生成的状态脚本页面作用域中求值的 JavaScript 布尔表达式。当设备枚举、扬声器路由或播放正在等待完成时，通话所有权可能会变化，此时应使用它。结果为 false 会停止该路由过程，通过会话的音频清理辅助函数恢复匹配的来源，退役拥有的桥接，并将输出报告为未路由且可重试。省略该选项会保持生成的状态源不变。

浏览器会议参与¶

现有 openclaw/plugin-sdk/meeting-runtime 入口在 MeetingSessionRuntime 上暴露可选参与方法。为其 participation 选项提供基于 SQLite 插件的键控存储、当前能力、操作验证以及 provider 执行器。provider 通过 observeParticipationSource 观察规范源身份、epoch、revision 和 finality；切勿从模型参数接受这些字段。inspectParticipationSource 返回快照和实时守卫，用于跨越异步边界的工作。

参与相关的命名导出为 runMeetingParticipationWithBrowser、MeetingBrowserParticipationAdapter、MeetingParticipationRequest、MeetingParticipationSource 和 MeetingParticipationAttempt。其他 payload 和 option 形状仍属于类型化运行时和适配器签名，而不是单独的顶层 SDK 别名。

每个会话最多保留 1,024 个实时源，自其首次观察起保留两分钟。容量准入和驱逐使用原始观察顺序，而不是快照重放或修正时间。重复快照保留未更改的保留引用和守卫；较旧的重放源不能从已满的实时源窗口中替换较新的源。

保留的转录行携带独立的 provenance 信封：观察者、可选的观察/会话/文档标识符和观察时间、观察到的说话人标签，以及原生 self、other 或 unknown 归属。说话人标签不是参与者身份。缺失或格式错误的归属仍保持 unknown；provenance 记录从不授予参与权限。临时、历史、自身回声以及其他不可操作行独立于 source 保留 provenance。

这是保留快照契约，而不是修订日志。未更改的轮询保持未更改的观察标识符；轮询之间的中间状态无需保留。现有转录存储在其已存储的 utterance 上，通过 metadata.meetingObservationProvenance 携带该信封，并遵循现有保留策略。没有独立的观察归档。移除一个 DOM 副本不得使仍有实时副本的源最终化。

浏览器适配器可以实现 MeetingBrowserParticipationAdapter 并通过 runMeetingParticipationWithBrowser 分发。该 helper 使用现有标签页锁、固定路由和会话守卫。可选的准备脚本可以打开控件并等待就绪，但不得执行所请求的操作。准备完成后，host 重新验证权限。最终脚本检查页面会话和 URL，并在其第一个 await 之前同步执行其效果；后续等待可以观察结果，但不得产生另一个效果。只有证明未发生所请求效果的被拒绝结果才可以设置 correctable: true。其他会议平台无需更改适配器，并继续报告不支持参与。

浏览器分发后的取消是尽力而为：效果可能在 host 检测到源过期、修正或会话撤销之前发生。运行时将该结果报告为 uncertain；不得将其视为取消的证明，或视为使用新请求 ID 重试的许可。分发前的权限检查以及适配器的最终页面会话和 URL 检查仍然是必需的。

Worker provider 分配权限¶

Gateway 在传递给 worker provider 的 provision 和 prepareProvision 方法的 options 中提供 assertCurrent()。此必需的运行时回调将操作绑定到实时环境所有者和任何请求 run。在等待的准备完成后、分配、检查点分叉或采用之前立即调用它。未中止的 signal 不能证明调用者仍具有权限。具有项目准备的 provider 必须将此回调与 project.assertCurrent() 组合，使两个所有者都保持当前状态。

该回调属于 provision 尝试。将其带入返回的已准备分配闭包，但切勿序列化它，或将其保留在持久或可重用的准备记录中。尝试关闭后，该回调拒绝保留的工作。Teardown 保留其现有清理权限，并且当请求 run 结束时仍必须结算所拥有的 lease。

旧版可选参数形状在下一个声明的破坏性 Plugin SDK 修订版之前保持源码兼容。它不是无能力要求的运行时路径：当前 host 提供此断言，并且捆绑的 provider 在执行工作前拒绝缺失的分配权限。较旧的 host 必须更新以使用这些 provider。

其他顶层 api 字段¶

除了 api.runtime 之外，API 对象还提供：

api.id string (路径)

插件 ID。

api.name string (路径)

插件显示名称。

api.config OpenClawConfig (路径)

只读配置快照，在此实例注册时提供。在默认混合重载模式下，对此插件的 plugins.entries.<id> 的更改默认会替换其实例并重新运行注册。保留的实例在无关配置更改中保持其快照。在长生命周期回调中，优先使用提供的 cfg，或者使用 api.runtime.config.current()（当未传递配置时）。

来自 plugins.entries.<id>.config 的插件特定配置，在注册时捕获。 在混合模式下，对此配置的普通编辑会自动替换实例，除非适用更窄的插件重载策略。源或清单编辑仍然需要 plugin Reload。

api.logger PluginLogger (路径)

作用域 logger（debug、info、warn、error）。

api.registrationMode PluginRegistrationMode (路径)

当前加载模式："full"（实时激活）、"discovery" / "tool-discovery"（只读能力发现）、"setup-only"（轻量级 setup 入口）、"setup-runtime"（也需要运行时通道入口的 setup 流程），或 "cli-metadata"（CLI 命令元数据收集）。

api.resolvePath(input) true (path)

string"> 解析相对于插件根目录的路径。

各章节迁移位置¶

来自先前单页版本的每个章节标题和命名空间锚点都会在此保留其锚点，因此现有链接（例如 /plugins/sdk-runtime#api-runtime-subagent）仍可解析。每个条目都指向当前承载该内容的页面。

• 配置加载与写入
• 可复用运行时工具
• 阶段计时诊断
• 插件命令运行时辅助函数
• 网关服务事件
• api.runtime.agent
• api.runtime.agent.defaults
• api.runtime.llm
• api.runtime.gateway
• api.runtime.hooks
• api.runtime.subagent
• api.runtime.sandbox
• api.runtime.nodes
• api.runtime.tts
• api.runtime.mediaUnderstanding
• api.runtime.imageGeneration
• api.runtime.videoGeneration
• api.runtime.musicGeneration
• api.runtime.webSearch
• api.runtime.media
• api.runtime.config
• api.runtime.system
• api.runtime.events
• api.runtime.logging
• api.runtime.modelConfig
• api.runtime.modelAuth
• api.runtime.state
• api.runtime.channel

相关¶

• 插件内部机制 — 能力模型与注册表
• SDK 入口点 — definePluginEntry 选项
• SDK 概览 — 子路径参考

决策模型运行时¶

api.runtime.decisions 是一种闭包绑定的可选能力，用于小型类型化 Choice、有序 Score 以及布尔概率批次。保留的句柄在消费者退役后会被拒绝。请参阅决策模型 了解提供商选择、生命周期、故障处理、限制和诊断。

先前的 Tasks 运行时不再可用。有关原生所有者替代方案，请参阅已移除的 Tasks 和 TaskFlow API。