diff --git a/docs/zh-CN/plugins/architecture-internals.md b/docs/zh-CN/plugins/architecture-internals.md index 972f092be..a40c9e642 100644 --- a/docs/zh-CN/plugins/architecture-internals.md +++ b/docs/zh-CN/plugins/architecture-internals.md @@ -1,106 +1,107 @@ --- read_when: - - 实现提供商运行时钩子、渠道生命周期或软件包打包集 + - 实现提供商运行时钩子、渠道生命周期或包打包功能 - 调试插件加载顺序或注册表状态 - 添加新的插件能力或上下文引擎插件 -summary: 插件架构内部机制：加载管线、注册表、运行时钩子、HTTP 路由和参考表格 +summary: 插件架构内部机制：加载流水线、注册表、运行时钩子、HTTP 路由和参考表格 title: 插件架构内部机制 x-i18n: - generated_at: "2026-04-24T03:06:49Z" + generated_at: "2026-04-24T05:09:37Z" model: gpt-5.4 provider: openai - source_hash: 243ccb0cb5b55c4ba08ac387f5b19949391b3a4f1772f6d7ac889f3d8f548a47 + source_hash: 01e258ab1666f7aff112fa3f897a40bf28dccaa8d06265fcf21e53479ee1ebda source_path: plugins/architecture-internals.md workflow: 15 --- -关于公开能力模型、插件形态以及所有权 / 执行契约，请参阅 [插件架构](/zh-CN/plugins/architecture)。本页是内部机制的参考文档：加载管线、注册表、运行时钩子、Gateway 网关 HTTP 路由、导入路径和 schema 表格。 +关于公开能力模型、插件形态以及所有权/执行契约，请参见 [插件架构](/zh-CN/plugins/architecture)。本页是内部机制的参考：加载流水线、注册表、运行时钩子、Gateway 网关 HTTP 路由、导入路径和架构表格。 -## 加载管线 +## 加载流水线 -启动时，OpenClaw 大致会执行以下步骤： +在启动时，OpenClaw 大致会执行以下步骤： 1. 发现候选插件根目录 -2. 读取原生或兼容 bundle 清单以及包元数据 +2. 读取原生或兼容打包产物的清单和包元数据 3. 拒绝不安全的候选项 4. 规范化插件配置（`plugins.enabled`、`allow`、`deny`、`entries`、`slots`、`load.paths`） -5. 为每个候选项决定是否启用 +5. 决定每个候选项是否启用 6. 加载已启用的原生模块：已构建的内置模块使用原生加载器；未构建的原生插件使用 `jiti` -7. 调用原生 `register(api)` 钩子，并将注册内容收集到插件注册表中 -8. 将注册表暴露给命令 / 运行时表面 +7. 调用原生 `register(api)` 钩子，并将注册结果收集到插件注册表中 +8. 将注册表暴露给命令/运行时表面 -`activate` 是 `register` 的旧别名 —— 加载器会解析存在的那个（`def.register ?? def.activate`），并在同一时机调用它。所有内置插件都使用 `register`；新插件请优先使用 `register`。 +`activate` 是 `register` 的旧别名——加载器会解析存在的那个（`def.register ?? def.activate`），并在相同时间点调用它。所有内置插件都使用 `register`；新插件请优先使用 `register`。 -安全门禁会在运行时执行**之前**发生。当入口逃逸出插件根目录、路径可被所有人写入，或者对于非内置插件来说路径所有权看起来可疑时，候选项会被阻止。 +安全检查会在运行时执行**之前**发生。当入口逃逸出插件根目录、路径对所有人可写，或对于非内置插件而言路径所有权看起来可疑时，候选项会被阻止。 -### Manifest 优先行为 +### 清单优先行为 -manifest 是控制平面的事实来源。OpenClaw 用它来： +清单是控制平面的事实来源。OpenClaw 使用它来： - 标识插件 -- 发现已声明的渠道 / Skills / 配置 schema 或 bundle 能力 +- 发现声明的渠道/Skills/配置架构或打包能力 - 验证 `plugins.entries..config` -- 增强 Control UI 标签 / 占位符 -- 显示安装 / catalog 元数据 -- 在不加载插件运行时的情况下，保留低成本的激活与设置描述符 +- 增强控制 UI 标签/占位符 +- 显示安装/目录元数据 +- 在不加载插件运行时的情况下保留轻量的激活和设置描述符 -对于原生插件，运行时模块是数据平面部分。它负责注册实际行为，例如钩子、工具、命令或提供商流程。 +对于原生插件，运行时模块是数据平面部分。它会注册实际行为，例如钩子、工具、命令或提供商流程。 -可选的 manifest `activation` 和 `setup` 块仍然属于控制平面。它们只是用于激活规划和设置发现的纯元数据描述符；不会替代运行时注册、`register(...)` 或 `setupEntry`。 -首批实时激活使用方现在会利用 manifest 的命令、渠道和提供商提示，在更广泛的注册表物化之前缩小插件加载范围： +可选的清单 `activation` 和 `setup` 块仍然留在控制平面。它们是用于激活规划和设置发现的纯元数据描述符；它们不会替代运行时注册、`register(...)` 或 `setupEntry`。首批实时激活使用方现在会使用清单中的命令、渠道和提供商提示，在更广泛的注册表具体化之前缩小插件加载范围： - CLI 加载会缩小到拥有所请求主命令的插件 -- 渠道设置 / 插件解析会缩小到拥有所请求渠道 id 的插件 -- 显式提供商设置 / 运行时解析会缩小到拥有所请求提供商 id 的插件 +- 渠道设置/插件解析会缩小到拥有所请求渠道 id 的插件 +- 显式提供商设置/运行时解析会缩小到拥有所请求提供商 id 的插件 -设置发现现在优先使用描述符自有 id，例如 `setup.providers` 和 `setup.cliBackends`，以便在回退到 `setup-api` 之前先缩小候选插件范围；`setup-api` 仅用于那些仍需要设置期运行时钩子的插件。如果发现的多个插件声称拥有同一个规范化后的设置提供商或 CLI 后端 id，设置查找会拒绝这个存在歧义的所有者，而不是依赖发现顺序。 +激活规划器同时暴露面向现有调用方的仅 id API，以及面向新诊断的规划 API。规划条目会报告某个插件为何被选中，并将显式 `activation.*` 规划器提示与清单所有权回退原因区分开来，例如 `providers`、`channels`、`commandAliases`、`setup.providers`、`contracts.tools` 和钩子。这种原因拆分就是兼容性边界：现有插件元数据仍然可以正常工作，而新代码可以检测宽泛提示或回退行为，而无需改变运行时加载语义。 + +设置发现现在会优先使用描述符拥有的 id，例如 `setup.providers` 和 `setup.cliBackends`，在回退到 `setup-api` 之前先缩小候选插件范围；`setup-api` 用于那些仍然需要设置阶段运行时钩子的插件。如果发现的多个插件声明了同一个规范化设置提供商或 CLI 后端 id，设置查找会拒绝这个存在歧义的所有者，而不是依赖发现顺序。 ### 加载器会缓存什么 -OpenClaw 会在进程内维护短期缓存，用于： +OpenClaw 会在进程内维护一些短期缓存，用于： - 发现结果 -- manifest 注册表数据 +- 清单注册表数据 - 已加载的插件注册表 -这些缓存可以减少突发启动和重复命令的开销。可以把它们看作短生命周期的性能缓存，而不是持久化机制。 +这些缓存可以减少突发启动和重复命令的开销。你可以安全地将它们视为短生命周期的性能缓存，而不是持久化机制。 性能说明： - 设置 `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` 或 `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` 可禁用这些缓存。 -- 使用 `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` 和 `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS` 调整缓存窗口。 +- 使用 `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` 和 `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS` 调整缓存时间窗口。 ## 注册表模型 -已加载的插件不会直接随意修改核心全局状态。它们会注册到一个中心化的插件注册表中。 +已加载的插件不会直接修改任意核心全局状态。它们会注册到一个中央插件注册表中。 注册表会跟踪： -- 插件记录（标识、来源、源头、状态、诊断信息） +- 插件记录（身份、来源、起源、状态、诊断） - 工具 -- 旧式钩子和类型化钩子 +- 旧版钩子和类型化钩子 - 渠道 - 提供商 - Gateway 网关 RPC 处理器 - HTTP 路由 - CLI 注册器 - 后台服务 -- 插件自有命令 +- 插件拥有的命令 -然后，核心功能会从这个注册表中读取，而不是直接与插件模块交互。这让加载保持单向： +然后，核心功能会从这个注册表中读取，而不是直接与插件模块交互。这使得加载保持单向： - 插件模块 -> 注册表注册 - 核心运行时 -> 注册表消费 -这种分离对可维护性非常重要。它意味着大多数核心表面只需要一个集成点：“读取注册表”，而不是“为每个插件模块做特殊处理”。 +这种分离对于可维护性很重要。这意味着大多数核心表面只需要一个集成点：“读取注册表”，而不是“为每个插件模块做特殊处理”。 ## 会话绑定回调 -绑定会话的插件可以在审批完成时作出响应。 +绑定会话的插件可以在批准结果确定后作出响应。 -使用 `api.onConversationBindingResolved(...)` 可以在绑定请求被批准或拒绝后接收回调： +使用 `api.onConversationBindingResolved(...)` 在绑定请求被批准或拒绝后接收回调： ```ts export default { @@ -108,12 +109,12 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // 现在已为该插件 + 会话建立绑定。 + // A binding now exists for this plugin + conversation. console.log(event.binding?.conversationId); return; } - // 请求已被拒绝；清理任何本地挂起状态。 + // The request was denied; clear any local pending state. console.log(event.request.conversation.conversationId); }); }, @@ -124,82 +125,82 @@ export default { - `status`：`"approved"` 或 `"denied"` - `decision`：`"allow-once"`、`"allow-always"` 或 `"deny"` -- `binding`：已批准请求的已解析绑定 +- `binding`：用于已批准请求的已解析绑定 - `request`：原始请求摘要、分离提示、发送者 id 和会话元数据 -这个回调仅用于通知。它不会改变谁被允许绑定会话，并且会在核心审批处理完成后运行。 +这个回调仅用于通知。它不会改变谁被允许绑定会话，并且它会在核心批准处理完成后运行。 ## 提供商运行时钩子 提供商插件有三层： -- **Manifest 元数据**，用于廉价的运行前查找：`providerAuthEnvVars`、`providerAuthAliases`、`providerAuthChoices` 和 `channelEnvVars`。 -- **配置期钩子**：`catalog`（旧版 `discovery`）以及 `applyConfigDefaults`。 -- **运行时钩子**：40 多个可选钩子，涵盖凭证、模型解析、流包装、思考级别、重放策略和用量端点。完整列表见 [钩子顺序与用法](#hook-order-and-usage)。 +- 用于低成本运行时前查找的**清单元数据**：`providerAuthEnvVars`、`providerAuthAliases`、`providerAuthChoices` 和 `channelEnvVars`。 +- **配置时钩子**：`catalog`（旧版 `discovery`）以及 `applyConfigDefaults`。 +- **运行时钩子**：40 多个可选钩子，涵盖凭证、模型解析、流包装、思考级别、重放策略和用量端点。完整列表见下方的[钩子顺序和用法](#hook-order-and-usage)。 -OpenClaw 仍然负责通用智能体循环、故障切换、转录处理和工具策略。这些钩子是提供商特定行为的扩展表面，因此无需整套自定义推理传输也能实现相应能力。 +OpenClaw 仍然负责通用智能体循环、故障转移、转录处理和工具策略。这些钩子是提供商特定行为的扩展表面，无需实现完整的自定义推理传输。 -当提供商具有基于环境变量的凭证，并且希望通用凭证 / 状态 / 模型选择器路径在不加载插件运行时的情况下也能看到这些信息时，请使用 manifest `providerAuthEnvVars`。当某个提供商 id 应复用另一个提供商 id 的环境变量、凭证配置文件、基于配置的凭证和 API 密钥新手引导选项时，请使用 manifest `providerAuthAliases`。当新手引导 / 凭证选择 CLI 表面需要在不加载提供商运行时的情况下了解该提供商的 choice id、分组标签和简单的单标志凭证接线方式时，请使用 manifest `providerAuthChoices`。请将提供商运行时 `envVars` 保留给面向操作员的提示，例如新手引导标签或 OAuth client-id / client-secret 设置变量。 +当提供商具有基于环境变量的凭证，并且通用凭证/状态/模型选择器路径需要在不加载插件运行时的情况下看到这些凭证时，请使用清单中的 `providerAuthEnvVars`。当某个提供商 id 需要复用另一个提供商 id 的环境变量、凭证配置文件、基于配置的凭证和 API 密钥新手引导选择时，请使用清单中的 `providerAuthAliases`。当新手引导/凭证选择 CLI 表面需要在不加载提供商运行时的情况下知道该提供商的选择 id、分组标签和简单单标志凭证接线时，请使用清单中的 `providerAuthChoices`。把提供商运行时的 `envVars` 保留给面向运维人员的提示，例如新手引导标签或 OAuth `client-id`/`client-secret` 设置变量。 -当某个渠道具有由环境变量驱动的凭证或设置，并且希望通用 shell 环境变量回退、配置 / 状态检查或设置提示在不加载渠道运行时的情况下也能看到这些信息时，请使用 manifest `channelEnvVars`。 +当某个渠道具有由环境变量驱动的凭证或设置，并且通用 shell 环境变量回退、配置/状态检查或设置提示需要在不加载渠道运行时的情况下看到这些内容时，请使用清单中的 `channelEnvVars`。 -### 钩子顺序与用法 +### 钩子顺序和用法 -对于模型 / 提供商插件，OpenClaw 大致会按以下顺序调用钩子。 -“何时使用”列是快速决策指南。 +对于模型/提供商插件，OpenClaw 大致会按以下顺序调用这些钩子。 +“何时使用”这一列是快速决策指南。 | # | 钩子 | 作用 | 何时使用 | | --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | 在生成 `models.json` 期间，将提供商配置发布到 `models.providers` 中 | 提供商拥有 catalog 或 base URL 默认值 | -| 2 | `applyConfigDefaults` | 在配置物化期间应用提供商自有的全局配置默认值 | 默认值依赖于凭证模式、环境变量或提供商模型族语义 | -| -- | _(内置模型查找)_ | OpenClaw 会先尝试常规的注册表 / catalog 路径 | _(不是插件钩子)_ | -| 3 | `normalizeModelId` | 在查找前规范化旧版或预览版 model-id 别名 | 提供商拥有在规范模型解析之前进行别名清理的逻辑 | -| 4 | `normalizeTransport` | 在通用模型组装前规范化提供商族的 `api` / `baseUrl` | 提供商需要为同一传输族中的自定义提供商 id 执行传输清理 | -| 5 | `normalizeConfig` | 在运行时 / 提供商解析前规范化 `models.providers.` | 提供商需要将配置清理逻辑放在插件中；内置的 Google 族辅助逻辑也会为受支持的 Google 配置项提供兜底 | -| 6 | `applyNativeStreamingUsageCompat` | 将原生流式使用量兼容性重写应用到配置提供商 | 提供商需要基于端点驱动修复原生流式使用量元数据 | -| 7 | `resolveConfigApiKey` | 在加载运行时凭证前，为配置提供商解析 env-marker 凭证 | 提供商拥有自己的 env-marker API 密钥解析逻辑；`amazon-bedrock` 在这里也有一个内置的 AWS env-marker 解析器 | -| 8 | `resolveSyntheticAuth` | 在不持久化明文的情况下暴露本地 / 自托管或基于配置的凭证 | 提供商可以使用 synthetic / 本地凭证标记运行 | -| 9 | `resolveExternalAuthProfiles` | 叠加提供商自有的外部凭证配置文件；CLI / app 自有凭证的默认 `persistence` 为 `runtime-only` | 提供商可复用外部凭证，而无需持久化复制的 refresh token；请在 manifest 中声明 `contracts.externalAuthProviders` | -| 10 | `shouldDeferSyntheticProfileAuth` | 将已存储的 synthetic 配置文件占位符降级到 env / 基于配置的凭证之后 | 提供商会存储 synthetic 占位配置文件，而这些配置文件不应获得更高优先级 | -| 11 | `resolveDynamicModel` | 为尚未出现在本地注册表中的提供商自有模型 id 提供同步回退 | 提供商接受任意上游模型 id | -| 12 | `prepareDynamicModel` | 异步预热，然后再次运行 `resolveDynamicModel` | 提供商在解析未知 id 之前需要网络元数据 | -| 13 | `normalizeResolvedModel` | 在嵌入式 runner 使用已解析模型之前进行最终重写 | 提供商需要进行传输重写，但仍然使用核心传输 | -| 14 | `contributeResolvedModelCompat` | 为位于另一兼容传输之后的供应商模型提供兼容性标志 | 提供商可以在代理传输上识别自己的模型，而无需接管该提供商 | -| 15 | `capabilities` | 由共享核心逻辑使用的提供商自有转录 / 工具元数据 | 提供商需要处理转录或提供商族特有的差异 | -| 16 | `normalizeToolSchemas` | 在嵌入式 runner 看到工具 schema 之前进行规范化 | 提供商需要进行传输族的 schema 清理 | -| 17 | `inspectToolSchemas` | 在规范化后暴露提供商自有的 schema 诊断信息 | 提供商希望提供关键字警告，而无需让核心理解特定于提供商的规则 | -| 18 | `resolveReasoningOutputMode` | 选择原生还是带标签的推理输出契约 | 提供商需要带标签的推理 / 最终输出，而不是原生字段 | -| 19 | `prepareExtraParams` | 在通用流选项包装器之前进行请求参数规范化 | 提供商需要默认请求参数或按提供商进行参数清理 | -| 20 | `createStreamFn` | 使用自定义传输完全替换常规流路径 | 提供商需要自定义线协议，而不只是包装器 | -| 21 | `wrapStreamFn` | 在应用通用包装器之后再包装流函数 | 提供商需要请求头 / 请求体 / 模型兼容性包装器，但不需要自定义传输 | +| 1 | `catalog` | 在生成 `models.json` 期间，将提供商配置发布到 `models.providers` 中 | 提供商拥有目录或基础 URL 默认值 | +| 2 | `applyConfigDefaults` | 在配置具体化期间应用由提供商拥有的全局配置默认值 | 默认值依赖于凭证模式、环境变量或提供商模型族语义 | +| -- | _(内置模型查找)_ | OpenClaw 会先尝试常规注册表/目录路径 | _(不是插件钩子)_ | +| 3 | `normalizeModelId` | 在查找之前规范化旧版或预览版 model-id 别名 | 提供商拥有在规范模型解析之前进行别名清理的逻辑 | +| 4 | `normalizeTransport` | 在通用模型组装之前规范化提供商族的 `api` / `baseUrl` | 提供商拥有同一传输族中自定义提供商 id 的传输清理逻辑 | +| 5 | `normalizeConfig` | 在运行时/提供商解析之前规范化 `models.providers.` | 提供商需要将配置清理逻辑保留在插件中；内置的 Google 系列辅助逻辑也会为受支持的 Google 配置条目提供兜底 | +| 6 | `applyNativeStreamingUsageCompat` | 对配置提供商应用原生流式用量兼容性改写 | 提供商需要基于端点驱动的原生流式用量元数据修复 | +| 7 | `resolveConfigApiKey` | 在加载运行时凭证之前，为配置提供商解析 env-marker 凭证 | 提供商拥有自己的 env-marker API 密钥解析逻辑；`amazon-bedrock` 在这里也有内置的 AWS env-marker 解析器 | +| 8 | `resolveSyntheticAuth` | 暴露 local/self-hosted 或基于配置的凭证，而不持久化明文 | 提供商可以使用 synthetic/local 凭证标记运行 | +| 9 | `resolveExternalAuthProfiles` | 叠加由提供商拥有的外部凭证配置文件；对于 CLI/应用拥有的凭证，默认 `persistence` 为 `runtime-only` | 提供商会复用外部凭证凭据，而不持久化复制的刷新令牌；请在清单中声明 `contracts.externalAuthProviders` | +| 10 | `shouldDeferSyntheticProfileAuth` | 将已存储的 synthetic 配置文件占位符降级到环境变量/基于配置的凭证之后 | 提供商会存储 synthetic 占位配置文件，而这些占位配置文件不应获得更高优先级 | +| 11 | `resolveDynamicModel` | 为本地注册表中尚不存在的提供商模型 id 提供同步回退 | 提供商接受任意上游模型 id | +| 12 | `prepareDynamicModel` | 先执行异步预热，然后再次运行 `resolveDynamicModel` | 提供商在解析未知 id 之前需要网络元数据 | +| 13 | `normalizeResolvedModel` | 在嵌入式运行器使用已解析模型之前执行最终改写 | 提供商需要进行传输改写，但仍使用核心传输 | +| 14 | `contributeResolvedModelCompat` | 为位于另一兼容传输之后的厂商模型提供兼容性标志 | 提供商可以在代理传输上识别自己的模型，而无需接管该提供商 | +| 15 | `capabilities` | 由共享核心逻辑使用的提供商自有转录/工具元数据 | 提供商需要处理转录/提供商族特有行为 | +| 16 | `normalizeToolSchemas` | 在嵌入式运行器看到工具架构之前规范化工具架构 | 提供商需要针对传输族清理架构 | +| 17 | `inspectToolSchemas` | 在规范化之后暴露由提供商拥有的架构诊断 | 提供商希望提供关键字警告，而无需让核心理解提供商特定规则 | +| 18 | `resolveReasoningOutputMode` | 选择原生或带标签的 reasoning-output 契约 | 提供商需要带标签的推理/最终输出，而不是原生字段 | +| 19 | `prepareExtraParams` | 在通用流选项包装器之前规范化请求参数 | 提供商需要默认请求参数或按提供商清理参数 | +| 20 | `createStreamFn` | 用自定义传输完全替换常规流路径 | 提供商需要自定义线协议，而不只是包装器 | +| 21 | `wrapStreamFn` | 在应用通用包装器之后再对流进行包装 | 提供商需要请求头/请求体/模型兼容性包装器，而不是自定义传输 | | 22 | `resolveTransportTurnState` | 附加原生的逐轮传输请求头或元数据 | 提供商希望通用传输发送提供商原生的轮次标识 | -| 23 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 请求头或会话冷却策略 | 提供商希望通用 WS 传输调整会话请求头或回退策略 | -| 24 | `formatApiKey` | 凭证配置文件格式化器：已存储的配置文件会变成运行时 `apiKey` 字符串 | 提供商存储了额外凭证元数据，并需要自定义的运行时 token 形态 | -| 25 | `refreshOAuth` | 针对自定义刷新端点或刷新失败策略的 OAuth 刷新覆盖 | 提供商不适用于共享的 `pi-ai` 刷新器 | -| 26 | `buildAuthDoctorHint` | 当 OAuth 刷新失败时附加修复提示 | 提供商需要在刷新失败后提供其自有的凭证修复指引 | -| 27 | `matchesContextOverflowError` | 提供商自有的上下文窗口溢出匹配器 | 提供商存在通用启发式无法捕获的原始溢出错误 | -| 28 | `classifyFailoverReason` | 提供商自有的故障切换原因分类 | 提供商可以将原始 API / 传输错误映射为速率限制、过载等 | -| 29 | `isCacheTtlEligible` | 面向代理 / 回传提供商的 prompt-cache 策略 | 提供商需要代理特定的缓存 TTL 门禁 | -| 30 | `buildMissingAuthMessage` | 替换通用的缺失凭证恢复消息 | 提供商需要特定于提供商的缺失凭证恢复提示 | -| 31 | `suppressBuiltInModel` | 抑制过时的上游模型，并可选替换为面向用户的错误提示 | 提供商需要隐藏过时的上游条目，或用供应商提示替换它们 | -| 32 | `augmentModelCatalog` | 在发现后附加 synthetic / 最终 catalog 条目 | 提供商需要在 `models list` 和选择器中加入 synthetic 的前向兼容条目 | -| 33 | `resolveThinkingProfile` | 设置模型特定的 `/think` 级别、显示标签和默认值 | 提供商为选定模型公开自定义的思考梯度或二元标签 | -| 34 | `isBinaryThinking` | 开 / 关推理切换兼容性钩子 | 提供商只支持二元的思考开 / 关 | -| 35 | `supportsXHighThinking` | `xhigh` 推理支持兼容性钩子 | 提供商希望仅在部分模型上支持 `xhigh` | +| 23 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 请求头或会话冷却策略 | 提供商希望通用 WS 传输能够调整会话请求头或回退策略 | +| 24 | `formatApiKey` | 凭证配置文件格式化器：已存储配置文件会变为运行时 `apiKey` 字符串 | 提供商会存储额外凭证元数据，并需要自定义运行时令牌形态 | +| 25 | `refreshOAuth` | 为自定义刷新端点或刷新失败策略覆盖 OAuth 刷新逻辑 | 提供商不适配共享的 `pi-ai` 刷新器 | +| 26 | `buildAuthDoctorHint` | 当 OAuth 刷新失败时追加修复提示 | 提供商需要在刷新失败后提供由自己维护的凭证修复指导 | +| 27 | `matchesContextOverflowError` | 由提供商维护的上下文窗口溢出匹配器 | 提供商存在通用启发式无法捕获的原始溢出错误 | +| 28 | `classifyFailoverReason` | 由提供商维护的故障转移原因分类 | 提供商可以将原始 API/传输错误映射为速率限制、过载等 | +| 29 | `isCacheTtlEligible` | 面向代理/回传提供商的提示缓存策略 | 提供商需要面向代理的缓存 TTL 控制 | +| 30 | `buildMissingAuthMessage` | 替换通用的缺失凭证恢复消息 | 提供商需要提供商特定的缺失凭证恢复提示 | +| 31 | `suppressBuiltInModel` | 过时上游模型抑制，以及可选的面向用户错误提示 | 提供商需要隐藏过时的上游条目，或用厂商提示替换它们 | +| 32 | `augmentModelCatalog` | 在发现之后追加 synthetic/最终目录条目 | 提供商需要在 `models list` 和选择器中加入 synthetic 的前向兼容条目 | +| 33 | `resolveThinkingProfile` | 设置特定模型的 `/think` 级别、显示标签和默认值 | 提供商为选定模型暴露自定义思考梯度或二元标签 | +| 34 | `isBinaryThinking` | 开/关推理切换兼容性钩子 | 提供商只暴露二元的思考开/关 | +| 35 | `supportsXHighThinking` | `xhigh` 推理支持兼容性钩子 | 提供商只希望在部分模型上启用 `xhigh` | | 36 | `resolveDefaultThinkingLevel` | 默认 `/think` 级别兼容性钩子 | 提供商拥有某个模型族的默认 `/think` 策略 | -| 37 | `isModernModelRef` | 用于实时配置文件过滤和 smoke 选择的现代模型匹配器 | 提供商拥有实时 / smoke 首选模型匹配逻辑 | -| 38 | `prepareRuntimeAuth` | 在推理前立即将已配置的凭证交换为实际运行时 token / 密钥 | 提供商需要 token 交换或短期请求凭证 | -| 39 | `resolveUsageAuth` | 为 `/usage` 及相关状态表面解析使用量 / 计费凭证 | 提供商需要自定义使用量 / 配额 token 解析，或需要不同的使用量凭证 | -| 40 | `fetchUsageSnapshot` | 在凭证解析后获取并规范化特定于提供商的使用量 / 配额快照 | 提供商需要特定于提供商的使用量端点或负载解析器 | -| 41 | `createEmbeddingProvider` | 为内存 / 搜索构建提供商自有的 embedding 适配器 | Memory embedding 行为应归属于提供商插件 | -| 42 | `buildReplayPolicy` | 返回一个控制该提供商转录处理方式的重放策略 | 提供商需要自定义转录策略（例如去除 thinking 块） | -| 43 | `sanitizeReplayHistory` | 在通用转录清理后重写重放历史 | 提供商需要共享压缩辅助逻辑之外的特定于提供商的重放重写 | -| 44 | `validateReplayTurns` | 在嵌入式 runner 执行前，对重放轮次进行最终验证或重塑 | 提供商传输在通用清洗后需要更严格的轮次验证 | -| 45 | `onModelSelected` | 在模型被选中后运行提供商自有的副作用 | 当模型变为活动状态时，提供商需要遥测或提供商自有状态 | +| 37 | `isModernModelRef` | 用于实时配置文件筛选和冒烟选择的现代模型匹配器 | 提供商拥有实时/冒烟首选模型匹配逻辑 | +| 38 | `prepareRuntimeAuth` | 在推理之前，将已配置凭证交换为实际运行时令牌/密钥 | 提供商需要令牌交换或短期请求凭证 | +| 39 | `resolveUsageAuth` | 为 `/usage` 及相关状态表面解析用量/计费凭证 | 提供商需要自定义用量/配额令牌解析，或使用不同的用量凭证 | +| 40 | `fetchUsageSnapshot` | 在凭证解析完成后，获取并规范化提供商特定的用量/配额快照 | 提供商需要提供商特定的用量端点或负载解析器 | +| 41 | `createEmbeddingProvider` | 为内存/搜索构建由提供商拥有的嵌入适配器 | Memory 嵌入行为应归属于提供商插件 | +| 42 | `buildReplayPolicy` | 返回一个重放策略，用于控制该提供商的转录处理 | 提供商需要自定义转录策略（例如剥离 thinking 块） | +| 43 | `sanitizeReplayHistory` | 在通用转录清理之后重写重放历史 | 提供商需要超出共享压缩辅助函数之外的提供商特定重放改写 | +| 44 | `validateReplayTurns` | 在嵌入式运行器之前，对重放轮次进行最终验证或重塑 | 在通用净化之后，提供商传输需要更严格的轮次验证 | +| 45 | `onModelSelected` | 在模型被选中后运行由提供商拥有的副作用 | 当模型变为活动状态时，提供商需要遥测或由提供商拥有的状态 | -`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查已匹配的提供商插件，然后继续落到其他具备钩子能力的提供商插件，直到某个插件实际修改了模型 id 或传输 / 配置。这样可以让别名 / 兼容提供商 shim 正常工作，而不要求调用方知道哪个内置插件拥有该重写逻辑。如果没有任何提供商钩子重写受支持的 Google 族配置项，内置的 Google 配置规范化器仍会应用该兼容性清理。 +`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查匹配到的提供商插件，然后再依次回退到其他支持这些钩子的提供商插件，直到有插件实际更改了模型 id 或传输/配置。这样可以让别名/兼容性提供商垫片继续工作，而不要求调用方知道哪个内置插件拥有该改写逻辑。如果没有任何提供商钩子改写受支持的 Google 系列配置条目，内置的 Google 配置规范化器仍会应用该兼容性清理。 -如果提供商需要完全自定义的线协议或自定义请求执行器，那属于另一类扩展。这些钩子适用于仍运行在 OpenClaw 常规推理循环上的提供商行为。 +如果提供商需要完全自定义的线协议或自定义请求执行器，那就是另一类扩展了。这些钩子适用于仍运行在 OpenClaw 常规推理循环上的提供商行为。 ### 提供商示例 @@ -257,29 +258,29 @@ api.registerProvider({ ### 内置示例 -内置提供商插件会组合使用上述钩子，以适配各个供应商在 catalog、凭证、思考、重放和使用量方面的需求。权威的钩子集合与各插件一起保存在 `extensions/` 下；本页用于说明其形态，而不是镜像列出完整清单。 +内置提供商插件会组合使用上述钩子，以适配各个厂商在目录、凭证、思考、重放和用量方面的需求。权威的钩子集合与各个 `extensions/` 下的插件放在一起；本页展示的是这些形态，而不是镜像列出完整清单。 - - OpenRouter、Kilocode、Z.AI、xAI 会注册 `catalog`，以及 `resolveDynamicModel` / `prepareDynamicModel`，这样它们就能在 OpenClaw 的静态 catalog 之前暴露上游模型 id。 + + OpenRouter、Kilocode、Z.AI、xAI 注册 `catalog` 以及 `resolveDynamicModel` / `prepareDynamicModel`，这样它们就能在 OpenClaw 的静态目录之前暴露上游模型 id。 - - GitHub Copilot、Gemini CLI、ChatGPT Codex、MiniMax、Xiaomi、z.ai 会将 `prepareRuntimeAuth` 或 `formatApiKey` 与 `resolveUsageAuth` + `fetchUsageSnapshot` 配对使用，以接管 token 交换和 `/usage` 集成。 + + GitHub Copilot、Gemini CLI、ChatGPT Codex、MiniMax、Xiaomi、z.ai 将 `prepareRuntimeAuth` 或 `formatApiKey` 与 `resolveUsageAuth` + `fetchUsageSnapshot` 配合使用，以接管令牌交换和 `/usage` 集成。 - 共享的命名族（`google-gemini`、`passthrough-gemini`、`anthropic-by-model`、`hybrid-anthropic-openai`）让提供商可以通过 `buildReplayPolicy` 选择加入转录策略，而不是让每个插件各自重新实现清理逻辑。 + 共享的命名族（`google-gemini`、`passthrough-gemini`、`anthropic-by-model`、`hybrid-anthropic-openai`）让提供商可以通过 `buildReplayPolicy` 选择转录策略，而不必让每个插件都重新实现清理逻辑。 - - `byteplus`、`cloudflare-ai-gateway`、`huggingface`、`kimi-coding`、`nvidia`、`qianfan`、`synthetic`、`together`、`venice`、`vercel-ai-gateway` 和 `volcengine` 只注册 `catalog`，并复用共享推理循环。 + + `byteplus`、`cloudflare-ai-gateway`、`huggingface`、`kimi-coding`、`nvidia`、`qianfan`、`synthetic`、`together`、`venice`、`vercel-ai-gateway` 和 `volcengine` 只注册 `catalog`，并使用共享推理循环。 - - Beta 请求头、`/fast` / `serviceTier` 以及 `context1m` 位于 Anthropic 插件公开的 `api.ts` / `contract-api.ts` 接缝中（`wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier`），而不是位于通用 SDK 中。 + + Beta 请求头、`/fast` / `serviceTier` 和 `context1m` 位于 Anthropic 插件公开的 `api.ts` / `contract-api.ts` 接口中（`wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier`），而不是放在通用 SDK 中。 -## 运行时辅助工具 +## 运行时辅助函数 -插件可以通过 `api.runtime` 访问选定的核心辅助工具。对于 TTS： +插件可以通过 `api.runtime` 访问选定的核心辅助函数。对于 TTS： ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -300,12 +301,12 @@ const voices = await api.runtime.tts.listVoices({ 说明： -- `textToSpeech` 返回文件 / 语音笔记表面使用的常规核心 TTS 输出负载。 +- `textToSpeech` 返回普通核心 TTS 输出负载，用于文件/语音消息表面。 - 使用核心 `messages.tts` 配置和提供商选择逻辑。 -- 返回 PCM 音频缓冲区 + 采样率。插件必须为提供商自行重采样 / 编码。 -- `listVoices` 对每个提供商来说都是可选的。可将其用于供应商自有的语音选择器或设置流程。 -- 语音列表可以包含更丰富的元数据，例如语言区域、性别和个性标签，以支持提供商感知的选择器。 -- 目前支持电话语音的有 OpenAI 和 ElevenLabs。Microsoft 不支持。 +- 返回 PCM 音频缓冲区 + 采样率。插件必须为提供商自行重采样/编码。 +- `listVoices` 对每个提供商来说是可选的。将其用于厂商自有语音选择器或设置流程。 +- 语音列表可以包含更丰富的元数据，例如区域设置、性别和个性标签，供感知提供商的选择器使用。 +- 目前 OpenAI 和 ElevenLabs 支持电话语音。Microsoft 不支持。 插件也可以通过 `api.registerSpeechProvider(...)` 注册语音提供商。 @@ -328,11 +329,11 @@ api.registerSpeechProvider({ 说明： - 将 TTS 策略、回退和回复投递保留在核心中。 -- 对供应商自有的合成行为使用语音提供商。 +- 使用语音提供商来承载厂商自有的合成行为。 - 旧版 Microsoft `edge` 输入会被规范化为 `microsoft` 提供商 id。 -- 首选的所有权模型是面向公司的：随着 OpenClaw 增加这些能力契约，一个供应商插件可以同时拥有文本、语音、图像以及未来的媒体提供商。 +- 推荐的所有权模型是面向公司的：随着 OpenClaw 增加这些能力契约，一个厂商插件可以拥有文本、语音、图像以及未来的媒体提供商。 -对于图像 / 音频 / 视频理解，插件会注册一个类型化的媒体理解提供商，而不是通用的键值包： +对于图像/音频/视频理解，插件会注册一个类型化的媒体理解提供商，而不是使用通用的键值包： ```ts api.registerMediaUnderstandingProvider({ @@ -347,14 +348,14 @@ api.registerMediaUnderstandingProvider({ 说明： - 将编排、回退、配置和渠道接线保留在核心中。 -- 将供应商行为保留在提供商插件中。 +- 将厂商行为保留在提供商插件中。 - 增量扩展应保持类型化：新的可选方法、新的可选结果字段、新的可选能力。 -- 视频生成已经遵循相同模式： - - 核心拥有能力契约和运行时辅助工具 - - 供应商插件注册 `api.registerVideoGenerationProvider(...)` - - 功能 / 渠道插件消费 `api.runtime.videoGeneration.*` +- 视频生成已经遵循同样的模式： + - 核心拥有能力契约和运行时辅助函数 + - 厂商插件注册 `api.registerVideoGenerationProvider(...)` + - 功能/渠道插件消费 `api.runtime.videoGeneration.*` -对于媒体理解运行时辅助工具，插件可以调用： +对于媒体理解运行时辅助函数，插件可以调用： ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -375,19 +376,19 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // 当无法可靠推断 MIME 时可选： + // Optional when MIME cannot be inferred reliably: mime: "audio/ogg", }); ``` 说明： -- `api.runtime.mediaUnderstanding.*` 是图像 / 音频 / 视频理解的首选共享表面。 +- `api.runtime.mediaUnderstanding.*` 是图像/音频/视频理解的首选共享表面。 - 使用核心媒体理解音频配置（`tools.media.audio`）和提供商回退顺序。 -- 当未产生转录输出时返回 `{ text: undefined }`（例如输入被跳过 / 不受支持）。 -- `api.runtime.stt.transcribeAudioFile(...)` 仍然保留作为兼容性别名。 +- 当未产生转录输出时（例如输入被跳过/不受支持），返回 `{ text: undefined }`。 +- `api.runtime.stt.transcribeAudioFile(...)` 仍保留为兼容性别名。 -插件也可以通过 `api.runtime.subagent` 启动后台子智能体运行： +插件还可以通过 `api.runtime.subagent` 启动后台子智能体运行： ```ts const result = await api.runtime.subagent.run({ @@ -401,13 +402,13 @@ const result = await api.runtime.subagent.run({ 说明： -- `provider` 和 `model` 是每次运行的可选覆盖项，不是持久化的会话更改。 -- OpenClaw 只会为受信任调用方应用这些覆盖字段。 -- 对于插件自有的回退运行，操作员必须通过 `plugins.entries..subagent.allowModelOverride: true` 明确启用。 -- 使用 `plugins.entries..subagent.allowedModels` 可将受信任插件限制为特定的规范 `provider/model` 目标，或设为 `"*"` 以明确允许任意目标。 -- 非受信任插件的子智能体运行仍然可用，但覆盖请求会被拒绝，而不是静默回退。 +- `provider` 和 `model` 是单次运行的可选覆盖项，不是持久性会话变更。 +- OpenClaw 只会对受信任调用方尊重这些覆盖字段。 +- 对于插件拥有的回退运行，运维人员必须通过 `plugins.entries..subagent.allowModelOverride: true` 显式启用。 +- 使用 `plugins.entries..subagent.allowedModels` 将受信任插件限制到特定的规范 `provider/model` 目标，或设为 `"*"` 以显式允许任意目标。 +- 不受信任的插件子智能体运行仍然可用，但覆盖请求会被拒绝，而不是静默回退。 -对于 Web 搜索，插件可以消费共享运行时辅助工具，而不是深入智能体工具接线： +对于 Web 搜索，插件可以消费共享运行时辅助函数，而不是深入智能体工具接线： ```ts const providers = api.runtime.webSearch.listProviders({ @@ -428,8 +429,8 @@ const result = await api.runtime.webSearch.search({ 说明： - 将提供商选择、凭证解析和共享请求语义保留在核心中。 -- 对供应商特定的搜索传输使用 Web 搜索提供商。 -- `api.runtime.webSearch.*` 是功能 / 渠道插件在不依赖智能体工具包装器的情况下需要搜索行为时的首选共享表面。 +- 使用 Web 搜索提供商来承载厂商特定的搜索传输。 +- `api.runtime.webSearch.*` 是功能/渠道插件在需要搜索行为但又不依赖智能体工具包装器时的首选共享表面。 ### `api.runtime.imageGeneration` @@ -467,151 +468,149 @@ api.registerHttpRoute({ 路由字段： - `path`：Gateway 网关 HTTP 服务器下的路由路径。 -- `auth`：必填。使用 `"gateway"` 以要求常规 Gateway 网关认证，或使用 `"plugin"` 进行插件管理的认证 / webhook 验证。 +- `auth`：必填。使用 `"gateway"` 以要求普通 Gateway 网关凭证，或使用 `"plugin"` 以启用插件管理的凭证/Webhook 验证。 - `match`：可选。`"exact"`（默认）或 `"prefix"`。 -- `replaceExisting`：可选。允许同一插件替换自己已存在的路由注册。 +- `replaceExisting`：可选。允许同一插件替换它自己已存在的路由注册。 - `handler`：当路由处理了请求时返回 `true`。 说明： -- `api.registerHttpHandler(...)` 已移除，并会导致插件加载错误。请改用 `api.registerHttpRoute(...)`。 +- `api.registerHttpHandler(...)` 已被移除，并会导致插件加载错误。请改用 `api.registerHttpRoute(...)`。 - 插件路由必须显式声明 `auth`。 -- 除非设置了 `replaceExisting: true`，否则精确的 `path + match` 冲突会被拒绝，而且一个插件不能替换另一个插件的路由。 -- 不同 `auth` 级别的重叠路由会被拒绝。请仅在相同认证级别内保持 `exact` / `prefix` 贯穿链。 -- `auth: "plugin"` 路由**不会**自动接收操作员运行时作用域。它们用于插件管理的 webhook / 签名验证，而不是特权 Gateway 网关辅助调用。 -- `auth: "gateway"` 路由会在 Gateway 网关请求运行时作用域内运行，但该作用域刻意保持保守： - - 共享密钥 bearer 认证（`gateway.auth.mode = "token"` / `"password"`）会将插件路由运行时作用域固定为 `operator.write`，即使调用方发送了 `x-openclaw-scopes` 也是如此 - - 受信任的、携带身份的 HTTP 模式（例如 `trusted-proxy`，或私有入口上的 `gateway.auth.mode = "none"`）仅在显式存在该请求头时才会采纳 `x-openclaw-scopes` - - 如果这些携带身份的插件路由请求中缺少 `x-openclaw-scopes`，运行时作用域会回退为 `operator.write` -- 实用规则：不要假设经过 Gateway 网关认证的插件路由就是隐式管理员表面。如果你的路由需要仅管理员可用的行为，请要求使用携带身份的认证模式，并记录显式的 `x-openclaw-scopes` 请求头契约。 +- 除非设置 `replaceExisting: true`，否则精确的 `path + match` 冲突会被拒绝，并且一个插件不能替换另一个插件的路由。 +- 不同 `auth` 级别的重叠路由会被拒绝。仅在相同凭证级别上保留 `exact`/`prefix` 贯穿链。 +- `auth: "plugin"` 路由**不会**自动获得运维人员运行时作用域。它们用于插件管理的 Webhook/签名验证，而不是特权 Gateway 网关辅助调用。 +- `auth: "gateway"` 路由会在 Gateway 网关请求运行时作用域内运行，但该作用域被有意设计得较为保守： + - 共享密钥 Bearer 凭证（`gateway.auth.mode = "token"` / `"password"`）会将插件路由运行时作用域固定为 `operator.write`，即使调用方发送了 `x-openclaw-scopes` + - 受信任的、携带身份的 HTTP 模式（例如 `trusted-proxy`，或私有入口上的 `gateway.auth.mode = "none"`）仅在显式提供该请求头时才会尊重 `x-openclaw-scopes` + - 如果这些携带身份的插件路由请求中不存在 `x-openclaw-scopes`，运行时作用域会回退为 `operator.write` +- 实际规则：不要假设一个经过 gateway 凭证保护的插件路由天然就是隐式管理表面。如果你的路由需要仅管理员可用的行为，请要求使用携带身份的凭证模式，并记录显式的 `x-openclaw-scopes` 请求头契约。 ## 插件 SDK 导入路径 -在编写新插件时，请使用狭窄的 SDK 子路径，而不是单体式的 `openclaw/plugin-sdk` 根 barrel。核心子路径： +在编写新插件时，请使用窄化的 SDK 子路径，而不是单体的 `openclaw/plugin-sdk` 根 barrel。核心子路径包括： | 子路径 | 用途 | | ----------------------------------- | -------------------------------------------------- | -| `openclaw/plugin-sdk/plugin-entry` | 插件注册原语 | -| `openclaw/plugin-sdk/channel-core` | 渠道入口 / 构建辅助工具 | -| `openclaw/plugin-sdk/core` | 通用共享辅助工具和总括契约 | -| `openclaw/plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema（`OpenClawSchema`） | +| `openclaw/plugin-sdk/plugin-entry` | 插件注册基础能力 | +| `openclaw/plugin-sdk/channel-core` | 渠道入口/构建辅助函数 | +| `openclaw/plugin-sdk/core` | 通用共享辅助函数和总括契约 | +| `openclaw/plugin-sdk/config-schema` | 根 `openclaw.json` Zod 架构（`OpenClawSchema`） | -渠道插件应从一组狭窄接缝中进行选择 —— `channel-setup`、`setup-runtime`、`setup-adapter-runtime`、`setup-tools`、`channel-pairing`、`channel-contract`、`channel-feedback`、`channel-inbound`、`channel-lifecycle`、`channel-reply-pipeline`、`command-auth`、`secret-input`、`webhook-ingress`、`channel-targets` 和 `channel-actions`。审批行为应统一到单一的 `approvalCapability` 契约上，而不是分散混用在不相关的插件字段中。参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。 +渠道插件可以从一组窄化接口中选择——`channel-setup`、`setup-runtime`、`setup-adapter-runtime`、`setup-tools`、`channel-pairing`、`channel-contract`、`channel-feedback`、`channel-inbound`、`channel-lifecycle`、`channel-reply-pipeline`、`command-auth`、`secret-input`、`webhook-ingress`、`channel-targets` 和 `channel-actions`。批准行为应统一到单一的 `approvalCapability` 契约上，而不是分散在无关的插件字段之间。参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。 -运行时和配置辅助工具位于对应的 `*-runtime` 子路径下（`approval-runtime`、`config-runtime`、`infra-runtime`、`agent-runtime`、`lazy-runtime`、`directory-runtime`、`text-runtime`、`runtime-store` 等）。 +运行时和配置辅助函数位于匹配的 `*-runtime` 子路径下（`approval-runtime`、`config-runtime`、`infra-runtime`、`agent-runtime`、`lazy-runtime`、`directory-runtime`、`text-runtime`、`runtime-store` 等）。 -`openclaw/plugin-sdk/channel-runtime` 已弃用 —— 它只是面向旧插件的兼容性 shim。新代码应改为导入更狭窄的通用原语。 +`openclaw/plugin-sdk/channel-runtime` 已弃用——它是为旧插件保留的兼容性垫片。新代码应改为导入更窄化的通用基础能力。 -仓库内部入口点（按每个内置插件包根目录划分）： +仓库内部入口点（每个内置插件包根目录）： -- `index.js` —— 内置插件入口 -- `api.js` —— 辅助工具 / 类型 barrel -- `runtime-api.js` —— 仅运行时 barrel -- `setup-entry.js` —— 设置插件入口 +- `index.js` — 内置插件入口 +- `api.js` — 辅助函数/类型 barrel +- `runtime-api.js` — 仅运行时 barrel +- `setup-entry.js` — 设置插件入口 -外部插件应只导入 `openclaw/plugin-sdk/*` 子路径。绝不要从核心或另一个插件中导入其他插件包的 `src/*`。 -通过 facade 加载的入口点会优先使用当前活动的运行时配置快照；如果不存在，再回退到磁盘上的已解析配置文件。 +外部插件应只导入 `openclaw/plugin-sdk/*` 子路径。绝不要从核心或另一个插件中导入其他插件包的 `src/*`。由 facade 加载的入口点在存在活动运行时配置快照时会优先使用它，否则回退到磁盘上的已解析配置文件。 -像 `image-generation`、`media-understanding` 和 `speech` 这样的能力专用子路径之所以存在，是因为内置插件目前正在使用它们。它们并不自动构成长期冻结的外部契约 —— 在依赖它们时，请查阅对应的 SDK 参考页面。 +像 `image-generation`、`media-understanding` 和 `speech` 这样的能力专用子路径之所以存在，是因为内置插件当前在使用它们。它们并不自动成为长期冻结的外部契约——在依赖它们时，请查阅相应的 SDK 参考页。 -## 消息工具 schema +## 消息工具架构 -对于 reaction、已读和投票这类非消息原语，插件应自行提供特定于渠道的 `describeMessageTool(...)` schema 贡献。共享发送呈现应使用通用的 `MessagePresentation` 契约，而不是提供商原生的按钮、组件、块或卡片字段。关于契约、回退规则、提供商映射以及插件作者检查清单，请参见 [Message Presentation](/zh-CN/plugins/message-presentation)。 +对于反应、已读和投票这类非消息原语，插件应拥有各自渠道专用的 `describeMessageTool(...)` 架构贡献。共享发送展示应使用通用 `MessagePresentation` 契约，而不是提供商原生的按钮、组件、块或卡片字段。有关契约、回退规则、提供商映射和插件作者检查清单，请参见 [Message Presentation](/zh-CN/plugins/message-presentation)。 -具备发送能力的插件通过消息能力声明自己可以渲染的内容： +具备发送能力的插件通过消息能力声明它们可以渲染的内容： -- `presentation`：用于语义化呈现块（`text`、`context`、`divider`、`buttons`、`select`） -- `delivery-pin`：用于置顶投递请求 +- `presentation` 用于语义化展示块（`text`、`context`、`divider`、`buttons`、`select`） +- `delivery-pin` 用于固定投递请求 -核心决定是原生渲染该 presentation，还是将其降级为文本。不要从通用消息工具中暴露提供商原生 UI 逃生口。 -面向旧原生 schema 的已弃用 SDK 辅助工具仍会为现有第三方插件导出，但新插件不应使用它们。 +核心负责决定是原生渲染该展示，还是将其降级为文本。不要从通用消息工具中暴露提供商原生 UI 的逃逸接口。面向旧版原生架构的已弃用 SDK 辅助函数仍然会为现有第三方插件导出，但新插件不应使用它们。 ## 渠道目标解析 -渠道插件应拥有特定于渠道的目标语义。保持共享出站宿主通用，并通过消息适配器表面处理提供商规则： +渠道插件应拥有渠道专用的目标语义。保持共享出站主机的通用性，并使用消息适配器表面来承载提供商规则： -- `messaging.inferTargetChatType({ to })` 用于在目录查找前判断规范化目标应被视为 `direct`、`group` 还是 `channel`。 -- `messaging.targetResolver.looksLikeId(raw, normalized)` 用于告知核心，某个输入是否应跳过目录搜索，直接进入类似 id 的解析。 -- `messaging.targetResolver.resolveTarget(...)` 是插件的回退路径，当核心在规范化之后或目录未命中之后需要最终的提供商自有解析时使用。 -- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后负责构建特定于提供商的会话路由。 +- `messaging.inferTargetChatType({ to })` 决定规范化目标在目录查找前应被视为 `direct`、`group` 还是 `channel` +- `messaging.targetResolver.looksLikeId(raw, normalized)` 告诉核心某个输入是否应直接跳到类似 id 的解析，而不是进行目录搜索 +- `messaging.targetResolver.resolveTarget(...)` 是插件回退路径，当核心在规范化之后或目录未命中之后需要最终由提供商拥有的解析结果时使用 +- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后负责构建提供商专用的会话路由 推荐拆分方式： -- 对于应在搜索联系人 / 群组之前发生的类别判定，使用 `inferTargetChatType`。 -- 对于“把这个视为显式 / 原生目标 id”的检查，使用 `looksLikeId`。 -- 对于提供商特定的规范化回退，使用 `resolveTarget`，而不是用它做宽泛的目录搜索。 -- 将 chat id、thread id、JID、handle 和 room id 这类提供商原生 id 保留在 `target` 值或提供商专用参数中，而不是放入通用 SDK 字段。 +- 对于应在搜索联系人/群组之前发生的分类决策，使用 `inferTargetChatType` +- 对于“将其视为显式/原生目标 id”的判断，使用 `looksLikeId` +- 将 `resolveTarget` 用于提供商专用的规范化回退，而不是广泛的目录搜索 +- 将 chat id、thread id、JID、handle 和 room id 这类提供商原生 id 保留在 `target` 值或提供商专用参数中，而不是放进通用 SDK 字段中 ## 基于配置的目录 -对于从配置派生目录项的插件，应将该逻辑保留在插件内部，并复用 `openclaw/plugin-sdk/directory-runtime` 中的共享辅助工具。 +对于从配置派生目录条目的插件，应将该逻辑保留在插件内，并复用 `openclaw/plugin-sdk/directory-runtime` 中的共享辅助函数。 -适用于以下这类渠道需要基于配置的联系人 / 群组时： +当渠道需要基于配置的联系人/群组时，请使用这一方式，例如： - 基于 allowlist 的私信联系人 -- 已配置的渠道 / 群组映射 -- 按账号作用域的静态目录回退 +- 已配置的渠道/群组映射 +- 基于账号作用域的静态目录回退 -`directory-runtime` 中的共享辅助工具只处理通用操作： +`directory-runtime` 中的共享辅助函数只处理通用操作： - 查询过滤 -- 限制数量应用 -- 去重 / 规范化辅助工具 +- 限制应用 +- 去重/规范化辅助函数 - 构建 `ChannelDirectoryEntry[]` -特定于渠道的账号检查和 id 规范化应保留在插件实现中。 +渠道专用的账号检查和 id 规范化应保留在插件实现中。 -## 提供商 catalog +## 提供商目录 -提供商插件可以通过 `registerProvider({ catalog: { run(...) { ... } } })` 为推理定义模型 catalog。 +提供商插件可以通过 `registerProvider({ catalog: { run(...) { ... } } })` 为推理定义模型目录。 -`catalog.run(...)` 返回的形态与 OpenClaw 写入 `models.providers` 的内容相同： +`catalog.run(...)` 返回与 OpenClaw 写入 `models.providers` 相同的结构： -- `{ provider }`：单个提供商条目 -- `{ providers }`：多个提供商条目 +- `{ provider }` 表示一个提供商条目 +- `{ providers }` 表示多个提供商条目 -当插件拥有特定于提供商的模型 id、base URL 默认值或受凭证控制的模型元数据时，请使用 `catalog`。 +当插件拥有提供商专用模型 id、基础 URL 默认值或受凭证控制的模型元数据时，请使用 `catalog`。 -`catalog.order` 用于控制插件的 catalog 相对于 OpenClaw 内置隐式提供商的合并时机： +`catalog.order` 控制插件目录相对于 OpenClaw 内置隐式提供商的合并时机： -- `simple`：普通 API 密钥或环境变量驱动的提供商 -- `profile`：当存在凭证配置文件时出现的提供商 +- `simple`：普通 API 密钥或基于环境变量的提供商 +- `profile`：存在凭证配置文件时出现的提供商 - `paired`：合成多个相关提供商条目的提供商 - `late`：最后一轮，在其他隐式提供商之后 -在键冲突时，后出现的提供商会胜出，因此插件可以有意使用相同的提供商 id 覆盖某个内置提供商条目。 +在键冲突时，后面的提供商会获胜，因此插件可以有意用相同提供商 id 覆盖内置提供商条目。 兼容性： -- `discovery` 仍然作为旧别名可用 +- `discovery` 仍然可作为旧别名使用 - 如果同时注册了 `catalog` 和 `discovery`，OpenClaw 会使用 `catalog` ## 只读渠道检查 -如果你的插件注册了一个渠道，请优先实现 `plugin.config.inspectAccount(cfg, accountId)`，并与 `resolveAccount(...)` 配套使用。 +如果你的插件注册了一个渠道，除了 `resolveAccount(...)` 之外，优先同时实现 `plugin.config.inspectAccount(cfg, accountId)`。 原因： -- `resolveAccount(...)` 是运行时路径。它可以假定凭证已被完整物化，并且当缺少必需 secret 时可以快速失败。 -- 只读命令路径，例如 `openclaw status`、`openclaw status --all`、`openclaw channels status`、`openclaw channels resolve` 以及 doctor / config 修复流程，不应仅仅为了描述配置就去物化运行时凭证。 +- `resolveAccount(...)` 是运行时路径。它可以假定凭证已经完全具体化，并且在缺少必要密钥时快速失败。 +- 像 `openclaw status`、`openclaw status --all`、`openclaw channels status`、`openclaw channels resolve` 以及 doctor/配置修复流程这样的只读命令路径，不应仅为了描述配置就必须具体化运行时凭证。 推荐的 `inspectAccount(...)` 行为： - 只返回描述性的账号状态。 - 保留 `enabled` 和 `configured`。 -- 在相关时包含凭证来源 / 状态字段，例如： +- 在相关时包含凭证来源/状态字段，例如： - `tokenSource`、`tokenStatus` - `botTokenSource`、`botTokenStatus` - `appTokenSource`、`appTokenStatus` - `signingSecretSource`、`signingSecretStatus` -- 仅为了报告只读可用性，并不需要返回原始 token 值。返回 `tokenStatus: "available"`（以及对应的来源字段）就足以支持状态类命令。 +- 你不需要为了报告只读可用性而返回原始令牌值。返回 `tokenStatus: "available"`（以及对应的来源字段）就足以支持状态类命令。 - 当凭证通过 SecretRef 配置但在当前命令路径中不可用时，请使用 `configured_unavailable`。 -这样，只读命令就可以报告“已配置，但在当前命令路径中不可用”，而不是崩溃或误报该账号未配置。 +这样只读命令就可以报告“已配置但在当前命令路径中不可用”，而不是崩溃或错误地将账号报告为未配置。 -## 软件包打包集 +## 包打包功能 插件目录可以包含一个带有 `openclaw.extensions` 的 `package.json`： @@ -625,37 +624,37 @@ api.registerHttpRoute({ } ``` -每个条目都会变成一个插件。如果该打包集列出多个扩展，插件 id 会变成 `name/`。 +每个条目都会变成一个插件。如果该打包列出了多个扩展，插件 id 会变为 `name/`。 如果你的插件导入了 npm 依赖，请在该目录中安装它们，以便 `node_modules` 可用（`npm install` / `pnpm install`）。 -安全护栏：每个 `openclaw.extensions` 条目在解析符号链接后都必须仍然位于插件目录内。逃逸出包目录的条目会被拒绝。 +安全护栏：每个 `openclaw.extensions` 条目在解析符号链接后都必须保持在插件目录内。逃逸出包目录的条目会被拒绝。 -安全说明：`openclaw plugins install` 会使用 `npm install --omit=dev --ignore-scripts` 安装插件依赖（不运行生命周期脚本，运行时不安装开发依赖）。请保持插件依赖树为“纯 JS / TS”，并避免需要 `postinstall` 构建的包。 +安全说明：`openclaw plugins install` 会使用 `npm install --omit=dev --ignore-scripts` 安装插件依赖（无生命周期脚本，运行时不安装开发依赖）。请保持插件依赖树为“纯 JS/TS”，并避免需要 `postinstall` 构建的包。 -可选：`openclaw.setupEntry` 可以指向一个轻量级的仅设置模块。当 OpenClaw 需要为一个已禁用的渠道插件提供设置表面，或者当某个渠道插件已启用但尚未配置时，它会加载 `setupEntry`，而不是完整插件入口。这样在主插件入口还会接线工具、钩子或其他仅运行时代码时，可以让启动和设置更轻量。 +可选：`openclaw.setupEntry` 可以指向一个轻量级、仅用于设置的模块。当 OpenClaw 需要为已禁用的渠道插件提供设置表面时，或者当渠道插件已启用但尚未配置时，它会加载 `setupEntry` 而不是完整插件入口。这样在你的主插件入口还会接入工具、钩子或其他仅运行时代码时，可以让启动和设置更轻量。 -可选：`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` 可以让一个渠道插件在 Gateway 网关 pre-listen 启动阶段也选择使用相同的 `setupEntry` 路径，即使该渠道已经配置完成。 +可选：`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` 可以让渠道插件在 Gateway 网关的监听前启动阶段，即使渠道已经配置好，也选择同样的 `setupEntry` 路径。 -仅当 `setupEntry` 完整覆盖 Gateway 网关开始监听之前必须存在的启动表面时，才应使用此选项。实际而言，这意味着设置入口必须注册启动所依赖的每一项渠道自有能力，例如： +仅当 `setupEntry` 完全覆盖 Gateway 网关开始监听之前必须存在的启动表面时，才应使用它。实际中，这意味着设置入口必须注册启动所依赖的每一项由渠道拥有的能力，例如： - 渠道注册本身 -- 任何必须在 Gateway 网关开始监听前可用的 HTTP 路由 -- 任何必须在同一时间窗口内存在的 Gateway 网关方法、工具或服务 +- 任何必须在 Gateway 网关开始监听之前可用的 HTTP 路由 +- 在同一时间窗口内必须存在的任何 Gateway 网关方法、工具或服务 -如果你的完整入口仍拥有任何必需的启动能力，就不要启用这个标志。请保持插件采用默认行为，让 OpenClaw 在启动期间加载完整入口。 +如果你的完整入口仍然拥有任何必需的启动能力，请不要启用此标志。保持插件的默认行为，让 OpenClaw 在启动期间加载完整入口。 -内置渠道还可以发布仅设置期的契约表面辅助工具，供核心在完整渠道运行时加载前查询。当前的设置提升表面包括： +内置渠道还可以发布仅设置阶段使用的契约表面辅助函数，供核心在完整渠道运行时加载之前查询。当前的设置提升表面包括： - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -当核心需要在不加载完整插件入口的情况下，将旧版单账号渠道配置提升到 `channels..accounts.*` 时，就会使用这组表面。Matrix 是当前的内置示例：当已存在命名账号时，它只会把凭证 / bootstrap 键移动到某个已命名的提升账号中，并且它能够保留一个已配置的非规范 default-account 键，而不是总是创建 `accounts.default`。 +当核心需要在不加载完整插件入口的情况下，将旧版单账号渠道配置提升到 `channels..accounts.*` 时，会使用这个表面。Matrix 是当前的内置示例：当命名账号已经存在时，它只会把凭证/引导键移动到一个已命名的提升账号中，并且它可以保留已配置的非规范默认账号键，而不是总是创建 `accounts.default`。 -这些设置补丁适配器让内置契约表面发现保持惰性。导入时开销保持很轻；提升表面只会在首次使用时加载，而不是在模块导入时重新进入内置渠道启动过程。 +这些设置补丁适配器会让内置契约表面发现保持惰性。导入时间保持轻量；提升表面只会在首次使用时加载，而不是在模块导入时重新进入内置渠道启动流程。 -当这些启动表面包含 Gateway 网关 RPC 方法时，请将它们保持在插件专用前缀下。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍然是保留的，并且始终解析为 `operator.admin`，即使某个插件请求了更窄的作用域也是如此。 +当这些启动表面包含 Gateway 网关 RPC 方法时，请将它们保留在插件专用前缀下。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍然保留，并且始终解析为 `operator.admin`，即使插件请求了更窄的作用域。 示例： @@ -672,9 +671,9 @@ api.registerHttpRoute({ } ``` -### 渠道 catalog 元数据 +### 渠道目录元数据 -渠道插件可以通过 `openclaw.channel` 公布设置 / 发现元数据，并通过 `openclaw.install` 公布安装提示。这样可以让核心 catalog 保持无数据。 +渠道插件可以通过 `openclaw.channel` 宣告设置/发现元数据，并通过 `openclaw.install` 宣告安装提示。这样可以让核心目录保持无数据状态。 示例： @@ -686,10 +685,10 @@ api.registerHttpRoute({ "channel": { "id": "nextcloud-talk", "label": "Nextcloud Talk", - "selectionLabel": "Nextcloud Talk（自托管）", + "selectionLabel": "Nextcloud Talk（self-hosted）", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "通过 Nextcloud Talk webhook 机器人实现的自托管聊天。", + "blurb": "通过 Nextcloud Talk webhook 机器人实现自托管聊天。", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -702,34 +701,34 @@ api.registerHttpRoute({ } ``` -除了最小示例之外，还有一些有用的 `openclaw.channel` 字段： +除了最小示例外，有用的 `openclaw.channel` 字段还包括： -- `detailLabel`：用于更丰富的 catalog / 状态表面的次级标签 +- `detailLabel`：用于更丰富目录/状态表面的次级标签 - `docsLabel`：覆盖文档链接的链接文本 -- `preferOver`：该 catalog 条目应优先于的较低优先级插件 / 渠道 id +- `preferOver`：该目录条目应优先于的低优先级插件/渠道 id - `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`：选择表面文案控制 -- `markdownCapable`：将该渠道标记为支持 Markdown，以供出站格式化决策使用 -- `exposure.configured`：设置为 `false` 时，在已配置渠道列表表面中隐藏该渠道 -- `exposure.setup`：设置为 `false` 时，在交互式设置 / 配置选择器中隐藏该渠道 -- `exposure.docs`：将该渠道标记为内部 / 私有，以供文档导航表面使用 -- `showConfigured` / `showInSetup`：出于兼容性仍接受的旧别名；优先使用 `exposure` -- `quickstartAllowFrom`：让该渠道接入标准快速开始 `allowFrom` 流程 +- `markdownCapable`：将该渠道标记为支持 Markdown，以用于出站格式决策 +- `exposure.configured`：当设置为 `false` 时，在已配置渠道列表表面中隐藏该渠道 +- `exposure.setup`：当设置为 `false` 时，在交互式设置/配置选择器中隐藏该渠道 +- `exposure.docs`：将该渠道标记为内部/私有，以用于文档导航表面 +- `showConfigured` / `showInSetup`：为兼容性仍接受的旧别名；优先使用 `exposure` +- `quickstartAllowFrom`：让该渠道加入标准快速开始 `allowFrom` 流程 - `forceAccountBinding`：即使只存在一个账号，也要求显式账号绑定 -- `preferSessionLookupForAnnounceTarget`：在解析公告目标时优先进行会话查找 +- `preferSessionLookupForAnnounceTarget`：在解析公告目标时优先使用会话查找 -OpenClaw 还可以合并**外部渠道 catalog**（例如 MPM 注册表导出）。将 JSON 文件放到以下任一位置： +OpenClaw 还可以合并**外部渠道目录**（例如 MPM 注册表导出）。将 JSON 文件放在以下任一位置： - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` -或者将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向一个或多个 JSON 文件（以逗号 / 分号 / `PATH` 分隔）。每个文件应包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器还接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的旧别名。 +或者将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向一个或多个 JSON 文件（使用逗号/分号/`PATH` 分隔）。每个文件应包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器也接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的旧别名。 ## 上下文引擎插件 -上下文引擎插件负责会话上下文编排，包括摄取、组装和压缩。通过 `api.registerContextEngine(id, factory)` 从你的插件中注册它们，然后通过 `plugins.slots.contextEngine` 选择活动引擎。 +上下文引擎插件负责会话上下文编排，包括摄取、组装和压缩。通过 `api.registerContextEngine(id, factory)` 从你的插件中注册它们，然后使用 `plugins.slots.contextEngine` 选择活动引擎。 -当你的插件需要替换或扩展默认上下文管线，而不仅仅是添加内存搜索或钩子时，请使用此机制。 +当你的插件需要替换或扩展默认上下文流水线，而不只是添加内存搜索或钩子时，请使用这个方式。 ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -794,51 +793,51 @@ export default function (api) { ## 添加新的能力 -当插件需要当前 API 无法容纳的行为时，不要通过私有深度访问绕过插件系统。请添加缺失的能力。 +当插件需要当前 API 无法适配的行为时，不要通过私有深入访问绕过插件系统。应添加缺失的能力。 推荐顺序： 1. 定义核心契约 - 决定哪些共享行为应由核心拥有：策略、回退、配置合并、生命周期、面向渠道的语义，以及运行时辅助工具形态。 -2. 添加类型化的插件注册 / 运行时表面 - 用最小但有用的类型化能力表面扩展 `OpenClawPluginApi` 和 / 或 `api.runtime`。 -3. 接入核心 + 渠道 / 功能使用方 - 渠道和功能插件应通过核心消费这个新能力，而不是直接导入某个供应商实现。 -4. 注册供应商实现 - 然后由供应商插件针对该能力注册它们的后端实现。 + 确定哪些共享行为应由核心负责：策略、回退、配置合并、生命周期、面向渠道的语义以及运行时辅助函数形态。 +2. 添加类型化的插件注册/运行时表面 + 使用最小但有用的类型化能力表面扩展 `OpenClawPluginApi` 和/或 `api.runtime`。 +3. 连接核心 + 渠道/功能使用方 + 渠道和功能插件应通过核心消费新能力，而不是直接导入某个厂商实现。 +4. 注册厂商实现 + 然后由厂商插件针对该能力注册它们的后端。 5. 添加契约覆盖 - 添加测试，使所有权和注册形态在长期演进中保持明确。 + 添加测试，以便随着时间推移，所有权和注册形态仍然保持明确。 -这正是 OpenClaw 在保持鲜明立场的同时，不会被硬编码到某个提供商世界观中的方式。关于具体文件检查清单和完整示例，请参见 [能力扩展手册](/zh-CN/plugins/architecture)。 +这就是 OpenClaw 在保持鲜明立场的同时，不会被硬编码到某个提供商世界观中的方式。有关具体文件清单和完整示例，请参见[能力扩展手册](/zh-CN/plugins/architecture)。 ### 能力检查清单 -当你添加一个新能力时，实现通常应同时涉及以下表面： +当你添加一个新能力时，通常实现应同时涉及这些表面： - `src//types.ts` 中的核心契约类型 -- `src//runtime.ts` 中的核心 runner / 运行时辅助工具 +- `src//runtime.ts` 中的核心运行器/运行时辅助函数 - `src/plugins/types.ts` 中的插件 API 注册表面 - `src/plugins/registry.ts` 中的插件注册表接线 -- 当功能 / 渠道插件需要消费它时，位于 `src/plugins/runtime/*` 中的插件运行时暴露 -- `src/test-utils/plugin-registration.ts` 中的捕获 / 测试辅助工具 -- `src/plugins/contracts/registry.ts` 中的所有权 / 契约断言 -- `docs/` 中面向操作员 / 插件的文档 +- 当功能/渠道插件需要消费它时，位于 `src/plugins/runtime/*` 中的插件运行时暴露 +- `src/test-utils/plugin-registration.ts` 中的捕获/测试辅助函数 +- `src/plugins/contracts/registry.ts` 中的所有权/契约断言 +- `docs/` 中的运维人员/插件文档 -如果这些表面中有某一项缺失，通常就说明该能力尚未完全集成。 +如果这些表面中缺少某一个，通常说明该能力尚未完全集成。 ### 能力模板 最小模式： ```ts -// 核心契约 +// core contract export type VideoGenerationProviderPlugin = { id: string; label: string; generateVideo: (req: VideoGenerationRequest) => Promise; }; -// 插件 API +// plugin API api.registerVideoGenerationProvider({ id: "openai", label: "OpenAI", @@ -847,7 +846,7 @@ api.registerVideoGenerationProvider({ }, }); -// 面向功能 / 渠道插件的共享运行时辅助工具 +// shared runtime helper for feature/channel plugins const clip = await api.runtime.videoGeneration.generate({ prompt: "Show the robot walking through the lab.", cfg, @@ -863,13 +862,13 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); 这样规则就很简单： - 核心拥有能力契约 + 编排 -- 供应商插件拥有供应商实现 -- 功能 / 渠道插件消费运行时辅助工具 -- 契约测试让所有权保持明确 +- 厂商插件拥有厂商实现 +- 功能/渠道插件消费运行时辅助函数 +- 契约测试使所有权保持明确 ## 相关内容 -- [插件架构](/zh-CN/plugins/architecture) —— 公开能力模型和形态 +- [插件架构](/zh-CN/plugins/architecture) — 公开能力模型和形态 - [插件 SDK 子路径](/zh-CN/plugins/sdk-subpaths) - [插件 SDK 设置](/zh-CN/plugins/sdk-setup) - [构建插件](/zh-CN/plugins/building-plugins) diff --git a/docs/zh-CN/plugins/architecture.md b/docs/zh-CN/plugins/architecture.md index 943a0f2c6..682909045 100644 --- a/docs/zh-CN/plugins/architecture.md +++ b/docs/zh-CN/plugins/architecture.md @@ -2,28 +2,28 @@ read_when: - 构建或调试原生 OpenClaw 插件 - 理解插件能力模型或归属边界 - - 开发插件加载流水线或注册表 + - 处理插件加载流水线或注册表 - 实现提供商运行时钩子或渠道插件 sidebarTitle: Internals summary: 插件内部机制：能力模型、归属、契约、加载流水线和运行时辅助工具 title: 插件内部机制 x-i18n: - generated_at: "2026-04-24T03:42:04Z" + generated_at: "2026-04-24T05:09:38Z" model: gpt-5.4 provider: openai - source_hash: 4506472486e09f33a2e87f0a3c38191a9817d1f36fcdd7dd4f57f0a8453e9b4f + source_hash: 344c02f9f0bb19780d262929e665fcaf8093ac08cda30b61af56857368b0b07a source_path: plugins/architecture.md workflow: 15 --- -这是 OpenClaw 插件系统的**深度架构参考**。如需实践指南，请先从下方的专题页面开始。 +这是 OpenClaw 插件系统的**深度架构参考**。如需实用指南，请先从下面的专题页面之一开始。 - 面向最终用户的指南，介绍如何添加、启用和排查插件。 + 面向终端用户的指南，介绍如何添加、启用和排查插件问题。 - 首个插件教程，包含最小可工作的 manifest。 + 以最小可用清单为起点的首个插件教程。 构建一个消息渠道插件。 @@ -32,125 +32,136 @@ x-i18n: 构建一个模型提供商插件。 - import map 和注册 API 参考。 + 导入映射和注册 API 参考。 -## 公共能力模型 +## 公开能力模型 -能力是 OpenClaw 中公共的**原生插件**模型。每个原生 OpenClaw 插件都会针对一个或多个能力类型进行注册： +能力是 OpenClaw 内部公开的**原生插件**模型。每个原生 OpenClaw 插件都会针对一种或多种能力类型进行注册： -| 能力 | 注册方法 | 示例插件 | -| ---------------------- | ---------------------------------------------- | ------------------------------------ | -| 文本推理 | `api.registerProvider(...)` | `openai`、`anthropic` | -| CLI 推理后端 | `api.registerCliBackend(...)` | `openai`、`anthropic` | -| 语音 | `api.registerSpeechProvider(...)` | `elevenlabs`、`microsoft` | -| 实时转写 | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | `openai`、`google` | -| 图像生成 | `api.registerImageGenerationProvider(...)` | `openai`、`google`、`fal`、`minimax` | -| 音乐生成 | `api.registerMusicGenerationProvider(...)` | `google`、`minimax` | -| 视频生成 | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Web 抓取 | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Web 搜索 | `api.registerWebSearchProvider(...)` | `google` | -| 渠道 / 消息 | `api.registerChannel(...)` | `msteams`、`matrix` | +| 能力 | 注册方法 | 示例插件 | +| ---------------------- | ------------------------------------------------ | ------------------------------------ | +| 文本推理 | `api.registerProvider(...)` | `openai`, `anthropic` | +| CLI 推理后端 | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| 语音 | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| 实时转录 | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| 图像生成 | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| 音乐生成 | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| 视频生成 | `api.registerVideoGenerationProvider(...)` | `qwen` | +| 网页抓取 | `api.registerWebFetchProvider(...)` | `firecrawl` | +| 网页搜索 | `api.registerWebSearchProvider(...)` | `google` | +| 渠道 / 消息 | `api.registerChannel(...)` | `msteams`, `matrix` | -一个注册了零个能力、但提供 hooks、工具或服务的插件是**旧版仅 hook** 插件。这种模式仍然被完全支持。 +注册零个能力，但提供 hooks、工具或服务的插件，属于**仅 legacy hook** 插件。这种模式目前仍被完全支持。 -### 外部兼容性立场 +### 对外兼容性立场 -能力模型已经落地到 core，并且当前已被内置 / 原生插件使用，但外部插件兼容性仍然需要比“已导出，因此已冻结”更严格的标准。 +能力模型已经在核心中落地，并已被当前的内置 / 原生插件使用，但外部插件兼容性仍需要比“已导出，因此已冻结”更严格的标准。 -| 插件情况 | 指导原则 | -| ------------------------------------------- | ---------------------------------------------------------------------------------------------- | -| 现有外部插件 | 保持基于 hook 的集成正常工作；这是兼容性基线。 | -| 新的内置 / 原生插件 | 优先选择显式能力注册，而不是供应商特定的深入访问或新的仅 hook 设计。 | -| 采用能力注册的外部插件 | 允许，但除非文档将其标记为稳定，否则应将能力专用的辅助 surface 视为持续演进中。 | +| 插件情况 | 指南 | +| ------------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| 现有外部插件 | 保持基于 hook 的集成可用；这是兼容性的基线。 | +| 新的内置 / 原生插件 | 优先使用显式能力注册，而不是特定厂商的内部访问方式或新的仅 hook 设计。 | +| 采用能力注册的外部插件 | 允许，但除非文档将其标记为稳定，否则应将特定能力的辅助接口视为仍在演进中。 | -能力注册是预期的发展方向。在过渡期间，对于外部插件而言，旧版 hook 仍然是最安全、最不容易破坏兼容性的路径。已导出的辅助子路径并不都具有同等稳定性——应优先选择范围狭窄、文档化的契约，而不是偶然导出的辅助接口。 +能力注册是预期的发展方向。在过渡期间，对于外部插件来说，legacy hooks 仍然是最安全、最不容易破坏兼容性的路径。导出的辅助子路径并不完全等价——优先使用范围明确、已有文档说明的契约，而不是偶然暴露出来的辅助导出。 ### 插件形态 -OpenClaw 会根据每个已加载插件的实际注册行为（而不仅仅是静态元数据）将其分类为以下形态之一： +OpenClaw 会根据每个已加载插件的实际注册行为来分类其形态（而不只是依据静态元数据）： -- **plain-capability**：只注册一种能力类型（例如仅提供商插件 `mistral`）。 +- **plain-capability**：只注册恰好一种能力类型（例如像 `mistral` 这样的仅提供商插件）。 - **hybrid-capability**：注册多种能力类型（例如 `openai` 同时拥有文本推理、语音、媒体理解和图像生成）。 -- **hook-only**：仅注册 hooks（类型化或自定义），不注册任何能力、工具、命令或服务。 +- **hook-only**：只注册 hooks（类型化或自定义），不注册能力、工具、命令或服务。 - **non-capability**：注册工具、命令、服务或路由，但不注册能力。 -使用 `openclaw plugins inspect ` 可查看某个插件的形态和能力拆分。详情参见 [CLI 参考](/zh-CN/cli/plugins#inspect)。 +使用 `openclaw plugins inspect ` 可查看插件的形态和能力明细。详见 [CLI 参考](/zh-CN/cli/plugins#inspect)。 -### 旧版 hooks +### Legacy hooks -`before_agent_start` hook 仍作为仅 hook 插件的兼容路径被支持。现实中的旧版插件仍然依赖它。 +`before_agent_start` hook 仍然作为仅 hook 插件的兼容路径受到支持。现实中的 legacy 插件仍然依赖它。 -方向是： +方向如下： - 保持其可用 -- 将其文档标记为旧版 -- 对于模型 / 提供商覆盖工作，优先使用 `before_model_resolve` -- 对于 prompt 变更工作，优先使用 `before_prompt_build` -- 只有在真实使用量下降且 fixture 覆盖证明迁移安全之后才移除 +- 在文档中标记为 legacy +- 对于模型 / 提供商覆写工作，优先使用 `before_model_resolve` +- 对于提示词修改工作，优先使用 `before_prompt_build` +- 仅在真实使用量下降且 fixture 覆盖证明迁移安全后再移除 ### 兼容性信号 -运行 `openclaw doctor` 或 `openclaw plugins inspect ` 时，你可能会看到以下标签之一： +当你运行 `openclaw doctor` 或 `openclaw plugins inspect ` 时，可能会看到以下标签之一： -| 信号 | 含义 | -| -------------------------- | ---------------------------------------------------------- | -| **config valid** | 配置解析正常，插件可解析 | -| **compatibility advisory** | 插件使用了受支持但较旧的模式（例如 `hook-only`） | -| **legacy warning** | 插件使用了 `before_agent_start`，该接口已弃用 | -| **hard error** | 配置无效或插件加载失败 | +| 信号 | 含义 | +| -------------------------- | ------------------------------------------------------------ | +| **config valid** | 配置解析正常，且插件可成功解析 | +| **compatibility advisory** | 插件使用了受支持但较旧的模式（例如 `hook-only`） | +| **legacy warning** | 插件使用了 `before_agent_start`，该接口已弃用 | +| **hard error** | 配置无效，或插件加载失败 | -当前 `hook-only` 和 `before_agent_start` 都不会破坏你的插件： -`hook-only` 只是提示信息，而 `before_agent_start` 只会触发警告。这些信号也会出现在 `openclaw status --all` 和 `openclaw plugins doctor` 中。 +`hook-only` 和 `before_agent_start` 目前都不会导致你的插件失效：`hook-only` 只是提示性信息，而 `before_agent_start` 只会触发警告。这些信号也会显示在 `openclaw status --all` 和 `openclaw plugins doctor` 中。 ## 架构概览 OpenClaw 的插件系统分为四层： -1. **Manifest + 设备发现** - OpenClaw 会从配置的路径、工作区根目录、全局插件根目录以及内置插件中查找候选插件。设备发现会优先读取原生 `openclaw.plugin.json` manifest 和受支持 bundle 的 manifest。 -2. **启用 + 校验** - Core 决定某个已发现插件是启用、禁用、阻止，还是被选入某个排他插槽（例如 memory）。 +1. **清单 + 设备发现** + OpenClaw 会从已配置路径、工作区根目录、全局插件根目录以及内置插件中查找候选插件。设备发现会优先读取原生 `openclaw.plugin.json` 清单以及受支持的 bundle 清单。 +2. **启用 + 验证** + 核心决定某个已发现插件是启用、禁用、阻止，还是被选入诸如 memory 之类的独占槽位。 3. **运行时加载** - 原生 OpenClaw 插件通过 jiti 在进程内加载，并将能力注册到中央注册表中。兼容的 bundle 会被标准化为注册表记录，而无需导入运行时代码。 -4. **Surface 消费** - OpenClaw 的其余部分读取注册表，以暴露工具、渠道、提供商设置、hooks、HTTP 路由、CLI 命令和服务。 + 原生 OpenClaw 插件通过 jiti 在进程内加载，并将能力注册到中央注册表中。兼容的 bundle 会在不导入运行时代码的情况下被规范化为注册表记录。 +4. **表面消费** + OpenClaw 的其余部分会读取注册表，以暴露工具、渠道、提供商设置、hooks、HTTP 路由、CLI 命令和服务。 -对于插件 CLI，根命令设备发现会拆分为两个阶段： +对于插件 CLI 而言，根命令的设备发现专门拆分为两个阶段： -- 解析时元数据来自 `registerCli(..., { descriptors: [...] })` -- 真正的插件 CLI 模块可以保持惰性加载，并在首次调用时注册 +- 解析阶段元数据来自 `registerCli(..., { descriptors: [...] })` +- 实际的插件 CLI 模块可以保持惰性加载，并在首次调用时再注册 -这样可以在 OpenClaw 解析之前预留根命令名，同时将插件拥有的 CLI 代码保留在插件内部。 +这样可以让插件自有的 CLI 代码保持在插件内部，同时仍允许 OpenClaw 在解析之前预留根命令名称。 重要的设计边界是： -- 设备发现 + 配置校验应基于 **manifest / schema 元数据** 工作，而不执行插件代码 +- 设备发现 + 配置验证应当基于**清单 / schema 元数据**工作，而不执行插件代码 - 原生运行时行为来自插件模块的 `register(api)` 路径 -这种拆分使 OpenClaw 能在完整运行时激活之前，先校验配置、解释缺失 / 已禁用的插件，并构建 UI / schema 提示。 +这种拆分让 OpenClaw 能在完整运行时尚未激活之前，就验证配置、解释缺失 / 已禁用的插件，并构建 UI / schema 提示信息。 + +### 激活规划 + +激活规划是控制平面的一部分。调用方可以在加载更广泛的运行时注册表之前，先询问哪些插件与某个具体命令、提供商、渠道、路由、智能体 harness 或能力相关。 + +规划器保持与当前清单行为兼容： + +- `activation.*` 字段是显式的规划器提示 +- `providers`、`channels`、`commandAliases`、`setup.providers`、`contracts.tools` 以及 hooks 仍然作为清单归属关系的后备来源 +- 仅返回 id 的规划器 API 仍然对现有调用方可用 +- 规划 API 会报告 reason 标签，以便诊断区分显式提示与归属关系后备来源 + +不要把 `activation` 视为生命周期 hook，也不要把它当作 `register(...)` 的替代品。它只是用于缩小加载范围的元数据。如果已有归属字段可以描述这种关系，就优先使用归属字段；只有在需要额外规划提示时才使用 `activation`。 ### 渠道插件与共享 message 工具 -对于常规聊天动作，渠道插件不需要单独注册发送 / 编辑 / reaction 工具。OpenClaw 在 core 中保留了一个共享的 `message` 工具，而渠道插件负责其背后的渠道特定设备发现和执行。 +对于常规聊天操作，渠道插件不需要单独注册发送 / 编辑 / 响应工具。OpenClaw 在核心中保留了一个共享的 `message` 工具，而渠道插件负责其背后的渠道特定设备发现和执行。 -当前边界是： +当前边界如下： -- core 负责共享 `message` 工具宿主、prompt 接线、会话 / 线程簿记和执行分发 -- 渠道插件负责有范围限制的动作设备发现、能力设备发现以及所有渠道特定的 schema 片段 -- 渠道插件负责提供商特定的会话会话语法，例如会话 id 如何编码线程 id 或从父会话继承 -- 渠道插件通过其动作适配器执行最终动作 +- 核心负责共享 `message` 工具宿主、提示词接线、session / thread 记账以及执行分发 +- 渠道插件负责作用域内操作发现、能力发现，以及任何渠道特定的 schema 片段 +- 渠道插件负责提供商特定的 session 会话语法，例如会话 id 如何编码 thread id，或如何从父会话继承 +- 渠道插件通过其 action adapter 执行最终操作 -对于渠道插件，SDK surface 是 -`ChannelMessageActionAdapter.describeMessageTool(...)`。这个统一的设备发现调用允许插件同时返回其可见动作、能力和 schema 贡献，以避免这些部分彼此漂移。 +对于渠道插件，SDK 接口为 `ChannelMessageActionAdapter.describeMessageTool(...)`。这个统一的发现调用让插件可以一起返回其可见操作、能力以及 schema 贡献，从而避免这些部分彼此漂移。 -当渠道特定的 message-tool 参数携带媒体来源，例如本地路径或远程媒体 URL 时，插件还应从 `describeMessageTool(...)` 返回 `mediaSourceParams`。Core 使用这份显式列表来应用沙箱路径标准化和出站媒体访问提示，而不是对插件拥有的参数名进行硬编码。 -这里应优先使用按动作划分的映射，而不是单一的全渠道平面列表，这样仅用于 profile 的媒体参数就不会在 `send` 这类无关动作上被标准化。 +当某个渠道特定的 message-tool 参数携带媒体来源，例如本地路径或远程媒体 URL 时，插件还应从 `describeMessageTool(...)` 返回 `mediaSourceParams`。核心会使用这份显式列表来应用沙箱路径规范化和出站媒体访问提示，而无需硬编码插件自有的参数名称。 +这里应优先使用按操作划分的映射，而不是整个渠道共用的一份扁平列表，这样仅用于 profile 的媒体参数就不会在 `send` 这类无关操作中被规范化。 -Core 会将运行时 scope 传入该设备发现步骤。重要字段包括： +核心会把运行时作用域传入该发现步骤。重要字段包括： - `accountId` - `currentChannelId` @@ -161,81 +172,80 @@ Core 会将运行时 scope 传入该设备发现步骤。重要字段包括： - `agentId` - 受信任的入站 `requesterSenderId` -这对上下文敏感型插件非常重要。渠道可以根据活动账户、当前房间 / 线程 / 消息，或受信任的请求者身份来隐藏或暴露消息动作，而无需在 core 的 `message` 工具中硬编码渠道特定分支。 +这对于上下文敏感型插件很重要。一个渠道可以根据当前账户、当前房间 / thread / 消息，或受信任的请求方身份来隐藏或暴露消息操作，而无需在核心 `message` 工具中硬编码渠道特定分支。 -这也是为什么嵌入式 runner 路由变更仍然属于插件工作：runner 负责将当前聊天 / 会话身份转发到插件设备发现边界，以便共享 `message` 工具为当前轮次暴露正确的渠道拥有 surface。 +这也是为什么嵌入式 runner 路由变更仍然属于插件工作：runner 负责把当前聊天 / session 身份转发到插件发现边界，从而让共享的 `message` 工具为当前轮次暴露正确的渠道自有表面。 -对于渠道拥有的执行辅助器，内置插件应将执行运行时保留在它们自己的 extension 模块中。Core 不再拥有位于 `src/agents/tools` 下的 Discord、Slack、Telegram 或 WhatsApp 消息动作运行时。 -我们不会发布单独的 `plugin-sdk/*-action-runtime` 子路径，内置插件应直接从其 extension 自有模块中导入自己的本地运行时代码。 +对于渠道自有的执行辅助运行时，内置插件应将执行运行时保留在其自身扩展模块内。核心不再在 `src/agents/tools` 下持有 Discord、Slack、Telegram 或 WhatsApp 的消息操作运行时。我们不会发布单独的 `plugin-sdk/*-action-runtime` 子路径，内置插件应直接从其扩展自有模块导入本地运行时代码。 -同样的边界也适用于一般意义上的带提供商名称的 SDK seam：core 不应导入 Slack、Discord、Signal、WhatsApp 或类似 extension 的渠道专用便捷 barrel。如果 core 需要某种行为，要么消费该内置插件自己的 `api.ts` / `runtime-api.ts` barrel，要么将需求提升为共享 SDK 中一个范围狭窄的通用能力。 +同样的边界也适用于一般情况下带有提供商命名的 SDK 接缝：核心不应导入 Slack、Discord、Signal、WhatsApp 或类似扩展的渠道特定便捷 barrel。如果核心需要某种行为，要么消费内置插件自己的 `api.ts` / `runtime-api.ts` barrel，要么将该需求提升为共享 SDK 中一个范围明确的通用能力。 -对于投票，具体有两条执行路径： +对于投票，当前有两条执行路径： - `outbound.sendPoll` 是适用于符合通用投票模型的渠道的共享基线 - `actions.handleAction("poll")` 是处理渠道特定投票语义或额外投票参数的首选路径 -现在，Core 会将共享投票解析推迟到插件投票分发拒绝该动作之后，因此插件拥有的投票处理器可以接受渠道特定投票字段，而不会先被通用投票解析器拦住。 +现在，核心会在插件投票分发拒绝该操作之后，才延迟执行共享投票解析，这样插件自有的投票处理器就能接受渠道特定的投票字段，而不会先被通用投票解析器拦住。 完整启动顺序请参见 [插件架构内部机制](/zh-CN/plugins/architecture-internals)。 ## 能力归属模型 -OpenClaw 将原生插件视为某个**公司**或某个**功能**的归属边界，而不是一堆彼此无关集成的杂物袋。 +OpenClaw 将原生插件视为某个**公司**或某个**功能**的归属边界，而不是一堆互不相关集成的杂货袋。 这意味着： -- 公司插件通常应拥有该公司的所有 OpenClaw 对外 surface -- 功能插件通常应拥有其引入的完整功能 surface -- 渠道应消费共享的 core 能力，而不是临时重新实现提供商行为 +- 一个公司插件通常应拥有该公司的所有面向 OpenClaw 的表面 +- 一个功能插件通常应拥有其引入的完整功能表面 +- 渠道应消费共享的核心能力，而不是临时重新实现提供商行为 - - **供应商多能力**：`openai` 拥有文本推理、语音、实时语音、媒体理解和图像生成。`google` 拥有文本推理以及媒体理解、图像生成和 Web 搜索。`qwen` 拥有文本推理以及媒体理解和视频生成。 - - **供应商单能力**：`elevenlabs` 和 `microsoft` 拥有语音；`firecrawl` 拥有 Web 抓取；`minimax` / `mistral` / `moonshot` / `zai` 拥有媒体理解后端。 - - **功能插件**：`voice-call` 拥有呼叫传输、工具、CLI、路由和 Twilio 媒体流桥接，但会消费共享的语音、实时转写和实时语音能力，而不是直接导入供应商插件。 + - **厂商多能力**：`openai` 拥有文本推理、语音、实时语音、媒体理解和图像生成。`google` 拥有文本推理，以及媒体理解、图像生成和网页搜索。`qwen` 拥有文本推理，以及媒体理解和视频生成。 + - **厂商单能力**：`elevenlabs` 和 `microsoft` 拥有语音；`firecrawl` 拥有网页抓取；`minimax` / `mistral` / `moonshot` / `zai` 拥有媒体理解后端。 + - **功能插件**：`voice-call` 拥有通话传输、工具、CLI、路由和 Twilio 媒体流桥接，但它会消费共享的语音、实时转录和实时语音能力，而不是直接导入厂商插件。 预期的最终状态是： -- OpenAI 位于同一个插件中，即使它覆盖文本模型、语音、图像以及未来的视频 -- 另一个供应商也可以对其自己的 surface 采用相同模式 -- 渠道并不关心哪个供应商插件拥有该提供商；它们消费的是 core 暴露的共享能力契约 +- 即使 OpenAI 横跨文本模型、语音、图像以及未来的视频，它也只存在于一个插件中 +- 其他厂商也可以对自己的表面区域采用同样方式 +- 渠道不需要关心哪个厂商插件拥有该提供商；它们消费的是由核心暴露的共享能力契约 -这就是关键区别： +这是关键区别： - **plugin** = 归属边界 -- **capability** = 可由多个插件实现或消费的 core 契约 +- **capability** = 可由多个插件实现或消费的核心契约 -因此，如果 OpenClaw 新增了一个像视频这样的新领域，第一个问题不应是“哪个提供商应该硬编码视频处理？”第一个问题应是“core 的视频能力契约是什么？”一旦这个契约存在，供应商插件就可以针对它注册，而渠道 / 功能插件也可以消费它。 +因此，如果 OpenClaw 新增一个领域，例如视频，首要问题不是“哪个提供商应该硬编码视频处理？”首要问题是“核心视频能力契约是什么？”一旦该契约存在，厂商插件就可以对其注册，渠道 / 功能插件也可以消费它。 如果该能力尚不存在，通常正确的做法是： -1. 在 core 中定义缺失的能力 +1. 在核心中定义缺失的能力 2. 通过插件 API / 运行时以类型化方式暴露它 -3. 让渠道 / 功能接入该能力 -4. 让供应商插件注册实现 +3. 让渠道 / 功能围绕该能力完成接线 +4. 让厂商插件注册实现 -这样可以在保持归属明确的同时，避免 core 行为依赖单一供应商或某个一次性的插件专用代码路径。 +这样既能保持归属关系清晰，又能避免依赖单一厂商或一次性插件专用代码路径的核心行为。 ### 能力分层 -在决定代码归属位置时，可使用以下思维模型： +在决定代码应放在哪里时，可使用以下思维模型： -- **core 能力层**：共享编排、策略、回退、配置合并规则、投递语义和类型化契约 -- **供应商插件层**：供应商特定 API、认证、模型目录、语音合成、图像生成、未来视频后端、用量端点 -- **渠道 / 功能插件层**：Slack / Discord / voice-call / 等集成，它们消费 core 能力并将其呈现在某个 surface 上 +- **核心能力层**：共享编排、策略、回退、配置合并规则、交付语义和类型化契约 +- **厂商插件层**：厂商特定 API、认证、模型目录、语音合成、图像生成、未来的视频后端、使用量端点 +- **渠道 / 功能插件层**：Slack / Discord / voice-call / 等集成，负责消费核心能力并将其呈现在某个表面上 -例如，TTS 遵循如下形态： +例如，TTS 采用如下结构： -- core 负责回复时 TTS 策略、回退顺序、偏好设置和渠道投递 +- 核心负责回复时 TTS 策略、回退顺序、偏好设置和渠道交付 - `openai`、`elevenlabs` 和 `microsoft` 负责合成实现 -- `voice-call` 消费电话 TTS 运行时辅助器 +- `voice-call` 消费电话 TTS 运行时辅助接口 -未来的能力也应优先采用同样的模式。 +未来的新能力也应优先采用相同模式。 ### 多能力公司插件示例 -从外部看，公司插件应当是有内聚性的。如果 OpenClaw 对模型、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、Web 抓取和 Web 搜索都已有共享契约，那么一个供应商就可以在一个地方拥有其所有 surface： +一个公司插件从外部看应当是内聚的。如果 OpenClaw 为模型、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取和网页搜索提供了共享契约，那么某个厂商就可以在一个地方拥有其所有表面： ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -289,115 +299,111 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -重要的不是辅助器名称是否完全一致，而是这种形态： +重要的不是辅助函数的精确名称，而是这种结构： -- 一个插件拥有供应商 surface -- core 仍然拥有能力契约 -- 渠道和功能插件消费的是 `api.runtime.*` 辅助器，而不是供应商代码 -- 契约测试可以断言该插件确实注册了它声称拥有的那些能力 +- 一个插件拥有该厂商表面 +- 核心仍然拥有能力契约 +- 渠道和功能插件消费 `api.runtime.*` 辅助接口，而不是厂商代码 +- 契约测试可以断言该插件注册了它声称拥有的能力 ### 能力示例：视频理解 OpenClaw 已经将图像 / 音频 / 视频理解视为一种共享能力。相同的归属模型也适用于这里： -1. core 定义媒体理解契约 -2. 供应商插件按适用情况注册 `describeImage`、`transcribeAudio` 和 `describeVideo` -3. 渠道和功能插件消费共享的 core 行为，而不是直接接入供应商代码 +1. 核心定义媒体理解契约 +2. 厂商插件按适用情况注册 `describeImage`、`transcribeAudio` 和 `describeVideo` +3. 渠道和功能插件消费共享核心行为，而不是直接接线到厂商代码 -这样可以避免将某个提供商的视频假设硬编码到 core 中。插件拥有供应商 surface；core 拥有能力契约和回退行为。 +这样可以避免把某个提供商的视频假设直接写进核心中。插件拥有厂商表面；核心拥有能力契约和回退行为。 -视频生成已经采用了相同顺序：core 拥有类型化能力契约和运行时辅助器，而供应商插件针对它注册 `api.registerVideoGenerationProvider(...)` 实现。 +视频生成也已经采用相同顺序：核心拥有类型化能力契约和运行时辅助接口，而厂商插件通过 `api.registerVideoGenerationProvider(...)` 注册其实现。 -需要一个具体的推出清单吗？请参见 +需要具体的发布清单吗？请参见 [能力扩展手册](/zh-CN/plugins/architecture)。 ## 契约与强制执行 -插件 API surface 被有意设计为类型化，并集中在 -`OpenClawPluginApi` 中。该契约定义了受支持的注册点，以及插件可依赖的运行时辅助器。 +插件 API 表面有意通过 `OpenClawPluginApi` 进行类型化和集中化。该契约定义了受支持的注册点，以及插件可依赖的运行时辅助接口。 -这为什么重要： +这很重要，原因如下： -- 插件作者可以获得一个稳定的内部标准 -- core 可以拒绝重复归属，例如两个插件注册同一个 provider id -- 启动阶段可以为格式错误的注册提供可操作的诊断信息 -- 契约测试可以强制执行内置插件的归属，并防止无声漂移 +- 插件作者获得一套稳定的内部标准 +- 核心可以拒绝重复归属，例如两个插件注册相同的提供商 id +- 启动过程可以为格式错误的注册提供可操作的诊断信息 +- 契约测试可以强制执行内置插件归属，防止无声漂移 -有两层强制执行： +这里有两层强制执行： 1. **运行时注册强制执行** - 插件注册表会在插件加载时校验注册。例如：重复的 provider id、重复的语音提供商 id，以及格式错误的注册，都会生成插件诊断，而不是导致未定义行为。 + 插件注册表会在插件加载时验证注册内容。例如：重复的提供商 id、重复的语音提供商 id，以及格式错误的注册，都会产出插件诊断，而不是导致未定义行为。 2. **契约测试** - 内置插件会在测试运行期间被捕获到契约注册表中，以便 OpenClaw 能够明确断言归属。目前这已用于模型提供商、语音提供商、Web 搜索提供商和内置注册归属。 + 在测试运行期间，内置插件会被捕获到契约注册表中，以便 OpenClaw 可以显式断言归属关系。目前这已用于模型提供商、语音提供商、网页搜索提供商以及内置注册归属。 -实际效果是，OpenClaw 可以预先知道哪个插件拥有哪个 surface。因为归属是声明式、类型化且可测试的，所以 core 和渠道可以无缝组合，而不是依赖隐式约定。 +实际效果是，OpenClaw 能在一开始就知道哪个插件拥有哪个表面。这样核心和渠道就能无缝组合，因为归属是声明式、类型化且可测试的，而不是隐式的。 -### 什么应属于契约 +### 什么内容应属于契约 -好的插件契约应当是： +好的插件契约应当具备以下特点： -- 类型化 +- 有类型 - 小而精 -- 能力专用 -- 由 core 拥有 +- 能力特定 +- 由核心拥有 - 可被多个插件复用 -- 可被渠道 / 功能消费，而无需了解供应商细节 +- 可在不了解厂商细节的前提下被渠道 / 功能消费 -不好的插件契约则是： +不好的插件契约包括： -- 隐藏在 core 中的供应商专用策略 -- 绕过注册表的一次性插件逃生口 -- 渠道代码直接深入某个供应商实现 -- 不属于 `OpenClawPluginApi` 或 - `api.runtime` 的临时运行时对象 +- 隐藏在核心中的厂商特定策略 +- 绕过注册表的一次性插件逃逸口 +- 直接探入厂商实现的渠道代码 +- 不属于 `OpenClawPluginApi` 或 `api.runtime` 的临时运行时对象 -如果拿不准，请提升抽象层级：先定义能力，再让插件接入它。 +如果拿不准，应提高抽象层级：先定义能力，再让插件接入它。 ## 执行模型 -原生 OpenClaw 插件与 Gateway 网关**在同一进程内**运行。它们没有被沙箱隔离。已加载的原生插件与 core 代码具有相同的进程级信任边界。 +原生 OpenClaw 插件与 Gateway 网关**在同一进程内**运行。它们不在沙箱中。已加载的原生插件与核心代码处于相同的进程级信任边界内。 -其影响是： +其含义包括： - 原生插件可以注册工具、网络处理器、hooks 和服务 - 原生插件中的 bug 可能导致 Gateway 网关崩溃或失稳 - 恶意原生插件等同于在 OpenClaw 进程内执行任意代码 -兼容 bundle 默认更安全，因为 OpenClaw 当前将其视为元数据 / 内容包。在当前版本中，这主要意味着内置 Skills。 +兼容 bundle 默认更安全，因为 OpenClaw 当前将它们视为元数据 / 内容包。在当前版本中，这主要意味着内置 Skills。 -对于非内置插件，请使用 allowlist 和显式安装 / 加载路径。请将工作区插件视为开发期代码，而不是生产默认项。 +对于非内置插件，请使用 allowlist 和显式安装 / 加载路径。将工作区插件视为开发期代码，而不是生产环境默认项。 -对于内置工作区 package 名，请让插件 id 固定在 npm 名称中：默认使用 `@openclaw/`，或者在 package 有意暴露更窄的插件角色时，使用经过批准的类型化后缀，例如 `-provider`、`-plugin`、`-speech`、`-sandbox` 或 `-media-understanding`。 +对于内置工作区包名，请让插件 id 默认锚定在 npm 名称中：`@openclaw/`，或者使用经过批准的类型化后缀，例如 `-provider`、`-plugin`、`-speech`、`-sandbox` 或 `-media-understanding`，前提是该包有意暴露更窄的插件角色。 重要的信任说明： - `plugins.allow` 信任的是**插件 id**，而不是来源出处。 -- 当启用 / allowlist 某个与内置插件同 id 的工作区插件时，它会有意遮蔽内置副本。 +- 与内置插件拥有相同 id 的工作区插件，在该工作区插件被启用 / 加入 allowlist 时，会有意遮蔽内置副本。 - 这属于正常且有用的行为，适用于本地开发、补丁测试和热修复。 -- 内置插件信任是根据源码快照解析的——即加载时磁盘上的 manifest 和代码——而不是根据安装元数据。损坏或被替换的安装记录无法在实际源码声明范围之外，悄悄扩大内置插件的信任 surface。 +- 内置插件信任是根据源码快照解析的——即加载时磁盘上的清单和代码——而不是根据安装元数据解析。损坏或被替换的安装记录，不能在实际源码声明之外静默扩大内置插件的信任表面。 ## 导出边界 -OpenClaw 导出的是能力，而不是实现便利性。 +OpenClaw 导出的是能力，而不是实现便利接口。 -保持能力注册为公共接口。裁剪非契约辅助器导出： +保持能力注册公开。应裁剪非契约辅助导出： -- 内置插件专用的辅助器子路径 -- 不打算作为公共 API 的运行时管线子路径 -- 供应商专用便捷辅助器 -- 属于实现细节的设置 / 新手引导辅助器 +- 内置插件特定的辅助子路径 +- 不打算作为公开 API 的运行时管线子路径 +- 厂商特定的便捷辅助函数 +- 属于实现细节的设置 / 新手引导辅助函数 -出于兼容性和内置插件维护需要，一些内置插件辅助器子路径仍保留在生成的 SDK 导出映射中。当前示例包括 -`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、 -`plugin-sdk/zalo-setup` 以及若干 `plugin-sdk/matrix*` seam。请将这些视为保留的实现细节导出，而不是新第三方插件推荐采用的 SDK 模式。 +为了兼容性和内置插件维护，某些内置插件辅助子路径仍保留在生成的 SDK 导出映射中。当前示例包括 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 以及若干 `plugin-sdk/matrix*` 接缝。应将这些视为保留的实现细节导出，而不是新第三方插件推荐采用的 SDK 模式。 ## 内部机制与参考 -关于加载流水线、注册表模型、提供商运行时钩子、Gateway 网关 HTTP 路由、message 工具 schema、渠道目标解析、提供商目录、上下文引擎插件，以及添加新能力的指南，请参见 +关于加载流水线、注册表模型、提供商运行时钩子、Gateway 网关 HTTP 路由、message 工具 schema、渠道目标解析、提供商目录、上下文引擎插件，以及新增能力的指南，请参见 [插件架构内部机制](/zh-CN/plugins/architecture-internals)。 ## 相关内容 - [构建插件](/zh-CN/plugins/building-plugins) - [插件 SDK 设置](/zh-CN/plugins/sdk-setup) -- [插件 manifest](/zh-CN/plugins/manifest) +- [插件清单](/zh-CN/plugins/manifest) diff --git a/docs/zh-CN/plugins/manifest.md b/docs/zh-CN/plugins/manifest.md index c7d35f613..2da98438b 100644 --- a/docs/zh-CN/plugins/manifest.md +++ b/docs/zh-CN/plugins/manifest.md @@ -1,21 +1,21 @@ --- read_when: - 你正在构建一个 OpenClaw 插件 - - 你需要提供插件配置 schema，或调试插件校验错误 -summary: 插件清单 + JSON schema 要求（严格配置校验） + - 你需要提供插件配置 schema，或调试插件验证错误 +summary: 插件清单 + JSON schema 要求（严格配置验证） title: 插件清单 x-i18n: - generated_at: "2026-04-24T04:55:18Z" + generated_at: "2026-04-24T05:09:38Z" model: gpt-5.4 provider: openai - source_hash: fd130accdaf606afc07a34cf064588087227bafc23279d31e33c4fdc8863a4a4 + source_hash: d27765f1efc9720bd68c73d3ede796a91e9afec479f89eda531dd14adc708e53 source_path: plugins/manifest.md workflow: 15 --- -此页面仅适用于**原生 OpenClaw 插件清单**。 +本页仅适用于**原生 OpenClaw 插件清单**。 -有关兼容的 bundle 布局，请参阅 [Plugin bundles](/zh-CN/plugins/bundles)。 +关于兼容的 bundle 布局，请参阅 [Plugin bundles](/zh-CN/plugins/bundles)。 兼容的 bundle 格式使用不同的清单文件： @@ -23,31 +23,31 @@ x-i18n: - Claude bundle：`.claude-plugin/plugin.json`，或不带清单的默认 Claude 组件布局 - Cursor bundle：`.cursor-plugin/plugin.json` -OpenClaw 也会自动检测这些 bundle 布局，但它们不会根据此处描述的 `openclaw.plugin.json` schema 进行校验。 +OpenClaw 也会自动检测这些 bundle 布局，但不会按照这里描述的 `openclaw.plugin.json` schema 对它们进行验证。 -对于兼容 bundle，OpenClaw 目前会在布局符合 OpenClaw 运行时预期时，读取 bundle 元数据，以及声明的 skill 根目录、Claude 命令根目录、Claude bundle 的 `settings.json` 默认值、Claude bundle 的 LSP 默认值，以及受支持的 hook pack。 +对于兼容 bundle，当前在布局符合 OpenClaw 运行时预期时，OpenClaw 会读取 bundle 元数据、声明的 skill 根目录、Claude 命令根目录、Claude bundle 的 `settings.json` 默认值、Claude bundle 的 LSP 默认值，以及受支持的 hook pack。 -每个原生 OpenClaw 插件**都必须**在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用这个清单在**不执行插件代码的情况下**校验配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。 +每个原生 OpenClaw 插件**都必须**在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单在**不执行插件代码的情况下**验证配置。缺失或无效的清单会被视为插件错误，并阻止配置验证。 -查看完整的插件系统指南：[Plugins](/zh-CN/tools/plugin)。 -有关原生能力模型和当前外部兼容性指南，请参阅： +请参阅完整的插件系统指南：[Plugins](/zh-CN/tools/plugin)。 +关于原生能力模型及当前的外部兼容性指导，请参阅： [Capability model](/zh-CN/plugins/architecture#public-capability-model)。 -## 这个文件的作用 +## 此文件的作用 -`openclaw.plugin.json` 是 OpenClaw 在**加载你的插件代码之前**读取的元数据。下面的所有内容都必须足够轻量，以便在不启动插件运行时的情况下进行检查。 +`openclaw.plugin.json` 是 OpenClaw 在**加载你的插件代码之前**读取的元数据。下面的所有内容都必须足够轻量，能够在不启动插件运行时的情况下进行检查。 -**将其用于：** +**用于：** -- 插件标识、配置校验，以及配置 UI 提示 -- 认证、新手引导和设置元数据（别名、自动启用、provider 环境变量、认证选项） +- 插件标识、配置验证，以及配置 UI 提示 +- 凭证、onboarding 和设置元数据（别名、自动启用、provider 环境变量、认证选项） - 控制平面界面的激活提示 -- 简写模型族归属 +- 简写的模型家族归属 - 静态能力归属快照（`contracts`） -- 共享 `openclaw qa` 主机可检查的 QA 运行器元数据 -- 合并到目录和校验界面中的渠道专用配置元数据 +- 共享 `openclaw qa` 主机可检查的 QA runner 元数据 +- 合并到目录和验证界面中的特定于渠道的配置元数据 -**不要将其用于：**注册运行时行为、声明代码入口点，或 npm 安装元数据。这些应放在你的插件代码和 `package.json` 中。 +**不要用于：**注册运行时行为、声明代码入口点，或 npm 安装元数据。这些应放在你的插件代码和 `package.json` 中。 ## 最小示例 @@ -131,62 +131,62 @@ OpenClaw 也会自动检测这些 bundle 布局，但它们不会根据此处描 | ------------------------------------ | -------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | 是 | `string` | 规范的插件 id。这是 `plugins.entries.` 中使用的 id。 | | `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 | -| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略此字段，或将其设为任何非 `true` 的值，则该插件默认保持禁用。 | -| `legacyPluginIds` | 否 | `string[]` | 会规范化为此标准插件 id 的旧版 id。 | -| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当认证、配置或模型引用提到这些 provider id 时，应自动启用此插件。 | -| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明由 `plugins.slots.*` 使用的排他性插件类型。 | -| `channels` | 否 | `string[]` | 由此插件拥有的渠道 id。用于发现和配置校验。 | -| `providers` | 否 | `string[]` | 由此插件拥有的 provider id。 | -| `providerDiscoveryEntry` | 否 | `string` | 轻量级 provider 发现模块路径，相对于插件根目录，用于可在不激活完整插件运行时的情况下加载的、限定于清单范围内的 provider 目录元数据。 | -| `modelSupport` | 否 | `object` | 由清单持有的简写模型族元数据，用于在运行时之前自动加载插件。 | -| `providerEndpoints` | 否 | `object[]` | 由清单持有的 endpoint host/baseUrl 元数据，用于核心在 provider 运行时加载前必须分类的 provider 路由。 | -| `cliBackends` | 否 | `string[]` | 由此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 | -| `syntheticAuthRefs` | 否 | `string[]` | provider 或 CLI 后端引用；在运行时加载前的冷启动模型发现期间，应探测其由插件持有的 synthetic auth hook。 | -| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件持有的占位 API key 值，表示非密钥的本地、OAuth 或环境凭证状态。 | -| `commandAliases` | 否 | `object[]` | 由此插件拥有的命令名称；在运行时加载前，这些名称应生成具备插件感知能力的配置和 CLI 诊断信息。 | +| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略此字段，或将其设置为任何非 `true` 的值，则该插件默认禁用。 | +| `legacyPluginIds` | 否 | `string[]` | 会规范化为此规范插件 id 的旧版 id。 | +| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当凭证、配置或模型引用提到这些 provider id 时，应自动启用此插件。 | +| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明 `plugins.slots.*` 使用的独占插件类型。 | +| `channels` | 否 | `string[]` | 此插件拥有的渠道 id。用于设备发现和配置验证。 | +| `providers` | 否 | `string[]` | 此插件拥有的 provider id。 | +| `providerDiscoveryEntry` | 否 | `string` | 轻量级 provider 发现模块路径，相对于插件根目录，用于可在不激活完整插件运行时的情况下加载的、受清单作用域约束的 provider 目录元数据。 | +| `modelSupport` | 否 | `object` | 由清单拥有的简写模型家族元数据，用于在运行时之前自动加载插件。 | +| `providerEndpoints` | 否 | `object[]` | 由清单拥有的 endpoint 主机 / `baseUrl` 元数据，用于核心在 provider 运行时加载前必须分类的 provider 路由。 | +| `cliBackends` | 否 | `string[]` | 此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 | +| `syntheticAuthRefs` | 否 | `string[]` | provider 或 CLI 后端引用，在运行时加载前的冷启动模型发现期间，应探测其插件拥有的 synthetic auth hook。 | +| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件拥有的占位 API key 值，表示非秘密的本地、OAuth 或环境凭证状态。 | +| `commandAliases` | 否 | `object[]` | 此插件拥有的命令名称，在运行时加载前应生成带有插件感知能力的配置和 CLI 诊断信息。 | | `providerAuthEnvVars` | 否 | `Record` | OpenClaw 可在不加载插件代码的情况下检查的轻量级 provider 认证环境变量元数据。 | -| `providerAuthAliases` | 否 | `Record` | 应复用另一个 provider id 进行认证查找的 provider id，例如与基础 provider 共享 API key 和认证配置文件的 coding provider。 | -| `channelEnvVars` | 否 | `Record` | OpenClaw 可在不加载插件代码的情况下检查的轻量级渠道环境变量元数据。将其用于由环境变量驱动的渠道设置或认证界面，以便通用启动/配置辅助工具能够识别。 | -| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选 provider 解析和简单 CLI 标志绑定的轻量级认证选项元数据。 | -| `activation` | 否 | `object` | 用于 provider、命令、渠道、路由和能力触发加载的轻量级激活提示。仅为元数据；实际行为仍由插件运行时负责。 | -| `setup` | 否 | `object` | 轻量级设置/新手引导描述符，供发现和设置界面在不加载插件运行时的情况下检查。 | -| `qaRunners` | 否 | `object[]` | 共享 `openclaw qa` 主机在插件运行时加载前使用的轻量级 QA 运行器描述符。 | -| `contracts` | 否 | `object` | 外部认证 hook、语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、网页抓取、网页搜索和工具归属的静态内置能力快照。 | -| `mediaUnderstandingProviderMetadata` | 否 | `Record` | 为 `contracts.mediaUnderstandingProviders` 中声明的 provider id 提供的轻量级媒体理解默认元数据。 | -| `channelConfigs` | 否 | `Record` | 由清单持有的渠道配置元数据，会在运行时加载前合并到发现和校验界面中。 | -| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 | +| `providerAuthAliases` | 否 | `Record` | 应复用另一个 provider id 进行认证查找的 provider id，例如共享基础 provider API key 和认证配置文件的 coding provider。 | +| `channelEnvVars` | 否 | `Record` | OpenClaw 可在不加载插件代码的情况下检查的轻量级渠道环境变量元数据。将其用于由环境变量驱动的渠道设置，或通用启动 / 配置辅助工具应识别的认证界面。 | +| `providerAuthChoices` | 否 | `object[]` | 用于 onboarding 选择器、首选 provider 解析和简单 CLI 标志接线的轻量级认证选项元数据。 | +| `activation` | 否 | `object` | 用于 provider、命令、渠道、路由和能力触发加载的轻量级激活规划器元数据。仅为元数据；实际行为仍由插件运行时负责。 | +| `setup` | 否 | `object` | 可供设备发现和设置界面在不加载插件运行时的情况下检查的轻量级设置 / onboarding 描述符。 | +| `qaRunners` | 否 | `object[]` | 共享 `openclaw qa` 主机在插件运行时加载前使用的轻量级 QA runner 描述符。 | +| `contracts` | 否 | `object` | 用于 external auth hook、语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、web-fetch、网页搜索和工具归属的静态内置能力快照。 | +| `mediaUnderstandingProviderMetadata` | 否 | `Record` | 为 `contracts.mediaUnderstandingProviders` 中声明的 provider id 提供的轻量级媒体理解默认值。 | +| `channelConfigs` | 否 | `Record` | 由清单拥有的渠道配置元数据，在运行时加载前合并到设备发现和验证界面中。 | +| `skills` | 否 | `string[]` | 要加载的 Skill 目录，相对于插件根目录。 | | `name` | 否 | `string` | 人类可读的插件名称。 | | `description` | 否 | `string` | 显示在插件界面中的简短摘要。 | -| `version` | 否 | `string` | 信息性插件版本。 | +| `version` | 否 | `string` | 仅供参考的插件版本。 | | `uiHints` | 否 | `Record` | 配置字段的 UI 标签、占位符和敏感性提示。 | ## `providerAuthChoices` 参考 -每个 `providerAuthChoices` 条目都描述一个新手引导或认证选项。 -OpenClaw 会在 provider 运行时加载前读取这些内容。 +每个 `providerAuthChoices` 条目描述一个 onboarding 或认证选项。 +OpenClaw 会在 provider 运行时加载前读取它。 | 字段 | 必填 | 类型 | 含义 | | --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `provider` | 是 | `string` | 此选项所属的 provider id。 | -| `method` | 是 | `string` | 要分发到的认证方法 id。 | -| `choiceId` | 是 | `string` | 新手引导和 CLI 流程使用的稳定认证选项 id。 | +| `method` | 是 | `string` | 要分派到的认证方法 id。 | +| `choiceId` | 是 | `string` | onboarding 和 CLI 流程使用的稳定认证选项 id。 | | `choiceLabel` | 否 | `string` | 面向用户的标签。如果省略，OpenClaw 会回退到 `choiceId`。 | | `choiceHint` | 否 | `string` | 选择器的简短辅助文本。 | -| `assistantPriority` | 否 | `number` | 在由助手驱动的交互式选择器中，值越小排序越靠前。 | -| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在助手选择器中隐藏该选项，但仍允许手动通过 CLI 选择。 | +| `assistantPriority` | 否 | `number` | 在由智能体驱动的交互式选择器中，值越小排序越靠前。 | +| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在智能体选择器中隐藏该选项，但仍允许通过手动 CLI 进行选择。 | | `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选项的旧版选项 id。 | -| `groupId` | 否 | `string` | 用于对相关选项进行分组的可选分组 id。 | -| `groupLabel` | 否 | `string` | 该分组面向用户的标签。 | -| `groupHint` | 否 | `string` | 该分组的简短辅助文本。 | +| `groupId` | 否 | `string` | 用于对相关选项进行分组的可选组 id。 | +| `groupLabel` | 否 | `string` | 该组面向用户的标签。 | +| `groupHint` | 否 | `string` | 该组的简短辅助文本。 | | `optionKey` | 否 | `string` | 用于简单单标志认证流程的内部选项键。 | | `cliFlag` | 否 | `string` | CLI 标志名称，例如 `--openrouter-api-key`。 | | `cliOption` | 否 | `string` | 完整的 CLI 选项形式，例如 `--openrouter-api-key `。 | -| `cliDescription` | 否 | `string` | 用于 CLI 帮助中的说明。 | -| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 此选项应出现在哪些新手引导界面中。如果省略，默认值为 `["text-inference"]`。 | +| `cliDescription` | 否 | `string` | 在 CLI 帮助中使用的说明。 | +| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 此选项应出现在哪些 onboarding 界面中。如果省略，默认值为 `["text-inference"]`。 | ## `commandAliases` 参考 -当插件拥有一个运行时命令名称，而用户可能误将其放入 `plugins.allow`，或尝试将其作为根 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用这些元数据进行诊断，而无需导入插件运行时代码。 +当插件拥有一个运行时命令名称，而用户可能会误将其放入 `plugins.allow`，或尝试将其作为根 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用这些元数据来生成诊断信息，而无需导入插件运行时代码。 ```json { @@ -204,15 +204,52 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。 | ------------ | -------- | ----------------- | ----------------------------------------------------------------------- | | `name` | 是 | `string` | 属于此插件的命令名称。 | | `kind` | 否 | `"runtime-slash"` | 将该别名标记为聊天斜杠命令，而不是根 CLI 命令。 | -| `cliCommand` | 否 | `string` | 若存在相关的根 CLI 命令，则建议用于 CLI 操作的命令。 | +| `cliCommand` | 否 | `string` | 若存在，用于 CLI 操作时建议的相关根 CLI 命令。 | ## `activation` 参考 -当插件可以低成本地声明哪些控制平面事件应在稍后激活它时，请使用 `activation`。 +当插件可以以低成本声明哪些控制平面事件应将其纳入激活 / 加载计划时，请使用 `activation`。 + +此块是规划器元数据，而不是生命周期 API。它不会注册运行时行为，不会替代 `register(...)`，也不保证插件代码已经执行。激活规划器使用这些字段来缩小候选插件范围，然后才回退到现有的清单归属元数据，例如 `providers`、`channels`、`commandAliases`、`setup.providers`、`contracts.tools` 和 hooks。 + +优先使用已经能够描述归属关系的最窄元数据。如果 `providers`、`channels`、`commandAliases`、设置描述符或 `contracts` 已能表达这种关系，请使用这些字段。只有当这些归属字段无法表示额外的规划器提示时，才使用 `activation`。 + +此块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时 / 插件入口点。当前使用方将其用作更广泛插件加载前的缩小范围提示，因此缺少激活元数据通常只会带来性能成本；在旧版清单归属回退仍然存在的情况下，不应改变正确性。 + +```json +{ + "activation": { + "onProviders": ["openai"], + "onCommands": ["models"], + "onChannels": ["web"], + "onRoutes": ["gateway-webhook"], + "onCapabilities": ["provider", "tool"] + } +} +``` + +| 字段 | 必填 | 类型 | 含义 | +| ---------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `onProviders` | 否 | `string[]` | 应将此插件纳入激活 / 加载计划的 provider id。 | +| `onCommands` | 否 | `string[]` | 应将此插件纳入激活 / 加载计划的命令 id。 | +| `onChannels` | 否 | `string[]` | 应将此插件纳入激活 / 加载计划的渠道 id。 | +| `onRoutes` | 否 | `string[]` | 应将此插件纳入激活 / 加载计划的路由类型。 | +| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的宽泛能力提示。能用更窄字段时应优先使用更窄字段。 | + +当前在线使用方： + +- 由命令触发的 CLI 规划会回退到旧版 + `commandAliases[].cliCommand` 或 `commandAliases[].name` +- 由渠道触发的设置 / 渠道规划在缺少显式渠道激活元数据时， + 会回退到旧版 `channels[]` 归属 +- 由 provider 触发的设置 / 运行时规划在缺少显式 provider + 激活元数据时，会回退到旧版 `providers[]` 和顶层 `cliBackends[]` 归属 + +规划器诊断可以区分显式激活提示和清单归属回退。例如，`activation-command-hint` 表示匹配了 `activation.onCommands`，而 `manifest-command-alias` 表示规划器改用了 `commandAliases` 归属。这些原因标签用于主机诊断和测试；插件作者应继续声明最能描述归属关系的元数据。 ## `qaRunners` 参考 -当插件在共享 `openclaw qa` 根命令下贡献一个或多个传输运行器时，请使用 `qaRunners`。保持这些元数据轻量且静态；实际的 CLI 注册仍由插件运行时通过导出 `qaRunnerCliRegistrations` 的轻量级 `runtime-api.ts` 接口负责。 +当插件在共享 `openclaw qa` 根命令下贡献一个或多个传输 runner 时，请使用 `qaRunners`。保持这些元数据轻量且静态；实际的 CLI 注册仍由插件运行时通过导出 `qaRunnerCliRegistrations` 的轻量级 `runtime-api.ts` 界面负责。 ```json { @@ -228,44 +265,11 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。 | 字段 | 必填 | 类型 | 含义 | | ------------- | -------- | -------- | ------------------------------------------------------------------ | | `commandName` | 是 | `string` | 挂载在 `openclaw qa` 下的子命令，例如 `matrix`。 | -| `description` | 否 | `string` | 当共享主机需要一个占位命令时使用的回退帮助文本。 | - -此区块仅包含元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时/插件入口点。 -当前使用方将其作为更广泛插件加载前的收窄提示，因此缺少激活元数据通常只会带来性能损耗；在旧版清单归属回退机制仍存在时，它不应改变正确性。 - -```json -{ - "activation": { - "onProviders": ["openai"], - "onCommands": ["models"], - "onChannels": ["web"], - "onRoutes": ["gateway-webhook"], - "onCapabilities": ["provider", "tool"] - } -} -``` - -| 字段 | 必填 | 类型 | 含义 | -| ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- | -| `onProviders` | 否 | `string[]` | 请求这些 provider id 时应激活此插件。 | -| `onCommands` | 否 | `string[]` | 应激活此插件的命令 id。 | -| `onChannels` | 否 | `string[]` | 应激活此插件的渠道 id。 | -| `onRoutes` | 否 | `string[]` | 应激活此插件的路由类型。 | -| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的宽泛能力提示。 | - -当前在线使用方： - -- 命令触发的 CLI 规划会回退到旧版的 - `commandAliases[].cliCommand` 或 `commandAliases[].name` -- 渠道触发的设置/渠道规划在缺少显式渠道激活元数据时，会回退到旧版 `channels[]` - 归属 -- provider 触发的设置/运行时规划在缺少显式 provider - 激活元数据时，会回退到旧版 `providers[]` 和顶层 `cliBackends[]` - 归属 +| `description` | 否 | `string` | 当共享主机需要 stub 命令时使用的回退帮助文本。 | ## `setup` 参考 -当设置和新手引导界面需要在运行时加载前使用由插件持有的轻量级元数据时，请使用 `setup`。 +当设置和 onboarding 界面在运行时加载前需要插件拥有的轻量级元数据时，请使用 `setup`。 ```json { @@ -284,32 +288,32 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。 } ``` -顶层 `cliBackends` 仍然有效，并继续描述 CLI 推理后端。`setup.cliBackends` 是面向控制平面/设置流程的设置专用描述符界面，应保持为纯元数据。 +顶层 `cliBackends` 仍然有效，并继续描述 CLI 推理后端。`setup.cliBackends` 是面向控制平面 / 设置流程、应保持仅元数据形式的设置专用描述符界面。 -存在时，`setup.providers` 和 `setup.cliBackends` 是设置发现的首选“描述符优先”查找界面。如果描述符仅用于收窄候选插件，而设置仍需要更丰富的设置期运行时 hook，请设置 `requiresRuntime: true`，并保留 `setup-api` 作为回退执行路径。 +存在时，`setup.providers` 和 `setup.cliBackends` 是设置发现的首选描述符优先查找界面。如果描述符仅用于缩小候选插件范围，而设置仍需要更丰富的设置时运行时 hook，请将 `requiresRuntime` 设为 `true`，并保留 `setup-api` 作为回退执行路径。 -由于设置查找可能会执行由插件持有的 `setup-api` 代码，规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值必须在已发现的插件之间保持唯一。归属不明确时会采用失败即关闭的方式，而不是按发现顺序选择一个胜出者。 +由于设置查找可能会执行插件拥有的 `setup-api` 代码，规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值在已发现插件之间必须保持唯一。归属关系不明确时会采用失败即关闭的方式，而不是根据发现顺序选择一个“赢家”。 ### `setup.providers` 参考 | 字段 | 必填 | 类型 | 含义 | | ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ | -| `id` | 是 | `string` | 在设置或新手引导期间暴露的 provider id。保持规范化 id 在全局唯一。 | -| `authMethods` | 否 | `string[]` | 此 provider 在不加载完整运行时的情况下支持的设置/认证方法 id。 | -| `envVars` | 否 | `string[]` | 通用设置/状态界面可在插件运行时加载前检查的环境变量。 | +| `id` | 是 | `string` | 在设置或 onboarding 期间暴露的 provider id。保持规范化 id 在全局范围内唯一。 | +| `authMethods` | 否 | `string[]` | 此 provider 在不加载完整运行时的情况下支持的设置 / 认证方法 id。 | +| `envVars` | 否 | `string[]` | 通用设置 / 状态界面可在插件运行时加载前检查的环境变量。 | ### `setup` 字段 | 字段 | 必填 | 类型 | 含义 | | ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- | -| `providers` | 否 | `object[]` | 在设置和新手引导期间暴露的 provider 设置描述符。 | -| `cliBackends` | 否 | `string[]` | 用于“描述符优先”设置查找的设置期后端 id。保持规范化 id 在全局唯一。 | -| `configMigrations` | 否 | `string[]` | 由此插件的设置界面拥有的配置迁移 id。 | +| `providers` | 否 | `object[]` | 在设置和 onboarding 期间暴露的 provider 设置描述符。 | +| `cliBackends` | 否 | `string[]` | 用于描述符优先设置查找的设置时后端 id。保持规范化 id 在全局范围内唯一。 | +| `configMigrations` | 否 | `string[]` | 由此插件设置界面拥有的配置迁移 id。 | | `requiresRuntime` | 否 | `boolean` | 在描述符查找之后，设置是否仍需要执行 `setup-api`。 | ## `uiHints` 参考 -`uiHints` 是从配置字段名称到小型渲染提示的映射。 +`uiHints` 是从配置字段名称映射到小型渲染提示的映射表。 ```json { @@ -332,12 +336,12 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。 | `help` | `string` | 简短辅助文本。 | | `tags` | `string[]` | 可选的 UI 标签。 | | `advanced` | `boolean` | 将该字段标记为高级项。 | -| `sensitive` | `boolean` | 将该字段标记为密钥或敏感项。 | +| `sensitive` | `boolean` | 将该字段标记为秘密或敏感项。 | | `placeholder` | `string` | 表单输入的占位文本。 | ## `contracts` 参考 -仅当 `contracts` 用于 OpenClaw 可在不导入插件运行时的情况下读取的静态能力归属元数据时，才使用它。 +仅当 OpenClaw 可以在不导入插件运行时的情况下读取静态能力归属元数据时，才使用 `contracts`。 ```json { @@ -363,27 +367,25 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。 | 字段 | 类型 | 含义 | | -------------------------------- | ---------- | ----------------------------------------------------------------- | | `embeddedExtensionFactories` | `string[]` | 内置插件可为其注册工厂的嵌入式运行时 id。 | -| `externalAuthProviders` | `string[]` | 此插件拥有其外部认证配置文件 hook 的 provider id。 | +| `externalAuthProviders` | `string[]` | 此插件拥有其 external auth profile hook 的 provider id。 | | `speechProviders` | `string[]` | 此插件拥有的语音 provider id。 | | `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转录 provider id。 | | `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音 provider id。 | -| `memoryEmbeddingProviders` | `string[]` | 此插件拥有的 Memory 嵌入 provider id。 | +| `memoryEmbeddingProviders` | `string[]` | 此插件拥有的 Memory embedding provider id。 | | `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解 provider id。 | | `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成 provider id。 | | `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成 provider id。 | -| `webFetchProviders` | `string[]` | 此插件拥有的网页抓取 provider id。 | +| `webFetchProviders` | `string[]` | 此插件拥有的 web-fetch provider id。 | | `webSearchProviders` | `string[]` | 此插件拥有的网页搜索 provider id。 | -| `tools` | `string[]` | 此插件为内置契约检查所拥有的智能体工具名称。 | +| `tools` | `string[]` | 在内置契约检查中，此插件拥有的智能体工具名称。 | -实现了 `resolveExternalAuthProfiles` 的 provider 插件应声明 -`contracts.externalAuthProviders`。未声明的插件仍会通过已弃用的兼容性回退路径运行，但该回退路径更慢，并将在迁移窗口结束后移除。 +实现 `resolveExternalAuthProfiles` 的 provider 插件应声明 `contracts.externalAuthProviders`。未声明的插件仍会通过一个已弃用的兼容性回退路径运行，但该回退路径更慢，并将在迁移窗口结束后移除。 -内置的 Memory 嵌入 provider 应为其公开的每个适配器 id 声明 -`contracts.memoryEmbeddingProviders`，包括诸如 `local` 之类的内置适配器。独立 CLI 路径使用此清单契约在完整 Gateway 网关运行时注册 provider 之前，仅加载所属插件。 +内置的 Memory embedding provider 应为其暴露的每个适配器 id 声明 `contracts.memoryEmbeddingProviders`，包括 `local` 这类内置适配器。独立 CLI 路径使用此清单契约，在完整 Gateway 网关运行时注册 provider 之前，仅加载拥有该 provider 的插件。 ## `mediaUnderstandingProviderMetadata` 参考 -当媒体理解 provider 具有默认模型、自动认证回退优先级或原生文档支持，且通用核心辅助工具在运行时加载前需要这些信息时，请使用 `mediaUnderstandingProviderMetadata`。键也必须在 `contracts.mediaUnderstandingProviders` 中声明。 +当媒体理解 provider 具有默认模型、自动认证回退优先级，或通用核心辅助工具在运行时加载前需要的原生文档支持时，请使用 `mediaUnderstandingProviderMetadata`。键也必须在 `contracts.mediaUnderstandingProviders` 中声明。 ```json { @@ -410,14 +412,14 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。 | 字段 | 类型 | 含义 | | ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | 此 provider 提供的媒体能力。 | -| `defaultModels` | `Record` | 当配置未指定模型时使用的“能力到模型”默认值。 | -| `autoPriority` | `Record` | 用于基于凭证自动回退 provider 时，数字越小排序越靠前。 | +| `capabilities` | `("image" \| "audio" \| "video")[]` | 此 provider 暴露的媒体能力。 | +| `defaultModels` | `Record` | 当配置未指定模型时使用的能力到模型默认映射。 | +| `autoPriority` | `Record` | 用于基于凭证的自动 provider 回退时，数值越小排序越靠前。 | | `nativeDocumentInputs` | `"pdf"[]` | 该 provider 支持的原生文档输入。 | ## `channelConfigs` 参考 -当渠道插件在运行时加载前需要低成本的配置元数据时，请使用 `channelConfigs`。 +当渠道插件在运行时加载前需要轻量级配置元数据时，请使用 `channelConfigs`。 ```json { @@ -449,14 +451,14 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。 | 字段 | 类型 | 含义 | | ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | | `schema` | `object` | `channels.` 的 JSON Schema。每个已声明的渠道配置条目都必须提供。 | -| `uiHints` | `Record` | 该渠道配置区块的可选 UI 标签 / 占位符 / 敏感性提示。 | -| `label` | `string` | 当运行时元数据尚未就绪时，合并到选择器和检查界面中的渠道标签。 | +| `uiHints` | `Record` | 该渠道配置部分可选的 UI 标签 / 占位符 / 敏感性提示。 | +| `label` | `string` | 当运行时元数据尚未准备好时，合并到选择器和检查界面中的渠道标签。 | | `description` | `string` | 用于检查和目录界面的简短渠道说明。 | -| `preferOver` | `string[]` | 在选择界面中，此渠道应优先于的旧版或较低优先级插件 id。 | +| `preferOver` | `string[]` | 在选择界面中，该渠道应优先于的旧版或较低优先级插件 id。 | ## `modelSupport` 参考 -当 OpenClaw 应在插件运行时加载前，根据诸如 `gpt-5.5` 或 `claude-sonnet-4.6` 这样的简写模型 id 推断出你的 provider 插件时，请使用 `modelSupport`。 +当 OpenClaw 应在插件运行时加载前，根据像 `gpt-5.5` 或 `claude-sonnet-4.6` 这样的简写模型 id 推断你的 provider 插件时，请使用 `modelSupport`。 ```json { @@ -467,75 +469,70 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。 } ``` -OpenClaw 按以下优先级处理： +OpenClaw 按以下优先级应用： -- 显式 `provider/model` 引用使用所属 `providers` 清单元数据 +- 显式 `provider/model` 引用使用其所属 `providers` 清单元数据 - `modelPatterns` 优先于 `modelPrefixes` -- 如果一个非内置插件和一个内置插件都匹配，则非内置插件胜出 -- 若仍存在歧义，则在用户或配置明确指定 provider 之前会忽略该歧义 +- 如果一个非内置插件和一个内置插件都匹配，则非内置插件优先 +- 剩余的歧义会被忽略，直到用户或配置指定了 provider 字段： | 字段 | 类型 | 含义 | | --------------- | ---------- | ------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | 对简写模型 id 使用 `startsWith` 进行匹配的前缀。 | +| `modelPrefixes` | `string[]` | 使用 `startsWith` 对简写模型 id 进行匹配的前缀。 | | `modelPatterns` | `string[]` | 在移除 profile 后缀后，对简写模型 id 进行匹配的正则表达式源码。 | -旧版顶层能力键已弃用。使用 `openclaw doctor --fix` 将 -`speechProviders`、`realtimeTranscriptionProviders`、 -`realtimeVoiceProviders`、`mediaUnderstandingProviders`、 -`imageGenerationProviders`、`videoGenerationProviders`、 -`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；常规清单加载不再将这些顶层字段视为能力归属。 +旧版顶层能力键已弃用。请使用 `openclaw doctor --fix`，将 `speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；常规清单加载不再将这些顶层字段视为能力归属。 ## 清单与 `package.json` 的区别 -这两个文件承担不同职责： +这两个文件承担不同的职责： | 文件 | 用途 | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | 发现、配置校验、认证选项元数据，以及在插件代码运行前必须存在的 UI 提示 | -| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 区块 | +| `openclaw.plugin.json` | 发现、配置验证、auth-choice 元数据，以及必须在插件代码运行前存在的 UI 提示 | +| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 配置块 | -如果你不确定某条元数据应放在哪里，请使用以下规则： +如果你不确定某项元数据应放在哪里，请使用以下规则： -- 如果 OpenClaw 必须在加载插件代码前知道它，请将其放在 `openclaw.plugin.json` -- 如果它与打包、入口文件或 npm 安装行为有关，请将其放在 `package.json` +- 如果 OpenClaw 必须在加载插件代码前知道它，把它放在 `openclaw.plugin.json` 中 +- 如果它与打包、入口文件或 npm 安装行为有关，把它放在 `package.json` 中 -### 会影响发现流程的 `package.json` 字段 +### 会影响发现的 `package.json` 字段 -某些运行时前的插件元数据被有意放在 `package.json` 的 -`openclaw` 区块下，而不是 `openclaw.plugin.json` 中。 +一些运行时前的插件元数据有意放在 `package.json` 的 `openclaw` 配置块下，而不是 `openclaw.plugin.json` 中。 重要示例： | 字段 | 含义 | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.extensions` | 声明原生插件入口点。必须保持在插件包目录内。 | -| `openclaw.runtimeExtensions` | 为已安装包声明构建后的 JavaScript 运行时入口点。必须保持在插件包目录内。 | -| `openclaw.setupEntry` | 在新手引导、延迟渠道启动以及只读渠道状态 / SecretRef 发现期间使用的轻量级仅设置入口点。必须保持在插件包目录内。 | -| `openclaw.runtimeSetupEntry` | 为已安装包声明构建后的 JavaScript 设置入口点。必须保持在插件包目录内。 | -| `openclaw.channel` | 轻量级渠道目录元数据，例如标签、文档路径、别名和选择文案。 | -| `openclaw.channel.configuredState` | 轻量级已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅环境变量设置？”。 | +| `openclaw.extensions` | 声明原生插件入口点。必须保留在插件包目录内。 | +| `openclaw.runtimeExtensions` | 为已安装包声明构建后的 JavaScript 运行时入口点。必须保留在插件包目录内。 | +| `openclaw.setupEntry` | 在 onboarding、延迟渠道启动以及只读渠道状态 / SecretRef 发现期间使用的轻量级仅设置入口点。必须保留在插件包目录内。 | +| `openclaw.runtimeSetupEntry` | 为已安装包声明构建后的 JavaScript 设置入口点。必须保留在插件包目录内。 | +| `openclaw.channel` | 轻量级渠道目录元数据，例如标签、文档路径、别名和选择说明文案。 | +| `openclaw.channel.configuredState` | 轻量级 configured-state 检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅由环境变量驱动的设置？”。 | | `openclaw.channel.persistedAuthState` | 轻量级持久化认证状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何账号登录？”。 | | `openclaw.install.npmSpec` / `openclaw.install.localPath` | 内置插件和外部发布插件的安装 / 更新提示。 | -| `openclaw.install.defaultChoice` | 当有多个安装来源可用时的首选安装路径。 | +| `openclaw.install.defaultChoice` | 有多个安装来源可用时的首选安装路径。 | | `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 主机版本，使用如 `>=2026.3.22` 这样的 semver 下限。 | -| `openclaw.install.expectedIntegrity` | 预期的 npm 分发完整性字符串，例如 `sha512-...`；安装和更新流程会据此校验获取到的工件。 | -| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个范围很窄的内置插件重新安装恢复路径。 | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间先加载仅设置用的渠道界面，再加载完整渠道插件。 | +| `openclaw.install.expectedIntegrity` | 预期的 npm 分发完整性字符串，例如 `sha512-...`；安装和更新流程会据此校验获取的制品。 | +| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一种范围很窄的内置插件重新安装恢复路径。 | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间先加载仅设置的渠道界面，再加载完整的渠道插件。 | -清单元数据决定了在运行时加载前，新手引导中会出现哪些 provider / 渠道 / 设置选项。`package.json#openclaw.install` 则告诉新手引导，当用户选择其中某个选项时，应如何获取或启用该插件。不要将安装提示移到 `openclaw.plugin.json` 中。 +清单元数据决定了在运行时加载前，onboarding 中会出现哪些 provider / 渠道 / 设置选项。`package.json#openclaw.install` 则告诉 onboarding，当用户选择这些选项之一时，应如何获取或启用该插件。不要将安装提示移到 `openclaw.plugin.json` 中。 -`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间强制执行。无效值会被拒绝；较新但有效的值会让该插件在较旧主机上被跳过。 +`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间强制执行。无效值会被拒绝；较新的但有效的值会使旧主机跳过该插件。 精确的 npm 版本固定已经存在于 `npmSpec` 中，例如 -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`。当你希望一旦获取到的 npm 工件不再匹配固定发布版本时，更新流程能够以失败即关闭的方式处理，就应将其与 `expectedIntegrity` 搭配使用。交互式新手引导会提供受信任注册表的 npm 规格，包括裸包名和 dist-tag。存在 `expectedIntegrity` 时，安装 / 更新流程会强制校验它；省略时，注册表解析结果会被记录，但不会带完整性固定。 +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`。当你希望更新流程在获取到的 npm 制品不再匹配已固定版本时采用失败即关闭的方式，请将其与 `expectedIntegrity` 配合使用。交互式 onboarding 会提供受信任注册表的 npm spec，包括裸包名和 dist-tag。存在 `expectedIntegrity` 时，安装 / 更新流程会强制校验；省略时，注册表解析结果会被记录，但不会附带完整性固定。 -渠道插件应提供 `openclaw.setupEntry`，以便状态、渠道列表或 SecretRef 扫描在不加载完整运行时的情况下识别已配置账号。该设置入口点应暴露渠道元数据以及可安全用于设置的配置、状态和 secrets 适配器；网络客户端、网关监听器和传输运行时应保留在主扩展入口点中。 +当状态、渠道列表或 SecretRef 扫描需要在不加载完整运行时的情况下识别已配置账号时，渠道插件应提供 `openclaw.setupEntry`。设置入口点应暴露渠道元数据以及适用于设置阶段的配置、状态和 secrets 适配器；网络客户端、Gateway 网关监听器和传输运行时应保留在主扩展入口点中。 -运行时入口点字段不会覆盖源码入口点字段的包边界检查。例如，`openclaw.runtimeExtensions` 不能让一个越出边界的 `openclaw.extensions` 路径变为可加载。 +运行时入口点字段不会覆盖源码入口点字段的包边界检查。例如，`openclaw.runtimeExtensions` 不能让一个越界的 `openclaw.extensions` 路径变得可加载。 -`openclaw.install.allowInvalidConfigRecovery` 的设计范围刻意很窄。它不会让任意损坏的配置变得可安装。当前它只允许安装流程从特定的陈旧内置插件升级失败中恢复，例如缺失的内置插件路径，或同一内置插件的陈旧 `channels.` 条目。无关的配置错误仍会阻止安装，并将操作员引导至 `openclaw doctor --fix`。 +`openclaw.install.allowInvalidConfigRecovery` 的适用范围被有意限制得很窄。它不会让任意损坏的配置变得可安装。当前它只允许安装流程从某些特定的陈旧内置插件升级失败中恢复，例如缺失的内置插件路径，或同一内置插件对应的陈旧 `channels.` 条目。无关的配置错误仍会阻止安装，并引导操作人员运行 `openclaw doctor --fix`。 `openclaw.channel.persistedAuthState` 是一个微型检查器模块的包元数据： @@ -553,9 +550,9 @@ OpenClaw 按以下优先级处理： } ``` -当设置、Doctor 或已配置状态流程在完整渠道插件加载前需要一个低成本的认证“是 / 否”探测时，请使用它。目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 暴露它。 +当设置、Doctor 或 configured-state 流程需要在完整渠道插件加载前进行低成本的认证是 / 否探测时，请使用它。目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 暴露它。 -`openclaw.channel.configuredState` 对低成本的仅环境变量配置检查使用相同结构： +`openclaw.channel.configuredState` 对低成本的仅环境变量 configured 检查采用相同结构： ```json { @@ -571,58 +568,57 @@ OpenClaw 按以下优先级处理： } ``` -当某个渠道可以仅通过环境变量或其他很小的非运行时输入来回答已配置状态时，请使用它。如果检查需要完整配置解析或真实的渠道运行时，则应将该逻辑保留在插件 `config.hasConfiguredState` hook 中。 +当渠道可以通过环境变量或其他轻量级非运行时输入来判断 configured-state 时，请使用它。如果检查需要完整配置解析或真实的渠道运行时，请将该逻辑保留在插件 `config.hasConfiguredState` hook 中。 -## 发现优先级（重复插件 id） +## 设备发现优先级（重复插件 id） -OpenClaw 会从多个根位置发现插件（内置、全局安装、工作区、配置中显式选择的路径）。如果两个发现结果共享相同的 `id`，则只保留**优先级最高**的清单；优先级较低的重复项会被丢弃，而不是与其并行加载。 +OpenClaw 会从多个根目录发现插件（内置、全局安装、工作区、配置中显式选择的路径）。如果两个发现结果共享同一个 `id`，则只保留**优先级最高**的清单；优先级较低的重复项会被丢弃，而不是与其并列加载。 优先级从高到低如下： -1. **配置选定** —— 在 `plugins.entries.` 中显式固定的路径 -2. **内置** —— 随 OpenClaw 一起发布的插件 -3. **全局安装** —— 安装到全局 OpenClaw 插件根目录的插件 -4. **工作区** —— 相对于当前工作区发现的插件 +1. **Config-selected** —— 在 `plugins.entries.` 中显式固定的路径 +2. **Bundled** —— 随 OpenClaw 一起发布的插件 +3. **Global install** —— 安装到全局 OpenClaw 插件根目录中的插件 +4. **Workspace** —— 相对于当前工作区发现的插件 -影响： +影响如下： -- 位于工作区中的某个内置插件 fork 或过时副本，不会遮蔽内置构建版本。 -- 如果你确实要用本地插件覆盖某个内置插件，应通过 `plugins.entries.` 固定它，使其凭借优先级获胜，而不是依赖工作区发现。 -- 重复项丢弃会被记录日志，这样 Doctor 和启动诊断就能指出被丢弃的副本。 +- 工作区中放置的内置插件分叉版本或陈旧副本不会遮蔽内置构建版本。 +- 若要真正用本地插件覆盖内置插件，请通过 `plugins.entries.` 固定它，使其凭优先级获胜，而不是依赖工作区发现。 +- 被丢弃的重复项会被记录日志，以便 Doctor 和启动诊断指出被舍弃的副本。 ## JSON Schema 要求 - **每个插件都必须提供一个 JSON Schema**，即使它不接受任何配置。 -- 允许使用空 schema（例如 `{ "type": "object", "additionalProperties": false }`）。 -- Schema 会在配置读取 / 写入时校验，而不是在运行时校验。 +- 空 schema 也是允许的（例如 `{ "type": "object", "additionalProperties": false }`）。 +- Schema 会在配置读写时验证，而不是在运行时验证。 -## 校验行为 +## 验证行为 -- 未知的 `channels.*` 键是**错误**，除非该渠道 id 由某个插件清单声明。 -- `plugins.entries.`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` - 必须引用**可发现的**插件 id。未知 id 属于**错误**。 -- 如果某个插件已安装，但其清单或 schema 缺失或损坏，则校验会失败，Doctor 会报告该插件错误。 -- 如果插件配置存在，但插件处于**禁用**状态，配置会被保留，并且 Doctor + 日志中会显示一条**警告**。 +- 未知的 `channels.*` 键会被视为**错误**，除非该渠道 id 已由某个插件清单声明。 +- `plugins.entries.`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现的**插件 id。未知 id 会被视为**错误**。 +- 如果插件已安装，但其清单或 schema 损坏或缺失，验证会失败，Doctor 会报告该插件错误。 +- 如果插件配置存在但插件**已禁用**，配置会被保留，并且会在 Doctor 和日志中显示**警告**。 -完整的 `plugins.*` schema 请参阅 [配置参考](/zh-CN/gateway/configuration)。 +完整的 `plugins.*` schema 请参阅[配置参考](/zh-CN/gateway/configuration)。 ## 说明 -- 对于**原生 OpenClaw 插件**，包括本地文件系统加载，清单都是**必需的**。运行时仍会单独加载插件模块；清单仅用于发现 + 校验。 -- 原生清单使用 JSON5 解析，因此允许注释、尾随逗号和未加引号的键，只要最终值仍是一个对象即可。 -- 清单加载器只会读取有文档说明的清单字段。避免使用自定义顶层键。 -- 当插件不需要时，`channels`、`providers`、`cliBackends` 和 `skills` 都可以省略。 -- `providerDiscoveryEntry` 必须保持轻量，不应导入庞大的运行时代码；应将其用于静态 provider 目录元数据或窄范围发现描述符，而不是请求时执行。 -- 排他性插件类型通过 `plugins.slots.*` 选择：`kind: "memory"` 通过 `plugins.slots.memory`，`kind: "context-engine"` 通过 `plugins.slots.contextEngine`（默认 `legacy`）。 -- 环境变量元数据（`providerAuthEnvVars`、`channelEnvVars`）仅具声明性。状态、审计、cron 投递校验和其他只读界面，在将环境变量视为已配置之前，仍会应用插件信任和有效激活策略。 -- 对于需要 provider 代码的运行时向导元数据，请参阅 [Provider runtime hooks](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 -- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器 allowlist 要求（例如 pnpm `allow-build-scripts` + `pnpm rebuild `）。 +- **原生 OpenClaw 插件必须提供清单**，包括本地文件系统加载。运行时仍会单独加载插件模块；清单仅用于设备发现 + 验证。 +- 原生清单使用 JSON5 解析，因此允许注释、尾随逗号和未加引号的键，只要最终值仍然是一个对象即可。 +- 清单加载器只会读取文档中记录的清单字段。避免使用自定义顶层键。 +- 当插件不需要它们时，`channels`、`providers`、`cliBackends` 和 `skills` 都可以省略。 +- `providerDiscoveryEntry` 必须保持轻量，不应导入宽泛的运行时代码；应将其用于静态 provider 目录元数据或窄范围的发现描述符，而不是请求时执行。 +- 独占插件类型通过 `plugins.slots.*` 选择：`kind: "memory"` 通过 `plugins.slots.memory`，`kind: "context-engine"` 通过 `plugins.slots.contextEngine`（默认 `legacy`）。 +- 环境变量元数据（`providerAuthEnvVars`、`channelEnvVars`）仅具有声明性。状态、审计、cron 投递验证以及其他只读界面，在将某个环境变量视为已配置前，仍会应用插件信任和有效激活策略。 +- 关于需要 provider 代码的运行时向导元数据，请参阅 [Provider runtime hooks](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 +- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器允许列表要求（例如 pnpm `allow-build-scripts` + `pnpm rebuild `）。 ## 相关内容 - 插件入门指南。 + 插件快速开始。 内部架构和能力模型。 diff --git a/docs/zh-CN/plugins/sdk-migration.md b/docs/zh-CN/plugins/sdk-migration.md index c91dd656e..92715b882 100644 --- a/docs/zh-CN/plugins/sdk-migration.md +++ b/docs/zh-CN/plugins/sdk-migration.md @@ -3,95 +3,109 @@ read_when: - 你看到了 `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` 警告 - 你看到了 `OPENCLAW_EXTENSION_API_DEPRECATED` 警告 - 你正在将插件更新到现代插件架构 - - 你维护一个外部 OpenClaw 插件 + - 你在维护一个外部 OpenClaw 插件 sidebarTitle: Migrate to SDK summary: 从旧版向后兼容层迁移到现代插件 SDK title: 插件 SDK 迁移 x-i18n: - generated_at: "2026-04-24T00:54:27Z" + generated_at: "2026-04-24T05:09:40Z" model: gpt-5.4 provider: openai - source_hash: d1b53d2e6c1a332c928aae62323619b3983a1b0b68ec178451bb5d3a0819585c + source_hash: d1612fbdc0e472a0ba1ae310ceeca9c672afa5a7eba77637b94726ef1fedee87 source_path: plugins/sdk-migration.md workflow: 15 --- -OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，后者提供聚焦且有文档说明的导入路径。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。 +OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，采用聚焦且有文档说明的导入方式。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。 ## 正在发生的变化 -旧版插件系统提供了两个开放范围很大的入口，使插件能够从单一入口点导入所需的任何内容： +旧版插件系统提供了两个开放度很高的接口，让插件可以通过单个入口点导入所需的任何内容： -- **`openclaw/plugin-sdk/compat`** — 一个单一导入路径，重新导出了数十个辅助工具。它的引入是为了在新插件架构构建期间，让较旧的基于 hook 的插件继续正常工作。 -- **`openclaw/extension-api`** — 一个桥接层，使插件可以直接访问宿主侧辅助工具，例如嵌入式 Pi 智能体运行器。 +- **`openclaw/plugin-sdk/compat`** —— 一个会重新导出数十个辅助工具的单一导入入口。它的引入是为了在构建新插件架构期间，保持较旧的基于 hook 的插件继续工作。 +- **`openclaw/extension-api`** —— 一个桥接层，让插件可以直接访问宿主端辅助工具，例如嵌入式智能体运行器。 -这两个入口现在都已**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。 +这两个接口现已**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。 + +OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解释已文档化的插件行为。破坏性契约变更必须先经过兼容适配器、诊断信息、文档以及弃用窗口。这适用于 SDK 导入、清单字段、设置 API、hooks 以及运行时注册行为。 - 向后兼容层将在未来的主版本中移除。 - 到那时，仍然从这些入口导入的插件将会失效。 + 向后兼容层将在未来的某个主版本中移除。到那时，仍从这些接口导入的插件将会失效。 ## 为什么会有这项变更 -旧方式会带来一些问题： +旧方法带来了这些问题： -- **启动缓慢** — 导入一个辅助工具会加载数十个无关模块 -- **循环依赖** — 宽泛的重新导出使创建导入循环变得很容易 -- **API 表面不清晰** — 无法区分哪些导出是稳定的，哪些是内部实现 +- **启动缓慢** —— 导入一个辅助工具会加载数十个无关模块 +- **循环依赖** —— 宽泛的重新导出使导入环很容易出现 +- **API 接口不清晰** —— 无法分辨哪些导出是稳定接口，哪些是内部实现 -现代插件 SDK 修复了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含的模块，具有清晰的用途和有文档说明的契约。 +现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、独立的模块，具有明确用途和文档化契约。 -针对内置渠道的旧版 provider 便捷接缝也已移除。诸如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、带渠道品牌的辅助工具接缝，以及 `openclaw/plugin-sdk/telegram-core` 之类的导入路径，都是私有 monorepo 快捷方式，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区中，请将 provider 自有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 +面向内置渠道的旧版 provider 便捷接口也已移除。诸如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、带渠道品牌的辅助接口，以及 `openclaw/plugin-sdk/telegram-core` 之类的导入，都是私有 monorepo 快捷方式，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区内部，应将 provider 自有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 -当前内置 provider 示例： +当前内置 provider 的示例： -- Anthropic 将 Claude 专用的流式辅助工具保留在它自己的 `api.ts` / `contract-api.ts` 接缝中 +- Anthropic 将 Claude 专用的流处理辅助工具保留在它自己的 `api.ts` / `contract-api.ts` 接口中 - OpenAI 将 provider 构建器、默认模型辅助工具和实时 provider 构建器保留在它自己的 `api.ts` 中 -- OpenRouter 将 provider 构建器以及新手引导 / 配置辅助工具保留在它自己的 `api.ts` 中 +- OpenRouter 将 provider 构建器以及新手引导/配置辅助工具保留在它自己的 `api.ts` 中 + +## 兼容性策略 + +对于外部插件，兼容性工作遵循以下顺序： + +1. 添加新契约 +2. 通过兼容适配器保留旧行为的接线方式 +3. 发出诊断信息或警告，明确指出旧路径及其替代方案 +4. 在测试中覆盖两种路径 +5. 记录弃用信息和迁移路径 +6. 仅在已宣布的迁移窗口结束后移除，通常是在主版本中 + +如果某个清单字段仍然被接受，那么在文档和诊断信息另有说明之前，插件作者可以继续使用它。新代码应优先采用文档化的替代方案，但现有插件不应在常规次版本发布中失效。 ## 如何迁移 - - 支持审批能力的渠道插件现在通过 `approvalCapability.nativeRuntime` 以及共享的运行时上下文注册表来暴露原生审批行为。 + + 具备审批能力的渠道插件现在通过 `approvalCapability.nativeRuntime` 加上共享的运行时上下文注册表来公开原生审批行为。 关键变更： - 将 `approvalCapability.handler.loadRuntime(...)` 替换为 `approvalCapability.nativeRuntime` - - 将审批专用的认证 / 投递逻辑从旧版 `plugin.auth` / `plugin.approvals` 接线迁移到 `approvalCapability` - - `ChannelPlugin.approvals` 已从公共渠道插件契约中移除；请将 delivery / native / render 字段迁移到 `approvalCapability` - - `plugin.auth` 仅保留用于渠道登录 / 登出流程；其中的审批认证 hook 不再由 core 读取 - - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道自有的运行时对象，例如客户端、令牌或 Bolt 应用 - - 不要从原生审批处理器发送插件自有的改道通知；core 现在会根据实际投递结果统一处理“已路由到其他位置”的通知 - - 在将 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 `createPluginRuntime().channel` 表面。部分 stub 会被拒绝。 + - 将审批专用的认证/投递逻辑从旧版 `plugin.auth` / `plugin.approvals` 接线迁移到 `approvalCapability` + - `ChannelPlugin.approvals` 已从公共渠道插件契约中移除；请将 delivery/native/render 字段迁移到 `approvalCapability` + - `plugin.auth` 仍仅用于渠道登录/登出流程；其中的审批认证 hooks 不再被核心读取 + - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册由渠道拥有的运行时对象，例如客户端、令牌或 Bolt 应用 + - 不要从原生审批处理器发送插件自有的 reroute 通知；核心现在会根据实际投递结果负责 routed-elsewhere 通知 + - 当把 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 `createPluginRuntime().channel` 接口。部分 stub 会被拒绝。 当前审批 capability 布局请参见 `/plugins/sdk-channel-plugins`。 - 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，那么在 Windows 上，未解析的 `.cmd` / `.bat` 包装器现在会默认以关闭方式失败，除非你显式传入 `allowShellFallback: true`。 + 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，现在在无法解析 Windows `.cmd`/`.bat` 包装器时，会默认直接失败，除非你显式传入 `allowShellFallback: true`。 ```typescript - // 之前 + // Before const program = applyWindowsSpawnProgramPolicy({ candidate }); - // 之后 + // After const program = applyWindowsSpawnProgramPolicy({ candidate, - // 仅当受信任的兼容性调用方明确接受由 shell 介导的回退时， - // 才设置此项。 + // Only set this for trusted compatibility callers that intentionally + // accept shell-mediated fallback. allowShellFallback: true, }); ``` - 如果你的调用方并非有意依赖 shell 回退，请不要设置 `allowShellFallback`，而是改为处理抛出的错误。 + 如果你的调用方并非有意依赖 shell 回退，请不要设置 `allowShellFallback`，而应改为处理抛出的错误。 - 在你的插件中搜索是否从任一已弃用入口导入： + 在你的插件中搜索是否从以下任一已弃用接口导入： ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -101,36 +115,36 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，后者提 - 旧入口中的每个导出都对应一个特定的现代导入路径： + 旧接口中的每个导出，都映射到一个特定的现代导入路径： ```typescript - // 之前（已弃用的向后兼容层） + // Before (deprecated backwards-compatibility layer) import { createChannelReplyPipeline, createPluginRuntimeStore, resolveControlCommandGate, } from "openclaw/plugin-sdk/compat"; - // 之后（现代聚焦导入） + // After (modern focused imports) import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - 对于宿主侧辅助工具，请使用注入的插件运行时，而不是直接导入： + 对于宿主端辅助工具，请使用注入的插件运行时，而不是直接导入： ```typescript - // 之前（已弃用的 extension-api 桥接层） + // Before (deprecated extension-api bridge) import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); - // 之后（注入的运行时） + // After (injected runtime) const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - 其他旧版桥接辅助工具也适用相同模式： + 同样的模式也适用于其他旧版桥接辅助工具： - | 旧导入 | 现代等价写法 | + | 旧导入 | 现代等价项 | | --- | --- | | `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` | | `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` | @@ -156,205 +170,205 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，后者提 | 导入路径 | 用途 | 关键导出 | | --- | --- | --- | | `plugin-sdk/plugin-entry` | 规范的插件入口辅助工具 | `definePluginEntry` | - | `plugin-sdk/core` | 用于渠道入口定义 / 构建器的旧版总括式重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | 根配置模式导出 | `OpenClawSchema` | + | `plugin-sdk/core` | 面向渠道入口定义/构建器的旧版聚合重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` | | `plugin-sdk/provider-entry` | 单一 provider 入口辅助工具 | `defineSingleProviderPluginEntry` | | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | 共享的设置向导辅助工具 | 允许列表提示、设置状态构建器 | - | `plugin-sdk/setup-runtime` | 设置时运行时辅助工具 | 可安全导入的设置补丁适配器、查找说明辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托式设置代理 | + | `plugin-sdk/setup` | 共享的设置向导辅助工具 | allowlist 提示、设置状态构建器 | + | `plugin-sdk/setup-runtime` | 设置时运行时辅助工具 | 可安全导入的设置补丁适配器、lookup note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托式设置代理 | | `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助工具 | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | 设置工具辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表 / 配置 / 操作门控辅助工具 | - | `plugin-sdk/account-id` | 账户 ID 辅助工具 | `DEFAULT_ACCOUNT_ID`、账户 ID 规范化 | + | `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表/配置/操作门控辅助工具 | + | `plugin-sdk/account-id` | account-id 辅助工具 | `DEFAULT_ACCOUNT_ID`、account-id 标准化 | | `plugin-sdk/account-resolution` | 账户查找辅助工具 | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表 / 账户操作辅助工具 | - | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` | - | `plugin-sdk/channel-pairing` | 私信配对原语 | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 正在输入状态接线 | `createChannelReplyPipeline` | + | `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表/账户操作辅助工具 | + | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/channel-pairing` | 私信配对基础组件 | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 正在输入接线 | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | 配置模式构建器 | 渠道配置模式类型 | - | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名称规范化、描述裁剪、重复 / 冲突校验 | - | `plugin-sdk/channel-policy` | 群组 / 私信策略解析 | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | 账户状态和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览最终化辅助工具 | - | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享路由 + envelope 构建器辅助工具 | - | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录与分发辅助工具 | - | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析 / 匹配辅助工具 | + | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 渠道配置 schema 类型 | + | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名标准化、描述裁剪、重复/冲突校验 | + | `plugin-sdk/channel-policy` | 群组/私信策略解析 | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-lifecycle` | 账户状态和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览终结辅助工具 | + | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享路由 + envelope 构建辅助工具 | + | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录并分发辅助工具 | + | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析/匹配辅助工具 | | `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享出站媒体加载 | - | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站身份 / 发送委托和负载规划辅助工具 | + | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站身份/发送委托和负载规划辅助工具 | | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 | - | `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 用于旧字段布局的智能体媒体负载构建器 | - | `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅旧版渠道运行时工具 | + | `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 面向旧字段布局的智能体媒体负载构建器 | + | `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅保留旧版渠道运行时工具 | | `plugin-sdk/channel-send-result` | 发送结果类型 | 回复结果类型 | | `plugin-sdk/runtime-store` | 持久化插件存储 | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | 宽范围运行时辅助工具 | 运行时 / 日志 / 备份 / 插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | 日志器 / 运行时环境、超时、重试和退避辅助工具 | - | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令 / hooks / HTTP / 交互式辅助工具 | - | `plugin-sdk/hook-runtime` | Hook 管道辅助工具 | 共享 webhook / 内部 hook 管道辅助工具 | + | `plugin-sdk/runtime` | 宽范围运行时辅助工具 | 运行时/日志/备份/插件安装辅助工具 | + | `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | 日志器/运行时环境、超时、重试和退避辅助工具 | + | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令/hooks/http/交互式辅助工具 | + | `plugin-sdk/hook-runtime` | hook 管道辅助工具 | 共享 webhook/内部 hook 管道辅助工具 | | `plugin-sdk/lazy-runtime` | 惰性运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | 进程辅助工具 | 共享 exec 辅助工具 | | `plugin-sdk/cli-runtime` | CLI 运行时辅助工具 | 命令格式化、等待、版本辅助工具 | | `plugin-sdk/gateway-runtime` | Gateway 网关辅助工具 | Gateway 网关客户端和渠道状态补丁辅助工具 | - | `plugin-sdk/config-runtime` | 配置辅助工具 | 配置加载 / 写入辅助工具 | - | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约表面不可用时，提供具有稳定回退能力的 Telegram 命令校验辅助工具 | - | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec / 插件审批负载、审批 capability / profile 辅助工具、原生审批路由 / 运行时辅助工具 | - | `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | 审批人解析、同聊天操作认证 | - | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批 profile / 过滤器辅助工具 | - | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批 capability / 投递适配器 | + | `plugin-sdk/config-runtime` | 配置辅助工具 | 配置加载/写入辅助工具 | + | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约接口不可用时，提供回退稳定的 Telegram 命令校验辅助工具 | + | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec/插件审批负载、审批 capability/profile 辅助工具、原生审批路由/运行时辅助工具 | + | `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | approver 解析、同聊天操作认证 | + | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批 profile/filter 辅助工具 | + | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批 capability/投递适配器 | | `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关辅助工具 | 共享审批 Gateway 网关解析辅助工具 | - | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 用于高频渠道入口点的轻量级原生审批适配器加载辅助工具 | - | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽范围的审批处理器运行时辅助工具；如果更窄的 adapter / gateway 接缝已足够，请优先使用它们 | - | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标 / 账户绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec / 插件审批回复负载辅助工具 | - | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register / get / watch 辅助工具 | - | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和密钥收集辅助工具 | - | `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机允许列表和私有网络策略辅助工具 | + | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 面向高频渠道入口点的轻量级原生审批适配器加载辅助工具 | + | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽范围的审批处理器运行时辅助工具；如果更窄的 adapter/gateway 接口已足够，应优先使用它们 | + | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标/账户绑定辅助工具 | + | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec/插件审批回复负载辅助工具 | + | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register/get/watch 辅助工具 | + | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和敏感信息收集辅助工具 | + | `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机 allowlist 和私有网络策略辅助工具 | | `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | 固定 dispatcher、受保护 fetch、SSRF 策略辅助工具 | | `plugin-sdk/collection-runtime` | 有界缓存辅助工具 | `pruneMapToMaxSize` | | `plugin-sdk/diagnostic-runtime` | 诊断门控辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | | `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助工具 | - | `plugin-sdk/fetch-runtime` | 包装的 fetch / 代理辅助工具 | `resolveFetch`、代理辅助工具 | - | `plugin-sdk/host-runtime` | 宿主规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/fetch-runtime` | 封装的 fetch/代理辅助工具 | `resolveFetch`、代理辅助工具 | + | `plugin-sdk/host-runtime` | 主机标准化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` | | `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`、策略运行器 | - | `plugin-sdk/allow-from` | 允许列表格式化 | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | 允许列表输入映射 | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | 命令门控和命令表面辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具 | - | `plugin-sdk/command-status` | 命令状态 / 帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | 密钥输入解析 | 密钥输入辅助工具 | - | `plugin-sdk/webhook-ingress` | Webhook 请求辅助工具 | Webhook 目标工具 | - | `plugin-sdk/webhook-request-guards` | Webhook 请求体保护辅助工具 | 请求体读取 / 限制辅助工具 | + | `plugin-sdk/allow-from` | allowlist 格式化 | `formatAllowFromLowercase` | + | `plugin-sdk/allowlist-resolution` | allowlist 输入映射 | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | 命令门控和命令接口辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具 | + | `plugin-sdk/command-status` | 命令状态/帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | + | `plugin-sdk/secret-input` | 敏感信息输入解析 | 敏感信息输入辅助工具 | + | `plugin-sdk/webhook-ingress` | webhook 请求辅助工具 | webhook 目标工具 | + | `plugin-sdk/webhook-request-guards` | webhook 请求体保护辅助工具 | 请求体读取/限制辅助工具 | | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 | - | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | 最终化 + provider 分发辅助工具 | + | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | 终结 + provider 分发辅助工具 | | `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | 回复引用规划 | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本 / markdown 分块辅助工具 | + | `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本/Markdown 分块辅助工具 | | `plugin-sdk/session-store-runtime` | 会话存储辅助工具 | 存储路径 + updated-at 辅助工具 | | `plugin-sdk/state-paths` | 状态路径辅助工具 | 状态和 OAuth 目录辅助工具 | - | `plugin-sdk/routing` | 路由 / 会话键辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键规范化辅助工具 | - | `plugin-sdk/status-helpers` | 渠道状态辅助工具 | 渠道 / 账户状态摘要构建器、运行时状态默认值、问题元数据辅助工具 | + | `plugin-sdk/routing` | 路由/会话键辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键标准化辅助工具 | + | `plugin-sdk/status-helpers` | 渠道状态辅助工具 | 渠道/账户状态摘要构建器、运行时状态默认值、问题元数据辅助工具 | | `plugin-sdk/target-resolver-runtime` | 目标解析器辅助工具 | 共享目标解析器辅助工具 | - | `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助工具 | slug / 字符串规范化辅助工具 | - | `plugin-sdk/request-url` | 请求 URL 辅助工具 | 从类似请求的输入中提取字符串 URL | - | `plugin-sdk/run-command` | 定时命令辅助工具 | 带标准化 stdout / stderr 的定时命令运行器 | - | `plugin-sdk/param-readers` | 参数读取器 | 通用工具 / CLI 参数读取器 | + | `plugin-sdk/string-normalization-runtime` | 字符串标准化辅助工具 | slug/字符串标准化辅助工具 | + | `plugin-sdk/request-url` | 请求 URL 辅助工具 | 从类请求输入中提取字符串 URL | + | `plugin-sdk/run-command` | 定时命令辅助工具 | 具有标准化 stdout/stderr 的定时命令运行器 | + | `plugin-sdk/param-readers` | 参数读取器 | 常用工具/CLI 参数读取器 | | `plugin-sdk/tool-payload` | 工具负载提取 | 从工具结果对象中提取标准化负载 | - | `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范的发送目标字段 | + | `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范发送目标字段 | | `plugin-sdk/temp-path` | 临时路径辅助工具 | 共享临时下载路径辅助工具 | | `plugin-sdk/logging-core` | 日志辅助工具 | 子系统日志器和脱敏辅助工具 | | `plugin-sdk/markdown-table-runtime` | Markdown 表格辅助工具 | Markdown 表格模式辅助工具 | | `plugin-sdk/reply-payload` | 消息回复类型 | 回复负载类型 | - | `plugin-sdk/provider-setup` | 精选的本地 / 自托管 provider 设置辅助工具 | 自托管 provider 发现 / 配置辅助工具 | - | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管 provider 设置辅助工具 | 同样的自托管 provider 发现 / 配置辅助工具 | - | `plugin-sdk/provider-auth-runtime` | provider 运行时认证辅助工具 | 运行时 API 密钥解析辅助工具 | - | `plugin-sdk/provider-auth-api-key` | provider API 密钥设置辅助工具 | API 密钥新手引导 / profile 写入辅助工具 | + | `plugin-sdk/provider-setup` | 精选的本地/自托管 provider 设置辅助工具 | 自托管 provider 发现/配置辅助工具 | + | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管 provider 设置辅助工具 | 与上相同的自托管 provider 发现/配置辅助工具 | + | `plugin-sdk/provider-auth-runtime` | provider 运行时认证辅助工具 | 运行时 API key 解析辅助工具 | + | `plugin-sdk/provider-auth-api-key` | provider API key 设置辅助工具 | API key 新手引导/profile 写入辅助工具 | | `plugin-sdk/provider-auth-result` | provider auth-result 辅助工具 | 标准 OAuth auth-result 构建器 | | `plugin-sdk/provider-auth-login` | provider 交互式登录辅助工具 | 共享交互式登录辅助工具 | | `plugin-sdk/provider-selection-runtime` | provider 选择辅助工具 | 已配置或自动 provider 选择，以及原始 provider 配置合并 | | `plugin-sdk/provider-env-vars` | provider 环境变量辅助工具 | provider 认证环境变量查找辅助工具 | - | `plugin-sdk/provider-model-shared` | 共享 provider 模型 / 重放辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略构建器、provider 端点辅助工具，以及模型 ID 规范化辅助工具 | + | `plugin-sdk/provider-model-shared` | 共享 provider 模型/重放辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略构建器、provider 端点辅助工具，以及 model-id 标准化辅助工具 | | `plugin-sdk/provider-catalog-shared` | 共享 provider 目录辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | | `plugin-sdk/provider-onboard` | provider 新手引导补丁 | 新手引导配置辅助工具 | - | `plugin-sdk/provider-http` | provider HTTP 辅助工具 | 通用 provider HTTP / 端点 capability 辅助工具，包括音频转录 multipart form 辅助工具 | - | `plugin-sdk/provider-web-fetch` | provider web-fetch 辅助工具 | web-fetch provider 注册 / 缓存辅助工具 | - | `plugin-sdk/provider-web-search-config-contract` | provider web-search 配置辅助工具 | 为不需要插件启用接线的 provider 提供窄范围 web-search 配置 / 凭证辅助工具 | - | `plugin-sdk/provider-web-search-contract` | provider web-search 契约辅助工具 | 窄范围 web-search 配置 / 凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig`，以及作用域化凭证 setter / getter | - | `plugin-sdk/provider-web-search` | provider web-search 辅助工具 | web-search provider 注册 / 缓存 / 运行时辅助工具 | - | `plugin-sdk/provider-tools` | provider 工具 / schema 兼容性辅助工具 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | provider 用量辅助工具 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage`，以及其他 provider 用量辅助工具 | - | `plugin-sdk/provider-stream` | provider 流包装辅助工具 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装辅助工具 | - | `plugin-sdk/provider-transport-runtime` | provider 传输辅助工具 | 原生 provider 传输辅助工具，例如受保护 fetch、传输消息转换和可写传输事件流 | + | `plugin-sdk/provider-http` | provider HTTP 辅助工具 | 通用 provider HTTP/端点 capability 辅助工具，包括音频转录 multipart form 辅助工具 | + | `plugin-sdk/provider-web-fetch` | provider web-fetch 辅助工具 | web-fetch provider 注册/缓存辅助工具 | + | `plugin-sdk/provider-web-search-config-contract` | provider web-search 配置辅助工具 | 面向不需要插件启用接线的 provider 的窄范围 web-search 配置/凭证辅助工具 | + | `plugin-sdk/provider-web-search-contract` | provider web-search 契约辅助工具 | 窄范围 web-search 配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域化的凭证 setter/getter | + | `plugin-sdk/provider-web-search` | provider web-search 辅助工具 | web-search provider 注册/缓存/运行时辅助工具 | + | `plugin-sdk/provider-tools` | provider 工具/schema 兼容辅助工具 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容辅助工具，如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | provider 用量辅助工具 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` 以及其他 provider 用量辅助工具 | + | `plugin-sdk/provider-stream` | provider 流包装辅助工具 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装辅助工具 | + | `plugin-sdk/provider-transport-runtime` | provider 传输辅助工具 | 原生 provider 传输辅助工具，例如受保护的 fetch、传输消息转换，以及可写的传输事件流 | | `plugin-sdk/keyed-async-queue` | 有序异步队列 | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取 / 转换 / 存储辅助工具，以及媒体负载构建器 | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 图像 / 视频 / 音乐生成的共享故障转移辅助工具、候选项选择和缺失模型提示 | - | `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解 provider 类型，以及面向 provider 的图像 / 音频辅助工具导出 | - | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 面向助手可见文本剥离、 markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、指令标签辅助工具、安全文本工具，以及相关文本 / 日志辅助工具 | + | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取/转换/存储辅助工具，以及媒体负载构建器 | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 图像/视频/音乐生成的共享故障转移辅助工具、候选选择和缺失模型提示 | + | `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解 provider 类型，以及面向 provider 的图像/音频辅助工具导出 | + | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 面向助手可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive 标签辅助工具、安全文本工具，以及相关文本/日志辅助工具 | | `plugin-sdk/text-chunking` | 文本分块辅助工具 | 出站文本分块辅助工具 | - | `plugin-sdk/speech` | 语音辅助工具 | 语音 provider 类型，以及面向 provider 的指令、注册表和校验辅助工具 | - | `plugin-sdk/speech-core` | 共享语音核心 | 语音 provider 类型、注册表、指令、规范化 | - | `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | provider 类型、注册表辅助工具和共享 WebSocket 会话辅助工具 | - | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型、注册表 / 解析辅助工具，以及桥接会话辅助工具 | + | `plugin-sdk/speech` | 语音辅助工具 | 语音 provider 类型，以及面向 provider 的 directive、注册表和校验辅助工具 | + | `plugin-sdk/speech-core` | 共享语音核心 | 语音 provider 类型、注册表、directives、标准化 | + | `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | provider 类型、注册表辅助工具，以及共享 WebSocket 会话辅助工具 | + | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型、注册表/解析辅助工具，以及桥接会话辅助工具 | | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、认证和注册表辅助工具 | - | `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成 provider / 请求 / 结果类型 | + | `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成 provider/请求/结果类型 | | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障转移辅助工具、provider 查找和 model-ref 解析 | - | `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成 provider / 请求 / 结果类型 | + | `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成 provider/请求/结果类型 | | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移辅助工具、provider 查找和 model-ref 解析 | - | `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复负载规范化 / 归约 | - | `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄范围渠道 config-schema 原语 | + | `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复负载标准化/归约 | + | `plugin-sdk/channel-config-primitives` | 渠道配置基础组件 | 窄范围渠道 config-schema 基础组件 | | `plugin-sdk/channel-config-writes` | 渠道配置写入辅助工具 | 渠道配置写入授权辅助工具 | | `plugin-sdk/channel-plugin-common` | 共享渠道前导模块 | 共享渠道插件前导模块导出 | - | `plugin-sdk/channel-status` | 渠道状态辅助工具 | 共享渠道状态快照 / 摘要辅助工具 | - | `plugin-sdk/allowlist-config-edit` | 允许列表配置辅助工具 | 允许列表配置编辑 / 读取辅助工具 | + | `plugin-sdk/channel-status` | 渠道状态辅助工具 | 共享渠道状态快照/摘要辅助工具 | + | `plugin-sdk/allowlist-config-edit` | allowlist 配置辅助工具 | allowlist 配置编辑/读取辅助工具 | | `plugin-sdk/group-access` | 群组访问辅助工具 | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证 / 保护辅助工具 | - | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道 / 状态和环境代理辅助原语 | - | `plugin-sdk/webhook-targets` | Webhook 目标辅助工具 | Webhook 目标注册表和路由安装辅助工具 | - | `plugin-sdk/webhook-path` | Webhook 路径辅助工具 | Webhook 路径规范化辅助工具 | - | `plugin-sdk/web-media` | 共享 Web 媒体辅助工具 | 远程 / 本地媒体加载辅助工具 | - | `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用者重新导出的 `zod` | - | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | Memory 管理器 / 配置 / 文件 / CLI 辅助工具表面 | - | `plugin-sdk/memory-core-engine-runtime` | Memory 引擎运行时门面 | Memory 索引 / 搜索运行时门面 | + | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证/保护辅助工具 | + | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道/状态和环境代理辅助工具基础组件 | + | `plugin-sdk/webhook-targets` | webhook 目标辅助工具 | webhook 目标注册表和路由安装辅助工具 | + | `plugin-sdk/webhook-path` | webhook 路径辅助工具 | webhook 路径标准化辅助工具 | + | `plugin-sdk/web-media` | 共享 web 媒体辅助工具 | 远程/本地媒体加载辅助工具 | + | `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用方重新导出的 `zod` | + | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | Memory 管理器/配置/文件/CLI 辅助工具接口 | + | `plugin-sdk/memory-core-engine-runtime` | Memory 引擎运行时门面 | Memory 索引/搜索运行时门面 | | `plugin-sdk/memory-core-host-engine-foundation` | Memory 宿主基础引擎 | Memory 宿主基础引擎导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 宿主嵌入引擎 | Memory 嵌入契约、注册表访问、本地 provider 和通用批处理 / 远程辅助工具；具体远程 provider 位于其所属插件中 | + | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 宿主嵌入引擎 | Memory 嵌入契约、注册表访问、本地 provider 和通用批处理/远程辅助工具；具体远程 provider 位于其所属插件中 | | `plugin-sdk/memory-core-host-engine-qmd` | Memory 宿主 QMD 引擎 | Memory 宿主 QMD 引擎导出 | | `plugin-sdk/memory-core-host-engine-storage` | Memory 宿主存储引擎 | Memory 宿主存储引擎导出 | | `plugin-sdk/memory-core-host-multimodal` | Memory 宿主多模态辅助工具 | Memory 宿主多模态辅助工具 | | `plugin-sdk/memory-core-host-query` | Memory 宿主查询辅助工具 | Memory 宿主查询辅助工具 | - | `plugin-sdk/memory-core-host-secret` | Memory 宿主密钥辅助工具 | Memory 宿主密钥辅助工具 | + | `plugin-sdk/memory-core-host-secret` | Memory 宿主敏感信息辅助工具 | Memory 宿主敏感信息辅助工具 | | `plugin-sdk/memory-core-host-events` | Memory 宿主事件日志辅助工具 | Memory 宿主事件日志辅助工具 | | `plugin-sdk/memory-core-host-status` | Memory 宿主状态辅助工具 | Memory 宿主状态辅助工具 | | `plugin-sdk/memory-core-host-runtime-cli` | Memory 宿主 CLI 运行时 | Memory 宿主 CLI 运行时辅助工具 | | `plugin-sdk/memory-core-host-runtime-core` | Memory 宿主核心运行时 | Memory 宿主核心运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory 宿主文件 / 运行时辅助工具 | Memory 宿主文件 / 运行时辅助工具 | - | `plugin-sdk/memory-host-core` | Memory 宿主核心运行时别名 | 面向供应商中立的 Memory 宿主核心运行时辅助工具别名 | - | `plugin-sdk/memory-host-events` | Memory 宿主事件日志别名 | 面向供应商中立的 Memory 宿主事件日志辅助工具别名 | - | `plugin-sdk/memory-host-files` | Memory 宿主文件 / 运行时别名 | 面向供应商中立的 Memory 宿主文件 / 运行时辅助工具别名 | - | `plugin-sdk/memory-host-markdown` | 托管 markdown 辅助工具 | 面向 Memory 相邻插件的共享托管 markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 活跃 Memory 搜索门面 | 惰性活跃 Memory 搜索管理器运行时门面 | - | `plugin-sdk/memory-host-status` | Memory 宿主状态别名 | 面向供应商中立的 Memory 宿主状态辅助工具别名 | - | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助工具 | Memory-lancedb 辅助工具表面 | - | `plugin-sdk/testing` | 测试工具 | 测试辅助工具和 mock | + | `plugin-sdk/memory-core-host-runtime-files` | Memory 宿主文件/运行时辅助工具 | Memory 宿主文件/运行时辅助工具 | + | `plugin-sdk/memory-host-core` | Memory 宿主核心运行时别名 | 面向 vendor-neutral 的 Memory 宿主核心运行时辅助工具别名 | + | `plugin-sdk/memory-host-events` | Memory 宿主事件日志别名 | 面向 vendor-neutral 的 Memory 宿主事件日志辅助工具别名 | + | `plugin-sdk/memory-host-files` | Memory 宿主文件/运行时别名 | 面向 vendor-neutral 的 Memory 宿主文件/运行时辅助工具别名 | + | `plugin-sdk/memory-host-markdown` | 托管 Markdown 辅助工具 | 面向 Memory 邻接插件的共享托管 Markdown 辅助工具 | + | `plugin-sdk/memory-host-search` | 活跃 Memory 搜索门面 | 惰性 active-memory search-manager 运行时门面 | + | `plugin-sdk/memory-host-status` | Memory 宿主状态别名 | 面向 vendor-neutral 的 Memory 宿主状态辅助工具别名 | + | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助工具 | Memory-lancedb 辅助工具接口 | + | `plugin-sdk/testing` | 测试工具 | 测试辅助工具和 mocks | -此表刻意只包含常见迁移子集，而不是完整的 SDK 表面。完整的 200 多个入口点列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 +此表有意只包含常见迁移子集，而非完整的 SDK 接口。完整的 200+ 入口点列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 -该列表仍然包含一些内置插件辅助工具接缝，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些导出仍然保留，用于内置插件维护和兼容性，但它们被有意省略在常见迁移表之外，也不是新插件代码的推荐目标。 +该列表仍包含一些内置插件辅助接口，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些接口仍会为内置插件维护和兼容性而继续导出，但它们被有意省略在常见迁移表之外，也不是新插件代码的推荐目标。 -同样的规则也适用于其他内置辅助工具家族，例如： +同样的规则也适用于其他内置辅助工具族，例如： - 浏览器支持辅助工具：`plugin-sdk/browser-cdp`、`plugin-sdk/browser-config-runtime`、`plugin-sdk/browser-config-support`、`plugin-sdk/browser-control-auth`、`plugin-sdk/browser-node-runtime`、`plugin-sdk/browser-profiles`、`plugin-sdk/browser-security-runtime`、`plugin-sdk/browser-setup-tools`、`plugin-sdk/browser-support` - Matrix：`plugin-sdk/matrix*` - LINE：`plugin-sdk/line*` - IRC：`plugin-sdk/irc*` -- 内置辅助工具 / 插件表面，例如 `plugin-sdk/googlechat`、`plugin-sdk/zalouser`、`plugin-sdk/bluebubbles*`、`plugin-sdk/mattermost*`、`plugin-sdk/msteams`、`plugin-sdk/nextcloud-talk`、`plugin-sdk/nostr`、`plugin-sdk/tlon`、`plugin-sdk/twitch`、`plugin-sdk/github-copilot-login`、`plugin-sdk/github-copilot-token`、`plugin-sdk/diagnostics-otel`、`plugin-sdk/diffs`、`plugin-sdk/llm-task`、`plugin-sdk/thread-ownership` 和 `plugin-sdk/voice-call` +- 内置辅助工具/插件接口，例如 `plugin-sdk/googlechat`、`plugin-sdk/zalouser`、`plugin-sdk/bluebubbles*`、`plugin-sdk/mattermost*`、`plugin-sdk/msteams`、`plugin-sdk/nextcloud-talk`、`plugin-sdk/nostr`、`plugin-sdk/tlon`、`plugin-sdk/twitch`、`plugin-sdk/github-copilot-login`、`plugin-sdk/github-copilot-token`、`plugin-sdk/diagnostics-otel`、`plugin-sdk/diffs`、`plugin-sdk/llm-task`、`plugin-sdk/thread-ownership` 和 `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` 当前公开的是窄范围 token 辅助工具表面：`DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。 +`plugin-sdk/github-copilot-token` 当前公开的是窄范围令牌辅助接口：`DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。 -请使用与任务最匹配的最窄导入路径。如果你找不到某个导出，请检查 `src/plugin-sdk/` 下的源码，或在 Discord 中提问。 +请使用与任务最匹配的最窄导入路径。如果你找不到某个导出，请查看 `src/plugin-sdk/` 下的源码，或在 Discord 中询问。 ## 移除时间线 | 时间 | 会发生什么 | | ---------------------- | ----------------------------------------------------------------------- | -| **现在** | 已弃用入口会发出运行时警告 | -| **下一个主版本** | 已弃用入口将被移除；仍在使用它们的插件将会失效 | +| **现在** | 已弃用接口会发出运行时警告 | +| **下一个主版本发布** | 已弃用接口将被移除；仍在使用它们的插件将会失效 | -所有 core 插件都已完成迁移。外部插件应在下一个主版本发布前完成迁移。 +所有核心插件都已经完成迁移。外部插件应在下一个主版本发布之前完成迁移。 ## 临时抑制警告 -在迁移过程中，可设置以下环境变量： +在你进行迁移期间，可以设置这些环境变量： ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -这只是临时的应急出口，不是永久解决方案。 +这只是一个临时逃生口，不是永久解决方案。 ## 相关内容 -- [入门指南](/zh-CN/plugins/building-plugins) — 构建你的第一个插件 -- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考 -- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件 -- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建 provider 插件 -- [插件内部机制](/zh-CN/plugins/architecture) — 架构深度解析 -- [插件清单](/zh-CN/plugins/manifest) — 清单 schema 参考 +- [入门指南](/zh-CN/plugins/building-plugins) —— 构建你的第一个插件 +- [SDK 概览](/zh-CN/plugins/sdk-overview) —— 完整子路径导入参考 +- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) —— 构建渠道插件 +- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) —— 构建提供商插件 +- [插件内部机制](/zh-CN/plugins/architecture) —— 架构深入解析 +- [插件清单](/zh-CN/plugins/manifest) —— 清单 schema 参考