跳转至

能力字段

这些 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