能力注册
OpenClawPluginApi 上的能力注册器,以及 worker、存储或 embedding 提供者必须满足的运行时契约。属于插件 SDK 概览的一部分。
能力注册¶
| Method | 注册内容 |
|---|---|
api.registerProvider(...) |
文本推理(LLM) |
api.registerWorkerProvider(...) |
Cloud-worker 生命周期租约 |
api.registerStorageProvider(...) |
用于命名位置的不透明对象存储 |
api.registerModelCatalogProvider(...) |
用于文本和媒体生成的模型目录行 |
api.registerAgentHarness(...) |
实验性 原生 agent 执行器(Codex、Copilot) |
api.registerCliBackend(...) |
本地 CLI 推理后端 |
api.registerChannel(...) |
消息通道 |
api.registerEmbeddingProvider(...) |
可复用的向量 embedding 提供者 |
api.registerSpeechProvider(...) |
文本转语音 / STT 合成 |
api.registerRealtimeTranscriptionProvider(...) |
流式实时转录 |
api.registerRealtimeVoiceProvider(...) |
双工实时语音会话 |
api.registerMediaUnderstandingProvider(...) |
图像/音频/视频分析 |
api.registerTranscriptSourceProvider(...) |
实时或导入的会议转录来源 |
api.registerImageGenerationProvider(...) |
图像生成 |
api.registerMusicGenerationProvider(...) |
音乐生成 |
api.registerVideoGenerationProvider(...) |
视频生成 |
api.registerWebFetchProvider(...) |
Web 获取 / 抓取提供者 |
api.registerWebSearchProvider(...) |
Web 搜索 |
api.registerCompactionProvider(...) |
可插拔的转录压缩后端 |
与入站通道共享账户命名空间的转录来源提供者,会声明一个带有该 channel id 和规范账户解析器的 accountOwnership 描述符。OpenClaw 随后会忽略同一通道捕获中由模型选择的账户 id,绑定受信任的入站账户,并将其记录为会话所有者,以供后续生命周期操作使用。该解析器还会在 OpenClaw 启动或持久化实时捕获之前,选择一个被省略的账户。它会验证已绑定的受信任账户,而不会重定向该账户;当不存在唯一可用的账户时,返回一个可操作的类型化错误。配置的自动启动必须提供非空的源账户,或使用此描述符解析出一个这样的账户。OpenClaw 会在持久化启动或调用提供者之前,拒绝存在歧义或无法解析的所有权。提供者别名仅是查找名称,绝不能用于此声明。
存储提供者¶
从 openclaw/plugin-sdk/plugin-entry 导入 StorageProvider、StorageProviderOpenParams、StorageBackend 和 StorageObjectInfo。使用 api.registerStorageProvider(provider) 注册传输层,并在 contracts.storageProviders 中声明其 id。未声明的 ID、重复的 ID 以及核心拥有的 filesystem ID 都会被拒绝。配置的 storage.locations.<name>.provider 会自动启用其捆绑的所有者,但须遵守显式插件禁用和拒绝规则。外部插件仍需要显式启用。
一个提供者具有 id、label、可选的同步 validateSettings(settings)(返回面向用户的错误)、可选的 describeTarget(settings),以及异步的 open(params)。describeTarget 返回一个非机密的显示目标或 undefined。它必须是纯函数且同步的:仅从设置中派生目标,不进行 I/O 或机密解析。配置列表只会在内置提供者或已在所提供的注册表中的提供者上调用它;它们绝不会为了描述目标而激活插件或打开后端。否则,displayTarget 会被省略。
核心会将位置名称、只读设置、可选的中止信号以及 resolveSecret(ref) 传递给 open。通过该回调解析凭据;包含机密的设置必须包含 SecretRefs。返回一个具有非机密 displayTarget 和后述方法的后端:
| Method | Contract |
|---|---|
probe({ signal }?) |
返回可选的 freeBytes 和 totalBytes。 |
putObject(key, body, { sizeBytes, signal }) |
消费一个 AsyncIterable<Uint8Array> 并返回存储的字节数。绝不覆盖已存在的 key。 |
getObject(key, { signal }?) |
返回字节流;若对象不存在,则返回 undefined。 |
statObject(key, { signal }?) |
返回 { key, sizeBytes, modifiedAt? },若不存在则返回 undefined。时间戳以毫秒为单位。 |
listObjects(prefix, { signal }?) |
流式返回该前缀下的对象元数据。 |
deleteObject(key, { signal }?) |
删除该对象。 |
close() |
可选的异步资源清理操作。 |
sizeBytes 在提供时是精确值。当后端支持时,使用原子条件创建;否则先检查现有对象并记录竞态条件。在流式处理全程遵循中止信号,并保持内存有界。核心在调用传输层之前会验证键:键由斜杠分隔的段组成,每段包含 ASCII 字母、数字、.、_ 和 -,排除 . 和 ..,不允许空段、前导斜杠或反斜杠,且最大长度为 512 字节。
提供者存储不透明字节。核心负责位置初始化、标记标识、命名空间、加密和健康分类;消费者负责保留。提供者不得创建或解释位置标记,也不得在 displayTarget 或错误中暴露凭据。参见 存储位置。
Worker 提供者¶
Worker 提供者还必须在其 contracts.workerProviders 中声明自己的 ID。
可选的同步钩子 resolveDisplayId(profile) 提供用于选择器展示的非机密后端显示 ID。返回 1–64 个小写 ASCII 字母、数字或连字符,并以字母开头(例如 aws)。从本地已验证的设置中派生;不要为品牌展示而运行命令、读取凭据或发起网络调用。现有配置文件目录会将该表面信息连同其提供者/设置快照一起缓存。缺失、无效或抛出的元数据会被忽略,但不会隐藏配置文件或其机器选项。environments.list 将其作为可选的 providerDisplayId 呈现,而绝不会作为设置。路由 providerId、配置文件 ID、权限和分配行为保持不变。Crabbox 使用其已验证的后端提供者,因此名为 production 的配置文件无需根据其名称猜测即可显示 AWS。
提供者可以实现 maintain({ profiles, signal, assertCurrent }) 来执行有界的清理工作,该清理工作必须在没有任何活动租约的情况下继续。网关会从现有的周期性 Worker 扫描中,为已启用且已配置的提供者调用该钩子,与分配和协调等待分开。profiles 包含提供者当前已配置配置文件的克隆设置。在产生外部效果之前,以及在被等待的工作完成之后、进行持久性变更之前,立即调用 assertCurrent();当调用结束、其配置或注册发生变化,或网关停止时,授权即告终止。遵循 signal,并且仅在所拥有的命令停止后才视为完成。提供者的插件服务还必须在代际替换期间取消并排空维护。该钩子不得分配运行容量,也不得将维护视为用户需求;保留与清理策略仍由提供者所有。
核心会在 provision(profile, operationId, options?) 之前持久化存储意图。提供者会在外部分配之前验证设置以及任何可选的 options.machineClass、options.os 和 options.executionMode,并在配置文件被永久拒绝时抛出 WorkerProviderError。provision 必须为相同的操作 ID 和所选执行模式采用相同的租约;重试不能静默更改模式。如果分配后提供者负责的设置失败且清理结果不确定,则抛出 WorkerProviderError.cleanupIndeterminate(leaseId, provisionError, cleanupError),以便核心持久化已知租约并协调拆除,而不是重放 provision。如果提供者确认清理已完成,则抛出 WorkerProviderError.cleanupComplete(leaseId, provisionError)。核心完成本地拆除,包括节点注册退役,并将原始错误报告为 provider_failure。预配意图变为终态。仅在操作的分支释放或权威性缺失得到证明,且其租约清理命令已完成之后,才报告已确认的清理完成。单独保留的检查点、镜像退役和捕获恢复义务仍由提供者所有;此信号不会清除它们。普通错误会保留不确定的分配,以便使用相同的操作 ID 进行重放。提供者可以通过异步 listMachineOptions(profile) 公开进程稳定的选择器元数据;当配置文件没有有意义的机器选项时,省略该钩子。机器选项包含 id、label、可选的 os、可选的正整数 cpu 和 memoryGb,以及可选的 default。没有 os 的选项适用于所有公布的操作系统。可选的异步 listOperatingSystems(profile) 钩子返回提供者所有的 { id, label, default?, disabledReason? } 选项。可选的 disabledReason 使不可用的目标保持可见但不可选择,并提供修复提示(1–256 个字符,不含首尾空白)。提供者仍会在分配之前验证目标可用性;选择器元数据不授权预配。插件作者可以从 Awaited<ReturnType<NonNullable<WorkerProvider["listOperatingSystems"]>>>[number] 推导出条目类型,或声明本地结构类型;没有公开的 WorkerOperatingSystem 导出。核心将操作系统 ID 视为不透明字符串;插件自行负责其含义和验证。environments.list 为每个配置文件公开最多 64 个机器选项和最多 8 个操作系统;当只有一种选择时,省略操作系统列表。会话放置提供者按确定性规范顺序声明一个或两个当前 supportedExecutionModes 值:["worker-turn"]、["remote-exec"] 或 ["worker-turn", "remote-exec"]。空列表、重复值、未知模式和非规范顺序均会被拒绝。worker-turn 需要节点租约;remote-exec 接受节点租约或现有 SSH 租约。省略则宣告不提供任何放置模式,同时保留直接的环境生命周期调用。没有会话的直接环境创建不提供执行模式,因此提供者保留其有意的默认设置;捆绑的 Crabbox 提供者默认为 worker-turn。若提供者的预配工作合法地可能超过核心默认的五分钟,则可以从 resolveProvisionTimeoutMs(profile, options?) 返回一个正的毫秒级预算;该界限内包括获取、提供者负责的设置和清理。resolveDestroyTimeoutMs(profile) 声明用于拆除的等效预算,包括在确认释放前的快照捕获或其他提供者负责的工作。核心将该预算同时用于请求的拆除和引导失败清理;显式的服务超时覆盖优先。预算必须是平台定时器限制内的正安全整数。
核心从持久化的环境记录中向 provision 和 prepareProvision 提供可选的 options.profileId。它标识用于展示的配置配置文件,包括在该配置文件更改或移除后的重放;它不会更改分配标识,也不会替换冻结的设置快照。
一个可选的 options.signal 会取消当前供应尝试。将其转发到获取、项目准备、设置、就绪和注册等待,并在拒绝之前结束活动命令;调用方可见的超时或中止并不能证明提供者子进程已退出或租约已释放。将其与项目、运行时准备和注册信号组合,而不是用更窄的授权信号替换它。保持清理在其独立的、未取消的生命周期权限上。Core 为确切操作记录销毁意图,并在标准拆除前解析其分配;无法及时取消的提供者仍保持所有权,直到其真实操作结算。Gateway 关闭是另一回事:仅注册关闭会为重启接管保留固定分配,而已中止的供应信号表示显式取消。
提供者可以实现 prepareProvision(profile, operationId, options?),返回分配函数 () => Promise<WorkerLease>。准备可以验证本地设置并读取配置,但不得分配、续期、修改资源、注册节点或调用项目准备。Core 在准备期间将新环境保持在 requested 中,并在调用返回函数之前立即记录 provisioning。已准备的事实保留在该次调用中;不要在分配函数内重新读取配置。新的准备失败无需提供者拆除。重放准备失败仍不确定,因为之前的调用可能已经分配。取消或超时丢弃已准备的函数。没有此钩子的提供者保留现有 provision 契约;实现它的提供者应将其直接 provision 入口点委托到相同的准备和分配流程。
对于提供者拥有的 SSH 身份解析,Core 提供可选的 request.assertCurrent 回调。它检查当前租约和本地身份调用;初始化 SSH 的调用方也将其绑定到其准备生命周期。Core 拒绝迟到的身份结果,并在解析或调用方可见超时后关闭保留的回调。遗留解析器在没有能力声明的情况下仍受支持;它们可以在 await 之后、进一步副作用之前调用该回调,但 Core 无法阻止忽略它的解析器中的内部副作用。这不会改变供应、续期或清理权限。
每个 worker 提供者必须实现 resolveAllocation(profile, operationId),为确切操作返回 { leaseId: string; sharedHost: boolean }。Core 传递冻结的设置快照,即使命名 profile 已更改或被移除。该句柄标识清理目标;它不证明已创建机器或传输已就绪。解析不得分配、启动、续期、运行设置、读取设置密钥、注册节点或等待可用性。如果身份无法安全解析,则抛出异常。当在记录 provision 结果之前请求销毁时,Core 使用现有拆除状态持久化此句柄并调用 destroy,而不重放 provision。destroy 仍必须证明释放或权威缺失。这两个调用都保持串行化,排在任何更早的提供者操作之后,直到其实际结算,包括在调用方可见超时之后。
对于节点提供者,Core 向 resolveProvisionTimeoutMs 和供应提供可选的 options.nodeBootstrapTimeoutMs。这是 Core 拥有的每个运行时准备/注册阶段的最大值,包括 bootstrap 后的连接等待;为提供者可能运行的每个阶段保留一次。授权在分配之后到达,因此其大小无法确定初始外部截止时间。每个运行时或注册授权提供可选的 bootstrapTimeoutMs,即从其实际工件派生的命令窗口(下载两个归档时的合并字节数)。在保留的外部预算内,使用该窗口执行命令,并保持诊断和清理分离。这些可选事实保留现有提供者源代码兼容性;它们承载计时策略,而非权限、过期或重试许可。
注册云节点的提供者设置 requiresNodeEnrollment: true,并在分配机器后调用 options.beginNodeEnrollment()。返回的 WorkerNodeEnrollment 提供 displayName、openclawVersion、可选的注册生命周期 signal、waitForDeviceId(),以及 mode: "connect" 并带有 setupCode 和 setupId,或 mode: "resume" 并带有绑定的 deviceId。其必需的 nodeBootstrap 包含 Gateway 准备的运行时归档的 url、机密 bearer token、sha256、bytes、openclawVersion、enabledPluginIds 以及可选的 tlsFingerprint。下载该确切归档,验证其大小和摘要,安装其目标平台依赖项,并在连接前在节点的隔离状态中启用列出的插件。不要仅基于匹配的版本替换全局或注册表包。将下载和注册凭据排除在命令参数、日志、npm 以及已启动节点的环境之外;当 signal 中止时取消工作。下载权限属于实时注册尝试,而不仅仅是 URL 或摘要。连接后,在节点租约中返回来自 waitForDeviceId() 的设备身份。有关源代码构建、工件重用和代理要求,请参阅 Bundle installation。Bootstrap 安装不会授权节点命令或替换调用策略。
捕获可重用项目镜像的提供者可以声明 supportsProjectPreparation(profile, machineClass?, os?)。可选的 placement 覆盖是字符串;machine-class 参数保留其现有位置,以便旧提供者保持兼容。在决定是否支持准备时使用这些覆盖。对于符合条件的 Git placement,Core 在分配前持久化项目身份和固定的基础提交,然后提供 options.project。在已分配的机器上调用其 prepare({ runScript, upload }) 适配器;Core 拥有有界的 Git 传输、干净 checkout 验证和缓存布局,而提供者拥有命令和文件传输。遵守 project.signal,并在 await 的提供者工作周围调用 project.assertCurrent()。保留的回调在 provision 尝试关闭后拒绝。项目键的范围限定于 Gateway 和仓库,包括链接的 worktree。仅仓库来源还绑定仓库实例和当前共享读取身份;Core 重新验证可见性和访问权限。公共来源无需 worker 凭据即可获取。私有来源使用 Gateway 拥有的经过身份验证的临时对象存储,并通过同一适配器仅传输经过验证的 Git pack;提供者脚本和上传永远不会接收 GitHub 凭据。公共和私有来源具有不同的项目键,而不更改其持久化的来源字段。没有项目准备的提供者在注册后保留普通 checkout。会话编辑和 Git 凭据被排除在已准备的基础之外。
可选的 project.label 是显示元数据,不会影响项目键。本地快照会保留从其 origin 远程获取的规范化 host/owner/repo,或者在无法解析仓库标签时保留项目根目录的 basename;该标签会在重放时保留。仓库项目会在核心将项目传递给提供者时,从其已接受的规范 URL 派生出相同的规范化标签。
能够在专用节点上保留已完成设置的提供者,还应实现 resolvePreparationTarget(profile, machineClass?, os?),返回生效的机器类别和平台,并在已知时返回架构。核心在分配之前,会对这些目标事实、设置配方、项目提交以及当前运行时工件进行指纹计算。当存在 options.project.preparation 时,除现有传输方法外,还应使用 runScriptWithBudget(createScript, signal) 调用 prepare;在运行仓库代码之前,将命令剩余的毫秒预算传递给渲染器。即使较旧的镜像具有相同的提交和运行时,也要尊重返回的 captureRequired: true,同时保留所选镜像代次的捕获权限。provision 返回的节点租约必须包含 sharedHost: false,以证明专用所有权;true 或省略该字段会在已准备的工作区注册之前被拒绝。核心在租约验证过程中保留所提供的布尔值。核心在完成注册后,注册返回的工作区和清单标识,然后将其一次性绑定到确切的会话。在已注册的 provision 重试中,调用 project.inspectPreparedWorkspace({ runScript }) 以恢复现有的完成事实,而不进行传输、执行设置或捕获。缺失或已更改的完成会显式失败;它不能成为新的纯净基线。
核心将 options.nodeRuntimeIdentity 作为无授权的已准备事实提供:节点归档的 SHA-256、执行模式,以及当项目准备保留该归档时的 worker 归档 SHA-256。在判断已捕获的运行时内容是否为当前版本时,应比较此标识;仅凭版本字符串是不够的。核心会将后续的运行时和注册描述符与这些已准备的字节进行比较,如果标识发生变化,则关闭其授权。
参与已准备项目的就绪容量的提供者应实现
resolvePreparedIdleTimeoutMs(profile),从其现有空闲策略返回一个正的安全毫秒
时长,或者在预留不受支持时返回 undefined。options.project.preparation 还携带 purpose("session"
或 "reserve")以及来源 demandAtMs;重复分配必须同时保留这两者。预留准备和补充不会创建新的需求。成功激活后,核心可以调用
notePreparedDemand({ leaseId, profile }, { preparationKey, demandAtMs })。
仅更新由该租约选择或生成的确切镜像代次;时间戳和匹配的摘要并不授权更改另一个代次。
此钩子仅记录元数据;它不得分配、捕获或续期 worker。
即使就绪容量被禁用,成功的前台需求仍会被记录。
分配和 fork 时间戳不会确立成功的前台需求。
在激活之前,保持新捕获的前台镜像的需求未设置,同时
保留其生产者的实际代次回执,直到确认源停止。
在普通注册或项目捕获之前,调用 options.prepareNodeRuntime() 以获取工件访问权限,而不创建节点标识或注册码。结果包括 nodeBootstrap、workerBundle 以及该操作的取消 signal。worker 归档描述符提供 url、机密 token、sha256、bytes、可选的 tlsFingerprint,以及已安装节点包内由核心拥有的 packageRelativePath。在注册或捕获之前,下载并验证这两个归档,安装运行时,并将压缩的 worker 归档发布到该确切包含位置。捆绑的 Crabbox 提供者对无项目注册使用相同的准备步骤,将 worker 归档下载与运行时安装重叠。每个运行时包只保留一个已发布的 worker 归档,排除凭据和回执,并且永远不要将独立负载添加到精简运行时归档中。普通认证安装器会验证已准备的字节,并在注册后创建全新安装;原始归档不授予任何准入权限。在调用 beginNodeEnrollment() 之前完成捕获。开始注册、取消、替换或关闭会撤销两个准备授权。结果不确定的原生捕获必须在注册将其凭据引入其源机器之前确定或被显式恢复。在联系提供者之前持久化原始的冷/检查点分配决策,保留检查点引用直到确认释放,并且在重放同一操作时永远不要切换镜像。
核心将经过验证的 profile 设置与租约一起持久化,并将该快照提供给 destroy({ leaseId, profile })(必须幂等)和 inspect({ leaseId, profile })(返回 active、dormant、destroyed 或 unknown)。这使得提供者能够在网关重启或命名 profile 移除后路由生命周期调用。SSH 端点使用 SecretRef 作为 keyRef,绝不内联密钥材料,并包含来自可信配置输出的 hostKey,其格式必须恰好为 algorithm base64,不包含主机名或注释。核心固定 hostKey,并且从不信任来自首次连接的密钥。提供者还可以返回最多 10 个有序且唯一的 fallbackPorts(1 到 65535 之间的整数端口,排除主 port);核心会验证并持久化这些已通告的候选项,用于幂等检查、内容寻址传输、由回执/锁保护的工件安装、收敛的 managed-worktree 镜像以及隧道重连。模糊的无保护有状态命令会失败关闭,并且不会跨候选项重放。当 SSH 账户还拥有无关进程时,租约可以设置 sharedHost: true;此时核心会避免在工作区协调期间冻结整个主机的进程。对于普通租约,省略该字段会保留传统的专用主机行为;已准备的工作区注册要求在 provision 结果中显式提供 sharedHost: false。活动检查会重复这一事实,以便核心能够协调该字段存在之前持久化的租约的提供者拥有的隔离;隧道启动会等待该首次权威检查。铸造动态 keyRef 的提供者可以实现 resolveSshIdentity({ leaseId, profile, keyRef });当存在时,该解析器是权威的,而没有它的提供者使用已配置的通用密钥解析器。
WorkerLease.desktop 是可选的,其形状为 { protocol: "rfb"; port: number; passwordFilePath?: string; username?: string; allowsResize?: boolean; apps?: WorkerDesktopApp[] };passwordFilePath 如果存在,必须是 worker 上的绝对路径(POSIX 或 Windows)。设置 allowsResize: false 会限制原生桌面进行提供者范围的虚拟显示器调整大小。提供者从 provision 报告此热时能力;它无法被追溯添加到活动租约上。拥有该租约的 SSH 或节点载体在需要时在 worker 上读取密码,并且永远不将其持久化到 Gateway 存储中。WorkerDesktopApp 是一个封闭联合类型:{ id: "browser"; executablePath: string; args?: string[]; cdpPort: number } 或 { id: "terminal"; executablePath: string; args?: string[] }。应用 id 必须唯一,可执行文件路径必须是绝对路径,浏览器 CDP 端口必须是 1 到 65535 之间的整数,并且列表最多接受八个条目。核心拒绝未知的 id 和字段。可选的 args 由提供者固定,并随其已接受的启动器一起传输,绝不由查看器提供。它们在节点上无 shell 运行;每个参数都不含 NUL 且限制在 4 KiB 以内,最多 32 个参数,总计 8 KiB。Gateway 验证独立于 Gateway 操作系统接受 POSIX 和 Windows 绝对路径;节点验证其原生路径语法。可选的 username 标识租约拥有的 ARD 账户,其密码从 passwordFilePath 读取,并在节点与 Gateway 之间保持临时状态。托管 ARD 账户认证需要节点载体;凭据绝不进入浏览器。普通主机桌面保留其现有的由查看器提供的 ARD 凭据。
具有可续期租约的提供者还可以实现 renew(leaseId)。
inspect 必须在瞬时或不确定失败时抛出异常;仅在权威缺失时返回 unknown。核心隔离环境并调用规范拆除;共享或未知主机隔离仍需要确认确切的 worker 已停止。不得仅仅为了释放其逻辑租约而停止或取消配对共享主机。
通过 api.registerEmbeddingProvider(...) 注册的嵌入提供方还必须列在插件清单的 contracts.embeddingProviders 中。这是用于可复用向量生成的通用嵌入接口。记忆搜索会消费此通用提供方接口。旧的记忆专用注册器和清单契约已在 2026 年 8 月迁移窗口结束后移除。
嵌入提供方可以使用来自 openclaw/plugin-sdk/embedding-provider-runtime-contract 的 EmbeddingProviderBatchRuntime 为其异步 batchEmbed(...) 能力添加类型。公共契约包含批处理块和执行选项,不包含主机缓存或身份元数据。除非运行时设置 sourceWideBatchEmbed: true,否则批处理仍按文件进行。该可选设置允许记忆主机在一次 batchEmbed(...) 调用中提交来自多个脏记忆文件和已启用来源的块,直至达到主机批处理限制。上传 JSONL 请求文件的批处理适配器必须在其上传大小上限以及请求数量上限之前拆分提供方作业。提供方必须按 batch.chunks 的相同顺序为每个输入块返回一个嵌入;当提供方期望文件本地批处理,或无法在更大的全来源作业中保持输入顺序时,应省略该标志。
决策模型(契约版本 1)¶
请先阅读 决策模型 了解模型选择、配置以及 Choice/Score/Boolean 评分标准示例。本节定义提供方和消费方 SDK 契约。
api.registerDecisionProvider({ id, contractVersion: 1, isReady, evaluate }) 注册一个可选的决策提供方,独立于对话模型提供方和代理工具。在清单的 contracts.decisionProviders 中声明该 ID;重复的 ID 会被拒绝。注册和可选的 isReady() 必须是本地、同步且无网络的。从 openclaw/plugin-sdk/decisions 导入类型。
消费方调用 api.runtime.decisions.evaluate(batch, { agentId?, purpose, rubricVersion, timeoutMs, signal })。状态和评分标准条目是有限 JSON。使用普通对象和数组;自定义原型、序列化钩子和 getter 在请求和响应边界都会被拒绝。选项保留所有提供的标签和概率;所选标签是提供方的决策,不一定等于最大的四舍五入概率。消费方选择是使用该标签还是显式分布策略。有序分数是分数形式的估计零基位置,具有索引对齐的概率;布尔答案携带 probabilityTrue。主机原子性地验证整个批处理:精确的答案键、[0, 1] 内的有限概率、分布质量为正,以及分数在提交的评分标准范围内。报告的概率可能经过四舍五入,且不一定精确加总为 1;分数不一定等于该四舍五入分布的期望值。主机会保留这些值。需要归一化权重的消费方必须应用自己的显式策略。提供方置信度是提供方特定的指标,不是经过校准的正确性。结果包括模型、可选的 token 用量,以及本地评分标准和运行时生成来源信息。
将 agents.defaults.decisionModel 设置为显式的 provider/model 引用。未设置或为空表示关闭。agents.entries.<id>.decisionModel 覆盖全局默认值;空的代理值会禁用该代理的决策。没有自动的对话模型回退。选择会使提供方对受支持的消费方可用。消费方负责其功能激活和证据选择;仅配置提供方不会调度后台工作。发送到所选提供方的证据可能产生其正常用量费用。插件禁用优先;仅安装工具或凭据不会选择提供方。供应商适配器负责传输和模型特定转换;没有任何供应商是核心依赖。
ONNX 插件 提供本地分类器;TypeSafe AI 插件 提供托管的 Jev 和本地 System One 适配器,包括 Kev。这两个插件都需要单独安装、显式配置和角色选择。
从第三方插件调用¶
与 api.runtime.llm.complete 类似,api.runtime.decisions.evaluate 允许插件使用主机配置的提供方,而无需处理其凭据。消费方不需要提供方的 SDK、API key、SecretRef 或提供方注册。只有提供方插件注册 contracts.decisionProviders,并拥有其供应商传输和准备好的凭据输入。这不会使对话模型凭据与决策提供方凭据可以互换。
操作员必须启用并配置提供方插件,并选择 agents.defaults.decisionModel(或代理覆盖)。第三方插件负责其功能的激活、证据选择以及发送该证据的权限。仅拥有凭据不得激活后台收集或支出。
从活动的插件工具、钩子或其他自有操作中调用,并携带其取消信号:
const outcome = await api.runtime.decisions.evaluate(
{
state: { message: "Can you help me with this?", directlyAddressed: true },
questions: {
respond: {
type: "boolean",
instructions: "Is this message asking the assistant to respond?",
criteria: {
true: "The message asks the assistant to respond",
false: "The message does not ask the assistant to respond",
},
},
},
},
{
agentId, // The agent that owns this operation; omit only for global-default selection.
purpose: "example-plugin.response-eligibility",
rubricVersion: "1",
timeoutMs: 1500,
signal,
},
);
ok 结果包含已验证的答案、模型/用量,以及提供方/评分标准/运行时来源信息。它是消费方决策的证据,而不是发送消息或执行其他效果的权限。unavailable 结果携带供消费方现有回退使用的原因。不要捕获取消或权限已关闭错误并将其转换为回退工作。
提供方在其评估上下文中接收所选的 model 和可选的 agentId。并发的代理/模型选择共享提供方健康状态,而不会相互退役。选择变更会在返回受影响请求之前对其进行隔离。
自动消费者在提供方分发时检查 Labs 选择加入状态。禁用它会停止未来的评估,而不是已分发的工作或其结果的使用。宿主提供 context.isAdmissible(),用于持续消费者权限、模型选择以及提供方配置/凭据生成检查;Labs 开关不属于这些持续检查的一部分。执行外部 I/O 的提供方必须在发送前同步调用它,且在任何延迟加载、DNS 或其他等待准备完成之后。返回 false 会关闭该评估;抛出权限断言是终局的。宿主会跨提供方清理记住任一观察结果,因此权限撤销不会变成提供方健康失败或后续成功结果。省略它会保留显式 decision_evaluate 调用和旧宿主兼容性;它不是显式调用的 Labs 检查。TypeSafe 使用其受保护传输的最终 beforeRequest 钩子。宿主仍会在提供方分发前和返回结果前进行检查,但无法阻止忽略此回调的第三方提供方执行 I/O。本地 ONNX 推理保留其现有的信号控制工作进程生命周期;它不会将证据传输到外部服务。
消费者共享所选提供方的宿主拥有的并发、熔断器和凭据刷新生命周期;每个插件不会创建自己的提供方客户端。不会向消费者返回任何凭据。提供方设置和刷新使用相同的已准备密钥路径,无论调用方是内置还是第三方。
宿主最多接纳四个请求,没有队列,最大 30 秒。消费者可以请求更短的截止时间并选择自己的回退策略。三次不健康响应会打开一个十秒熔断器;恢复时接纳一次试验。Retry-After 限制为一分钟。身份验证错误会锁存,直到已准备密钥或配置代际发生变化。宿主没有重试或健康检查。
调用方取消和已关闭的消费者权限会拒绝:不要启动回退。提供方退役会返回不可用,同时存活的消费者可以回退。提供方必须遵守组合的中止信号,并实际完成传输和正文清理;不配合的提供方仍由正常的失败排空恢复保持拥有并隔离。旧代际的结果不能更新新健康状态。
清单能力凭据使用 configContracts.secretInputs 和已编写的 SecretRefs。openclaw/plugin-sdk/secret-input-runtime 中的 getPreparedPluginSecretInput(pluginId, path) 只读取已准备且可用的快照;它从不解析冷引用或查询环境凭据。仅从插件实例的活跃调用中调用它。该辅助函数不是持久凭据能力:静默或退役该确切实例会立即移除读取权限,即使已接纳的工作仍在完成。提供方必须将缺失值视为不可用,并且不得在重新加载之间保留或重用先前值。使用 secrets.reload 刷新;能力失败不会保留旧密钥。
plugins.inspect 报告配置、凭据就绪状态、当前可调用性、最近成功、使用情况、延迟以及有界的不可用计数。计数是实例本地诊断,不是持久审计记录或写入权限。
用于发现,在提供方清单中声明静态 decisionModels 条目,包含 provider、id 和 name。每个提供方必须由 contracts.decisionProviders 拥有。Control UI 的 Decision 选择器通过单独的 models.list.decisionModels 投影读取此元数据;不会运行提供方运行时或凭据检查来填充选择器。这些条目永远不会进入聊天、主要、回退或实用模型目录。
可选的模型 capabilities 描述支持的问题类型、输入限制及其核算范围、布尔条件要求以及置信度语义。核心 decision_evaluate 工具使用这些相同的清单事实作为指导;提供方就绪状态不会改变其定义。有关有界的描述符字段,请参阅清单参考。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw