能力字段
这些 Manifest 字段声明插件拥有什么,以及激活规划器(activation planner)应在何时加载它。属于 Plugin manifest 参考的一部分;顶层字段参考 列出了所有字段。
contracts 参考¶
仅将 contracts 用于静态能力归属元数据,OpenClaw 无需导入插件运行时即可读取这些元数据。
contracts.codeModeExecutors 声明插件的 code-mode-executor-api 公共工件所提供的受支持执行器。插件目前实现 quickjs;另一个可选择的执行器 node 由核心(core)拥有。插件的安装 ID 与此执行器 ID 相互独立。选择 QuickJS 只会加载其获准的属主。当插件被全局禁用,或允许列表(allowlist)指定了其他插件时,已选的内置执行器仍然可用,从而保留其原先的核心运行时可用性。显式的属主拒绝或禁用条目仍会阻止选择;外部执行器遵循完整的插件策略。
该工件通过 openclaw/plugin-sdk/code-mode-executor-runtime 契约导出 codeModeExecutor。它不会注册模型工具,也不会取代宿主工具授权。参见 Code Mode executors。
{
"contracts": {
"agentToolResultMiddleware": ["openclaw", "codex"],
"trustedToolPolicies": ["workflow-budget"],
"externalAuthProviders": ["acme-ai"],
"embeddingProviders": ["openai-compatible"],
"decisionProviders": ["example-decisions"],
"speechProviders": ["openai"],
"realtimeTranscriptionProviders": ["openai"],
"realtimeVoiceProviders": ["openai"],
"mediaUnderstandingProviders": ["openai"],
"imageGenerationProviders": ["openai"],
"videoGenerationProviders": ["qwen"],
"musicGenerationProviders": ["stability-audio"],
"documentExtractors": ["example-docs"],
"webContentExtractors": ["firecrawl"],
"webFetchProviders": ["firecrawl"],
"webSearchProviders": ["gemini"],
"workerProviders": ["example-worker"],
"storageProviders": ["example-storage"],
"usageProviders": ["acme-ai"],
"migrationProviders": ["hermes"],
"gatewayMethodDispatch": ["authenticated-request"],
"tools": ["firecrawl_search", "firecrawl_scrape"]
}
}
每个列表都是可选的。对于 speechProviders 和 realtimeVoiceProviders,请先列出规范的提供者 ID,后跟限定于该能力的任何别名:
| 字段 | 类型 | 含义 |
|---|---|---|
embeddedExtensionFactories |
string[] |
Codex app-server 扩展工厂 ID。codex-app-server 是唯一接受的 ID。 |
agentToolResultMiddleware |
string[] |
此插件可为其注册工具结果中间件(tool-result middleware)的运行时 ID。 |
trustedToolPolicies |
string[] |
已安装插件可注册的插件本地受信任工具前策略(trusted pre-tool policy)ID。内置插件无需此字段即可注册策略。 |
externalAuthProviders |
string[] |
此插件拥有的外部认证配置文件钩子(external auth profile hook)所对应的提供者 ID。 |
embeddingProviders |
string[] |
此插件拥有的通用嵌入提供者 ID,用于可复用的向量嵌入,包括记忆(memory)。 |
decisionProviders |
string[] |
通过 api.registerDecisionProvider 注册的类型化决策提供者;通过 decisionModel 选择。 |
speechProviders |
string[] |
此插件拥有的语音提供者 ID。 |
realtimeTranscriptionProviders |
string[] |
此插件拥有的实时转录提供者 ID。 |
realtimeVoiceProviders |
string[] |
此插件拥有的实时语音提供者 ID。 |
mediaUnderstandingProviders |
string[] |
此插件拥有的媒体理解提供者 ID。 |
transcriptSourceProviders |
string[] |
此插件拥有的转录来源提供者 ID。 |
documentExtractors |
string[] |
此插件拥有的文档(例如 PDF)提取器提供者 ID。 |
imageGenerationProviders |
string[] |
此插件拥有的图像生成提供者 ID。 |
videoGenerationProviders |
string[] |
此插件拥有的视频生成提供者 ID。 |
musicGenerationProviders |
string[] |
此插件拥有的音乐生成提供者 ID。 |
webContentExtractors |
string[] |
此插件拥有的网页内容提取提供者 ID。 |
webFetchProviders |
string[] |
此插件拥有的网页抓取(web-fetch)提供者 ID。 |
webSearchProviders |
string[] |
此插件拥有的网页搜索提供者 ID。 |
workerProviders |
string[] |
该插件拥有的云工作器提供方 ID,用于预置和基于配置文件的租约生命周期管理。 |
storageProviders |
string[] |
通过 api.registerStorageProvider 注册的存储传输 ID;按指定的存储位置进行选择。 |
usageProviders |
string[] |
该插件拥有的使用量认证与使用量快照钩子所对应的提供方 ID。 |
migrationProviders |
string[] |
该插件拥有的导入提供方 ID,用于 openclaw migrate。 |
gatewayMethodDispatch |
string[] |
为通过进程内方式分发 Gateway 方法的已认证插件 HTTP 路由所保留的权限。 |
tools |
string[] |
该插件拥有的代理工具名称。 |
文档提取器可以随其文本和图像返回可选的完整性元数据。pages.processed 是一个有边界的列表,列出实际处理的从 1 开始的页码;pages.total 是文档页数;pages.selection 区分自动限制与显式请求;pages.truncated、textTruncated 和 imagesTruncated 报告已知的遗漏。maxPages 是数量上限;自动页面选择仍由提取器决定,而 pageNumbers 限制显式选择。当提取器无法确定这些事实时,应省略 metadata;不要在下游推断完整性。
contracts.embeddedExtensionFactories 保留用于捆绑的 Codex 应用服务器专用扩展工厂。捆绑的工具结果转换应声明 contracts.agentToolResultMiddleware,并改用 api.registerAgentToolResultMiddleware(...) 注册。已安装插件只有在显式启用时,并且仅针对它们在 contracts.agentToolResultMiddleware 中声明的运行时,才可以使用相同的中间件接缝。
需要主机信任的预工具策略层级的已安装插件,必须在 contracts.trustedToolPolicies 中声明每个已注册的本地 ID,并显式启用。捆绑插件保留现有的受信任策略路径,但已安装插件若包含未声明的策略 ID,则会在注册前被拒绝。策略 ID 作用域限定于注册插件,因此两个插件可以同时声明并注册 workflow-budget;单个插件不能重复注册同一个本地 ID。
运行时的 api.registerTool(...) 注册必须与 contracts.tools 相匹配。工具发现机制使用该列表仅加载能够拥有所请求工具的插件运行时。
实现 resolveExternalAuthProfiles 的提供方插件应声明 contracts.externalAuthProviders;未声明的外部认证钩子将被忽略。
同时实现 resolveUsageAuth 和 fetchUsageSnapshot 的提供方插件应在 contracts.usageProviders 中声明每个自动发现的提供方 ID。使用量发现机制会在加载运行时代码之前读取此契约,然后在仅加载已声明所有者之后验证这两个钩子。
嵌入提供方必须为通过 api.registerEmbeddingProvider(...) 注册的每个适配器声明 contracts.embeddingProviders。同一个通用契约同时服务于可复用的向量生成和记忆搜索。已停用的 contracts.memoryEmbeddingProviders 键不再被接受。
存储提供方必须声明 api.registerStorageProvider(...) 在 contracts.storageProviders 中注册的每个 ID。核心保留 filesystem。配置中对 storage.locations 的引用会通过该声明自动启用捆绑所有者;显式禁用和拒绝规则仍然适用。外部提供方需要显式启用插件。参见存储提供方契约。
工作器提供方必须声明 api.registerWorkerProvider(...) 在 contracts.workerProviders 中注册的每个 ID。注册要求实现 resolveAllocation、provision、inspect 和 destroy。分配解析器返回精确的操作清理句柄和显式的共享主机事实,而无需创建或准备机器;参见工作器提供方契约。核心在调用 provision 之前持久化持久意图;提供方在外部分配之前验证其设置以及可选的每次派发的 machineClass 和 executionMode,并且使用相同操作 ID 的重复调用必须采用相同的租约,且不得更改所选模式。提供方可以实现异步的 listMachineOptions(profile),以暴露进程稳定的选择器元数据;当机器选择没有意义时省略它。机器选项仅包含 id、label、可选的正整数 cpu 和 memoryGb,以及可选的 default。会话放置提供方声明一个封闭、唯一、按规范顺序排列的 supportedExecutionModes 元组:["worker-turn"]、["remote-exec"] 或 ["worker-turn", "remote-exec"]。空列表、重复值、未知值以及非规范顺序都会被拒绝。worker-turn 需要节点租约;remote-exec 接受节点租约或 SSH 租约。省略此字段表示不提供任何会话放置模式,同时仍保留直接生命周期操作。直接创建环境时不提供会话执行模式;提供方使用其文档记录的默认值,对 Crabbox 而言该默认值为 worker-turn。如果提供方的有界预置超过核心默认的五分钟,可以实现 resolveProvisionTimeoutMs(profile),并在返回的正毫秒预算中包含获取、提供方自有的设置和清理。可选的 resolveDestroyTimeoutMs(profile) 为请求的拆除和引导失败清理提供等效预算,包括在确认释放前捕获快照。这两个钩子必须返回平台计时器限制内的正安全整数;显式的服务超时覆盖优先。核心还会持久化该已校验的设置快照,并将其与 leaseId 一起传递给 inspect({ leaseId, profile }) 和 destroy({ leaseId, profile }),即使在指定配置文件被更改或删除之后也是如此。销毁操作是幂等的;检查返回封闭的 active / dormant / destroyed / unknown 状态联合;SSH 私钥材料仅通过 SecretRef 引用。预置的 SSH 端点还必须包含来自可信预置输出的公共 hostKey,其格式必须严格为 algorithm base64,不包含主机名或注释,以便核心在连接前固定主机。它们可以包含最多 10 个有序且唯一的 fallbackPorts,不包括主要 port;核心会持久化这些候选端口,并且仅在幂等检查、内容寻址传输、基于回执/锁保护的工件安装、收敛的托管工作树镜像以及隧道重连时在它们之间轮换。有歧义且无保护的状态ful命令会失败关闭,且不会在候选端口之间重放。当 SSH 账户还拥有无关进程时,租约可以设置 sharedHost: true;此时核心会在工作区协调期间避免冻结主机范围内的进程。省略或设为 false 表示专用工作器主机。主动检查会重复这一事实,以便核心为在该字段存在之前持久化的租约协调提供方自有的隔离;隧道启动会等待首次权威检查。可选的桌面元数据可以公布最多八个唯一的封闭应用:browser(带有绝对 executablePath 和 1 到 65535 之间的 CDP 端口)或 terminal(带有绝对 executablePath)。核心会拒绝未知的应用 ID 和字段,并将已校验的元数据与现有桌面记录一起持久化。生成动态身份引用的提供方可以实现权威的 resolveSshIdentity({ leaseId, profile, keyRef });没有该实现的提供方使用核心的通用密钥解析器。权威的 unknown 会隔离环境并进入规范拆除流程;它不会绕过在共享或未知主机上所需的精确工作器停止确认。
contracts.gatewayMethodDispatch 接受单个值 "authenticated-request"。它是针对已认证的原生插件 HTTP 路由和已注册 RPC 处理器的 API 卫生门禁,这些处理器有意在进程内分发 Gateway 方法;它不是针对恶意原生插件的沙箱。分发会保留原始已认证客户端和配置文件,应用目标方法的作用域,并且从不创建合成调用者。仅将其用于经过严格审查的表面。RPC 处理器仍会通过普通 Gateway 准入;此契约不添加任何暂停绕过。当 Gateway root-work 准入关闭时,只有同时声明 auth: "gateway" 和路由特定的 gatewayRuntimeScopeSurface: "trusted-operator" 的授权路由才保持可达;同一插件的普通同级路由仍位于准入边界之后。这使暂停状态和恢复保持可达,而无需授予整个插件准入绕过。将解析和响应整形限制在分发之外;实质性或变更性工作必须通过 Gateway 方法分发,分发负责准入和作用域强制。
Worker 提供方可在其桌面端点可安全调整大小时设置 allowsDesktopResize: true,例如专用虚拟显示器。省略或 false 不会授予权限。端点可以使用 allowsResize: false 进一步限制此提供方范围的权限,例如针对原生显示器。Core 会将此事实作为可选的 canResize 携带在桌面观察结果中,适用于 SSH 和 node 传输。这是请求调整大小的权限,而不是协商的 VNC 支持。查看器在请求调整大小之前还必须持有控制权并完成认证。
决策模型参考¶
将 decisionModels 声明为 contracts.decisionProviders 所拥有的提供方的静态选择器元数据。这些条目独立于对话式 modelCatalog 和 providers 元数据。发现过程读取清单,而不会加载提供方运行时或解析凭据。
{
"contracts": { "decisionProviders": ["example-decisions"] },
"decisionModels": [
{
"provider": "example-decisions",
"id": "fast",
"name": "Fast decisions",
"capabilities": {
"questionTypes": ["boolean", "choice", "score"],
"maxQuestions": 32,
"maxChoiceAlternatives": 64,
"maxScoreLevels": 16,
"maxInputTokens": 8192,
"inputTokenScope": "encoded-question",
"requiresBooleanCriteria": true,
"confidence": "provider-specific"
}
}
]
}
每个条目都需要提供方 ID、模型 ID 和显示名称。选择器使用
example-decisions/fast。已禁用的插件会从决策选择器中排除;
已保存的不可用选择项仍会显示,供操作员修复。
capabilities 是可选的静态元数据。它描述提供方对
发现和引导的支持;它不能证明凭据或运行时已
就绪,并且其限制不会提高 OpenClaw 的主机准入边界。
| 字段 | 必填 | 接受的值 | 省略语义 |
|---|---|---|---|
questionTypes |
是 | 非空数组,最多包含 boolean、choice 和 score 中的三项 |
当此字段缺失或无效时,整个 capabilities 对象会被省略;重复项会被移除。 |
maxQuestions |
否 | 正的安全整数 | 不声明特定于提供方的问题数量限制。 |
maxChoiceAlternatives |
否 | 正的安全整数 | 不声明特定于提供方的 Choice 备选限制。 |
maxScoreLevels |
否 | 正的安全整数 | 不声明特定于提供方的 Score 级别限制。 |
maxInputTokens |
否 | 正的安全整数 | 不声明特定于提供方的输入 token 限制。 |
inputTokenScope |
否 | encoded-question 或 state-plus-each-criterion |
提供方未声明如何计算 maxInputTokens。 |
requiresBooleanCriteria |
否 | 布尔值 | 不声明额外的 Boolean 条件要求。 |
confidence |
否 | provider-specific 或 none |
不声明置信度结果语义。 |
encoded-question 表示提供方计算其编码请求,包括
提供方添加的评分标准开销。state-plus-each-criterion 表示共享
状态会在每次条件评估时一起计算。provider-specific 置信度
是提供方指标,而不是答案正确的校准概率;
none 声明提供方不返回置信度。
格式错误的可选字段和未知字段会被单独忽略。
格式错误的 questionTypes 值会移除整个能力描述符,但不会
移除模型条目。重复的 provider/id 条目会保留第一个有效的
模型描述符。
工具元数据参考¶
toolMetadata 使用与生成提供方元数据相同的 configSignals 和 authSignals 形状,并以工具名称为键。contracts.tools 声明所有权。toolMetadata 声明低成本的可用性证据,以便 OpenClaw 可以避免仅为了让其工具工厂返回 null 而导入插件运行时。
{
"setup": {
"providers": [
{
"id": "example",
"envVars": ["EXAMPLE_API_KEY"]
}
]
},
"contracts": {
"tools": ["example_search"]
},
"toolMetadata": {
"example_search": {
"profiles": ["coding", "full"],
"authSignals": [
{
"provider": "example"
}
],
"configSignals": [
{
"rootPath": "plugins.entries.example.config",
"overlayPath": "search",
"required": ["apiKey"]
}
]
}
}
}
toolMetadata 条目还接受:
profiles:内置工具配置文件,默认公开该插件工具。有效值为minimal、coding、messaging和full。这些贡献会合并到对应配置文件的允许列表;显式的操作员允许列表和拒绝规则仍具有最终决定权。optional:将该工具标记为插件激活时非必需。replaySafe:将工具执行标记为在模型回合不完整后重复执行是安全的。sideEffecting:将执行标记为可能更改持久化状态或外部状态。
这些字段补充了上述共享的 configSignals 和 authSignals 字段。
如果工具没有 toolMetadata,OpenClaw 会保留现有行为,并在工具契约匹配策略时加载所属插件。对于工厂依赖 auth/config 的热路径工具,插件作者应声明 toolMetadata,而不是让核心导入运行时来询问。
激活参考¶
当插件可以低成本地声明哪些控制平面事件应将其包含在激活/加载计划中时,请使用 activation。
此块是规划器元数据,而不是生命周期 API。它不会注册运行时行为,不会替代 register(...),也不保证插件代码已经执行。激活规划器使用这些字段来缩小候选插件范围,然后再回退到现有的清单所有权元数据,例如 providers、channels、commandAliases、setup.providers、contracts.tools 和 hooks。
优先使用已经描述所有权的范围最窄的元数据。当这些字段能够表达关系时,请使用 providers、channels、commandAliases、setup 描述符或 contracts。对于无法由这些所有权字段表示的额外规划器提示,请使用 activation。对于 CLI 运行时别名(例如 claude-cli、my-cli 或 google-gemini-cli),请使用顶层 cliBackends;activation.onAgentHarnesses 仅用于尚未拥有所有权字段的嵌入式 agent harness id。
每个插件都应有意设置 activation.onStartup。仅当插件必须在 Gateway 启动期间运行时,才将其设置为 true。当插件在启动时处于非活动状态,并且应仅由更窄的触发器加载时,将其设置为 false。省略 onStartup 不再隐式地在启动时加载插件;对于启动、通道、配置、agent-harness、内存或其他更窄的激活触发器,请使用显式激活元数据。
{
"activation": {
"onStartup": false,
"onProviders": ["openai"],
"onCommands": ["models"],
"onChannels": ["web"],
"onRoutes": ["gateway-webhook"],
"onConfigPaths": ["browser"],
"onCapabilities": ["provider", "tool"]
}
}
| 字段 | 必需 | 类型 | 含义 |
|---|---|---|---|
onStartup |
否 | boolean |
显式的 Gateway 启动激活。每个插件都应设置此项。true 会在启动期间导入插件;false 会保持其启动惰性,除非另一个匹配的触发器要求加载。 |
onProviders |
否 | string[] |
应在激活/加载计划中包含此插件的 provider id。 |
onAgentHarnesses |
否 | string[] |
应在激活/加载计划中包含此插件的嵌入式 agent harness 运行时 id。对于 CLI 后端别名,请使用顶层 cliBackends。 |
onCommands |
否 | string[] |
应在激活/加载计划中包含此插件的命令 id。 |
onChannels |
否 | string[] |
应在激活/加载计划中包含此插件的通道 id。 |
onRoutes |
否 | string[] |
应在激活/加载计划中包含此插件的路由类型。 |
onConfigPaths |
否 | string[] |
当路径存在且未被显式禁用时,应在启动/加载计划中包含此插件的相对于根目录的配置路径。 |
onCapabilities |
否 | Array<"provider" \| "channel" \| "tool" \| "hook"> |
控制平面激活规划使用的宽泛能力提示。尽可能优先使用更窄的字段。 |
| 字段 | 必填 | 类型 | 含义 |
|---|---|---|---|
激活规划器使用者:
- 网关启动规划使用
activation.onStartup进行显式启动导入。 - 命令触发的 CLI 规划回退到旧版
commandAliases[].cliCommand或commandAliases[].name。 - Agent 运行时启动规划使用
activation.onAgentHarnesses处理嵌入式 harness,并使用顶层cliBackends[]处理 CLI 运行时别名。 - 通道触发的设置/通道规划在缺少显式通道激活元数据时,回退到旧版
channels[]所有权。 - 启动插件规划使用
activation.onConfigPaths处理非通道根配置表面,例如捆绑浏览器插件的browser块。 - 提供者触发的设置/运行时规划在缺少显式提供者激活元数据时,回退到旧版
providers[]和顶层cliBackends[]所有权。
规划器诊断可以区分显式激活提示与清单所有权回退。例如,activation-command-hint 表示 activation.onCommands 匹配,而 manifest-command-alias 表示规划器使用了 commandAliases 所有权。这些原因标签用于宿主诊断和测试;插件作者应继续声明最能描述所有权的元数据。加载流水线 参考是规划器收窄步骤和完整原因标签表的权威来源。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw