From 5997aa412cf9ab988cb4600a7cd1da1309bc215e Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 21 Apr 2026 17:56:25 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/plugins/manifest.md | 261 +++++++++++----------- docs/zh-CN/plugins/sdk-channel-plugins.md | 229 ++++++++++--------- 2 files changed, 246 insertions(+), 244 deletions(-) diff --git a/docs/zh-CN/plugins/manifest.md b/docs/zh-CN/plugins/manifest.md index 27e8b9a4e..d9a47b3e4 100644 --- a/docs/zh-CN/plugins/manifest.md +++ b/docs/zh-CN/plugins/manifest.md @@ -1,14 +1,14 @@ --- read_when: - 你正在构建一个 OpenClaw 插件 - - 你需要发布一个插件配置模式，或调试插件校验错误 -summary: 插件清单 + JSON 模式要求（严格配置校验） + - 你需要发布一个插件配置 schema，或调试插件校验错误 +summary: 插件清单 + JSON schema 要求（严格配置校验） title: 插件清单 x-i18n: - generated_at: "2026-04-18T20:10:17Z" + generated_at: "2026-04-21T17:54:51Z" model: gpt-5.4 provider: openai - source_hash: 2dfc00759108ddee7bfcda8c42acf7f2d47451676447ba3caf8b5950f8a1c181 + source_hash: 304c08035724dfb1ce6349972729b621aafc00880d4d259db78c22b86e9056ba source_path: plugins/manifest.md workflow: 15 --- @@ -17,23 +17,22 @@ x-i18n: 本页仅适用于**原生 OpenClaw 插件清单**。 -有关兼容的 bundle 布局，请参见 [插件 bundle](/zh-CN/plugins/bundles)。 +如需了解兼容的 bundle 布局，请参见 [插件 bundle](/zh-CN/plugins/bundles)。 兼容的 bundle 格式使用不同的清单文件： - Codex bundle：`.codex-plugin/plugin.json` -- Claude bundle：`.claude-plugin/plugin.json` 或不含清单的默认 Claude 组件布局 +- Claude bundle：`.claude-plugin/plugin.json`，或不带清单文件的默认 Claude 组件布局 - Cursor bundle：`.cursor-plugin/plugin.json` -OpenClaw 也会自动检测这些 bundle 布局，但不会根据此处描述的 `openclaw.plugin.json` 模式对它们进行校验。 +OpenClaw 也会自动检测这些 bundle 布局，但不会根据这里所述的 `openclaw.plugin.json` schema 对它们进行校验。 -对于兼容 bundle，OpenClaw 当前会在布局符合 OpenClaw 运行时预期时，读取 bundle 元数据，以及声明的 skill 根目录、Claude 命令根目录、Claude bundle 的 `settings.json` 默认值、Claude bundle 的 LSP 默认值，以及支持的 hook 包。 +对于兼容 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 使用这个清单在**不执行插件代码的情况下**验证配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。 参见完整的插件系统指南：[插件](/zh-CN/tools/plugin)。 -有关原生能力模型和当前外部兼容性指导，请参见： -[能力模型](/zh-CN/plugins/architecture#public-capability-model)。 +关于原生能力模型和当前的外部兼容性指引，请参见：[能力模型](/zh-CN/plugins/architecture#public-capability-model)。 ## 这个文件的作用 @@ -43,14 +42,14 @@ OpenClaw 也会自动检测这些 bundle 布局，但不会根据此处描述的 - 插件标识 - 配置校验 -- 无需启动插件运行时即可使用的认证和新手引导元数据 -- 供控制平面界面在运行时加载前检查的轻量激活提示 -- 供设置 / 新手引导界面在运行时加载前检查的轻量设置描述符 -- 在插件运行时加载前应解析完成的别名和自动启用元数据 -- 在运行时加载前应自动激活插件的简写模型家族归属元数据 -- 用于内置兼容性接线和契约覆盖的静态能力归属快照 -- 共享 `openclaw qa` 主机可在插件运行时加载前检查的轻量 QA 运行器元数据 -- 应合并到目录和校验界面中、且无需加载运行时的渠道特定配置元数据 +- 可在不启动插件运行时的情况下获取的认证和新手引导元数据 +- 控制平面界面可在运行时加载前检查的低成本激活提示 +- 设置 / 新手引导界面可在运行时加载前检查的低成本设置描述符 +- 应在插件运行时加载前解析的别名和自动启用元数据 +- 应在插件运行时加载前自动激活插件的模型家族简写归属元数据 +- 用于内置兼容接线和契约覆盖的静态能力归属快照 +- 共享 `openclaw qa` 宿主可在插件运行时加载前检查的低成本 QA 运行器元数据 +- 应在不加载运行时的情况下合并进目录和校验界面的渠道专用配置元数据 - 配置 UI 提示 不要将它用于： @@ -141,62 +140,62 @@ OpenClaw 也会自动检测这些 bundle 布局，但不会根据此处描述的 | 字段 | 必填 | 类型 | 含义 | | ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | 是 | `string` | 规范插件 id。这是 `plugins.entries.` 中使用的 id。 | +| `id` | 是 | `string` | 规范插件 id。这是在 `plugins.entries.` 中使用的 id。 | | `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 | -| `enabledByDefault` | 否 | `true` | 将一个内置插件标记为默认启用。省略此字段，或设置为任何非 `true` 的值，则该插件默认保持禁用。 | +| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略它，或将其设为任何非 `true` 的值，则该插件默认保持禁用。 | | `legacyPluginIds` | 否 | `string[]` | 会规范化为此规范插件 id 的旧版 id。 | | `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当认证、配置或模型引用提到这些 provider id 时，应自动启用此插件。 | -| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明一个由 `plugins.slots.*` 使用的排他性插件类型。 | +| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明一个由 `plugins.slots.*` 使用的排他性插件种类。 | | `channels` | 否 | `string[]` | 由此插件拥有的渠道 id。用于设备发现和配置校验。 | | `providers` | 否 | `string[]` | 由此插件拥有的 provider id。 | | `modelSupport` | 否 | `object` | 由清单拥有的简写模型家族元数据，用于在运行时之前自动加载插件。 | -| `providerEndpoints` | 否 | `object[]` | 由清单拥有的 endpoint host/baseUrl 元数据，用于核心在 provider 运行时加载前对 provider 路由进行分类。 | +| `providerEndpoints` | 否 | `object[]` | 由清单拥有的 endpoint 主机 / `baseUrl` 元数据，用于 core 在 provider 运行时加载前对 provider 路由进行分类。 | | `cliBackends` | 否 | `string[]` | 由此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 | -| `syntheticAuthRefs` | 否 | `string[]` | 在运行时加载前的冷启动模型发现期间，应探测其插件自有 synthetic auth hook 的 provider 或 CLI 后端引用。 | -| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件拥有的占位 API key 值，表示非密钥的本地、OAuth 或环境凭证状态。 | -| `commandAliases` | 否 | `object[]` | 由此插件拥有的命令名称，应在运行时加载前生成具备插件感知的配置和 CLI 诊断信息。 | -| `providerAuthEnvVars` | 否 | `Record` | OpenClaw 可在不加载插件代码的情况下检查的轻量 provider 认证环境变量元数据。 | -| `providerAuthAliases` | 否 | `Record` | 应复用另一个 provider id 进行认证查找的 provider id，例如与基础 provider 共享 API key 和 auth profile 的编码 provider。 | -| `channelEnvVars` | 否 | `Record` | OpenClaw 可在不加载插件代码的情况下检查的轻量渠道环境变量元数据。将其用于通用启动 / 配置辅助工具应可见的、由环境变量驱动的渠道设置或认证界面。 | -| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选 provider 解析和简单 CLI 标志接线的轻量认证选项元数据。 | -| `activation` | 否 | `object` | 用于由 provider、命令、渠道、路由和能力触发的加载的轻量激活提示。仅为元数据；实际行为仍由插件运行时负责。 | -| `setup` | 否 | `object` | 设备发现和设置界面可在不加载插件运行时的情况下检查的轻量设置 / 新手引导描述符。 | -| `qaRunners` | 否 | `object[]` | 共享 `openclaw qa` 主机在插件运行时加载前使用的轻量 QA 运行器描述符。 | -| `contracts` | 否 | `object` | 针对 speech、realtime transcription、realtime voice、media-understanding、image-generation、music-generation、video-generation、web-fetch、web search 和工具归属的静态内置能力快照。 | -| `channelConfigs` | 否 | `Record` | 由清单拥有的渠道配置元数据，会在运行时加载前合并到设备发现和校验界面中。 | -| `skills` | 否 | `string[]` | 要加载的 Skill 目录，相对于插件根目录。 | +| `syntheticAuthRefs` | 否 | `string[]` | 在运行时加载前进行冷启动模型发现期间，应探测其插件自有 synthetic auth hook 的 provider 或 CLI 后端引用。 | +| `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 flag 接线的低成本认证选项元数据。 | +| `activation` | 否 | `object` | 用于 provider、命令、渠道、路由和能力触发加载的低成本激活提示。仅为元数据；插件运行时仍拥有实际行为。 | +| `setup` | 否 | `object` | 设备发现和设置界面可在不加载插件运行时的情况下检查的低成本设置 / 新手引导描述符。 | +| `qaRunners` | 否 | `object[]` | 共享 `openclaw qa` 宿主在插件运行时加载前使用的低成本 QA 运行器描述符。 | +| `contracts` | 否 | `object` | 针对语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、网页抓取、Web 搜索和工具归属的静态内置能力快照。 | +| `channelConfigs` | 否 | `Record` | 由清单拥有的渠道配置元数据，在运行时加载前合并到设备发现和校验界面中。 | +| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 | | `name` | 否 | `string` | 人类可读的插件名称。 | | `description` | 否 | `string` | 在插件界面中显示的简短摘要。 | -| `version` | 否 | `string` | 仅供参考的插件版本。 | +| `version` | 否 | `string` | 信息性插件版本。 | | `uiHints` | 否 | `Record` | 配置字段的 UI 标签、占位符和敏感性提示。 | ## `providerAuthChoices` 参考 -每个 `providerAuthChoices` 条目都描述一个新手引导或认证选项。 -OpenClaw 会在 provider 运行时加载之前读取它。 +每个 `providerAuthChoices` 条目描述一个新手引导或认证选项。 +OpenClaw 会在 provider 运行时加载前读取它。 | 字段 | 必填 | 类型 | 含义 | | --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `provider` | 是 | `string` | 此选项所属的 provider id。 | | `method` | 是 | `string` | 要分发到的认证方法 id。 | -| `choiceId` | 是 | `string` | 由新手引导和 CLI 流程使用的稳定认证选项 id。 | +| `choiceId` | 是 | `string` | 新手引导和 CLI 流程使用的稳定认证选项 id。 | | `choiceLabel` | 否 | `string` | 面向用户的标签。如果省略，OpenClaw 会回退到 `choiceId`。 | -| `choiceHint` | 否 | `string` | 供选择器使用的简短辅助文本。 | -| `assistantPriority` | 否 | `number` | 在由智能体驱动的交互式选择器中，值越小排序越靠前。 | -| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在智能体选择器中隐藏该选项，但仍允许通过手动 CLI 选择。 | +| `choiceHint` | 否 | `string` | 选择器中的简短辅助文本。 | +| `assistantPriority` | 否 | `number` | 在由助手驱动的交互式选择器中，值越小排序越靠前。 | +| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在助手选择器中隐藏该选项，同时仍允许手动 CLI 选择。 | | `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选项的旧版选项 id。 | | `groupId` | 否 | `string` | 用于对相关选项分组的可选组 id。 | -| `groupLabel` | 否 | `string` | 该分组的面向用户标签。 | +| `groupLabel` | 否 | `string` | 该分组面向用户的标签。 | | `groupHint` | 否 | `string` | 该分组的简短辅助文本。 | -| `optionKey` | 否 | `string` | 用于简单单标志认证流程的内部选项键。 | -| `cliFlag` | 否 | `string` | CLI 标志名，例如 `--openrouter-api-key`。 | -| `cliOption` | 否 | `string` | 完整的 CLI 选项形式，例如 `--openrouter-api-key `。 | -| `cliDescription` | 否 | `string` | 用于 CLI 帮助中的说明。 | +| `optionKey` | 否 | `string` | 用于简单单 flag 认证流程的内部选项键。 | +| `cliFlag` | 否 | `string` | CLI flag 名称，例如 `--openrouter-api-key`。 | +| `cliOption` | 否 | `string` | 完整 CLI 选项形式，例如 `--openrouter-api-key `。 | +| `cliDescription` | 否 | `string` | 用于 CLI 帮助中的描述。 | | `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 此选项应出现在哪些新手引导界面中。如果省略，默认值为 `["text-inference"]`。 | ## `commandAliases` 参考 -当插件拥有一个运行时命令名称，而用户可能会错误地把它放进 `plugins.allow` 中，或尝试把它当作根级 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 会使用这些元数据来提供诊断信息，而无需导入插件运行时代码。 +当插件拥有一个运行时命令名称，而用户可能会错误地将其放入 `plugins.allow`，或尝试将其作为根 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用此元数据进行诊断，而无需导入插件运行时代码。 ```json { @@ -213,16 +212,16 @@ OpenClaw 会在 provider 运行时加载之前读取它。 | 字段 | 必填 | 类型 | 含义 | | ------------ | -------- | ----------------- | ----------------------------------------------------------------------- | | `name` | 是 | `string` | 属于此插件的命令名称。 | -| `kind` | 否 | `"runtime-slash"` | 将该别名标记为聊天斜杠命令，而不是根级 CLI 命令。 | -| `cliCommand` | 否 | `string` | 相关的根级 CLI 命令（如果存在），可用于建议 CLI 操作。 | +| `kind` | 否 | `"runtime-slash"` | 将该别名标记为聊天斜杠命令，而不是根 CLI 命令。 | +| `cliCommand` | 否 | `string` | 若存在，用于 CLI 操作时建议的相关根 CLI 命令。 | ## `activation` 参考 -当插件可以用低成本声明哪些控制平面事件应在稍后激活它时，请使用 `activation`。 +当插件可以低成本声明哪些控制平面事件应在之后激活它时，请使用 `activation`。 ## `qaRunners` 参考 -当插件在共享的 `openclaw qa` 根命令下提供一个或多个传输运行器时，请使用 `qaRunners`。请保持这些元数据轻量且静态；实际的 CLI 注册仍由插件运行时通过导出 `qaRunnerCliRegistrations` 的轻量 `runtime-api.ts` 界面负责。 +当插件在共享 `openclaw qa` 根命令下贡献一个或多个传输运行器时，请使用 `qaRunners`。请保持此元数据低成本且静态；插件运行时仍通过导出 `qaRunnerCliRegistrations` 的轻量级 `runtime-api.ts` 界面拥有实际 CLI 注册逻辑。 ```json { @@ -238,9 +237,9 @@ OpenClaw 会在 provider 运行时加载之前读取它。 | 字段 | 必填 | 类型 | 含义 | | ------------- | -------- | -------- | ------------------------------------------------------------------ | | `commandName` | 是 | `string` | 挂载在 `openclaw qa` 下的子命令，例如 `matrix`。 | -| `description` | 否 | `string` | 当共享主机需要一个占位命令时使用的后备帮助文本。 | +| `description` | 否 | `string` | 当共享宿主需要一个占位命令时使用的回退帮助文本。 | -此块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时 / 插件入口点。当前使用方会在更广泛的插件加载之前将它作为缩小范围的提示，因此缺少激活元数据通常只会影响性能；在旧版清单归属回退机制仍存在时，它不应改变正确性。 +这个块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时 / 插件入口点。当前使用方会在更广泛的插件加载之前将其用作缩小范围的提示，因此缺少激活元数据通常只会带来性能损失；在旧版清单归属回退机制仍存在时，它不应改变正确性。 ```json { @@ -256,25 +255,21 @@ OpenClaw 会在 provider 运行时加载之前读取它。 | 字段 | 必填 | 类型 | 含义 | | ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- | -| `onProviders` | 否 | `string[]` | 请求这些 provider id 时应激活此插件。 | +| `onProviders` | 否 | `string[]` | 当被请求时应激活此插件的 provider id。 | | `onCommands` | 否 | `string[]` | 应激活此插件的命令 id。 | | `onChannels` | 否 | `string[]` | 应激活此插件的渠道 id。 | | `onRoutes` | 否 | `string[]` | 应激活此插件的路由类型。 | -| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 由控制平面激活规划使用的广义能力提示。 | +| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的广义能力提示。 | -当前在线使用方： +当前的实际使用方： -- 由命令触发的 CLI 规划会回退到旧版的 - `commandAliases[].cliCommand` 或 `commandAliases[].name` -- 由渠道触发的设置 / 渠道规划会在缺少显式渠道激活元数据时，回退到旧版 `channels[]` - 归属 -- 由 provider 触发的设置 / 运行时规划会在缺少显式 provider - 激活元数据时，回退到旧版的 `providers[]` 和顶层 `cliBackends[]` - 归属 +- 由命令触发的 CLI 规划会回退到旧版 `commandAliases[].cliCommand` 或 `commandAliases[].name` +- 由渠道触发的设置 / 渠道规划在缺少显式渠道激活元数据时，会回退到旧版 `channels[]` 归属 +- 由 provider 触发的设置 / 运行时规划在缺少显式 provider 激活元数据时，会回退到旧版 `providers[]` 和顶层 `cliBackends[]` 归属 ## `setup` 参考 -当设置和新手引导界面需要在运行时加载前获取由插件拥有的轻量元数据时，请使用 `setup`。 +当设置和新手引导界面需要在运行时加载前获取低成本的插件自有元数据时，请使用 `setup`。 ```json { @@ -293,17 +288,17 @@ 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 在全局唯一。 | +| `id` | 是 | `string` | 在设置或新手引导期间暴露的 provider id。请保持规范化 id 全局唯一。 | | `authMethods` | 否 | `string[]` | 此 provider 在不加载完整运行时的情况下支持的设置 / 认证方法 id。 | | `envVars` | 否 | `string[]` | 通用设置 / 状态界面可在插件运行时加载前检查的环境变量。 | @@ -312,9 +307,9 @@ OpenClaw 会在 provider 运行时加载之前读取它。 | 字段 | 必填 | 类型 | 含义 | | ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- | | `providers` | 否 | `object[]` | 在设置和新手引导期间暴露的 provider 设置描述符。 | -| `cliBackends` | 否 | `string[]` | 用于“描述符优先”设置查找的设置时后端 id。保持规范化 id 在全局唯一。 | +| `cliBackends` | 否 | `string[]` | 用于“描述符优先”设置查找的设置期后端 id。请保持规范化 id 全局唯一。 | | `configMigrations` | 否 | `string[]` | 由此插件设置界面拥有的配置迁移 id。 | -| `requiresRuntime` | 否 | `boolean` | 描述符查找后，设置是否仍需要执行 `setup-api`。 | +| `requiresRuntime` | 否 | `boolean` | 在描述符查找之后，设置是否仍需要执行 `setup-api`。 | ## `uiHints` 参考 @@ -333,20 +328,20 @@ OpenClaw 会在 provider 运行时加载之前读取它。 } ``` -每个字段提示可包含： +每个字段提示可以包含： | 字段 | 类型 | 含义 | | ------------- | ---------- | --------------------------------------- | | `label` | `string` | 面向用户的字段标签。 | | `help` | `string` | 简短辅助文本。 | -| `tags` | `string[]` | 可选的 UI 标签。 | -| `advanced` | `boolean` | 将该字段标记为高级字段。 | -| `sensitive` | `boolean` | 将该字段标记为密钥或敏感字段。 | +| `tags` | `string[]` | 可选 UI 标签。 | +| `advanced` | `boolean` | 将该字段标记为高级项。 | +| `sensitive` | `boolean` | 将该字段标记为机密或敏感项。 | | `placeholder` | `string` | 表单输入的占位文本。 | ## `contracts` 参考 -仅当需要 OpenClaw 可在不导入插件运行时的情况下读取的静态能力归属元数据时，才使用 `contracts`。 +仅将 `contracts` 用于 OpenClaw 可在不导入插件运行时的情况下读取的静态能力归属元数据。 ```json { @@ -374,13 +369,13 @@ OpenClaw 会在 provider 运行时加载之前读取它。 | `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解 provider id。 | | `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成 provider id。 | | `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成 provider id。 | -| `webFetchProviders` | `string[]` | 此插件拥有的 Web 获取 provider id。 | +| `webFetchProviders` | `string[]` | 此插件拥有的网页抓取 provider id。 | | `webSearchProviders` | `string[]` | 此插件拥有的 Web 搜索 provider id。 | | `tools` | `string[]` | 此插件为内置契约检查所拥有的智能体工具名称。 | ## `channelConfigs` 参考 -当渠道插件需要在运行时加载前提供轻量配置元数据时，请使用 `channelConfigs`。 +当渠道插件需要在运行时加载前提供低成本配置元数据时，请使用 `channelConfigs`。 ```json { @@ -407,19 +402,19 @@ OpenClaw 会在 provider 运行时加载之前读取它。 } ``` -每个渠道条目可包含： +每个渠道条目可以包含： | 字段 | 类型 | 含义 | | ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | -| `schema` | `object` | `channels.` 的 JSON Schema。每个声明的渠道配置条目都必须提供。 | -| `uiHints` | `Record` | 该渠道配置部分的可选 UI 标签 / 占位符 / 敏感性提示。 | +| `schema` | `object` | `channels.` 的 JSON Schema。每个已声明的渠道配置条目都必须提供。 | +| `uiHints` | `Record` | 该渠道配置部分可选的 UI 标签 / 占位符 / 敏感性提示。 | | `label` | `string` | 当运行时元数据尚未就绪时，合并到选择器和检查界面中的渠道标签。 | -| `description` | `string` | 用于检查和目录界面的简短渠道说明。 | -| `preferOver` | `string[]` | 在选择界面中，此渠道应优先于其之上的旧版或较低优先级插件 id。 | +| `description` | `string` | 用于检查和目录界面的简短渠道描述。 | +| `preferOver` | `string[]` | 在选择界面中，此渠道应优先于的旧版或较低优先级插件 id。 | ## `modelSupport` 参考 -当 OpenClaw 应在插件运行时加载前，根据像 `gpt-5.4` 或 `claude-sonnet-4.6` 这样的简写模型 id 推断你的 provider 插件时，请使用 `modelSupport`。 +当 OpenClaw 应在插件运行时加载前，根据 `gpt-5.4` 或 `claude-sonnet-4.6` 之类的简写模型 id 推断你的 provider 插件时，请使用 `modelSupport`。 ```json { @@ -430,21 +425,21 @@ OpenClaw 会在 provider 运行时加载之前读取它。 } ``` -OpenClaw 按以下优先级应用： +OpenClaw 应用以下优先级： - 显式 `provider/model` 引用使用所属 `providers` 清单元数据 - `modelPatterns` 优先于 `modelPrefixes` - 如果一个非内置插件和一个内置插件都匹配，则非内置插件胜出 -- 剩余歧义会被忽略，直到用户或配置指定一个 provider +- 剩余的歧义会被忽略，直到用户或配置明确指定 provider 字段： | 字段 | 类型 | 含义 | | --------------- | ---------- | ------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | 对简写模型 id 使用 `startsWith` 进行匹配的前缀。 | -| `modelPatterns` | `string[]` | 在移除 profile 后缀后，对简写模型 id 进行匹配的正则表达式源码。 | +| `modelPrefixes` | `string[]` | 使用 `startsWith` 针对简写模型 id 进行匹配的前缀。 | +| `modelPatterns` | `string[]` | 在移除配置文件后缀后，针对简写模型 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` 的区别 @@ -452,38 +447,40 @@ OpenClaw 按以下优先级应用： | 文件 | 用途 | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | 设备发现、配置校验、认证选项元数据，以及在插件代码运行前必须存在的 UI 提示 | +| `openclaw.plugin.json` | 必须在插件代码运行前存在的设备发现、配置校验、认证选项元数据和 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.setupEntry` | 在新手引导和延迟渠道启动期间使用的轻量仅设置入口点。 | -| `openclaw.channel` | 轻量渠道目录元数据，例如标签、文档路径、别名和选择文案。 | -| `openclaw.channel.configuredState` | 轻量已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅由环境变量驱动的设置？”。 | -| `openclaw.channel.persistedAuthState` | 轻量持久化认证状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何账号登录？”。 | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 用于内置和外部发布插件的安装 / 更新提示。 | +| `openclaw.setupEntry` | 在新手引导、延后渠道启动以及只读渠道状态 / SecretRef 发现期间使用的轻量级仅设置入口点。 | +| `openclaw.channel` | 低成本渠道目录元数据，例如标签、文档路径、别名和选择文案。 | +| `openclaw.channel.configuredState` | 轻量级已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅基于环境变量的设置？”。 | +| `openclaw.channel.persistedAuthState` | 轻量级持久化认证状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已经有任何已登录状态？”。 | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 内置和外部发布插件的安装 / 更新提示。 | | `openclaw.install.defaultChoice` | 当有多个安装来源可用时的首选安装路径。 | -| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 主机版本，使用如 `>=2026.3.22` 这样的 semver 下限。 | -| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一种狭义的内置插件重装恢复路径。 | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间先加载仅设置用途的渠道界面，再加载完整渠道插件。 | +| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 宿主版本，使用如 `>=2026.3.22` 这样的 semver 下限。 | +| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个狭窄的内置插件重新安装恢复路径。 | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许仅设置的渠道界面在启动期间先于完整渠道插件加载。 | -`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间执行检查。无效值会被拒绝；值有效但要求更高版本时，旧主机会跳过该插件。 +`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间强制执行。无效值会被拒绝；较新但有效的值会使该插件在较旧宿主上被跳过。 -`openclaw.install.allowInvalidConfigRecovery` 的作用范围被有意限制。它不会让任意损坏的配置都变得可安装。当前它只允许安装流程从某些特定的旧版内置插件升级失败中恢复，例如缺失的内置插件路径，或同一内置插件下遗留的 `channels.` 条目。无关的配置错误仍会阻止安装，并将操作员引导至 `openclaw doctor --fix`。 +当状态、渠道列表或 SecretRef 扫描需要在不加载完整运行时的情况下识别已配置账号时，渠道插件应提供 `openclaw.setupEntry`。设置入口点应公开渠道元数据以及可安全用于设置的配置、状态和密钥适配器；网络客户端、Gateway 网关监听器和传输运行时应保留在主扩展入口点中。 -`openclaw.channel.persistedAuthState` 是一个用于微型检查器模块的包元数据： +`openclaw.install.allowInvalidConfigRecovery` 的适用范围刻意很窄。它不会让任意损坏的配置变得可安装。当前它只允许安装流程从特定的陈旧内置插件升级失败中恢复，例如缺失的内置插件路径，或同一内置插件对应的陈旧 `channels.` 条目。无关的配置错误仍会阻止安装，并将操作人员引导到 `openclaw doctor --fix`。 + +`openclaw.channel.persistedAuthState` 是一个微型检查器模块的包元数据： ```json { @@ -499,9 +496,9 @@ OpenClaw 按以下优先级应用： } ``` -当设置、Doctor 或已配置状态流程需要在完整渠道插件加载前进行一个轻量的“是 / 否”认证探测时，请使用它。目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 暴露它。 +当设置、Doctor 或已配置状态流程需要在完整渠道插件加载前进行低成本的二元认证探测时，请使用它。目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 暴露它。 -`openclaw.channel.configuredState` 对轻量仅环境变量已配置检查采用相同结构： +`openclaw.channel.configuredState` 对于低成本的仅环境变量已配置检查采用相同的结构： ```json { @@ -517,47 +514,45 @@ OpenClaw 按以下优先级应用： } ``` -当渠道可以仅通过环境变量或其他轻量非运行时输入回答已配置状态时，请使用它。如果检查需要完整配置解析或真实渠道运行时，则应将该逻辑保留在插件 `config.hasConfiguredState` hook 中。 +当渠道可以仅通过环境变量或其他微小的非运行时输入回答已配置状态时，请使用它。如果检查需要完整配置解析或真实渠道运行时，请将该逻辑保留在插件 `config.hasConfiguredState` hook 中。 ## JSON Schema 要求 - **每个插件都必须提供一个 JSON Schema**，即使它不接受任何配置。 -- 空 schema 也是可以接受的（例如 `{ "type": "object", "additionalProperties": false }`）。 +- 可以接受空 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 插件**是**必需的**，包括本地文件系统加载。 -- 运行时仍会单独加载插件模块；清单仅用于设备发现 + 校验。 +- 对于原生 OpenClaw 插件，清单是**必需的**，包括从本地文件系统加载的插件。 +- 运行时仍会单独加载插件模块；清单仅用于设备发现和校验。 - 原生清单使用 JSON5 解析，因此支持注释、尾随逗号和未加引号的键，只要最终值仍然是一个对象即可。 - 清单加载器只会读取文档中说明的清单字段。避免在这里添加自定义顶层键。 -- `providerAuthEnvVars` 是用于认证探测、环境变量标记校验以及类似 provider 认证界面的轻量元数据路径，这些场景不应仅为了检查环境变量名而启动插件运行时。 -- `providerAuthAliases` 允许 provider 变体复用另一个 provider 的认证环境变量、auth profile、基于配置的认证以及 API key 新手引导选项，而无需在核心中硬编码这种关系。 -- `providerEndpoints` 允许 provider 插件拥有简单 endpoint host/baseUrl 匹配元数据。仅将其用于核心已支持的 endpoint class；运行时行为仍由插件负责。 -- `syntheticAuthRefs` 是用于 provider 自有 synthetic auth hook 的轻量元数据路径，这些 hook 必须在运行时注册表存在之前，对冷启动模型发现可见。只列出那些其运行时 provider 或 CLI 后端实际实现了 `resolveSyntheticAuth` 的引用。 -- `nonSecretAuthMarkers` 是用于内置插件自有占位 API key 的轻量元数据路径，例如本地、OAuth 或环境凭证标记。核心会将这些值视为非密钥，用于认证显示和密钥审计，而无需硬编码所属 provider。 -- `channelEnvVars` 是用于 shell 环境变量回退、设置提示以及类似渠道界面的轻量元数据路径，这些场景不应仅为了检查环境变量名而启动插件运行时。 -- `providerAuthChoices` 是用于认证选项选择器、`--auth-choice` 解析、首选 provider 映射以及在 provider 运行时加载前进行简单新手引导 CLI 标志注册的轻量元数据路径。对于需要 provider 代码的运行时向导元数据，请参见 - [provider 运行时 hook](/zh-CN/plugins/architecture#provider-runtime-hooks)。 -- 排他性插件类型通过 `plugins.slots.*` 选择。 +- `providerAuthEnvVars` 是用于认证探测、环境变量标记校验以及类似 provider 认证界面的低成本元数据路径，这些场景不应仅为了检查环境变量名而启动插件运行时。 +- `providerAuthAliases` 允许 provider 变体复用另一个 provider 的认证环境变量、认证配置文件、配置支持的认证以及 API key 新手引导选项，而无需在 core 中硬编码这种关系。 +- `providerEndpoints` 允许 provider 插件拥有简单的 endpoint 主机 / `baseUrl` 匹配元数据。仅将其用于 core 已支持的 endpoint 类别；运行时行为仍由插件拥有。 +- `syntheticAuthRefs` 是用于 provider 自有 synthetic auth hook 的低成本元数据路径，这些 hook 必须在运行时注册表存在之前，对冷启动模型发现可见。这里只列出那些其运行时 provider 或 CLI 后端实际实现了 `resolveSyntheticAuth` 的引用。 +- `nonSecretAuthMarkers` 是用于内置插件自有占位 API key 的低成本元数据路径，例如本地、OAuth 或环境凭证标记。core 会将这些视为非机密项，用于认证显示和密钥审计，而无需硬编码所属 provider。 +- `channelEnvVars` 是用于 shell 环境变量回退、设置提示以及类似渠道界面的低成本元数据路径，这些场景不应仅为了检查环境变量名而启动插件运行时。 +- `providerAuthChoices` 是用于认证选项选择器、`--auth-choice` 解析、首选 provider 映射以及在 provider 运行时加载前进行简单新手引导 CLI flag 注册的低成本元数据路径。对于需要 provider 代码的运行时向导元数据，请参见[provider 运行时 hook](/zh-CN/plugins/architecture#provider-runtime-hooks)。 +- 排他性插件种类通过 `plugins.slots.*` 选择。 - `kind: "memory"` 由 `plugins.slots.memory` 选择。 - - `kind: "context-engine"` 由 `plugins.slots.contextEngine` - 选择（默认值：内置 `legacy`）。 -- 如果插件不需要 `channels`、`providers`、`cliBackends` 和 `skills`，则可以省略这些字段。 -- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器允许列表要求（例如 pnpm 的 `allow-build-scripts` + - `kind: "context-engine"` 由 `plugins.slots.contextEngine` 选择（默认值：内置 `legacy`）。 +- 当插件不需要它们时，可以省略 `channels`、`providers`、`cliBackends` 和 `skills`。 +- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器允许列表要求（例如 pnpm `allow-build-scripts` - `pnpm rebuild `）。 ## 相关内容 -- [构建插件](/zh-CN/plugins/building-plugins) — 插件的入门指南 +- [构建插件](/zh-CN/plugins/building-plugins) — 插件快速开始 - [插件架构](/zh-CN/plugins/architecture) — 内部架构 -- [SDK 概览](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考 +- [插件 SDK 概览](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考 diff --git a/docs/zh-CN/plugins/sdk-channel-plugins.md b/docs/zh-CN/plugins/sdk-channel-plugins.md index 932cb76d0..1d1e1aea9 100644 --- a/docs/zh-CN/plugins/sdk-channel-plugins.md +++ b/docs/zh-CN/plugins/sdk-channel-plugins.md @@ -4,86 +4,87 @@ read_when: - 你想将 OpenClaw 连接到一个消息平台 - 你需要了解 `ChannelPlugin` 适配器接口 sidebarTitle: Channel Plugins -summary: 构建 OpenClaw 消息渠道插件的分步指南 +summary: 为 OpenClaw 构建消息渠道插件的分步指南 title: 构建渠道插件 x-i18n: - generated_at: "2026-04-21T04:19:34Z" + generated_at: "2026-04-21T17:54:52Z" model: gpt-5.4 provider: openai - source_hash: 569394aeefa0231ae3157a13406f91c97fe7eeff2b62df0d35a893f1ad4d5d05 + source_hash: 35cae55c13b69f2219bd2f9bd3ee2f7d8c4075bd87f0be11c35a0fddb070fe1e source_path: plugins/sdk-channel-plugins.md workflow: 15 --- # 构建渠道插件 -本指南将带你逐步构建一个渠道插件，把 OpenClaw 连接到某个消息平台。完成后，你将拥有一个可用的渠道，支持私信安全、配对、回复线程处理和出站消息。 +本指南将带你构建一个把 OpenClaw 连接到消息平台的渠道插件。完成后，你将拥有一个可用的渠道，支持私信安全、配对、回复线程和出站消息。 - 如果你之前还没有构建过任何 OpenClaw 插件，请先阅读 + 如果你之前没有构建过任何 OpenClaw 插件，请先阅读 [入门指南](/zh-CN/plugins/building-plugins)，了解基础包结构和清单设置。 ## 渠道插件如何工作 -渠道插件不需要自己提供发送/编辑/响应工具。OpenClaw 在核心中保留了一个共享的 `message` 工具。你的插件负责： +渠道插件不需要自己实现发送/编辑/回应工具。OpenClaw 在核心中保留了一个共享的 `message` 工具。你的插件负责： - **配置** — 账户解析和设置向导 -- **安全** — 私信策略和允许列表 +- **安全** — 私信策略和允许名单 - **配对** — 私信批准流程 -- **会话语法** — 提供商特定的会话 id 如何映射到基础聊天、线程 id 和父级回退 +- **会话语法** — 提供商特定的会话 id 如何映射到底层聊天、线程 id 和父级回退 - **出站** — 向平台发送文本、媒体和投票 - **线程处理** — 如何组织回复线程 -核心负责共享消息工具、提示词接线、外层会话键形状、通用的 `:thread:` 记录，以及分发。 +核心负责共享的消息工具、提示词接线、外层会话键形状、通用的 `:thread:` 记录，以及分发。 -如果你的渠道为消息工具添加了携带媒体来源的参数，请通过 `describeMessageTool(...).mediaSourceParams` 公开这些参数名。核心会使用这个显式列表来进行沙箱路径规范化和出站媒体访问策略处理，因此插件不需要为了提供商特定的头像、附件或封面图参数，在共享核心中添加特殊分支。 -建议返回一个按动作分组的映射，例如 -`{ "set-profile": ["avatarUrl", "avatarPath"] }`，这样无关动作就不会继承其他动作的媒体参数。对于有意在所有公开动作之间共享的参数，扁平数组同样有效。 +如果你的渠道会为消息工具添加承载媒体来源的参数，请通过 `describeMessageTool(...).mediaSourceParams` 暴露这些参数名。核心使用这个显式列表来处理沙箱路径规范化和出站媒体访问策略，因此插件不需要为提供商特定的头像、附件或封面图片参数添加共享核心特例。 +优先返回一个按操作分组的映射，例如 +`{ "set-profile": ["avatarUrl", "avatarPath"] }`，这样无关操作就不会继承另一个操作的媒体参数。对于有意在每个已暴露操作之间共享的参数，扁平数组同样可用。 -如果你的平台会在会话 id 中存储额外作用域，请把这部分解析保留在插件中，使用 `messaging.resolveSessionConversation(...)`。这是将 `rawId` 映射到基础会话 id、可选线程 id、显式 `baseConversationId` 和任意 `parentConversationCandidates` 的规范钩子。 +如果你的平台会在会话 id 中存储额外作用域，请在插件中通过 `messaging.resolveSessionConversation(...)` 保持这部分解析。这是将 `rawId` 映射为基础会话 id、可选线程 id、显式 `baseConversationId` 以及任意 `parentConversationCandidates` 的规范钩子。 当你返回 `parentConversationCandidates` 时，请按从最窄父级到最宽/基础会话的顺序排列。 -如果某些内置插件需要在渠道注册表启动前完成相同解析，也可以公开一个顶层 `session-key-api.ts` 文件，并导出匹配的 `resolveSessionConversation(...)`。只有当运行时插件注册表尚不可用时，核心才会使用这个可安全引导的接口。 +如果内置插件在渠道注册表启动前也需要相同解析，也可以暴露一个顶层 `session-key-api.ts` 文件，并导出匹配的 `resolveSessionConversation(...)`。只有在运行时插件注册表尚不可用时，核心才会使用这个可安全引导的接口。 -当插件只需要在通用/原始 id 之上补充父级回退时，`messaging.resolveParentConversationCandidates(...)` 仍然可作为旧版兼容回退使用。如果两个钩子都存在，核心会优先使用 -`resolveSessionConversation(...).parentConversationCandidates`，只有当规范钩子省略它们时，才会回退到 `resolveParentConversationCandidates(...)`。 +当插件只需要在通用/原始 id 之上提供父级回退时，`messaging.resolveParentConversationCandidates(...)` 仍然可作为旧版兼容回退使用。如果两个钩子都存在，核心会优先使用 +`resolveSessionConversation(...).parentConversationCandidates`，只有在这个规范钩子未提供它们时，才会回退到 `resolveParentConversationCandidates(...)`。 ## 批准和渠道能力 -大多数渠道插件都不需要编写专门的批准代码。 +大多数渠道插件不需要特定于批准的代码。 -- 核心负责同聊天内的 `/approve`、共享批准按钮负载，以及通用回退投递。 -- 当渠道需要批准专属行为时，优先在渠道插件上使用单个 `approvalCapability` 对象。 -- `ChannelPlugin.approvals` 已被移除。请将批准投递/原生/渲染/认证相关事实放到 `approvalCapability` 上。 +- 核心负责同一聊天中的 `/approve`、共享批准按钮载荷和通用回退投递。 +- 当渠道需要特定于批准的行为时，优先在渠道插件上使用单个 `approvalCapability` 对象。 +- `ChannelPlugin.approvals` 已移除。把批准投递/原生/渲染/认证相关信息放到 `approvalCapability` 上。 - `plugin.auth` 仅用于登录/登出；核心不再从该对象读取批准认证钩子。 - `approvalCapability.authorizeActorAction` 和 `approvalCapability.getActionAvailabilityState` 是规范的批准认证接口。 -- 对于同聊天批准认证可用性，请使用 `approvalCapability.getActionAvailabilityState`。 -- 如果你的渠道公开原生 exec 批准，请在发起界面/原生客户端状态与同聊天批准认证不同时，使用 `approvalCapability.getExecInitiatingSurfaceState`。核心使用这个 exec 专用钩子来区分 `enabled` 和 `disabled`，判断发起渠道是否支持原生 exec 批准，并在原生客户端回退引导中包含该渠道。`createApproverRestrictedNativeApprovalCapability(...)` 已为常见场景填充了这一点。 -- 对于渠道专属的负载生命周期行为，例如隐藏重复的本地批准提示，或在投递前发送输入中指示，请使用 `outbound.shouldSuppressLocalPayloadPrompt` 或 `outbound.beforeDeliverPayload`。 +- 对于同一聊天中的批准认证可用性，请使用 `approvalCapability.getActionAvailabilityState`。 +- 如果你的渠道暴露原生 exec 批准，请在发起界面/原生客户端状态与同一聊天批准认证不同时使用 `approvalCapability.getExecInitiatingSurfaceState`。核心使用这个 exec 专用钩子来区分 `enabled` 和 `disabled`，判断发起渠道是否支持原生 exec 批准，并在原生客户端回退指引中包含该渠道。`createApproverRestrictedNativeApprovalCapability(...)` 为常见场景填充这部分。 +- 对于渠道特定的载荷生命周期行为，例如隐藏重复的本地批准提示或在投递前发送“正在输入”指示器，请使用 `outbound.shouldSuppressLocalPayloadPrompt` 或 `outbound.beforeDeliverPayload`。 - 仅在需要原生批准路由或抑制回退时使用 `approvalCapability.delivery`。 -- 对于渠道拥有的原生批准事实，请使用 `approvalCapability.nativeRuntime`。在高频渠道入口点中，请通过 `createLazyChannelApprovalNativeRuntimeAdapter(...)` 保持其惰性加载，这样它可以按需导入你的运行时模块，同时仍让核心组装批准生命周期。 -- 仅当渠道确实需要自定义批准负载而不是共享渲染器时，才使用 `approvalCapability.render`。 -- 当渠道希望禁用路径中的回复精确说明启用原生 exec 批准所需的配置项时，请使用 `approvalCapability.describeExecApprovalSetup`。该钩子接收 `{ channel, channelLabel, accountId }`；对于具名账户渠道，应渲染类似 `channels..accounts..execApprovals.*` 这样的账户作用域路径，而不是顶层默认值。 -- 如果某个渠道可以从现有配置中推断出稳定的类似所有者的私信身份，请使用 `openclaw/plugin-sdk/approval-runtime` 中的 `createResolvedApproverActionAuthAdapter` 来限制同聊天 `/approve`，而无需添加批准专用的核心逻辑。 -- 如果某个渠道需要原生批准投递，请让渠道代码只关注目标规范化以及传输/展示相关事实。请使用 `openclaw/plugin-sdk/approval-runtime` 中的 `createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver` 和 `createApproverRestrictedNativeApprovalCapability`。把渠道特定事实放到 `approvalCapability.nativeRuntime` 之后，最好通过 `createChannelApprovalNativeRuntimeAdapter(...)` 或 `createLazyChannelApprovalNativeRuntimeAdapter(...)`，这样核心就可以组装处理器，并负责请求过滤、路由、去重、过期、Gateway 网关订阅以及“已路由到其他位置”的通知。`nativeRuntime` 被拆分为几个更小的接口： -- `availability` — 账户是否已配置，以及请求是否应被处理 -- `presentation` — 将共享批准视图模型映射为待处理/已解决/已过期的原生负载或最终动作 -- `transport` — 准备目标并发送/更新/删除原生批准消息 -- `interactions` — 可选的绑定/解绑/清除动作钩子，用于原生按钮或响应 +- 对于由渠道拥有的原生批准信息，请使用 `approvalCapability.nativeRuntime`。在高频渠道入口点上，通过 `createLazyChannelApprovalNativeRuntimeAdapter(...)` 保持其惰性，该适配器可以按需导入你的运行时模块，同时仍允许核心组装批准生命周期。 +- 只有当渠道确实需要自定义批准载荷，而不是使用共享渲染器时，才使用 `approvalCapability.render`。 +- 当渠道希望在禁用路径回复中说明启用原生 exec 批准所需的确切配置开关时，请使用 `approvalCapability.describeExecApprovalSetup`。该钩子接收 `{ channel, channelLabel, accountId }`；具名账户渠道应渲染账户作用域路径，例如 `channels..accounts..execApprovals.*`，而不是顶层默认值。 +- 如果渠道能从现有配置推断出稳定的、类似所有者的私信身份，请使用来自 `openclaw/plugin-sdk/approval-runtime` 的 `createResolvedApproverActionAuthAdapter` 来限制同一聊天中的 `/approve`，而无需添加特定于批准的核心逻辑。 +- 如果渠道需要原生批准投递，请让渠道代码专注于目标规范化以及传输/展示信息。使用来自 `openclaw/plugin-sdk/approval-runtime` 的 `createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver` 和 `createApproverRestrictedNativeApprovalCapability`。把渠道特定信息放在 `approvalCapability.nativeRuntime` 之后，理想情况下通过 `createChannelApprovalNativeRuntimeAdapter(...)` 或 `createLazyChannelApprovalNativeRuntimeAdapter(...)`，这样核心就可以组装处理器，并负责请求过滤、路由、去重、过期、Gateway 网关订阅，以及“已路由到其他地方”的通知。`nativeRuntime` 被拆分为几个更小的接口： +- `availability` — 账户是否已配置，以及某个请求是否应被处理 +- `presentation` — 将共享的批准视图模型映射为待处理/已解决/已过期的原生载荷或最终操作 +- `transport` — 准备目标，并发送/更新/删除原生批准消息 +- `interactions` — 针对原生按钮或回应的可选绑定/解绑/清除操作钩子 - `observe` — 可选的投递诊断钩子 -- 如果渠道需要运行时持有的对象，例如客户端、令牌、Bolt 应用或 webhook 接收器，请通过 `openclaw/plugin-sdk/channel-runtime-context` 注册它们。通用运行时上下文注册表让核心能够从渠道启动状态引导基于能力的处理器，而无需添加批准专用的包装胶水代码。 -- 只有当能力驱动接口的表达力仍不够时，才使用更底层的 `createChannelApprovalHandler` 或 `createChannelNativeApprovalRuntime`。 -- 原生批准渠道必须通过这些辅助工具同时传递 `accountId` 和 `approvalKind`。`accountId` 可确保多账户批准策略被限定到正确的机器人账户，`approvalKind` 可让渠道在不向核心硬编码分支的前提下保留 exec 与插件批准行为的区别。 -- 核心现在也负责批准重路由通知。渠道插件不应再从 `createChannelNativeApprovalRuntime` 发送自己的“批准已发送到私信/其他渠道”后续消息；相反，应通过共享批准能力辅助工具公开准确的来源 + 批准者私信路由，并让核心在向发起聊天回发通知前汇总实际投递结果。 -- 在端到端流程中保留已投递批准 id 的类型。原生客户端不应根据渠道本地状态来猜测或改写 exec 与插件批准的路由。 -- 不同的批准类型可以有意公开不同的原生界面。 - 当前内置示例： - - Slack 对 exec 和插件 id 都保留原生批准路由能力。 - - Matrix 对 exec 和插件批准保持相同的原生私信/渠道路由和响应 UX，同时仍允许认证按批准类型有所不同。 -- `createApproverRestrictedNativeApprovalAdapter` 仍作为兼容包装器保留，但新代码应优先使用能力构建器，并在插件上公开 `approvalCapability`。 +- 如果渠道需要运行时持有的对象，例如客户端、令牌、Bolt 应用或 webhook 接收器，请通过 `openclaw/plugin-sdk/channel-runtime-context` 注册它们。通用的运行时上下文注册表让核心能够根据渠道启动状态引导基于能力的处理器，而无需添加特定于批准的包装胶水代码。 +- 仅当基于能力的接口尚不足以表达你的需求时，才使用更底层的 `createChannelApprovalHandler` 或 `createChannelNativeApprovalRuntime`。 +- 原生批准渠道必须通过这些辅助函数同时传递 `accountId` 和 `approvalKind`。`accountId` 让多账户批准策略能限定到正确的机器人账户，`approvalKind` 则让渠道在不需要核心硬编码分支的情况下区分 exec 与插件批准行为。 +- 核心现在也负责批准重路由通知。渠道插件不应再从 `createChannelNativeApprovalRuntime` 发送自己的“批准已发往私信/其他渠道”后续消息；相反，应通过共享的批准能力辅助函数暴露准确的来源 + 批准者私信路由，并让核心在向发起聊天回发任何通知之前聚合实际投递结果。 +- 在端到端流程中保留已投递批准 id 的种类。原生客户端不应 + 根据渠道本地状态去猜测或重写 exec 与插件批准路由。 +- 不同的批准种类可以有意暴露不同的原生界面。 + 当前的内置示例： + - Slack 对 exec 和插件 id 都保留原生批准路由。 + - Matrix 对 exec 和插件批准保留相同的原生私信/渠道路由和回应 UX，同时仍允许认证按批准种类区分。 +- `createApproverRestrictedNativeApprovalAdapter` 仍作为兼容包装器存在，但新代码应优先使用能力构建器，并在插件上暴露 `approvalCapability`。 -对于高频渠道入口点，如果你只需要这一系列中的某一部分，请优先使用更窄的运行时子路径： +对于高频渠道入口点，当你只需要这一组中的某一部分时，优先使用更窄的运行时子路径： - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -95,36 +96,41 @@ x-i18n: - `openclaw/plugin-sdk/approval-reply-runtime` - `openclaw/plugin-sdk/channel-runtime-context` -同样地，当你不需要更宽泛的总入口接口时，请优先使用 `openclaw/plugin-sdk/setup-runtime`、 +同样地，当你不需要更宽泛的总接口时，请优先使用 `openclaw/plugin-sdk/setup-runtime`、 `openclaw/plugin-sdk/setup-adapter-runtime`、 `openclaw/plugin-sdk/reply-runtime`、 `openclaw/plugin-sdk/reply-dispatch-runtime`、 `openclaw/plugin-sdk/reply-reference` 和 `openclaw/plugin-sdk/reply-chunking`。 -对于设置，具体如下： +对于设置，尤其如此： -- `openclaw/plugin-sdk/setup-runtime` 覆盖运行时安全的设置辅助工具： +- `openclaw/plugin-sdk/setup-runtime` 覆盖运行时安全的设置辅助函数： 可安全导入的设置补丁适配器（`createPatchedAccountSetupAdapter`、 `createEnvPatchedAccountSetupAdapter`、 `createSetupInputPresenceValidator`）、查找说明输出、 - `promptResolvedAllowFrom`、`splitSetupEntries` 以及委托式 + `promptResolvedAllowFrom`、`splitSetupEntries`，以及委托式 setup-proxy 构建器 -- `openclaw/plugin-sdk/setup-adapter-runtime` 是用于 `createEnvPatchedAccountSetupAdapter` 的窄化、感知环境变量的适配器接口 -- `openclaw/plugin-sdk/channel-setup` 覆盖可选安装设置构建器，以及少量设置安全原语： +- `openclaw/plugin-sdk/setup-adapter-runtime` 是面向环境变量感知适配器的窄接口， + 用于 `createEnvPatchedAccountSetupAdapter` +- `openclaw/plugin-sdk/channel-setup` 覆盖可选安装设置构建器以及少量设置安全原语： `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、 -如果你的渠道支持由环境变量驱动的设置或认证，并且通用启动/配置流程需要在运行时加载前知道这些环境变量名称，请在插件清单中通过 `channelEnvVars` 声明它们。保留渠道运行时 `envVars` 或本地常量仅用于面向操作者的文案。 +如果你的渠道支持基于环境变量的设置或认证，并且通用启动/配置流程需要在运行时加载前了解这些环境变量名称，请在插件清单中使用 `channelEnvVars` 声明它们。把渠道运行时 `envVars` 或本地常量仅用于面向运维者的文案。 + +如果你的渠道可能在插件运行时启动之前就出现在 `status`、`channels list`、`channels status` 或 SecretRef 扫描中，请在 `package.json` 中添加 `openclaw.setupEntry`。这个入口点在只读命令路径中应可安全导入，并应返回这些摘要所需的渠道元数据、设置安全配置适配器、状态适配器以及渠道 secret 目标元数据。不要从设置入口启动客户端、监听器或传输运行时。 + `createOptionalChannelSetupWizard`、`DEFAULT_ACCOUNT_ID`、 `createTopLevelChannelDmPolicy`、`setSetupChannelEnabled` 和 `splitSetupEntries` -- 只有当你还需要更重的共享设置/配置辅助工具时，才使用更宽泛的 `openclaw/plugin-sdk/setup` 接口，例如 +- 仅当你还需要更重型的共享设置/配置辅助函数时，才使用更宽泛的 + `openclaw/plugin-sdk/setup` 接口，例如 `moveSingleAccountChannelSectionToDefaultAccount(...)` -如果你的渠道只想在设置界面中提示“请先安装这个插件”，请优先使用 `createOptionalChannelSetupSurface(...)`。生成的 adapter/wizard 在配置写入和最终完成时会默认关闭，并会在验证、完成和文档链接文案中复用同一条“需要安装”的消息。 +如果你的渠道只想在设置界面中提示“先安装此插件”，优先使用 `createOptionalChannelSetupSurface(...)`。生成的适配器/向导会在配置写入和最终确认时默认拒绝，并且会在校验、finalize 和文档链接文案中复用相同的“需要安装”消息。 -对于其他高频渠道路径，也请优先使用窄化辅助工具，而不是更宽泛的旧接口： +对于其他高频渠道路径，也应优先使用窄辅助函数，而不是更宽泛的旧接口： - `openclaw/plugin-sdk/account-core`、 `openclaw/plugin-sdk/account-id`、 @@ -132,30 +138,32 @@ x-i18n: `openclaw/plugin-sdk/account-helpers`，用于多账户配置和 默认账户回退 - `openclaw/plugin-sdk/inbound-envelope` 和 - `openclaw/plugin-sdk/inbound-reply-dispatch`，用于入站路由/信封和 + `openclaw/plugin-sdk/inbound-reply-dispatch`，用于入站路由/信封以及 记录并分发接线 - `openclaw/plugin-sdk/messaging-targets`，用于目标解析/匹配 - `openclaw/plugin-sdk/outbound-media` 和 `openclaw/plugin-sdk/outbound-runtime`，用于媒体加载以及出站 - 身份/发送委托和负载规划 + 身份/发送委托和载荷规划 - `openclaw/plugin-sdk/thread-bindings-runtime`，用于线程绑定生命周期 和适配器注册 -- 仅当仍然需要旧版 智能体/媒体负载字段布局时，才使用 `openclaw/plugin-sdk/agent-media-payload` +- 仅在仍需要旧版智能体/媒体 + 载荷字段布局时，使用 `openclaw/plugin-sdk/agent-media-payload` - `openclaw/plugin-sdk/telegram-command-config`，用于 Telegram 自定义命令 - 规范化、重复/冲突校验，以及一个对回退稳定的命令 + 规范化、重复/冲突校验，以及稳定回退的命令 配置契约 -仅认证渠道通常可以停留在默认路径：核心处理批准，而插件只需公开出站/认证能力。像 Matrix、Slack、Telegram 以及自定义聊天传输这类原生批准渠道，应使用共享的原生辅助工具，而不是自行实现批准生命周期。 +仅认证类渠道通常可以停留在默认路径：核心负责批准，插件只需暴露出站/认证能力。像 Matrix、Slack、Telegram 和自定义聊天传输这类原生批准渠道，应使用共享的原生辅助函数，而不是自行实现批准生命周期。 ## 入站提及策略 -请将入站提及处理拆分为两层： +请将入站提及处理保持为两层拆分： -- 插件拥有的证据收集 +- 插件负责的证据收集 - 共享策略评估 -提及策略决策请使用 `openclaw/plugin-sdk/channel-mention-gating`。 -只有在你需要更宽泛的入站辅助工具 barrel 时，才使用 `openclaw/plugin-sdk/channel-inbound`。 +对于提及策略决策，请使用 `openclaw/plugin-sdk/channel-mention-gating`。 +仅当你需要更宽泛的入站 +辅助函数 barrel 时，才使用 `openclaw/plugin-sdk/channel-inbound`。 适合放在插件本地逻辑中的内容： @@ -163,20 +171,20 @@ x-i18n: - 引用机器人检测 - 线程参与检查 - 服务/系统消息排除 -- 证明机器人参与所需的平台原生缓存 +- 用于证明机器人参与的平台原生缓存 -适合使用共享辅助工具的内容： +适合放在共享辅助函数中的内容： - `requireMention` - 显式提及结果 -- 隐式提及允许列表 +- 隐式提及允许名单 - 命令绕过 - 最终跳过决策 推荐流程： 1. 计算本地提及事实。 -2. 将这些事实传入 `resolveInboundMentionDecision({ facts, policy })`。 +2. 将这些事实传给 `resolveInboundMentionDecision({ facts, policy })`。 3. 在你的入站门控中使用 `decision.effectiveWasMentioned`、`decision.shouldBypassMention` 和 `decision.shouldSkip`。 ```typescript @@ -216,7 +224,8 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -`api.runtime.channel.mentions` 为已经依赖运行时注入的内置渠道插件公开了同一组共享提及辅助工具： +`api.runtime.channel.mentions` 为 +已经依赖运行时注入的内置渠道插件暴露了同样的共享提及辅助函数： - `buildMentionRegexes` - `matchesMentionPatterns` @@ -226,10 +235,12 @@ if (decision.shouldSkip) return; 如果你只需要 `implicitMentionKindWhen` 和 `resolveInboundMentionDecision`，请从 -`openclaw/plugin-sdk/channel-mention-gating` 导入，以避免加载无关的入站运行时辅助工具。 +`openclaw/plugin-sdk/channel-mention-gating` 导入，以避免加载无关的入站 +运行时辅助函数。 -旧版的 `resolveMentionGating*` 辅助工具仍保留在 -`openclaw/plugin-sdk/channel-inbound` 中，但仅作为兼容性导出。新代码应使用 `resolveInboundMentionDecision({ facts, policy })`。 +较旧的 `resolveMentionGating*` 辅助函数仍保留在 +`openclaw/plugin-sdk/channel-inbound` 上，但仅作为兼容性导出。新代码 +应使用 `resolveInboundMentionDecision({ facts, policy })`。 ## 演练 @@ -237,8 +248,8 @@ if (decision.shouldSkip) return; 创建标准插件文件。`package.json` 中的 `channel` 字段 - 是使其成为渠道插件的关键。完整的包元数据接口 - 参见 [插件设置和配置](/zh-CN/plugins/sdk-setup#openclaw-channel)： + 决定它是一个渠道插件。有关完整的包元数据接口， + 请参见 [插件设置和配置](/zh-CN/plugins/sdk-setup#openclaw-channel)： ```json package.json @@ -288,8 +299,7 @@ if (decision.shouldSkip) return; - `ChannelPlugin` 接口包含许多可选的适配器接口。先从 - 最小集合开始——`id` 和 `setup`——然后按需添加适配器。 + `ChannelPlugin` 接口有许多可选适配器接口。先从最小集合开始——`id` 和 `setup`——然后按需添加适配器。 创建 `src/channel.ts`： @@ -384,24 +394,23 @@ if (decision.shouldSkip) return; }); ``` - - 你无需手动实现底层适配器接口，而是传入声明式选项， - 由构建器来完成组合： + + 你不需要手动实现底层适配器接口，而是传入声明式选项， + 构建器会完成组合： - | Option | What it wires | + | 选项 | 它会接线什么 | | --- | --- | - | `security.dm` | Scoped DM security resolver from config fields | - | `pairing.text` | Text-based DM pairing flow with code exchange | - | `threading` | Reply-to-mode resolver (fixed, account-scoped, or custom) | - | `outbound.attachedResults` | Send functions that return result metadata (message IDs) | + | `security.dm` | 从配置字段解析带作用域的私信安全 | + | `pairing.text` | 基于文本和验证码交换的私信配对流程 | + | `threading` | reply-to 模式解析器（固定、账户作用域或自定义） | + | `outbound.attachedResults` | 返回结果元数据（消息 ID）的发送函数 | - 如果你需要完全控制， - 也可以直接传入原始适配器对象，而不是这些声明式选项。 + 如果你需要完全控制，也可以传入原始适配器对象，而不是这些声明式选项。 - + 创建 `index.ts`： ```typescript index.ts @@ -437,14 +446,14 @@ if (decision.shouldSkip) return; }); ``` - 将渠道拥有的 CLI 描述符放在 `registerCliMetadata(...)` 中，这样 OpenClaw + 将渠道自有的 CLI 描述符放在 `registerCliMetadata(...)` 中，这样 OpenClaw 就能在不激活完整渠道运行时的情况下，在根帮助中显示它们； - 而正常的完整加载仍会获取相同描述符来完成真实命令注册。 - 请将 `registerFull(...)` 保留给仅运行时工作。 + 同时，常规完整加载仍会获取相同描述符，以进行真实命令 + 注册。将 `registerFull(...)` 保留给仅运行时的工作。 如果 `registerFull(...)` 注册 Gateway 网关 RPC 方法，请使用 插件专属前缀。核心管理命名空间（`config.*`、 - `exec.approvals.*`、`wizard.*`、`update.*`）仍然是保留的，并且始终 - 解析为 `operator.admin`。 + `exec.approvals.*`、`wizard.*`、`update.*`）仍然保留，并且始终 + 解析到 `operator.admin`。 `defineChannelPluginEntry` 会自动处理注册模式拆分。有关全部 选项，请参见 [入口点](/zh-CN/plugins/sdk-entrypoints#definechannelpluginentry)。 @@ -461,21 +470,19 @@ if (decision.shouldSkip) return; ``` 当渠道被禁用或尚未配置时，OpenClaw 会加载这个入口，而不是完整入口。 - 这可避免在设置流程中拉入沉重的运行时代码。 - 详情参见 [设置和配置](/zh-CN/plugins/sdk-setup#setup-entry)。 + 这样可以避免在设置流程中拉入沉重的运行时代码。 + 详情请参见 [设置和配置](/zh-CN/plugins/sdk-setup#setup-entry)。 将设置安全导出拆分到 sidecar - 模块中的内置工作区渠道，如果还需要一个 - 显式的设置期运行时 setter，可以使用 - `openclaw/plugin-sdk/channel-entry-contract` 中的 - `defineBundledChannelSetupEntry(...)`。 + 模块中的内置工作区渠道，在同时需要一个 + 显式设置时运行时 setter 时，可以使用来自 + `openclaw/plugin-sdk/channel-entry-contract` 的 `defineBundledChannelSetupEntry(...)`。 - 你的插件需要从平台接收消息并将其转发到 - OpenClaw。典型模式是一个 webhook，它会验证请求，并 - 通过你的渠道入站处理器进行分发： + 你的插件需要从平台接收消息，并将其转发给 + OpenClaw。典型模式是一个 webhook，它会验证请求，并通过你渠道的入站处理器进行分发： ```typescript registerFull(api) { @@ -499,9 +506,9 @@ if (decision.shouldSkip) return; ``` - 入站消息处理是渠道特定的。每个渠道插件都拥有 - 自己的入站流水线。请查看内置渠道插件 - （例如 Microsoft Teams 或 Google Chat 插件包）中的真实模式。 + 入站消息处理是渠道特定的。每个渠道插件都负责 + 自己的入站处理流水线。请查看内置渠道插件 + （例如 Microsoft Teams 或 Google Chat 插件包）以了解真实模式。 @@ -546,7 +553,7 @@ if (decision.shouldSkip) return; pnpm test -- /acme-chat/ ``` - 关于共享测试辅助工具，请参见 [测试](/zh-CN/plugins/sdk-testing)。 + 有关共享测试辅助函数，请参见 [测试](/zh-CN/plugins/sdk-testing)。 @@ -562,7 +569,7 @@ if (decision.shouldSkip) return; ├── api.ts # 公共导出（可选） ├── runtime-api.ts # 内部运行时导出（可选） └── src/ - ├── channel.ts # 通过 createChatChannelPlugin 定义的 ChannelPlugin + ├── channel.ts # 通过 createChatChannelPlugin 创建的 ChannelPlugin ├── channel.test.ts # 测试 ├── client.ts # 平台 API 客户端 └── runtime.ts # 运行时存储（如需要） @@ -575,26 +582,26 @@ if (decision.shouldSkip) return; 固定、账户作用域或自定义回复模式 - describeMessageTool 和动作发现 + describeMessageTool 和操作发现 inferTargetChatType、looksLikeId、resolveTarget - + 通过 api.runtime 使用 TTS、STT、媒体、子智能体 -某些内置辅助接口仍然存在，用于内置插件维护和兼容性。 -对于新的渠道插件，它们并不是推荐模式； -除非你正在直接维护该内置插件家族，否则请优先使用公共 SDK -接口中的通用 channel/setup/reply/runtime 子路径。 +某些内置辅助函数接口仍然保留，用于内置插件维护和兼容性。 +它们不是新渠道插件的推荐模式； +除非你在直接维护该内置插件家族，否则应优先使用通用 SDK +接口中的 channel/setup/reply/runtime 子路径。 ## 后续步骤 -- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 如果你的插件还提供模型 +- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 如果你的插件也提供模型 - [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考 - [插件 SDK 测试](/zh-CN/plugins/sdk-testing) — 测试工具和契约测试 - [插件清单](/zh-CN/plugins/manifest) — 完整清单 schema