能力字段

声明插件拥有什么以及激活规划器何时应加载它的清单字段。属于 插件清单 参考的一部分；顶层字段参考 列出了所有字段。

contracts 参考¶

仅将 contracts 用于静态能力所有权元数据，OpenClaw 可以在不导入插件运行时的情况下读取这些元数据。

contracts.codeModeExecutors 声明由插件的 code-mode-executor-api 公共工件提供的受支持执行器。插件当前实现 quickjs；另一个可选执行器 node 由核心拥有。插件的安装 ID 与此执行器 ID 是分开的。选择 QuickJS 只会加载其已获准的所有者。当插件被全局禁用或允许列表指定其他插件时，已选择的捆绑执行器仍保持可用，从而保留其先前的核心运行时可用性。显式的所有者拒绝或禁用条目仍会阻止选择；外部执行器遵循完整的插件策略。该工件使用 openclaw/plugin-sdk/code-mode-executor-runtime 契约导出 codeModeExecutor。它不会注册模型工具，也不会替换主机工具授权。参见 Code Mode 执行器。

{
  "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，然后列出限定于该能力的任何别名：

文档提取器可以随其文本和图像返回可选的完整性元数据。pages.processed 是实际处理的、以 1 为基数的页码的有界列表；pages.total 是文档页数；pages.selection 区分自动限制与显式请求；pages.truncated、textTruncated 和 imagesTruncated 报告已知的省略情况。maxPages 是数量上限；自动页面选择仍归提取器所有，而 pageNumbers 限制显式选择。当提取器无法确定这些事实时，请省略 metadata；不要在下游推断完整性。

contracts.embeddedExtensionFactories 保留用于捆绑的、仅限 Codex 应用服务器的扩展工厂。捆绑的工具结果转换应改为声明 contracts.agentToolResultMiddleware，并通过 api.registerAgentToolResultMiddleware(...) 注册。已安装插件只有在显式启用时，并且仅针对它们在 contracts.agentToolResultMiddleware 中声明的运行时，才可以使用同一中间件接缝。

需要主机信任的 pre-tool 策略层的已安装插件，必须在 contracts.trustedToolPolicies 中声明每个已注册的本地 ID，并被显式启用。捆绑插件保留现有的受信任策略路径，但已安装插件若包含未声明的策略 ID，将在注册前被拒绝。策略 ID 作用于注册该策略的插件，因此两个插件可以同时声明并注册 workflow-budget；但单个插件不能两次注册相同的本地 ID。

Runtime 的 api.registerTool(...) 注册必须与 contracts.tools 匹配。工具发现使用该列表仅加载能够拥有所请求工具的插件运行时。

实现 resolveExternalAuthProfiles 的提供方插件应声明 contracts.externalAuthProviders；未声明的 external-auth 钩子会被忽略。

实现 resolveUsageAuth 和 fetchUsageSnapshot 的提供方插件应在 contracts.usageProviders 中声明每个自动发现的提供方 ID。用量发现在加载运行时代码之前读取该契约，然后在仅加载已声明属主之后验证这两个钩子。

嵌入提供方必须为通过 api.registerEmbeddingProvider(...) 注册的每个适配器声明 contracts.embeddingProviders。这一通用契约同时服务于可复用的向量生成和记忆搜索。已退役的 contracts.memoryEmbeddingProviders 键不再被接受。

存储提供方必须为通过 api.registerStorageProvider(...) 注册的每个 ID 在 contracts.storageProviders 中声明。核心保留 filesystem。storage.locations 中的配置引用会通过此声明自动启用捆绑属主；显式禁用和拒绝规则仍然适用。外部提供方需要显式启用插件。请参阅 存储提供方契约。

工作器提供方必须为通过 api.registerWorkerProvider(...) 注册的每个 ID 在 contracts.workerProviders 中声明。注册要求提供 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；核心会持久化这些候选，并且仅在幂等探测、内容寻址传输、收据/锁保护的构件安装、收敛的托管工作树镜像以及隧道重连时在它们之间轮换。有歧义且无防护的状态命令会失败关闭，并且不会在候选之间重放。当 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 的主机准入边界。

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：内置工具 profile，默认公开插件工具。有效值为 minimal、coding、messaging 和 full。这些贡献会合并到相应 profile 的允许列表中；显式操作员允许列表和拒绝规则仍具有权威性。
• optional：将工具标记为插件激活时非必需。
• replaySafe：将工具执行标记为在不完整的模型轮次之后可安全重复。
• sideEffecting：将执行标记为可能更改持久或外部状态。

这些字段补充上述共享的 configSignals 和 authSignals 字段。

如果工具没有 toolMetadata，OpenClaw 会保留现有行为，并在工具契约匹配策略时加载所属插件。对于其工厂依赖身份验证/配置的热路径工具，插件作者应声明 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 仅用于尚未拥有所有权字段的嵌入式代理 harness id。

每个插件都应有意设置 activation.onStartup。仅当插件必须在 Gateway 启动期间运行时，才将其设置为 true。当插件在启动时处于非活动状态，并且应仅由更窄的触发器加载时，将其设置为 false。省略 onStartup 不再隐式地在启动时加载插件；对于启动、通道、配置、代理 harness、内存或其他更窄的激活触发器，请使用显式激活元数据。

{
  "activation": {
    "onStartup": false,
    "onProviders": ["openai"],
    "onCommands": ["models"],
    "onChannels": ["web"],
    "onRoutes": ["gateway-webhook"],
    "onConfigPaths": ["browser"],
    "onCapabilities": ["provider", "tool"]
  }
}

激活规划器的使用方：

• 网关启动规划使用 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 归属。这些原因标签用于宿主诊断和测试；插件作者应继续声明最能描述归属的元数据。加载流水线 参考文档是规划器收窄步骤和完整原因标签表的权威依据。