diff --git a/docs/zh-CN/plugins/manifest.md b/docs/zh-CN/plugins/manifest.md index b65842b9a..04de4cea6 100644 --- a/docs/zh-CN/plugins/manifest.md +++ b/docs/zh-CN/plugins/manifest.md @@ -1,62 +1,57 @@ --- read_when: - 你正在构建一个 OpenClaw 插件 - - 你需要发布插件配置模式，或调试插件验证错误 -summary: 插件清单 + JSON schema 要求（严格配置验证） + - 你需要发布插件配置模式或调试插件验证错误 +summary: 插件清单 + JSON 架构要求（严格配置验证） title: 插件清单 x-i18n: - generated_at: "2026-05-01T22:18:25Z" + generated_at: "2026-05-02T02:49:06Z" model: gpt-5.5 provider: openai - source_hash: 19eb639d3a511c7be916764abdb179c6d3c126968f640836686cd2250950c795 + source_hash: 83fb98614783b679d6b49d2237148765708e5c5fc2ee40162d3ddd4752f763c2 source_path: plugins/manifest.md workflow: 16 --- 此页面仅适用于 **OpenClaw 原生插件清单**。 -如需兼容的包布局，请参阅 [插件包](/zh-CN/plugins/bundles)。 +有关兼容的包布局，请参阅 [插件包](/zh-CN/plugins/bundles)。 -兼容的包格式使用不同的清单文件： +兼容包格式使用不同的清单文件： - Codex 包：`.codex-plugin/plugin.json` - Claude 包：`.claude-plugin/plugin.json`，或不带清单的默认 Claude 组件 布局 - Cursor 包：`.cursor-plugin/plugin.json` -OpenClaw 也会自动检测这些包布局，但不会根据此处描述的 `openclaw.plugin.json` 架构 -进行验证。 +OpenClaw 也会自动检测这些包布局，但不会根据此处描述的 `openclaw.plugin.json` schema +对它们进行验证。 -对于兼容包，当布局符合 OpenClaw 运行时期望时，OpenClaw 目前会读取包元数据以及声明的 +对于兼容包，当布局符合 OpenClaw 运行时预期时，OpenClaw 目前会读取包元数据、声明的 skill 根目录、Claude 命令根目录、Claude 包 `settings.json` 默认值、 -Claude 包 LSP 默认值，以及受支持的钩子包。 +Claude 包 LSP 默认值，以及受支持的 hook packs。 -每个 OpenClaw 原生插件都**必须**在**插件根目录**中随附一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单来验证配置， -**无需执行插件代码**。缺失或无效的清单会被视为 -插件错误，并阻止配置验证。 +每个原生 OpenClaw 插件**必须**在**插件根目录**中附带一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单在**不执行插件代码**的情况下验证配置。缺失或无效的清单会被视为插件错误，并会阻止配置验证。 -请参阅完整的插件系统指南：[插件](/zh-CN/tools/plugin)。 -有关原生能力模型和当前外部兼容性指导： +参阅完整插件系统指南：[插件](/zh-CN/tools/plugin)。 +有关原生能力模型和当前外部兼容性指南： [能力模型](/zh-CN/plugins/architecture#public-capability-model)。 ## 此文件的作用 -`openclaw.plugin.json` 是 OpenClaw 在**加载你的 -插件代码之前**读取的元数据。以下所有内容都必须足够轻量，可以在不启动 -插件运行时的情况下检查。 +`openclaw.plugin.json` 是 OpenClaw 在**加载你的插件代码之前**读取的元数据。下面的所有内容都必须足够轻量，能够在不启动插件运行时的情况下检查。 **将它用于：** - 插件身份、配置验证和配置 UI 提示 - 凭证、新手引导和设置元数据（别名、自动启用、提供商环境变量、凭证选项） - 控制平面界面的激活提示 -- 模型系列归属的简写 +- 简写模型系列归属 - 静态能力归属快照（`contracts`） -- 共享 `openclaw qa` 宿主可检查的 QA 运行器元数据 +- 共享 `openclaw qa` host 可检查的 QA runner 元数据 - 合并到目录和验证界面的渠道专用配置元数据 -**不要将它用于：**注册运行时行为、声明代码入口点， -或 npm 安装元数据。这些内容属于你的插件代码和 `package.json`。 +**不要将它用于：**注册运行时行为、声明代码入口点或 npm 安装元数据。这些应放在你的插件代码和 `package.json` 中。 ## 最小示例 @@ -71,7 +66,7 @@ Claude 包 LSP 默认值，以及受支持的钩子包。 } ``` -## 丰富示例 +## 完整示例 ```json { @@ -150,72 +145,74 @@ Claude 包 LSP 默认值，以及受支持的钩子包。 ## 顶层字段参考 -| 字段 | 必填 | 类型 | 含义 | -| ------------------------------------ | -------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | 是 | `string` | 规范插件 id。这是在 `plugins.entries.` 中使用的 id。 | -| `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 | -| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略它，或设置任何非 `true` 值，即可让插件默认保持禁用。 | -| `legacyPluginIds` | 否 | `string[]` | 会规范化为此规范插件 id 的旧版 id。 | -| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当凭证、配置或模型引用提及它们时，应自动启用此插件的提供商 id。 | -| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明由 `plugins.slots.*` 使用的互斥插件类型。 | -| `channels` | 否 | `string[]` | 此插件拥有的渠道 id。用于设备发现和配置验证。 | -| `providers` | 否 | `string[]` | 此插件拥有的提供商 id。 | -| `providerDiscoveryEntry` | 否 | `string` | 轻量级提供商发现模块路径，相对于插件根目录，用于清单作用域的提供商目录元数据，可在不激活完整插件运行时的情况下加载。 | -| `modelSupport` | 否 | `object` | 清单拥有的模型系列元数据简写，用于在运行时之前自动加载插件。 | -| `modelCatalog` | 否 | `object` | 此插件拥有的提供商的声明式模型目录元数据。这是未来只读列表、新手引导、模型选择器、别名和抑制功能的控制平面契约，无需加载插件运行时。 | -| `modelPricing` | 否 | `object` | 提供商拥有的外部价格查询策略。用它让本地/自托管提供商退出远程价格目录，或将提供商引用映射到 OpenRouter/LiteLLM 目录 id，而无需在核心中硬编码提供商 id。 | -| `modelIdNormalization` | 否 | `object` | 提供商拥有的模型 id 别名/前缀清理，必须在提供商运行时加载前执行。 | -| `providerEndpoints` | 否 | `object[]` | 清单拥有的端点 host/baseUrl 元数据，用于核心必须在提供商运行时加载前分类的提供商路由。 | -| `providerRequest` | 否 | `object` | 通用请求策略在提供商运行时加载前使用的低成本提供商系列和请求兼容性元数据。 | -| `cliBackends` | 否 | `string[]` | 此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 | -| `syntheticAuthRefs` | 否 | `string[]` | 提供商或 CLI 后端引用，其插件拥有的合成凭证钩子应在运行时加载前的冷模型发现期间探测。 | -| `nonSecretAuthMarkers` | 否 | `string[]` | 内置插件拥有的占位 API 密钥值，表示非机密的本地、OAuth 或环境凭证状态。 | -| `commandAliases` | 否 | `object[]` | 此插件拥有的命令名称，应在运行时加载前生成感知插件的配置和 CLI 诊断。 | -| `providerAuthEnvVars` | 否 | `Record` | 已弃用的兼容性环境变量元数据，用于提供商凭证/Status 查找。新插件首选 `setup.providers[].envVars`；OpenClaw 在弃用窗口期内仍会读取此项。 | -| `providerAuthAliases` | 否 | `Record` | 应复用另一个提供商 id 进行凭证查找的提供商 id，例如共享基础提供商 API 密钥和凭证配置文件的编码提供商。 | -| `channelEnvVars` | 否 | `Record` | 低成本渠道环境变量元数据，OpenClaw 可在不加载插件代码的情况下检查。将它用于通用启动/配置助手应能看到的环境变量驱动渠道设置或凭证界面。 | -| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选提供商解析和简单 CLI 标志接线的低成本凭证选项元数据。 | -| `activation` | 否 | `object` | 用于启动、提供商、命令、渠道、路由和能力触发加载的低成本激活规划器元数据。仅为元数据；插件运行时仍拥有实际行为。 | -| `setup` | 否 | `object` | 低成本设置/新手引导描述符，设备发现和设置界面可在不加载插件运行时的情况下检查。 | -| `qaRunners` | 否 | `object[]` | 共享 `openclaw qa` 宿主在插件运行时加载前使用的低成本 QA 运行器描述符。 | -| `contracts` | 否 | `object` | 外部凭证钩子、语音、实时转写、实时语音、媒体理解、图像生成、音乐生成、视频生成、网页抓取、Web 搜索和工具归属的静态内置能力快照。 | -| `mediaUnderstandingProviderMetadata` | 否 | `Record` | 为 `contracts.mediaUnderstandingProviders` 中声明的提供商 id 提供的低成本媒体理解默认值。 | -| `channelConfigs` | 否 | `Record` | 清单拥有的渠道配置元数据，在运行时加载前合并到设备发现和验证界面中。 | -| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 | -| `name` | 否 | `string` | 人类可读的插件名称。 | -| `description` | 否 | `string` | 在插件界面中显示的简短摘要。 | -| `version` | 否 | `string` | 信息性插件版本。 | -| `uiHints` | 否 | `Record` | 配置字段的 UI 标签、占位符和敏感性提示。 | +| 字段 | 必填 | 类型 | 含义 | +| ------------------------------------ | ---- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | 是 | `string` | 规范插件 id。这是在 `plugins.entries.` 中使用的 id。 | +| `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 | +| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略它，或设置任意非 `true` 值，可让插件默认保持禁用。 | +| `legacyPluginIds` | 否 | `string[]` | 会规范化为此规范插件 id 的旧版 id。 | +| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当凭证、配置或模型引用提到这些提供商 id 时，应自动启用此插件。 | +| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明由 `plugins.slots.*` 使用的独占插件类型。 | +| `channels` | 否 | `string[]` | 此插件拥有的渠道 id。用于设备发现和配置验证。 | +| `providers` | 否 | `string[]` | 此插件拥有的提供商 id。 | +| `providerDiscoveryEntry` | 否 | `string` | 轻量级提供商发现模块路径，相对于插件根目录，用于清单作用域内的提供商目录元数据，可在不激活完整插件运行时的情况下加载。 | +| `modelSupport` | 否 | `object` | 清单拥有的简写模型系列元数据，用于在运行时之前自动加载插件。 | +| `modelCatalog` | 否 | `object` | 此插件拥有的提供商的声明式模型目录元数据。这是未来只读列表、新手引导、模型选择器、别名和抑制功能的控制平面契约，无需加载插件运行时。 | +| `modelPricing` | 否 | `object` | 提供商拥有的外部定价查询策略。用它让本地/自托管提供商退出远程定价目录，或将提供商引用映射到 OpenRouter/LiteLLM 目录 id，而无需在核心中硬编码提供商 id。 | +| `modelIdNormalization` | 否 | `object` | 提供商拥有的模型 id 别名/前缀清理，必须在提供商运行时加载前运行。 | +| `providerEndpoints` | 否 | `object[]` | 清单拥有的端点 host/baseUrl 元数据，用于核心在提供商运行时加载前对提供商路由进行分类。 | +| `providerRequest` | 否 | `object` | 轻量级提供商系列和请求兼容性元数据，由通用请求策略在提供商运行时加载前使用。 | +| `cliBackends` | 否 | `string[]` | 此插件拥有的 CLI 推理后端 id。用于从显式配置引用进行启动自动激活。 | +| `syntheticAuthRefs` | 否 | `string[]` | 提供商或 CLI 后端引用，其插件拥有的合成凭证钩子应在运行时加载前的冷模型发现期间被探测。 | +| `nonSecretAuthMarkers` | 否 | `string[]` | 内置插件拥有的占位 API key 值，表示非密钥的本地、OAuth 或环境凭据状态。 | +| `commandAliases` | 否 | `object[]` | 此插件拥有的命令名称，应在运行时加载前生成插件感知的配置和 CLI 诊断。 | +| `providerAuthEnvVars` | 否 | `Record` | 已弃用的兼容性环境变量元数据，用于提供商凭证/Status 查询。新插件请优先使用 `setup.providers[].envVars`；OpenClaw 在弃用窗口期间仍会读取此项。 | +| `providerAuthAliases` | 否 | `Record` | 应复用另一个提供商 id 进行凭证查询的提供商 id，例如共享基础提供商 API key 和凭证配置文件的编码提供商。 | +| `channelEnvVars` | 否 | `Record` | OpenClaw 可在不加载插件代码的情况下检查的轻量级渠道环境变量元数据。将此项用于由环境变量驱动的渠道设置，或通用启动/配置帮助器应看到的凭证界面。 | +| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选提供商解析和简单 CLI 标志接线的轻量级凭证选择元数据。 | +| `activation` | 否 | `object` | 用于启动、提供商、命令、渠道、路由和能力触发加载的轻量级激活规划器元数据。仅为元数据；插件运行时仍拥有实际行为。 | +| `setup` | 否 | `object` | 轻量级设置/新手引导描述符，设备发现和设置界面可在不加载插件运行时的情况下检查。 | +| `qaRunners` | 否 | `object[]` | 共享 `openclaw qa` 宿主在插件运行时加载前使用的轻量级 QA 运行器描述符。 | +| `contracts` | 否 | `object` | 外部凭证钩子、语音、实时转写、实时语音、媒体理解、图像生成、音乐生成、视频生成、Web 获取、Web 搜索和工具所有权的静态内置能力快照。 | +| `mediaUnderstandingProviderMetadata` | 否 | `Record` | 针对 `contracts.mediaUnderstandingProviders` 中声明的提供商 id 的轻量级媒体理解默认值。 | +| `channelConfigs` | 否 | `Record` | 清单拥有的渠道配置元数据，在运行时加载前合并到设备发现和验证界面中。 | +| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 | +| `name` | 否 | `string` | 人类可读的插件名称。 | +| `description` | 否 | `string` | 显示在插件界面中的简短摘要。 | +| `version` | 否 | `string` | 信息性插件版本。 | +| `uiHints` | 否 | `Record` | 配置字段的 UI 标签、占位符和敏感性提示。 | ## providerAuthChoices 参考 -每个 `providerAuthChoices` 条目描述一个新手引导或凭证选项。 +每个 `providerAuthChoices` 条目描述一个新手引导或凭证选择。 OpenClaw 会在提供商运行时加载前读取此项。 -提供商设置列表使用这些清单选项、从描述符派生的设置 -选项，以及安装目录元数据，而无需加载提供商运行时。 +提供商设置列表会使用这些清单选择、从描述符派生的设置 +选择，以及安装目录元数据，而无需加载提供商运行时。 -| 字段 | 必填 | 类型 | 含义 | -| --------------------- | ---- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -| `provider` | 是 | `string` | 此选择所属的提供商 ID。 | -| `method` | 是 | `string` | 要分派到的身份验证方法 ID。 | -| `choiceId` | 是 | `string` | 新手引导和 CLI 流程使用的稳定身份验证选择 ID。 | -| `choiceLabel` | 否 | `string` | 面向用户的标签。如果省略，OpenClaw 会回退到 `choiceId`。 | -| `choiceHint` | 否 | `string` | 选择器的简短辅助文本。 | -| `assistantPriority` | 否 | `number` | 值越低，在助手驱动的交互式选择器中排序越靠前。 | -| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 从助手选择器中隐藏此选择，同时仍允许手动 CLI 选择。 | -| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选择的旧版选择 ID。 | -| `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"]`。 | +| 字段 | 必需 | 类型 | 含义 | +| --------------------- | ---- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ | +| `provider` | 是 | `string` | 此选项所属的提供商 ID。 | +| `method` | 是 | `string` | 要分发到的认证方法 ID。 | +| `choiceId` | 是 | `string` | 新手引导和 CLI 流程使用的稳定认证选项 ID。 | +| `choiceLabel` | 否 | `string` | 面向用户的标签。如果省略，OpenClaw 会回退到 `choiceId`。 | +| `choiceHint` | 否 | `string` | 用于选择器的简短辅助文本。 | +| `assistantPriority` | 否 | `number` | 数值越低，在助手驱动的交互式选择器中排序越靠前。 | +| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 从助手选择器中隐藏该选项，同时仍允许手动 CLI 选择。 | +| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选项的旧版选项 ID。 | +| `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"]`。 | ## commandAliases 参考 -当插件拥有一个运行时命令名称，而用户可能误将其放入 `plugins.allow` 或尝试作为根 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用此元数据进行诊断，而无需导入插件运行时代码。 +当插件拥有一个运行时命令名称，而用户可能会误将其放入 `plugins.allow` +或尝试将其作为根 CLI 命令运行时，请使用 `commandAliases`。OpenClaw +使用此元数据进行诊断，而无需导入插件运行时代码。 ```json { @@ -229,24 +226,33 @@ OpenClaw 会在提供商运行时加载前读取此项。 } ``` -| 字段 | 必填 | 类型 | 含义 | -| ------------ | ---- | ----------------- | -------------------------------------------------------------------- | -| `name` | 是 | `string` | 属于此插件的命令名称。 | -| `kind` | 否 | `"runtime-slash"` | 将别名标记为聊天斜杠命令，而不是根 CLI 命令。 | -| `cliCommand` | 否 | `string` | 如果存在，用于建议执行 CLI 操作的相关根 CLI 命令。 | +| 字段 | 必需 | 类型 | 含义 | +| ------------ | ---- | ----------------- | ----------------------------------------------------------------- | +| `name` | 是 | `string` | 属于此插件的命令名称。 | +| `kind` | 否 | `"runtime-slash"` | 将别名标记为聊天斜杠命令，而不是根 CLI 命令。 | +| `cliCommand` | 否 | `string` | 如果存在，用于建议 CLI 操作的相关根 CLI 命令。 | ## activation 参考 -当插件可以低成本声明哪些控制平面事件应将其纳入激活/加载计划时，请使用 `activation`。 +当插件可以低成本声明哪些控制平面事件应将其包含在激活/加载计划中时，请使用 `activation`。 -此块是规划器元数据，不是生命周期 API。它不会注册运行时行为，不会替代 `register(...)`，也不承诺插件代码已经执行。激活规划器会使用这些字段在回退到现有清单所有权元数据（例如 `providers`、`channels`、`commandAliases`、`setup.providers`、`contracts.tools` 和钩子）之前缩小候选插件范围。 +此块是规划器元数据，而不是生命周期 API。它不会注册运行时行为，不会替代 +`register(...)`，也不承诺插件代码已经执行。激活规划器使用这些字段在回退到现有清单所有权元数据 +（例如 `providers`、`channels`、`commandAliases`、`setup.providers`、 +`contracts.tools` 和钩子）之前缩小候选插件范围。 -优先使用已经描述所有权的最窄元数据。当 `providers`、`channels`、`commandAliases`、设置描述符或 `contracts` 能表达这种关系时，请使用这些字段。对无法由这些所有权字段表示的额外规划器提示使用 `activation`。 -对于 `claude-cli`、`codex-cli` 或 `google-gemini-cli` 等 CLI 运行时别名，请使用顶层 `cliBackends`；`activation.onAgentHarnesses` 仅用于尚无所有权字段的嵌入式智能体 harness ID。 +优先使用已经描述所有权的最窄元数据。当 `providers`、`channels`、`commandAliases`、设置描述符或 `contracts` +能够表达这种关系时，请使用这些字段。对于无法由这些所有权字段表示的额外规划器提示，请使用 `activation`。 +对 CLI 运行时别名（例如 `claude-cli`、`codex-cli` 或 `google-gemini-cli`）使用顶层 `cliBackends`； +`activation.onAgentHarnesses` 仅用于尚无所有权字段的嵌入式智能体 harness ID。 -此块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时/插件入口点。当前消费者会在更广泛的插件加载前将其用作缩小范围的提示，因此缺失非启动激活元数据通常只会影响性能；只要清单所有权回退仍然存在，它不应改变正确性。 +此块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时/插件入口点。 +当前消费者会在更广泛地加载插件之前将其用作缩小范围的提示，因此缺少非启动激活元数据通常只会影响性能； +只要清单所有权回退仍然存在，就不应改变正确性。 -每个插件都应有意设置 `activation.onStartup`。只有在插件必须在 Gateway 网关启动期间运行时，才将其设置为 `true`。当插件在启动时处于惰性状态，并且只应通过更窄的触发器加载时，将其设置为 `false`。省略 `onStartup` 不再隐式在启动时加载插件；请为启动、渠道、配置、智能体 harness、记忆或其他更窄的激活触发器使用显式激活元数据。 +每个插件都应有意设置 `activation.onStartup`。仅当插件必须在 Gateway 网关启动期间运行时，才将其设为 `true`。 +当插件在启动时处于惰性状态，并且只应由更窄的触发器加载时，将其设为 `false`。 +省略 `onStartup` 不再会隐式启动加载该插件；请为启动、渠道、配置、智能体 harness、记忆或其他更窄的激活触发器使用显式激活元数据。 ```json { @@ -262,31 +268,35 @@ OpenClaw 会在提供商运行时加载前读取此项。 } ``` -| 字段 | 必填 | 类型 | 含义 | -| ------------------ | ---- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `onStartup` | 否 | `boolean` | 显式 Gateway 网关启动激活。每个插件都应设置此项。`true` 会在启动期间导入插件；`false` 会让它保持启动惰性，除非另一个匹配的触发器要求加载。 | -| `onProviders` | 否 | `string[]` | 应将此插件纳入激活/加载计划的提供商 ID。 | -| `onAgentHarnesses` | 否 | `string[]` | 应将此插件纳入激活/加载计划的嵌入式智能体 harness 运行时 ID。对 CLI 后端别名使用顶层 `cliBackends`。 | -| `onCommands` | 否 | `string[]` | 应将此插件纳入激活/加载计划的命令 ID。 | -| `onChannels` | 否 | `string[]` | 应将此插件纳入激活/加载计划的渠道 ID。 | -| `onRoutes` | 否 | `string[]` | 应将此插件纳入激活/加载计划的路由种类。 | -| `onConfigPaths` | 否 | `string[]` | 当路径存在且未被显式禁用时，应将此插件纳入启动/加载计划的相对于根的配置路径。 | -| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的宽泛能力提示。请尽可能优先使用更窄的字段。 | +| 字段 | 必需 | 类型 | 含义 | +| ------------------ | ---- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `onStartup` | 否 | `boolean` | 显式 Gateway 网关启动激活。每个插件都应设置此项。`true` 会在启动期间导入插件；`false` 会使其在启动时保持惰性，除非另一个匹配的触发器要求加载。 | +| `onProviders` | 否 | `string[]` | 应将此插件包含在激活/加载计划中的提供商 ID。 | +| `onAgentHarnesses` | 否 | `string[]` | 应将此插件包含在激活/加载计划中的嵌入式智能体 harness 运行时 ID。对 CLI 后端别名使用顶层 `cliBackends`。 | +| `onCommands` | 否 | `string[]` | 应将此插件包含在激活/加载计划中的命令 ID。 | +| `onChannels` | 否 | `string[]` | 应将此插件包含在激活/加载计划中的渠道 ID。 | +| `onRoutes` | 否 | `string[]` | 应将此插件包含在激活/加载计划中的路由类型。 | +| `onConfigPaths` | 否 | `string[]` | 当路径存在且未被显式禁用时，应将此插件包含在启动/加载计划中的根相对配置路径。 | +| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的宽泛能力提示。尽可能优先使用更窄的字段。 | 当前实时消费者： - Gateway 网关启动规划使用 `activation.onStartup` 进行显式启动导入 - 命令触发的 CLI 规划会回退到旧版 `commandAliases[].cliCommand` 或 `commandAliases[].name` -- 智能体运行时启动规划对嵌入式 harness 使用 `activation.onAgentHarnesses`，并对 CLI 运行时别名使用顶层 `cliBackends[]` -- 渠道触发的设置/渠道规划在缺少显式渠道激活元数据时会回退到旧版 `channels[]` 所有权 +- 智能体运行时启动规划对嵌入式 harness 使用 `activation.onAgentHarnesses`，对 CLI 运行时别名使用顶层 `cliBackends[]` +- 渠道触发的设置/渠道规划会在缺少显式渠道激活元数据时回退到旧版 `channels[]` 所有权 - 启动插件规划会对非渠道根配置界面使用 `activation.onConfigPaths`，例如内置浏览器插件的 `browser` 块 -- 提供商触发的设置/运行时规划在缺少显式提供商激活元数据时会回退到旧版 `providers[]` 和顶层 `cliBackends[]` 所有权 +- 提供商触发的设置/运行时规划会在缺少显式提供商激活元数据时回退到旧版 `providers[]` 和顶层 `cliBackends[]` 所有权 -规划器诊断可以区分显式激活提示和清单所有权回退。例如，`activation-command-hint` 表示 `activation.onCommands` 匹配，而 `manifest-command-alias` 表示规划器改用了 `commandAliases` 所有权。这些原因标签用于宿主诊断和测试；插件作者应继续声明最能描述所有权的元数据。 +规划器诊断可以区分显式激活提示与清单所有权回退。例如，`activation-command-hint` 表示 +`activation.onCommands` 匹配，而 `manifest-command-alias` 表示规划器改用了 `commandAliases` 所有权。 +这些原因标签用于主机诊断和测试；插件作者应继续声明最能描述所有权的元数据。 ## qaRunners 参考 -当插件在共享的 `openclaw qa` 根命令下贡献一个或多个传输运行器时，请使用 `qaRunners`。保持此元数据低成本且静态；插件运行时仍通过导出 `qaRunnerCliRegistrations` 的轻量级 `runtime-api.ts` 界面拥有实际 CLI 注册。 +当插件在共享的 `openclaw qa` 根之下贡献一个或多个传输运行器时，请使用 `qaRunners`。 +保持此元数据低成本且静态；插件运行时仍通过轻量级 `runtime-api.ts` 界面拥有实际的 CLI 注册， +该界面会导出 `qaRunnerCliRegistrations`。 ```json { @@ -299,14 +309,14 @@ OpenClaw 会在提供商运行时加载前读取此项。 } ``` -| 字段 | 必填 | 类型 | 含义 | -| ------------- | ---- | -------- | ------------------------------------------------------------ | -| `commandName` | 是 | `string` | 挂载在 `openclaw qa` 下的子命令，例如 `matrix`。 | -| `description` | 否 | `string` | 当共享宿主需要存根命令时使用的回退帮助文本。 | +| 字段 | 必需 | 类型 | 含义 | +| ------------- | ---- | -------- | ------------------------------------------------------------------ | +| `commandName` | 是 | `string` | 挂载在 `openclaw qa` 之下的子命令，例如 `matrix`。 | +| `description` | 否 | `string` | 当共享主机需要存根命令时使用的回退帮助文本。 | ## setup 参考 -当设置和新手引导界面需要在运行时加载前获取低成本的插件自有元数据时，请使用 `setup`。 +当设置和新手引导界面需要在运行时加载之前获取低成本的插件自有元数据时，请使用 `setup`。 ```json { @@ -334,55 +344,55 @@ OpenClaw 会在提供商运行时加载前读取此项。 } ``` -顶层 `cliBackends` 仍然有效，并继续描述 CLI 推断后端。`setup.cliBackends` 是面向控制平面/设置流程的设置专用描述符表面，应保持为仅元数据。 +顶层 `cliBackends` 仍然有效，并继续描述 CLI 推断后端。`setup.cliBackends` 是用于控制平面/设置流程的设置专用描述符表面，这些流程应保持仅元数据。 -存在 `setup.providers` 和 `setup.cliBackends` 时，它们是设置发现的首选描述符优先查找表面。如果描述符只缩小候选插件范围，而设置仍需要更丰富的设置时运行时钩子，请设置 `requiresRuntime: true`，并保留 `setup-api` 作为回退执行路径。 +存在时，`setup.providers` 和 `setup.cliBackends` 是设置发现首选的描述符优先查找表面。如果描述符只缩小候选插件范围，而设置仍需要更丰富的设置期运行时钩子，请设置 `requiresRuntime: true`，并保留 `setup-api` 作为回退执行路径。 -OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.providers[].envVars`。`providerAuthEnvVars` 在弃用窗口期间仍通过兼容适配器受支持，但仍使用它的非内置插件会收到清单诊断。新插件应将设置/Status 环境变量元数据放在 `setup.providers[].envVars` 上。 +OpenClaw 还会在通用提供商认证和环境变量查找中包含 `setup.providers[].envVars`。`providerAuthEnvVars` 在弃用窗口期间仍通过兼容适配器受支持，但仍使用它的非内置插件会收到清单诊断。新插件应将设置/Status 环境元数据放在 `setup.providers[].envVars` 上。 -当没有可用的设置入口，或者 `setup.requiresRuntime: false` 声明不需要设置运行时时，OpenClaw 也可以从 `setup.providers[].authMethods` 推导简单的设置选项。对于自定义标签、CLI 标志、新手引导范围和助手元数据，显式的 `providerAuthChoices` 条目仍然优先。 +当没有可用的设置条目，或 `setup.requiresRuntime: false` 声明不需要设置运行时时，OpenClaw 也可以从 `setup.providers[].authMethods` 推导简单的设置选项。对于自定义标签、CLI 标志、新手引导范围和助手元数据，显式 `providerAuthChoices` 条目仍是首选。 -只有当这些描述符足以支持设置表面时，才设置 `requiresRuntime: false`。OpenClaw 会将显式的 `false` 视为仅描述符契约，并且不会执行 `setup-api` 或 `openclaw.setupEntry` 来进行设置查找。如果仅描述符插件仍随附这些设置运行时入口之一，OpenClaw 会报告一个追加诊断并继续忽略它。省略 `requiresRuntime` 会保留旧版回退行为，因此已添加描述符但未添加该标志的现有插件不会中断。 +仅当这些描述符足以支撑设置表面时，才设置 `requiresRuntime: false`。OpenClaw 会将显式 `false` 视为仅描述符契约，并且不会为了设置查找而执行 `setup-api` 或 `openclaw.setupEntry`。如果仅描述符插件仍随附这些设置运行时条目之一，OpenClaw 会报告一条附加诊断并继续忽略它。省略 `requiresRuntime` 会保留旧版回退行为，因此已添加描述符但未添加该标志的现有插件不会中断。 -由于设置查找可以执行插件拥有的 `setup-api` 代码，规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值必须在所有已发现插件中保持唯一。归属不明确时会失败关闭，而不是按发现顺序选择一个胜者。 +由于设置查找可以执行插件拥有的 `setup-api` 代码，规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值必须在已发现插件之间保持唯一。所有权不明确时会失败关闭，而不是从发现顺序中选出胜者。 -当设置运行时确实执行时，如果 `setup-api` 注册的提供商或 CLI 后端未由清单描述符声明，或者某个描述符没有匹配的运行时注册，设置注册表诊断会报告描述符漂移。这些诊断是追加性的，不会拒绝旧版插件。 +当设置运行时确实执行时，如果 `setup-api` 注册了清单描述符未声明的提供商或 CLI 后端，或如果某个描述符没有匹配的运行时注册，设置注册表诊断会报告描述符漂移。这些诊断是附加的，不会拒绝旧版插件。 ### setup.providers 参考 -| 字段 | 必需 | 类型 | 含义 | -| -------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------ | -| `id` | 是 | `string` | 设置或新手引导期间暴露的提供商 ID。保持规范化 ID 全局唯一。 | -| `authMethods` | 否 | `string[]` | 此提供商在不加载完整运行时的情况下支持的设置/凭证方法 ID。 | -| `envVars` | 否 | `string[]` | 通用设置/Status 表面可在插件运行时加载前检查的环境变量。 | -| `authEvidence` | 否 | `object[]` | 面向可通过非密钥标记进行身份验证的提供商的低成本本地凭证证据检查。 | +| 字段 | 必需 | 类型 | 含义 | +| -------------- | ---- | ---------- | ------------------------------------------------------------------------------------------------ | +| `id` | 是 | `string` | 设置或新手引导期间公开的提供商 ID。保持规范化 ID 全局唯一。 | +| `authMethods` | 否 | `string[]` | 此提供商在不加载完整运行时的情况下支持的设置/认证方法 ID。 | +| `envVars` | 否 | `string[]` | 通用设置/Status 表面可在插件运行时加载前检查的环境变量。 | +| `authEvidence` | 否 | `object[]` | 针对可通过非机密标记进行认证的提供商的低成本本地认证证据检查。 | -`authEvidence` 用于提供商拥有的本地凭证标记，可在不加载运行时代码的情况下验证。这些检查必须保持低成本且本地化：不进行网络调用，不读取钥匙串或密钥管理器，不执行 shell 命令，也不进行提供商 API 探测。 +`authEvidence` 用于提供商拥有的本地凭据标记，可在不加载运行时代码的情况下验证。这些检查必须保持低成本且本地：不进行网络调用，不读取钥匙串或密钥管理器，不执行 shell 命令，也不探测提供商 API。 支持的证据条目： -| 字段 | 必需 | 类型 | 含义 | -| ------------------ | -------- | ---------- | -------------------------------------------------------------------------------------------------------------- | -| `type` | 是 | `string` | 当前为 `local-file-with-env`。 | -| `fileEnvVar` | 否 | `string` | 包含显式凭证文件路径的环境变量。 | -| `fallbackPaths` | 否 | `string[]` | 当 `fileEnvVar` 缺失或为空时检查的本地凭证文件路径。支持 `${HOME}` 和 `${APPDATA}`。 | -| `requiresAnyEnv` | 否 | `string[]` | 至少一个列出的环境变量必须非空，证据才有效。 | -| `requiresAllEnv` | 否 | `string[]` | 每个列出的环境变量都必须非空，证据才有效。 | -| `credentialMarker` | 是 | `string` | 证据存在时返回的非密钥标记。 | -| `source` | 否 | `string` | 面向用户的凭证/Status 输出来源标签。 | +| 字段 | 必需 | 类型 | 含义 | +| ------------------ | ---- | ---------- | --------------------------------------------------------------------------------------------------------- | +| `type` | 是 | `string` | 当前为 `local-file-with-env`。 | +| `fileEnvVar` | 否 | `string` | 包含显式凭据文件路径的环境变量。 | +| `fallbackPaths` | 否 | `string[]` | 当 `fileEnvVar` 缺失或为空时检查的本地凭据文件路径。支持 `${HOME}` 和 `${APPDATA}`。 | +| `requiresAnyEnv` | 否 | `string[]` | 在证据有效前，列出的环境变量中至少一个必须非空。 | +| `requiresAllEnv` | 否 | `string[]` | 在证据有效前，列出的每个环境变量都必须非空。 | +| `credentialMarker` | 是 | `string` | 当证据存在时返回的非机密标记。 | +| `source` | 否 | `string` | 用于认证/Status 输出的面向用户来源标签。 | ### setup 字段 -| 字段 | 必需 | 类型 | 含义 | -| ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- | -| `providers` | 否 | `object[]` | 设置和新手引导期间暴露的提供商设置描述符。 | -| `cliBackends` | 否 | `string[]` | 用于描述符优先设置查找的设置时后端 ID。保持规范化 ID 全局唯一。 | -| `configMigrations` | 否 | `string[]` | 此插件设置表面拥有的配置迁移 ID。 | -| `requiresRuntime` | 否 | `boolean` | 描述符查找后，设置是否仍需要执行 `setup-api`。 | +| 字段 | 必需 | 类型 | 含义 | +| ------------------ | ---- | ---------- | ------------------------------------------------------------------------------------------------- | +| `providers` | 否 | `object[]` | 设置和新手引导期间公开的提供商设置描述符。 | +| `cliBackends` | 否 | `string[]` | 用于描述符优先设置查找的设置期后端 ID。保持规范化 ID 全局唯一。 | +| `configMigrations` | 否 | `string[]` | 此插件设置表面拥有的配置迁移 ID。 | +| `requiresRuntime` | 否 | `boolean` | 设置在描述符查找后是否仍需要执行 `setup-api`。 | ## uiHints 参考 -`uiHints` 是从配置字段名称到小型渲染提示的映射。 +`uiHints` 是从配置字段名到小型渲染提示的映射。 ```json { @@ -399,18 +409,18 @@ OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.pro 每个字段提示可以包含： -| 字段 | 类型 | 含义 | -| ------------- | ---------- | --------------------------------------- | -| `label` | `string` | 面向用户的字段标签。 | -| `help` | `string` | 简短辅助文本。 | -| `tags` | `string[]` | 可选 UI 标签。 | -| `advanced` | `boolean` | 将字段标记为高级。 | -| `sensitive` | `boolean` | 将字段标记为机密或敏感。 | -| `placeholder` | `string` | 表单输入的占位文本。 | +| 字段 | 类型 | 含义 | +| ------------- | ---------- | ---------------------------- | +| `label` | `string` | 面向用户的字段标签。 | +| `help` | `string` | 简短帮助文本。 | +| `tags` | `string[]` | 可选 UI 标签。 | +| `advanced` | `boolean` | 将字段标记为高级。 | +| `sensitive` | `boolean` | 将字段标记为机密或敏感。 | +| `placeholder` | `string` | 表单输入的占位符文本。 | ## contracts 参考 -仅将 `contracts` 用于静态能力归属元数据，OpenClaw 可以在不导入插件运行时的情况下读取这些元数据。 +仅将 `contracts` 用于 OpenClaw 可在不导入插件运行时的情况下读取的静态能力所有权元数据。 ```json { @@ -434,32 +444,32 @@ OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.pro 每个列表都是可选的： -| 字段 | 类型 | 含义 | -| -------------------------------- | ---------- | --------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Codex app-server 扩展工厂 ID，当前为 `codex-app-server`。 | -| `agentToolResultMiddleware` | `string[]` | 内置插件可以为其注册工具结果中间件的运行时 ID。 | -| `externalAuthProviders` | `string[]` | 此插件拥有其外部凭证配置文件钩子的提供商 ID。 | -| `speechProviders` | `string[]` | 此插件拥有的语音提供商 ID。 | -| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转写提供商 ID。 | -| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音提供商 ID。 | -| `memoryEmbeddingProviders` | `string[]` | 此插件拥有的记忆嵌入提供商 ID。 | -| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解提供商 ID。 | -| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成提供商 ID。 | -| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成提供商 ID。 | -| `webFetchProviders` | `string[]` | 此插件拥有的网页获取提供商 ID。 | -| `webSearchProviders` | `string[]` | 此插件拥有的网页搜索提供商 ID。 | -| `migrationProviders` | `string[]` | 此插件为 `openclaw migrate` 拥有的导入提供商 ID。 | -| `tools` | `string[]` | 此插件为内置契约检查拥有的 Agent 工具名称。 | +| 字段 | 类型 | 含义 | +| -------------------------------- | ---------- | ------------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | Codex 应用服务器扩展工厂 ID，当前为 `codex-app-server`。 | +| `agentToolResultMiddleware` | `string[]` | 内置插件可为其注册工具结果中间件的运行时 ID。 | +| `externalAuthProviders` | `string[]` | 此插件拥有其外部认证配置文件钩子的提供商 ID。 | +| `speechProviders` | `string[]` | 此插件拥有的语音提供商 ID。 | +| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转录提供商 ID。 | +| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音提供商 ID。 | +| `memoryEmbeddingProviders` | `string[]` | 此插件拥有的记忆嵌入提供商 ID。 | +| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解提供商 ID。 | +| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成提供商 ID。 | +| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成提供商 ID。 | +| `webFetchProviders` | `string[]` | 此插件拥有的 Web 获取提供商 ID。 | +| `webSearchProviders` | `string[]` | 此插件拥有的 Web 搜索提供商 ID。 | +| `migrationProviders` | `string[]` | 此插件为 `openclaw migrate` 拥有的导入提供商 ID。 | +| `tools` | `string[]` | 此插件为内置契约检查拥有的智能体工具名称。 | -`contracts.embeddedExtensionFactories` 保留给内置 Codex app-server 专用扩展工厂。内置工具结果转换应改为声明 `contracts.agentToolResultMiddleware`，并使用 `api.registerAgentToolResultMiddleware(...)` 注册。外部插件不能注册工具结果中间件，因为该接缝可在模型看到高信任工具输出之前重写它。 +`contracts.embeddedExtensionFactories` 保留给仅用于内置 Codex 应用服务器的扩展工厂。内置工具结果转换应声明 `contracts.agentToolResultMiddleware`，并改用 `api.registerAgentToolResultMiddleware(...)` 注册。外部插件无法注册工具结果中间件，因为该接缝可以在模型看到高信任度工具输出之前重写它。 -实现 `resolveExternalAuthProfiles` 的提供商插件应声明 `contracts.externalAuthProviders`。没有该声明的插件仍会通过已弃用的兼容性回退运行，但该回退较慢，并将在迁移窗口后移除。 +实现 `resolveExternalAuthProfiles` 的提供商插件应声明 `contracts.externalAuthProviders`。没有该声明的插件仍会通过已弃用的兼容回退运行，但该回退更慢，并将在迁移窗口之后移除。 -内置记忆嵌入提供商应为其暴露的每个适配器 ID 声明 `contracts.memoryEmbeddingProviders`，包括 `local` 等内置适配器。独立 CLI 路径会使用此清单契约，在完整 Gateway 网关运行时注册提供商之前，仅加载拥有方插件。 +内置记忆嵌入提供商应为其公开的每个适配器 ID 声明 `contracts.memoryEmbeddingProviders`，包括 `local` 等内置适配器。独立 CLI 路径会使用此清单契约，在完整 Gateway 网关运行时注册提供商之前，仅加载拥有它的插件。 ## mediaUnderstandingProviderMetadata 参考 -当媒体理解提供商具有默认模型、自动凭证回退优先级，或通用核心助手在运行时加载前需要的原生文档支持时，请使用 `mediaUnderstandingProviderMetadata`。键也必须在 `contracts.mediaUnderstandingProviders` 中声明。 +当媒体理解提供商具有默认模型、自动认证回退优先级，或通用核心助手需要在运行时加载前获知的原生文档支持时，使用 `mediaUnderstandingProviderMetadata`。键也必须在 `contracts.mediaUnderstandingProviders` 中声明。 ```json { @@ -486,25 +496,34 @@ OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.pro | 字段 | 类型 | 含义 | | ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | 此提供商暴露的媒体能力。 | +| `capabilities` | `("image" \| "audio" \| "video")[]` | 此提供商公开的媒体能力。 | | `defaultModels` | `Record` | 配置未指定模型时使用的能力到模型默认值。 | | `autoPriority` | `Record` | 数字越小，在基于凭证的自动提供商回退中排序越靠前。 | | `nativeDocumentInputs` | `"pdf"[]` | 提供商支持的原生文档输入。 | -## `channelConfigs` 参考 +## channelConfigs 参考 -当渠道插件需要在运行时加载前获取低成本的配置元数据时，使用 `channelConfigs`。只读渠道设置/Status 发现可以直接使用此元数据，用于没有可用设置入口的已配置外部渠道，或当 `setup.requiresRuntime: false` 声明设置不需要运行时时。 +当渠道插件需要在运行时加载前获取轻量配置元数据时，使用 `channelConfigs`。 +当没有可用的设置入口，或 `setup.requiresRuntime: false` 声明不需要设置运行时时，只读渠道设置/Status 发现可以直接将此元数据用于已配置的外部渠道。 -`channelConfigs` 是插件清单元数据，不是新的顶级用户配置部分。用户仍然在 `channels.` 下配置渠道实例。OpenClaw 会读取清单元数据，以便在插件运行时代码执行前决定哪个插件拥有该已配置渠道。 +`channelConfigs` 是插件清单元数据，不是新的顶层用户配置 +章节。用户仍然在 `channels.` 下配置渠道实例。 +OpenClaw 会读取清单元数据，以便在插件运行时代码执行前决定哪个插件拥有该已配置 +渠道。 -对于渠道插件，`configSchema` 和 `channelConfigs` 描述的是不同路径： +对于渠道插件，`configSchema` 和 `channelConfigs` 描述不同的 +路径： - `configSchema` 验证 `plugins.entries..config` - `channelConfigs..schema` 验证 `channels.` -声明 `channels[]` 的非内置插件也应声明匹配的 `channelConfigs` 条目。没有它们，OpenClaw 仍可加载插件，但冷路径配置模式、设置和 Control UI 界面在插件运行时执行前无法知道渠道拥有的选项形状。 +声明 `channels[]` 的非内置插件也应声明匹配的 +`channelConfigs` 条目。没有它们时，OpenClaw 仍然可以加载插件，但 +冷路径配置架构、设置和 Control UI 表面无法在插件运行时执行前知道 +渠道拥有的选项形状。 -`channelConfigs..commands.nativeCommandsAutoEnabled` 和 `nativeSkillsAutoEnabled` 可以为渠道运行时加载前执行的命令配置检查声明静态 `auto` 默认值。内置渠道也可以通过 `package.json#openclaw.channel.commands` 发布相同默认值，并与其他包拥有的渠道目录元数据并列。 +`channelConfigs..commands.nativeCommandsAutoEnabled` 和 +`nativeSkillsAutoEnabled` 可以为命令配置检查声明静态 `auto` 默认值，这些检查会在渠道运行时加载前运行。内置渠道也可以通过 `package.json#openclaw.channel.commands` 发布相同默认值，并与其他由包拥有的渠道目录元数据一起发布。 ```json { @@ -537,18 +556,18 @@ OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.pro 每个渠道条目可以包含： -| 字段 | 类型 | 含义 | -| ------------- | ------------------------ | ------------------------------------------------------------------------------------- | -| `schema` | `object` | `channels.` 的 JSON Schema。每个声明的渠道配置条目都必须提供。 | -| `uiHints` | `Record` | 该渠道配置部分的可选 UI 标签、占位符和敏感提示。 | -| `label` | `string` | 运行时元数据尚未就绪时，合并到选择器和检查界面的渠道标签。 | -| `description` | `string` | 用于检查和目录界面的简短渠道描述。 | -| `commands` | `object` | 用于运行时前配置检查的静态原生命令和原生 skill 自动默认值。 | -| `preferOver` | `string[]` | 在选择界面中，此渠道应优先于的旧版或较低优先级插件 id。 | +| 字段 | 类型 | 含义 | +| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ | +| `schema` | `object` | `channels.` 的 JSON Schema。每个声明的渠道配置条目都需要它。 | +| `uiHints` | `Record` | 该渠道配置章节的可选 UI 标签/占位符/敏感提示。 | +| `label` | `string` | 运行时元数据尚未就绪时，合并到选择器和检查表面的渠道标签。 | +| `description` | `string` | 用于检查和目录表面的简短渠道说明。 | +| `commands` | `object` | 用于运行时前配置检查的静态原生命令和原生 skill 自动默认值。 | +| `preferOver` | `string[]` | 此渠道在选择表面中应优先于的旧版或较低优先级插件 id。 | ### 替换另一个渠道插件 -当你的插件是某个渠道 id 的首选拥有者，而另一个插件也能提供该渠道 id 时，使用 `preferOver`。常见情况包括插件 id 被重命名、独立插件取代内置插件，或维护中的 fork 为了配置兼容性保留相同的渠道 id。 +当你的插件是某个渠道 id 的首选拥有者，而另一个插件也可以提供该渠道时，使用 `preferOver`。常见情况包括重命名的插件 id、取代内置插件的独立插件，或为了配置兼容性而保留相同渠道 id 的维护分支。 ```json { @@ -569,13 +588,19 @@ OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.pro } ``` -配置 `channels.chat` 时，OpenClaw 会同时考虑渠道 id 和首选插件 id。如果较低优先级插件只是因为它是内置插件或默认启用而被选中，OpenClaw 会在有效运行时配置中禁用它，从而由一个插件拥有该渠道及其工具。显式用户选择仍然优先：如果用户显式启用两个插件，OpenClaw 会保留该选择，并报告重复渠道/工具诊断，而不是静默更改请求的插件集。 +当配置了 `channels.chat` 时，OpenClaw 会同时考虑渠道 id 和 +首选插件 id。如果较低优先级插件只是因为它是内置插件或默认启用而被选中，OpenClaw 会在有效 +运行时配置中禁用它，这样一个插件就拥有该渠道及其工具。显式用户 +选择仍然优先：如果用户显式启用两个插件，OpenClaw 会 +保留该选择，并报告重复渠道/工具诊断，而不是 +静默更改请求的插件集。 -将 `preferOver` 限定在确实能提供同一渠道的插件 id 范围内。它不是通用优先级字段，也不会重命名用户配置键。 +将 `preferOver` 的作用范围限制在确实能够提供相同渠道的插件 id。 +它不是通用优先级字段，也不会重命名用户配置键。 -## `modelSupport` 参考 +## modelSupport 参考 -当 OpenClaw 应该在插件运行时加载前，根据 `gpt-5.5` 或 `claude-sonnet-4.6` 等简写模型 id 推断你的提供商插件时，使用 `modelSupport`。 +当 OpenClaw 应在插件运行时加载前，根据 `gpt-5.5` 或 `claude-sonnet-4.6` 等简写模型 id 推断你的提供商插件时，使用 `modelSupport`。 ```json { @@ -586,23 +611,24 @@ OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.pro } ``` -OpenClaw 按以下优先级处理： +OpenClaw 应用以下优先级： -- 显式 `provider/model` 引用使用拥有者的 `providers` 清单元数据 +- 显式 `provider/model` 引用使用拥有它的 `providers` 清单元数据 - `modelPatterns` 优先于 `modelPrefixes` -- 如果一个非内置插件和一个内置插件都匹配，则非内置插件胜出 -- 剩余歧义会被忽略，直到用户或配置指定提供商 +- 如果一个非内置插件和一个内置插件都匹配，则非内置 + 插件胜出 +- 剩余的歧义会被忽略，直到用户或配置指定提供商 字段： -| 字段 | 类型 | 含义 | -| --------------- | ---------- | ------------------------------------------------------------------------------ | -| `modelPrefixes` | `string[]` | 使用 `startsWith` 与简写模型 id 匹配的前缀。 | -| `modelPatterns` | `string[]` | 在移除 profile 后缀后，与简写模型 id 匹配的正则表达式源。 | +| 字段 | 类型 | 含义 | +| --------------- | ---------- | -------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | 使用 `startsWith` 与简写模型 id 匹配的前缀。 | +| `modelPatterns` | `string[]` | 移除 profile 后缀后，与简写模型 id 匹配的正则表达式源。 | -## `modelCatalog` 参考 +## modelCatalog 参考 -当 OpenClaw 应该在加载插件运行时前知道提供商模型元数据时，使用 `modelCatalog`。这是由清单拥有的来源，用于固定目录行、提供商别名、抑制规则和发现模式。运行时刷新仍属于提供商运行时代码，但清单会告诉核心何时需要运行时。 +当 OpenClaw 应在加载插件运行时前了解提供商模型元数据时，使用 `modelCatalog`。这是固定目录行、提供商别名、抑制规则和发现模式的清单拥有来源。运行时刷新仍然属于提供商运行时代码，但清单会告诉 core 何时需要运行时。 ```json { @@ -651,47 +677,54 @@ OpenClaw 按以下优先级处理： } ``` -顶级字段： +顶层字段： -| 字段 | 类型 | 含义 | -| -------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -| `providers` | `Record` | 此插件拥有的提供商 id 的目录行。键也应出现在顶级 `providers` 中。 | -| `aliases` | `Record` | 提供商别名，应解析为目录或抑制规划中的已拥有提供商。 | -| `suppressions` | `object[]` | 此插件因特定提供商原因而抑制的来自另一个来源的模型行。 | -| `discovery` | `Record` | 提供商目录是否可从清单元数据读取、刷新进缓存，或需要运行时。 | +| 字段 | 类型 | 含义 | +| -------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `providers` | `Record` | 此插件拥有的提供商 id 的目录行。键也应出现在顶层 `providers` 中。 | +| `aliases` | `Record` | 应解析为已拥有提供商的提供商别名，用于目录或抑制规划。 | +| `suppressions` | `object[]` | 此插件因提供商特定原因而抑制的来自其他来源的模型行。 | +| `discovery` | `Record` | 提供商目录是否可从清单元数据读取、刷新到缓存，或需要运行时。 | -`aliases` 参与模型目录规划中的提供商所有权查找。别名目标必须是同一插件拥有的顶级提供商。当按提供商过滤的列表使用别名时，OpenClaw 可以读取拥有者清单，并在不加载提供商运行时的情况下应用别名 API/基础 URL 覆盖。别名不会展开未过滤的目录列表；宽泛列表只发出拥有者的规范提供商行。 +`aliases` 参与模型目录规划的提供商所有权查找。 +别名目标必须是同一插件拥有的顶层提供商。当一个 +按提供商过滤的列表使用别名时，OpenClaw 可以读取拥有它的清单，并 +应用别名 API/base URL 覆盖，而无需加载提供商运行时。 +别名不会展开未过滤的目录列表；宽泛列表只发出拥有它的 +规范提供商行。 -`suppressions` 替换了旧的提供商运行时 `suppressBuiltInModel` 钩子。只有当提供商由该插件拥有，或声明为指向已拥有提供商的 `modelCatalog.aliases` 键时，抑制条目才会生效。模型解析期间不再调用运行时抑制钩子。 +`suppressions` 替代旧的提供商运行时 `suppressBuiltInModel` 钩子。 +只有当提供商由该插件拥有，或声明为 `modelCatalog.aliases` 键并指向已拥有提供商时，抑制条目才会被遵循。模型解析期间不再调用运行时 +抑制钩子。 提供商字段： -| 字段 | 类型 | 含义 | -| --------- | ------------------------ | --------------------------------------------------------------------- | -| `baseUrl` | `string` | 此提供商目录中模型的可选默认基础 URL。 | -| `api` | `ModelApi` | 此提供商目录中模型的可选默认 API 适配器。 | -| `headers` | `Record` | 适用于此提供商目录的可选静态标头。 | -| `models` | `object[]` | 必需的模型行。没有 `id` 的行会被忽略。 | +| 字段 | 类型 | 含义 | +| --------- | ------------------------ | ---------------------------------------------------------- | +| `baseUrl` | `string` | 此提供商目录中模型的可选默认 base URL。 | +| `api` | `ModelApi` | 此提供商目录中模型的可选默认 API 适配器。 | +| `headers` | `Record` | 应用于此提供商目录的可选静态标头。 | +| `models` | `object[]` | 必需的模型行。没有 `id` 的行会被忽略。 | 模型字段： | 字段 | 类型 | 含义 | | --------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------- | -| `id` | `string` | 提供商本地模型 ID，不含 `provider/` 前缀。 | +| `id` | `string` | 提供商本地模型 ID，不包含 `provider/` 前缀。 | | `name` | `string` | 可选显示名称。 | -| `api` | `ModelApi` | 可选的按模型 API 覆盖。 | -| `baseUrl` | `string` | 可选的按模型基础 URL 覆盖。 | +| `api` | `ModelApi` | 可选的按模型 API 覆盖值。 | +| `baseUrl` | `string` | 可选的按模型基础 URL 覆盖值。 | | `headers` | `Record` | 可选的按模型静态标头。 | | `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | 模型接受的模态。 | | `reasoning` | `boolean` | 模型是否暴露推理行为。 | | `contextWindow` | `number` | 原生提供商上下文窗口。 | -| `contextTokens` | `number` | 当不同于 `contextWindow` 时，可选的有效运行时上下文上限。 | -| `maxTokens` | `number` | 已知时的最大输出令牌数。 | -| `cost` | `object` | 可选的每百万令牌美元定价，包括可选的 `tieredPricing`。 | -| `compat` | `object` | 可选的兼容性标志，与 OpenClaw 模型配置兼容性匹配。 | -| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | 列表状态。仅当该行完全不应出现时才抑制。 | -| `statusReason` | `string` | 与非可用状态一起显示的可选原因。 | -| `replaces` | `string[]` | 此模型取代的较旧提供商本地模型 ID。 | +| `contextTokens` | `number` | 与 `contextWindow` 不同时，可选的有效运行时上下文上限。 | +| `maxTokens` | `number` | 已知时的最大输出 token 数。 | +| `cost` | `object` | 可选的每百万 token 美元定价，包括可选的 `tieredPricing`。 | +| `compat` | `object` | 与 OpenClaw 模型配置兼容性匹配的可选兼容性标志。 | +| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | 列表 Status。仅当该行完全不应出现时才抑制。 | +| `statusReason` | `string` | 与非可用 Status 一起显示的可选原因。 | +| `replaces` | `string[]` | 此模型取代的旧提供商本地模型 ID。 | | `replacedBy` | `string` | 已弃用行的替代提供商本地模型 ID。 | | `tags` | `string[]` | 选择器和过滤器使用的稳定标签。 | @@ -702,14 +735,14 @@ OpenClaw 按以下优先级处理： | `provider` | `string` | 要抑制的上游行的提供商 ID。必须由此插件拥有，或声明为已拥有的别名。 | | `model` | `string` | 要抑制的提供商本地模型 ID。 | | `reason` | `string` | 直接请求被抑制的行时显示的可选消息。 | -| `when.baseUrlHosts` | `string[]` | 应用抑制前要求的有效提供商基础 URL 主机可选列表。 | -| `when.providerConfigApiIn` | `string[]` | 应用抑制前要求的精确提供商配置 `api` 值可选列表。 | +| `when.baseUrlHosts` | `string[]` | 应用抑制之前所需的有效提供商基础 URL 主机可选列表。 | +| `when.providerConfigApiIn` | `string[]` | 应用抑制之前所需的精确提供商配置 `api` 值可选列表。 | -不要在 `modelCatalog` 中放入仅运行时数据。仅当清单行完整到足以让按提供商过滤的列表和选择器界面跳过注册表/运行时发现时，才使用 `static`。当清单行可作为有用的可列表化种子或补充，但刷新/缓存稍后可以添加更多行时，使用 `refreshable`；可刷新的行本身不是权威来源。当 OpenClaw 必须加载提供商运行时才能知道列表时，使用 `runtime`。 +不要把仅运行时数据放入 `modelCatalog`。仅当清单行足够完整，能让按提供商过滤的列表和选择器界面跳过注册表/运行时发现时，才使用 `static`。当清单行可作为有用的可列出种子或补充、但刷新/缓存之后可能继续添加更多行时，使用 `refreshable`；refreshable 行本身并非权威来源。当 OpenClaw 必须加载提供商运行时才能知道列表时，使用 `runtime`。 ## modelIdNormalization 参考 -使用 `modelIdNormalization` 处理必须在提供商运行时加载前发生的低成本、提供商自有模型 ID 清理。这会把短模型名称、提供商本地旧版 ID 和代理前缀规则等别名保留在所属插件清单中，而不是放进核心模型选择表。 +使用 `modelIdNormalization` 执行低成本的提供商自有模型 ID 清理，且该清理必须在提供商运行时加载之前发生。这样会把短模型名称、提供商本地旧版 ID、代理前缀规则等别名保留在所属插件清单中，而不是放进核心模型选择表。 ```json { @@ -733,29 +766,29 @@ OpenClaw 按以下优先级处理： | 字段 | 类型 | 含义 | | ------------------------------------ | ----------------------- | ----------------------------------------------------------------------------------------- | -| `aliases` | `Record` | 不区分大小写的精确模型 ID 别名。值会按原样返回。 | -| `stripPrefixes` | `string[]` | 在别名查找前移除的前缀，适用于旧版提供商/模型重复。 | -| `prefixWhenBare` | `string` | 当规范化后的模型 ID 尚未包含 `/` 时要添加的前缀。 | +| `aliases` | `Record` | 不区分大小写的精确模型 ID 别名。值会按写入形式返回。 | +| `stripPrefixes` | `string[]` | 别名查找前要移除的前缀，适用于旧版 provider/model 重复。 | +| `prefixWhenBare` | `string` | 规范化后的模型 ID 尚未包含 `/` 时要添加的前缀。 | | `prefixWhenBareAfterAliasStartsWith` | `object[]` | 别名查找后的条件裸 ID 前缀规则，以 `modelPrefix` 和 `prefix` 为键。 | ## providerEndpoints 参考 -使用 `providerEndpoints` 处理通用请求策略必须在提供商运行时加载前知道的端点分类。核心仍然拥有每个 `endpointClass` 的含义；插件清单拥有主机和基础 URL 元数据。 +使用 `providerEndpoints` 进行端点分类，供通用请求策略在提供商运行时加载之前了解。核心仍拥有每个 `endpointClass` 的含义；插件清单拥有主机和基础 URL 元数据。 端点字段： | 字段 | 类型 | 含义 | | ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------- | -| `endpointClass` | `string` | 已知的核心端点类，例如 `openrouter`、`moonshot-native` 或 `google-vertex`。 | -| `hosts` | `string[]` | 映射到端点类的精确主机名。 | -| `hostSuffixes` | `string[]` | 映射到端点类的主机后缀。使用 `.` 前缀表示仅匹配域名后缀。 | -| `baseUrls` | `string[]` | 映射到端点类的精确规范化 HTTP(S) 基础 URL。 | +| `endpointClass` | `string` | 已知的核心端点类别，例如 `openrouter`、`moonshot-native` 或 `google-vertex`。 | +| `hosts` | `string[]` | 映射到该端点类别的精确主机名。 | +| `hostSuffixes` | `string[]` | 映射到该端点类别的主机后缀。用 `.` 作为前缀表示仅匹配域名后缀。 | +| `baseUrls` | `string[]` | 映射到该端点类别的精确规范化 HTTP(S) 基础 URL。 | | `googleVertexRegion` | `string` | 精确全局主机的静态 Google Vertex 区域。 | | `googleVertexRegionHostSuffix` | `string` | 从匹配主机中剥离的后缀，用于暴露 Google Vertex 区域前缀。 | ## providerRequest 参考 -使用 `providerRequest` 提供通用请求策略在不加载提供商运行时的情况下所需的低成本请求兼容性元数据。将特定行为的载荷重写保留在提供商运行时钩子或共享提供商家族助手中。 +使用 `providerRequest` 存放低成本请求兼容性元数据，让通用请求策略无需加载提供商运行时即可使用。将特定行为的载荷重写保留在提供商运行时钩子或共享提供商族辅助工具中。 ```json { @@ -777,13 +810,13 @@ OpenClaw 按以下优先级处理： | 字段 | 类型 | 含义 | | --------------------- | ------------ | -------------------------------------------------------------------------------------- | -| `family` | `string` | 通用请求兼容性决策和诊断使用的提供商家族标签。 | -| `compatibilityFamily` | `"moonshot"` | 共享请求助手的可选提供商家族兼容性分组。 | -| `openAICompletions` | `object` | OpenAI 兼容补全请求标志，目前为 `supportsStreamingUsage`。 | +| `family` | `string` | 通用请求兼容性决策和诊断使用的提供商族标签。 | +| `compatibilityFamily` | `"moonshot"` | 共享请求辅助工具使用的可选提供商族兼容性分组。 | +| `openAICompletions` | `object` | OpenAI 兼容 completions 请求标志，目前为 `supportsStreamingUsage`。 | ## modelPricing 参考 -当提供商需要在运行时加载前控制平面定价行为时，使用 `modelPricing`。Gateway 网关定价缓存会读取此元数据，而不导入提供商运行时代码。 +当提供商需要在运行时加载之前控制控制面定价行为时，使用 `modelPricing`。Gateway 网关定价缓存会读取这些元数据，而不导入提供商运行时代码。 ```json { @@ -808,45 +841,47 @@ OpenClaw 按以下优先级处理： | 字段 | 类型 | 含义 | | ------------ | ----------------- | -------------------------------------------------------------------------------------------------- | -| `external` | `boolean` | 对本地/自托管提供商设为 `false`，这些提供商永远不应获取 OpenRouter 或 LiteLLM 定价。 | -| `openRouter` | `false \| object` | OpenRouter 定价查找映射。`false` 会为此提供商禁用 OpenRouter 查找。 | -| `liteLLM` | `false \| object` | LiteLLM 定价查找映射。`false` 会为此提供商禁用 LiteLLM 查找。 | +| `external` | `boolean` | 对本地/自托管提供商设置为 `false`，它们永远不应获取 OpenRouter 或 LiteLLM 定价。 | +| `openRouter` | `false \| object` | OpenRouter 定价查找映射。`false` 会禁用此提供商的 OpenRouter 查找。 | +| `liteLLM` | `false \| object` | LiteLLM 定价查找映射。`false` 会禁用此提供商的 LiteLLM 查找。 | 来源字段： | 字段 | 类型 | 含义 | | -------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | 当外部目录提供商 ID 不同于 OpenClaw 提供商 ID 时使用，例如 `zai` 提供商对应的 `z-ai`。 | -| `passthroughProviderModel` | `boolean` | 将包含斜杠的模型 ID 视为嵌套提供商/模型引用，适用于 OpenRouter 等代理提供商。 | -| `modelIdTransforms` | `"version-dots"[]` | 额外的外部目录模型 ID 变体。`version-dots` 会尝试点号版本 ID，例如 `claude-opus-4.6`。 | +| `provider` | `string` | 外部目录提供商 ID，当它不同于 OpenClaw 提供商 ID 时使用，例如 `zai` 提供商对应的 `z-ai`。 | +| `passthroughProviderModel` | `boolean` | 将包含斜杠的模型 ID 视为嵌套 provider/model 引用，适用于 OpenRouter 等代理提供商。 | +| `modelIdTransforms` | `"version-dots"[]` | 额外的外部目录模型 ID 变体。`version-dots` 会尝试带点号的版本 ID，例如 `claude-opus-4.6`。 | ### OpenClaw 提供商索引 -OpenClaw 提供商索引是 OpenClaw 拥有的预览元数据，用于插件可能尚未安装的提供商。它不是插件清单的一部分。插件清单仍然是已安装插件的权威来源。提供商索引是内部回退契约，未来的可安装提供商和预安装模型选择器界面会在提供商插件未安装时使用它。 +OpenClaw 提供商索引是 OpenClaw 拥有的提供商预览元数据，适用于其插件可能尚未安装的提供商。它不是插件清单的一部分。插件清单仍然是已安装插件的权威来源。提供商索引是内部回退契约，未来可安装提供商和预安装模型选择器界面会在提供商插件未安装时使用它。 目录权威顺序： 1. 用户配置。 2. 已安装插件清单 `modelCatalog`。 -3. 显式刷新生成的模型目录缓存。 +3. 来自显式刷新的模型目录缓存。 4. OpenClaw 提供商索引预览行。 提供商索引不得包含密钥、启用状态、运行时钩子或 -实时账号专属模型数据。它的预览目录使用与插件清单相同的 -`modelCatalog` 提供商行结构，但应仅限于稳定的显示元数据，除非运行时适配器字段（例如 `api`、 -`baseUrl`、价格或兼容性标志）被有意与已安装的插件清单保持一致。具备实时 `/models` 发现能力的提供商 -应通过显式模型目录缓存路径写入刷新的行，而不是让常规列表或新手引导调用提供商 API。 +实时账号特定模型数据。它的预览目录使用与插件清单相同的 +`modelCatalog` 提供商行形状，但除非 `api`、`baseUrl`、定价或兼容性标志等运行时适配器字段有意与已安装的插件清单保持一致， +否则应仅限于稳定的显示元数据。具有实时 `/models` 发现能力的提供商应通过显式模型目录缓存路径 +写入刷新的行，而不是让常规列表或新手引导调用提供商 API。 -对于插件已移出核心或尚未安装的提供商，提供商索引条目也可以携带可安装插件元数据。此 -元数据镜像渠道目录模式：包名、npm 安装规格、预期完整性，以及低成本的认证选项标签，已足够展示一个 -可安装的设置选项。插件安装后，其清单优先生效，并且该提供商的提供商索引条目会被忽略。 +提供商索引条目也可以携带可安装插件元数据，适用于插件已移出核心或尚未安装的提供商。此 +元数据沿用渠道目录模式：包名、npm 安装规格、 +预期完整性以及轻量的认证选择标签，足以显示一个 +可安装的设置选项。插件安装后，其清单优先，该提供商的 +提供商索引条目会被忽略。 旧版顶层能力键已弃用。使用 `openclaw doctor --fix` 将 `speechProviders`、`realtimeTranscriptionProviders`、 `realtimeVoiceProviders`、`mediaUnderstandingProviders`、 `imageGenerationProviders`、`videoGenerationProviders`、 -`webFetchProviders` 和 `webSearchProviders` 移到 `contracts` 下；正常的 -清单加载不再将这些顶层字段视为能力归属。 +`webFetchProviders` 和 `webSearchProviders` 移到 `contracts` 下；常规 +清单加载不再将这些顶层字段视为能力所有权。 ## 清单与 package.json @@ -854,75 +889,78 @@ OpenClaw 提供商索引是 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` 的 -`openclaw` 块下，而不是放在 `openclaw.plugin.json` 中。 +一些运行时前的插件元数据有意放在 `package.json` 的 +`openclaw` 块下，而不是 `openclaw.plugin.json` 中。 重要示例： | 字段 | 含义 | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `openclaw.extensions` | 声明原生插件入口点。必须保持在插件包目录内。 | -| `openclaw.runtimeExtensions` | 为已安装包声明已构建的 JavaScript 运行时入口点。必须保持在插件包目录内。 | -| `openclaw.setupEntry` | 新手引导、延迟渠道启动，以及只读渠道状态/SecretRef 发现期间使用的轻量级仅设置入口点。必须保持在插件包目录内。 | -| `openclaw.runtimeSetupEntry` | 为已安装包声明已构建的 JavaScript 设置入口点。需要 `setupEntry`，必须存在，并且必须保持在插件包目录内。 | -| `openclaw.channel` | 低成本渠道目录元数据，例如标签、文档路径、别名和选择文案。 | -| `openclaw.channel.commands` | 在渠道运行时加载前，由配置、审计和命令列表界面使用的静态原生命令和原生 Skills 自动默认元数据。 | -| `openclaw.channel.configuredState` | 轻量级已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已经存在仅环境变量设置？”。 | -| `openclaw.channel.persistedAuthState` | 轻量级持久化认证检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何登录？”。 | +| `openclaw.runtimeExtensions` | 声明已安装包的已构建 JavaScript 运行时入口点。必须保持在插件包目录内。 | +| `openclaw.setupEntry` | 轻量级的仅设置入口点，用于新手引导、延迟的渠道启动，以及只读渠道 Status/SecretRef 发现。必须保持在插件包目录内。 | +| `openclaw.runtimeSetupEntry` | 声明已安装包的已构建 JavaScript 设置入口点。需要 `setupEntry`，必须存在，并且必须保持在插件包目录内。 | +| `openclaw.channel` | 轻量渠道目录元数据，例如标签、文档路径、别名和选择文案。 | +| `openclaw.channel.commands` | 静态原生命令和原生 skill 自动默认元数据，在渠道运行时加载前供配置、审计和命令列表界面使用。 | +| `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.expectedIntegrity` | 预期的 npm 发布完整性字符串，例如 `sha512-...`；安装和更新流程会据此验证获取的构件。 | -| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一条狭窄的内置插件重装恢复路径。 | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间先加载仅设置渠道界面，再加载完整渠道插件。 | +| `openclaw.install.defaultChoice` | 当有多个安装来源可用时的首选安装路径。 | +| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 主机版本，使用类似 `>=2026.3.22` 或 `>=2026.5.1-beta.1` 的 semver 下限。 | +| `openclaw.install.expectedIntegrity` | 预期的 npm dist 完整性字符串，例如 `sha512-...`；安装和更新流程会用它校验获取到的构件。 | +| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个狭窄的内置插件重新安装恢复路径。 | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许仅设置的渠道界面在启动期间先于完整渠道插件加载。 | -清单元数据决定哪些提供商/渠道/设置选项会在运行时加载前出现在 +清单元数据决定运行时加载前哪些提供商/渠道/设置选择会出现在 新手引导中。`package.json#openclaw.install` 告诉 -新手引导在用户选择其中一个选项时如何获取或启用该插件。不要把安装提示移入 `openclaw.plugin.json`。 +新手引导当用户选择其中某个选项时如何获取或启用该插件。不要把安装提示移到 `openclaw.plugin.json` 中。 -`openclaw.install.minHostVersion` 会在安装和清单 -注册表加载期间强制执行。无效值会被拒绝；较新但有效的值会让 -旧宿主跳过该插件。 +`openclaw.install.minHostVersion` 会在非内置插件来源的安装和清单 +注册表加载期间强制执行。无效值会被拒绝； +较新但有效的值会让旧主机跳过外部插件。内置源 +插件会被假定与主机检出版本一致。 -精确 npm 版本固定已经存在于 `npmSpec` 中，例如 +精确的 npm 版本固定已存在于 `npmSpec` 中，例如 `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`。官方外部目录 -条目应将精确规格与 `expectedIntegrity` 配对，这样如果获取到的 npm 构件不再匹配固定发布版本， -更新流程会封闭失败。为兼容性起见，交互式新手引导仍会提供受信任注册表的 npm 规格，包括裸 -包名和 dist-tag。目录诊断可以 +条目应将精确规格与 `expectedIntegrity` 配对，这样如果获取到的 npm 构件不再匹配固定版本， +更新流程就会失败关闭。 +为兼容性，交互式新手引导仍会提供受信任注册表的 npm 规格，包括裸 +包名和 dist-tags。目录诊断可以 区分精确、浮动、完整性固定、缺少完整性、包名 -不匹配和无效默认选项来源。它们还会在 -存在 `expectedIntegrity` 但没有可固定的有效 npm 来源时发出警告。 -当存在 `expectedIntegrity` 时， -安装/更新流程会强制执行；当它省略时，注册表解析会 -在没有完整性固定的情况下记录。 +不匹配以及无效默认选择来源。它们还会在 +`expectedIntegrity` 存在但没有可用于固定它的有效 npm 来源时发出警告。 +当 `expectedIntegrity` 存在时， +安装/更新流程会强制执行它；当它省略时，注册表解析会在 +没有完整性固定的情况下记录。 当 Status、渠道列表或 SecretRef 扫描需要在不加载完整 -运行时的情况下识别已配置账号时，渠道插件应提供 `openclaw.setupEntry`。设置入口应暴露渠道元数据以及设置安全的配置、 -状态和密钥适配器；将网络客户端、Gateway 网关监听器和 +运行时的情况下识别已配置账号时，渠道插件应提供 `openclaw.setupEntry`。 +设置入口应暴露渠道元数据以及设置安全的配置、 +Status 和密钥适配器；将网络客户端、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` 是用于一个微型检查器 +`openclaw.channel.persistedAuthState` 是用于小型检查器 模块的包元数据： ```json @@ -939,15 +977,15 @@ OpenClaw 提供商索引是 OpenClaw 拥有的预览元数据，用于插件可 } ``` -当设置、Doctor、Status 或只读存在性流程需要在完整渠道插件加载前进行低成本 +当设置、Doctor、Status 或只读存在性流程需要在完整渠道插件加载前进行轻量 是/否认证探测时使用它。持久化认证状态不是 -已配置渠道状态：不要使用此元数据来自动启用插件、 -修复运行时依赖，或决定是否应加载渠道运行时。 +已配置渠道状态：不要使用此元数据自动启用插件、 +修复运行时依赖，或决定渠道运行时是否应加载。 目标导出应是一个只读取持久化状态的小函数；不要 -通过完整渠道运行时 barrel 转发它。 +通过完整渠道运行时 barrel 路由它。 -`openclaw.channel.configuredState` 对低成本仅环境变量 -已配置检查遵循相同结构： +`openclaw.channel.configuredState` 对轻量的仅环境变量 +已配置检查遵循相同形状： ```json { @@ -963,59 +1001,59 @@ OpenClaw 提供商索引是 OpenClaw 拥有的预览元数据，用于插件可 } ``` -当渠道可以从环境变量或其他微型 +当某个渠道可以根据环境变量或其他小型 非运行时输入回答已配置状态时使用它。如果检查需要完整配置解析或真实的 渠道运行时，请将该逻辑保留在插件 `config.hasConfiguredState` 钩子中。 ## 设备发现优先级（重复插件 ID） -OpenClaw 会从多个根发现插件（内置、全局安装、工作区、显式配置选定路径）。如果两个发现结果共享同一个 `id`，只保留**最高优先级**清单；较低优先级的重复项会被丢弃，而不是并列加载。 +OpenClaw 会从多个根发现插件（内置、全局安装、工作区、显式配置选择的路径）。如果两个发现结果共享相同 `id`，只保留**最高优先级**的清单；较低优先级的重复项会被丢弃，而不是并排加载。 -优先级从高到低： +优先级，从高到低： -1. **配置选定** — 在 `plugins.entries.` 中显式固定的路径 +1. **配置选择** — 在 `plugins.entries.` 中显式固定的路径 2. **内置** — 随 OpenClaw 一起发布的插件 -3. **全局安装** — 安装到全局 OpenClaw 插件根中的插件 +3. **全局安装** — 安装到全局 OpenClaw 插件根目录的插件 4. **工作区** — 相对于当前工作区发现的插件 影响： -- 位于工作区中的内置插件分叉或陈旧副本不会遮蔽内置构建。 -- 若要实际用本地插件覆盖内置插件，请通过 `plugins.entries.` 固定它，使其通过优先级胜出，而不是依赖工作区发现。 +- 位于工作区的内置插件分叉或过时副本不会遮蔽内置构建。 +- 如果确实要用本地插件覆盖内置插件，请通过 `plugins.entries.` 固定它，使它通过优先级获胜，而不是依赖工作区发现。 - 重复项丢弃会被记录，因此 Doctor 和启动诊断可以指向被丢弃的副本。 ## JSON Schema 要求 -- **每个插件都必须随附 JSON Schema**，即使它不接受配置。 +- **每个插件都必须随附 JSON Schema**，即使它不接受任何配置。 - 空 schema 可以接受（例如 `{ "type": "object", "additionalProperties": false }`）。 -- Schema 在配置读/写时验证，而不是在运行时验证。 +- Schema 在配置读写时验证，而不是在运行时验证。 ## 验证行为 -- 未知的 `channels.*` 键是**错误**，除非该渠道 id 由 +- 未知的 `channels.*` 键是**错误**，除非渠道 id 由 插件清单声明。 - `plugins.entries.`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` - 必须引用**可发现的**插件 id。未知 id 是**错误**。 -- 如果插件已安装，但清单或 schema 损坏或缺失， - 验证会失败，Doctor 会报告插件错误。 -- 如果插件配置存在但插件被**禁用**，配置会保留，并且 + 必须引用**可发现**的插件 id。未知 id 是**错误**。 +- 如果插件已安装，但清单或架构损坏或缺失， + 验证会失败，并且 Doctor 会报告插件错误。 +- 如果插件配置存在但插件已**禁用**，配置会保留，并且 Doctor + 日志中会显示**警告**。 -完整的 `plugins.*` schema 请参阅[配置参考](/zh-CN/gateway/configuration)。 +完整的 `plugins.*` 架构请参阅[配置参考](/zh-CN/gateway/configuration)。 ## 备注 -- 清单是**原生 OpenClaw 插件的必需项**，包括本地文件系统加载。运行时仍会单独加载插件模块；清单仅用于设备发现 + 验证。 -- 原生清单使用 JSON5 解析，因此只要最终值仍是对象，就接受注释、尾随逗号和未加引号的键。 -- 清单加载器只读取已记录的清单字段。避免使用自定义顶层键。 -- 当插件不需要时，`channels`、`providers`、`cliBackends` 和 `skills` 都可以省略。 -- `providerDiscoveryEntry` 必须保持轻量，不应导入范围较广的运行时代码；将它用于静态提供商目录元数据或窄范围发现描述符，而不是请求时执行。 -- 独占插件类型通过 `plugins.slots.*` 选择：通过 `plugins.slots.memory` 选择 `kind: "memory"`，通过 `plugins.slots.contextEngine` 选择 `kind: "context-engine"`（默认 `legacy`）。 -- 在此清单中声明独占插件类型。运行时入口 `OpenClawPluginDefinition.kind` 已弃用，仅作为较旧插件的兼容性回退保留。 -- 环境变量元数据（`setup.providers[].envVars`、已弃用的 `providerAuthEnvVars` 和 `channelEnvVars`）仅为声明式。Status、审计、cron 投递验证和其他只读表面，在将环境变量视为已配置之前，仍会应用插件信任和有效激活策略。 +- **原生 OpenClaw 插件**必须提供清单，包括从本地文件系统加载的插件。运行时仍会单独加载插件模块；清单仅用于发现 + 验证。 +- 原生清单使用 JSON5 解析，因此允许注释、尾随逗号和未加引号的键，只要最终值仍然是对象。 +- 清单加载器只读取已记录的清单字段。避免使用自定义顶级键。 +- 当插件不需要时，可以省略 `channels`、`providers`、`cliBackends` 和 `skills`。 +- `providerDiscoveryEntry` 必须保持轻量，不应导入大范围运行时代码；将它用于静态提供商目录元数据或窄范围发现描述符，而不是请求时执行。 +- 独占插件类型通过 `plugins.slots.*` 选择：`kind: "memory"` 通过 `plugins.slots.memory`，`kind: "context-engine"` 通过 `plugins.slots.contextEngine`（默认 `legacy`）。 +- 在此清单中声明独占插件类型。运行时入口 `OpenClawPluginDefinition.kind` 已弃用，仅作为旧版插件的兼容回退保留。 +- 环境变量元数据（`setup.providers[].envVars`、已弃用的 `providerAuthEnvVars` 和 `channelEnvVars`）仅是声明式的。Status、审计、cron 投递验证以及其他只读界面在将环境变量视为已配置之前，仍会应用插件信任和有效激活策略。 - 对于需要提供商代码的运行时向导元数据，请参阅[提供商运行时钩子](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 -- 如果你的插件依赖原生模块，请记录构建步骤和任何包管理器允许列表要求（例如 pnpm `allow-build-scripts` + `pnpm rebuild `）。 +- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器 allowlist 要求（例如 pnpm `allow-build-scripts` + `pnpm rebuild `）。 ## 相关 diff --git a/docs/zh-CN/plugins/sdk-overview.md b/docs/zh-CN/plugins/sdk-overview.md index 762abebb4..52f83d08e 100644 --- a/docs/zh-CN/plugins/sdk-overview.md +++ b/docs/zh-CN/plugins/sdk-overview.md @@ -1,24 +1,24 @@ --- read_when: - 你需要知道要从哪个 SDK 子路径导入 - - 你需要 OpenClawPluginApi 上所有注册方法的参考。 - - 你正在查找特定的 SDK 导出 + - 你需要 OpenClawPluginApi 上所有注册方法的参考 + - 你正在查找某个特定的 SDK 导出项 sidebarTitle: Plugin SDK overview summary: 导入映射、注册 API 参考和 SDK 架构 title: 插件 SDK 概览 x-i18n: - generated_at: "2026-05-01T20:39:35Z" + generated_at: "2026-05-02T02:49:08Z" model: gpt-5.5 provider: openai - source_hash: 28da709ac7dc86e6d5b553b6c8ecaed105c68de63f94804bc5aed56ebc6c5de9 + source_hash: be5fa531e603fb6d87f84e3193ebd61be1431b57b8f284871ae15f34ca93fc69 source_path: plugins/sdk-overview.md workflow: 16 --- -插件 SDK 是插件与核心之间的类型化契约。本页是关于**要导入什么**和**可以注册什么**的参考。 +插件 SDK 是插件与核心之间的类型化契约。本页是关于**导入内容**和**可注册内容**的参考。 - 本页适用于在 OpenClaw 内部使用 `openclaw/plugin-sdk/*` 的插件作者。对于想要通过 Gateway 网关运行智能体的外部应用、脚本、仪表板、CI 作业和 IDE 扩展，请改用 [OpenClaw 应用 SDK](/zh-CN/concepts/openclaw-sdk) 和 `@openclaw/sdk` 包。 + 本页面面向在 OpenClaw 内部使用 `openclaw/plugin-sdk/*` 的插件作者。对于想要通过 Gateway 网关运行智能体的外部应用、脚本、仪表盘、CI 作业和 IDE 扩展，请改用 [OpenClaw 应用 SDK](/zh-CN/concepts/openclaw-sdk) 和 `@openclaw/sdk` 包。 @@ -34,116 +34,116 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -每个子路径都是一个小型、自包含的模块。这能让启动保持快速，并防止循环依赖问题。对于特定渠道的入口/构建辅助工具，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更宽泛的伞状接口以及共享辅助工具，例如 `buildChannelConfigSchema`。 +每个子路径都是一个小型、自包含模块。这可以保持启动快速，并防止循环依赖问题。对于渠道专用的入口/构建辅助函数，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总括表面和共享辅助函数，例如 `buildChannelConfigSchema`。 -对于渠道配置，通过 `openclaw.plugin.json#channelConfigs` 发布渠道拥有的 JSON Schema。`plugin-sdk/channel-config-schema` 子路径用于共享 schema 原语和通用构建器。OpenClaw 的内置插件使用 `plugin-sdk/bundled-channel-config-schema` 来保留内置渠道 schema。已弃用的兼容导出仍保留在 `plugin-sdk/channel-config-schema-legacy`；这两个内置 schema 子路径都不是新插件的模式。 +对于渠道配置，请通过 `openclaw.plugin.json#channelConfigs` 发布渠道拥有的 JSON Schema。`plugin-sdk/channel-config-schema` 子路径用于共享 schema 原语和通用构建器。OpenClaw 的内置插件使用 `plugin-sdk/bundled-channel-config-schema` 来保留内置渠道 schema。已弃用的兼容性导出仍保留在 `plugin-sdk/channel-config-schema-legacy`；这两个内置 schema 子路径都不是新插件应采用的模式。 - 不要导入带有提供商或渠道品牌的便利接口（例如 `openclaw/plugin-sdk/slack`、`.../discord`、`.../signal`、`.../whatsapp`）。内置插件会在自己的 `api.ts` / `runtime-api.ts` barrel 中组合通用 SDK 子路径；核心消费者应使用这些插件本地 barrel，或在确实存在跨渠道需求时添加一个狭窄的通用 SDK 契约。 + 不要导入带有提供商或渠道品牌的便利连接点（例如 `openclaw/plugin-sdk/slack`、`.../discord`、`.../signal`、`.../whatsapp`）。内置插件会在自己的 `api.ts` / `runtime-api.ts` barrel 中组合通用 SDK 子路径；核心消费者应使用这些插件本地 barrel，或者在需求确实跨渠道时添加狭窄的通用 SDK 契约。 -当一小部分内置插件辅助接口有已跟踪的所有者使用时，它们仍会出现在生成的导出映射中。它们只用于内置插件维护，不建议作为新的第三方插件导入路径。 +当一小部分内置插件辅助连接点有被跟踪的所有者使用时，它们仍会出现在生成的导出映射中。它们仅用于内置插件维护，不建议作为新的第三方插件导入路径。 -`openclaw/plugin-sdk/discord` 和 `openclaw/plugin-sdk/telegram-account` 也作为已弃用的兼容外观保留，用于已跟踪的所有者使用。不要把这些导入路径复制到新插件中；请改用注入的运行时辅助工具和通用渠道 SDK 子路径。 +`openclaw/plugin-sdk/discord` 和 `openclaw/plugin-sdk/telegram-account` 也作为已弃用的兼容性外观保留，用于被跟踪的所有者使用。不要将这些导入路径复制到新插件中；请改用注入的运行时辅助函数和通用渠道 SDK 子路径。 ## 子路径参考 -插件 SDK 以一组按领域分组的狭窄子路径公开（插件入口、渠道、提供商、认证、运行时、能力、记忆，以及预留的内置插件辅助工具）。完整目录按组归类并带有链接，请参见[插件 SDK 子路径](/zh-CN/plugins/sdk-subpaths)。 +插件 SDK 以一组按领域分组的狭窄子路径公开（插件入口、渠道、提供商、凭证、运行时、能力、记忆和保留的内置插件辅助函数）。完整目录（已分组并带链接）请参见[插件 SDK 子路径](/zh-CN/plugins/sdk-subpaths)。 -生成的 200+ 子路径列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 +生成的 200+ 个子路径列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 ## 注册 API -`register(api)` 回调会收到一个 `OpenClawPluginApi` 对象，其中包含这些方法： +`register(api)` 回调会接收一个包含以下方法的 `OpenClawPluginApi` 对象： ### 能力注册 -| 方法 | 注册的内容 | -| ------------------------------------------------ | --------------------------------------- | -| `api.registerProvider(...)` | 文本推理（LLM） | -| `api.registerAgentHarness(...)` | 实验性低层级智能体执行器 | -| `api.registerCliBackend(...)` | 本地 CLI 推理后端 | -| `api.registerChannel(...)` | 消息渠道 | -| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 | -| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 | -| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 | -| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 | -| `api.registerImageGenerationProvider(...)` | 图像生成 | -| `api.registerMusicGenerationProvider(...)` | 音乐生成 | -| `api.registerVideoGenerationProvider(...)` | 视频生成 | -| `api.registerWebFetchProvider(...)` | Web 获取 / 抓取提供商 | -| `api.registerWebSearchProvider(...)` | Web 搜索 | +| 方法 | 注册内容 | +| ------------------------------------------------ | ------------------------------------- | +| `api.registerProvider(...)` | 文本推理（LLM） | +| `api.registerAgentHarness(...)` | 实验性低层级智能体执行器 | +| `api.registerCliBackend(...)` | 本地 CLI 推理后端 | +| `api.registerChannel(...)` | 消息渠道 | +| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 | +| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 | +| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 | +| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 | +| `api.registerImageGenerationProvider(...)` | 图像生成 | +| `api.registerMusicGenerationProvider(...)` | 音乐生成 | +| `api.registerVideoGenerationProvider(...)` | 视频生成 | +| `api.registerWebFetchProvider(...)` | 网页获取 / 抓取提供商 | +| `api.registerWebSearchProvider(...)` | Web 搜索 | ### 工具和命令 -| 方法 | 注册的内容 | -| ------------------------------- | ------------------------------------------- | -| `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） | -| `api.registerCommand(def)` | 自定义命令（绕过 LLM） | +| 方法 | 注册内容 | +| ------------------------------- | --------------------------------------------- | +| `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） | +| `api.registerCommand(def)` | 自定义命令（绕过 LLM） | -当智能体需要一条简短、由命令拥有的路由提示时，插件命令可以设置 `agentPromptGuidance`。该文本应只描述命令本身；不要向核心提示构建器添加提供商或插件特定策略。 +当智能体需要一段简短、由命令拥有的路由提示时，插件命令可以设置 `agentPromptGuidance`。该文本应围绕命令本身；不要把提供商或插件专用策略添加到核心提示构建器中。 ### 基础设施 -| 方法 | 注册的内容 | -| ---------------------------------------------- | ----------------------------------- | -| `api.registerHook(events, handler, opts?)` | 事件钩子 | -| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 | -| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | -| `api.registerGatewayDiscoveryService(service)` | 本地 Gateway 网关发现广播器 | +| 方法 | 注册内容 | +| ---------------------------------------------- | --------------------------------------- | +| `api.registerHook(events, handler, opts?)` | 事件钩子 | +| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 | +| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | +| `api.registerGatewayDiscoveryService(service)` | 本地 Gateway 网关设备发现广播器 | | `api.registerCli(registrar, opts?)` | CLI 子命令 | -| `api.registerService(service)` | 后台服务 | -| `api.registerInteractiveHandler(registration)` | 交互式处理器 | -| `api.registerAgentToolResultMiddleware(...)` | 运行时工具结果中间件 | -| `api.registerMemoryPromptSupplement(builder)` | 追加式、与记忆相邻的提示部分 | -| `api.registerMemoryCorpusSupplement(adapter)` | 追加式记忆搜索/读取语料 | +| `api.registerService(service)` | 后台服务 | +| `api.registerInteractiveHandler(registration)` | 交互式处理器 | +| `api.registerAgentToolResultMiddleware(...)` | 运行时工具结果中间件 | +| `api.registerMemoryPromptSupplement(builder)` | 附加的记忆相邻提示部分 | +| `api.registerMemoryCorpusSupplement(adapter)` | 附加的记忆搜索/读取语料库 | ### 工作流插件的主机钩子 -主机钩子是 SDK 接口，适用于需要参与主机生命周期，而不是只添加提供商、渠道或工具的插件。它们是通用契约；Plan Mode 可以使用它们，审批工作流、工作区策略门禁、后台监控、设置向导和 UI 配套插件也可以使用它们。 +主机钩子是 SDK 连接点，供需要参与主机生命周期而不只是添加提供商、渠道或工具的插件使用。它们是通用契约；计划模式可以使用它们，审批工作流、工作区策略门控、后台监视器、设置向导和 UI 配套插件也可以使用。 -| 方法 | 拥有的契约 | -| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | -| `api.registerSessionExtension(...)` | 插件拥有、JSON 兼容的会话状态，通过 Gateway 网关会话投射 | -| `api.enqueueNextTurnInjection(...)` | 持久的恰好一次上下文，注入到某个会话的下一个智能体轮次 | -| `api.registerTrustedToolPolicy(...)` | 内置/可信的前置插件工具策略，可阻止或重写工具参数 | -| `api.registerToolMetadata(...)` | 工具目录显示元数据，不改变工具实现 | -| `api.registerCommand(...)` | 作用域限定的插件命令；命令结果可以设置 `continueAgent: true` | -| `api.registerControlUiDescriptor(...)` | 面向会话、工具、运行或设置界面的 Control UI 贡献描述符 | -| `api.registerRuntimeLifecycle(...)` | 重置/删除/重新加载路径上插件拥有的运行时资源的清理回调 | -| `api.registerAgentEventSubscription(...)` | 面向工作流状态和监控器的已净化事件订阅 | -| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | 每次运行的插件临时状态，在终止性运行生命周期时清除 | -| `api.registerSessionSchedulerJob(...)` | 插件拥有的会话调度器作业记录，带确定性清理 | +| 方法 | 拥有的契约 | +| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerSessionExtension(...)` | 插件拥有、JSON 兼容的会话状态，通过 Gateway 网关会话投射 | +| `api.enqueueNextTurnInjection(...)` | 针对一个会话注入到下一次智能体回合的持久、恰好一次上下文 | +| `api.registerTrustedToolPolicy(...)` | 内置/受信任的前置插件工具策略，可阻止或重写工具参数 | +| `api.registerToolMetadata(...)` | 工具目录显示元数据，不改变工具实现 | +| `api.registerCommand(...)` | 有作用域的插件命令；命令结果可以设置 `continueAgent: true`；Discord 原生命令支持 `descriptionLocalizations` | +| `api.registerControlUiDescriptor(...)` | 用于会话、工具、运行或设置界面的控制 UI 贡献描述符 | +| `api.registerRuntimeLifecycle(...)` | 在重置/删除/重载路径上清理插件拥有的运行时资源的回调 | +| `api.registerAgentEventSubscription(...)` | 用于工作流状态和监视器的已清理事件订阅 | +| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | 每次运行的插件暂存状态，在终止运行生命周期时清除 | +| `api.registerSessionSchedulerJob(...)` | 插件拥有的会话调度器作业记录，具备确定性清理 | 这些契约有意拆分权限： -- 外部插件可以拥有会话扩展、UI 描述符、命令、工具元数据、下一轮注入和普通钩子。 -- 可信工具策略在普通 `before_tool_call` 钩子之前运行，并且仅限内置插件，因为它们参与主机安全策略。 -- 预留命令所有权仅限内置插件。外部插件应使用自己的命令名称或别名。 -- `allowPromptInjection=false` 会禁用会改变提示的钩子，包括 `agent_turn_prepare`、`before_prompt_build`、`heartbeat_prompt_contribution`、旧版 `before_agent_start` 中的提示字段，以及 `enqueueNextTurnInjection`。 +- 外部插件可以拥有会话扩展、UI 描述符、命令、工具元数据、下一回合注入和普通钩子。 +- 受信任工具策略在普通 `before_tool_call` 钩子之前运行，并且仅限内置插件，因为它们参与主机安全策略。 +- 保留命令所有权仅限内置插件。外部插件应使用自己的命令名称或别名。 +- `allowPromptInjection=false` 会禁用会修改提示的钩子，包括 `agent_turn_prepare`、`before_prompt_build`、`heartbeat_prompt_contribution`、旧版 `before_agent_start` 的提示字段以及 `enqueueNextTurnInjection`。 -非 Plan 使用方示例： +非计划模式消费者示例： -| 插件原型 | 使用的钩子 | -| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| 审批工作流 | 会话扩展、命令继续、下一轮注入、UI 描述符 | -| 预算/工作区策略门禁 | 可信工具策略、工具元数据、会话投射 | -| 后台生命周期监控器 | 运行时生命周期清理、智能体事件订阅、会话调度器所有权/清理、Heartbeat 提示贡献、UI 描述符 | -| 设置或新手引导向导 | 会话扩展、作用域限定命令、Control UI 描述符 | +| 插件原型 | 使用的钩子 | +| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| 审批工作流 | 会话扩展、命令延续、下一回合注入、UI 描述符 | +| 预算/工作区策略门控 | 受信任工具策略、工具元数据、会话投射 | +| 后台生命周期监视器 | 运行时生命周期清理、智能体事件订阅、会话调度器所有权/清理、Heartbeat 提示贡献、UI 描述符 | +| 设置或新手引导向导 | 会话扩展、有作用域命令、控制 UI 描述符 | - 预留的核心管理员命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的网关方法作用域也是如此。插件拥有的方法优先使用插件特定前缀。 + 保留的核心管理员命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。插件拥有的方法请优先使用插件专用前缀。 - 当内置插件需要在工具执行之后、运行时将结果反馈给模型之前重写工具结果时，可以使用 `api.registerAgentToolResultMiddleware(...)`。这是面向 tokenjuice 等异步输出规约器的可信、运行时中立接口。 + 当内置插件需要在执行后、运行时将工具结果反馈给模型之前重写工具结果时，可以使用 `api.registerAgentToolResultMiddleware(...)`。这是用于 tokenjuice 等异步输出归约器的受信任、运行时中立连接点。 -内置插件必须为每个目标运行时声明 `contracts.agentToolResultMiddleware`，例如 `["pi", "codex"]`。外部插件不能注册此中间件；对于不需要模型前工具结果时机的工作，请继续使用普通 OpenClaw 插件钩子。旧的仅限 Pi 的嵌入式扩展工厂注册路径已被移除。 +内置插件必须为每个目标运行时声明 `contracts.agentToolResultMiddleware`，例如 `["pi", "codex"]`。外部插件不能注册此中间件；对于不需要模型前工具结果时序的工作，请继续使用普通 OpenClaw 插件钩子。旧的仅 Pi 嵌入式扩展工厂注册路径已被移除。 -### Gateway 网关发现注册 +### Gateway 网关设备发现注册 -`api.registerGatewayDiscoveryService(...)` 允许插件在 mDNS/Bonjour 等本地发现传输协议上广播活动的 Gateway 网关。当启用本地发现时，OpenClaw 会在 Gateway 网关启动期间调用该服务，传入当前 Gateway 网关端口和非机密 TXT 提示数据，并在 Gateway 网关关闭期间调用返回的 `stop` 处理器。 +`api.registerGatewayDiscoveryService(...)` 允许插件通过 mDNS/Bonjour 等本地设备发现传输协议通告活动的 Gateway 网关。启用本地设备发现后，OpenClaw 会在 Gateway 网关启动期间调用该服务，传入当前 Gateway 网关端口和非机密 TXT 提示数据，并在 Gateway 网关关闭期间调用返回的 `stop` 处理程序。 ```typescript api.registerGatewayDiscoveryService({ @@ -159,19 +159,16 @@ api.registerGatewayDiscoveryService({ }); ``` -Gateway 网关设备发现插件不得将播发的 TXT 值视为秘密或 -认证。设备发现只是路由提示；Gateway 网关认证和 TLS 固定仍然 -负责信任。 +Gateway 网关设备发现插件不得将通告的 TXT 值视为机密或身份验证。设备发现是路由提示；Gateway 网关身份验证和 TLS 固定仍然负责信任。 ### CLI 注册元数据 `api.registerCli(registrar, opts?)` 接受两类顶层元数据： - `commands`：注册器拥有的显式命令根 -- `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析期命令描述符 +- `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析时命令描述符 -如果你希望插件命令在常规根 CLI 路径中保持延迟加载， -请提供覆盖该注册器暴露的每个顶层命令根的 `descriptors`。 +如果你希望插件命令在正常根 CLI 路径中保持延迟加载，请提供覆盖该注册器暴露的每个顶层命令根的 `descriptors`。 ```typescript api.registerCli( @@ -191,29 +188,26 @@ api.registerCli( ); ``` -仅在不需要延迟根 CLI 注册时，才单独使用 `commands`。 -这个急切兼容路径仍受支持，但它不会安装由描述符支持的占位符， -用于解析期延迟加载。 +只有在不需要延迟根 CLI 注册时，才单独使用 `commands`。该立即加载的兼容路径仍受支持，但它不会为解析时延迟加载安装由描述符支持的占位符。 ### CLI 后端注册 -`api.registerCliBackend(...)` 让插件拥有本地 -AI CLI 后端（例如 `codex-cli`）的默认配置。 +`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（如 `codex-cli`）的默认配置。 - 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。 - 后端 `config` 使用与 `agents.defaults.cliBackends.` 相同的形状。 -- 用户配置仍然优先。OpenClaw 会在运行 CLI 之前，将 `agents.defaults.cliBackends.` 合并到插件默认值之上。 -- 当后端需要在合并后进行兼容性重写时，使用 `normalizeConfig`（例如规范化旧的标志形状）。 +- 用户配置仍然优先。OpenClaw 会先将 `agents.defaults.cliBackends.` 合并到插件默认值之上，然后再运行 CLI。 +- 当后端需要在合并后执行兼容性重写时，请使用 `normalizeConfig`（例如规范化旧标志形状）。 ### 独占槽位 -| 方法 | 注册内容 | -| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | 上下文引擎（一次只能有一个处于活动状态）。`assemble()` 回调会收到 `availableTools` 和 `citationsMode`，因此引擎可以定制提示补充内容。 | -| `api.registerMemoryCapability(capability)` | 统一记忆能力 | -| `api.registerMemoryPromptSection(builder)` | 记忆提示段构建器 | -| `api.registerMemoryFlushPlan(resolver)` | 记忆刷新计划解析器 | -| `api.registerMemoryRuntime(runtime)` | 记忆运行时适配器 | +| 方法 | 注册内容 | +| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | 上下文引擎（一次只激活一个）。`assemble()` 回调会接收 `availableTools` 和 `citationsMode`，以便引擎定制提示词追加内容。 | +| `api.registerMemoryCapability(capability)` | 统一记忆能力 | +| `api.registerMemoryPromptSection(builder)` | 记忆提示词区段构建器 | +| `api.registerMemoryFlushPlan(resolver)` | 记忆刷新计划解析器 | +| `api.registerMemoryRuntime(runtime)` | 记忆运行时适配器 | ### 记忆嵌入适配器 @@ -222,41 +216,34 @@ AI CLI 后端（例如 `codex-cli`）的默认配置。 | `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的记忆嵌入适配器 | - `registerMemoryCapability` 是首选的独占记忆插件 API。 -- `registerMemoryCapability` 也可以暴露 `publicArtifacts.listArtifacts(...)`， - 以便配套插件通过 `openclaw/plugin-sdk/memory-host-core` 消费导出的记忆制品， - 而不是访问某个特定记忆插件的私有布局。 -- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 - `registerMemoryRuntime` 是兼容旧版的独占记忆插件 API。 -- `MemoryFlushPlan.model` 可以将刷新轮次固定到精确的 `provider/model` - 引用，例如 `ollama/qwen3:8b`，而不会继承活动的回退链。 -- `registerMemoryEmbeddingProvider` 让活动记忆插件注册一个或多个 - 嵌入适配器 ID（例如 `openai`、`gemini`，或插件定义的自定义 ID）。 -- 用户配置（例如 `agents.defaults.memorySearch.provider` 和 - `agents.defaults.memorySearch.fallback`）会根据这些已注册的 - 适配器 ID 解析。 +- `registerMemoryCapability` 也可以暴露 `publicArtifacts.listArtifacts(...)`，让配套插件通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的记忆制品，而不是访问某个特定记忆插件的私有布局。 +- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是兼容旧版的独占记忆插件 API。 +- `MemoryFlushPlan.model` 可以将刷新轮次固定到精确的 `provider/model` 引用，例如 `ollama/qwen3:8b`，而不继承活动备用链。 +- `registerMemoryEmbeddingProvider` 允许活动记忆插件注册一个或多个嵌入适配器 ID（例如 `openai`、`gemini`，或自定义的插件定义 ID）。 +- 用户配置（如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`）会针对这些已注册的适配器 ID 解析。 ### 事件和生命周期 | 方法 | 作用 | | -------------------------------------------- | ---------------- | | `api.on(hookName, handler, opts?)` | 类型化生命周期钩子 | -| `api.onConversationBindingResolved(handler)` | 对话绑定回调 | +| `api.onConversationBindingResolved(handler)` | 会话绑定回调 | -有关示例、常见钩子名称和保护语义，请参阅 [插件钩子](/zh-CN/plugins/hooks)。 +示例、常见钩子名称和守卫语义请参见 [插件钩子](/zh-CN/plugins/hooks)。 ### 钩子决策语义 -- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦任何处理器设置它，就会跳过较低优先级的处理器。 +- `before_tool_call`：返回 `{ block: true }` 是终止性决策。一旦任何处理程序设置它，较低优先级的处理程序会被跳过。 - `before_tool_call`：返回 `{ block: false }` 会被视为没有决策（与省略 `block` 相同），而不是覆盖。 -- `before_install`：返回 `{ block: true }` 是终止性的。一旦任何处理器设置它，就会跳过较低优先级的处理器。 +- `before_install`：返回 `{ block: true }` 是终止性决策。一旦任何处理程序设置它，较低优先级的处理程序会被跳过。 - `before_install`：返回 `{ block: false }` 会被视为没有决策（与省略 `block` 相同），而不是覆盖。 -- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦任何处理器声明已调度，就会跳过较低优先级的处理器以及默认模型调度路径。 -- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦任何处理器设置它，就会跳过较低优先级的处理器。 +- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性决策。一旦任何处理程序声明已处理分发，较低优先级的处理程序和默认模型分发路径都会被跳过。 +- `message_sending`：返回 `{ cancel: true }` 是终止性决策。一旦任何处理程序设置它，较低优先级的处理程序会被跳过。 - `message_sending`：返回 `{ cancel: false }` 会被视为没有决策（与省略 `cancel` 相同），而不是覆盖。 - `message_received`：当你需要入站线程/主题路由时，请使用类型化的 `threadId` 字段。将 `metadata` 保留给渠道特定的额外信息。 - `message_sending`：先使用类型化的 `replyToId` / `threadId` 路由字段，再回退到渠道特定的 `metadata`。 -- `gateway_start`：使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()` 获取 Gateway 网关拥有的启动状态，而不是依赖内部 `gateway:startup` 钩子。 -- `cron_changed`：观察 Gateway 网关拥有的 cron 生命周期变化。同步外部唤醒调度器时，使用 `event.job?.state?.nextRunAtMs` 和 `ctx.getCron?.()`，并让 OpenClaw 作为到期检查和执行的事实来源。 +- `gateway_start`：使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()` 表示 Gateway 网关拥有的启动状态，而不是依赖内部 `gateway:startup` 钩子。 +- `cron_changed`：观察 Gateway 网关拥有的 cron 生命周期变更。同步外部唤醒调度器时使用 `event.job?.state?.nextRunAtMs` 和 `ctx.getCron?.()`，并让 OpenClaw 作为到期检查和执行的事实来源。 ### API 对象字段 @@ -269,15 +256,15 @@ AI CLI 后端（例如 `codex-cli`）的默认配置。 | `api.source` | `string` | 插件源路径 | | `api.rootDir` | `string?` | 插件根目录（可选） | | `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动的内存中运行时快照） | -| `api.pluginConfig` | `Record` | 来自 `plugins.entries..config` 的插件特定配置 | -| `api.runtime` | `PluginRuntime` | [运行时助手](/zh-CN/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | 作用域日志器（`debug`、`info`、`warn`、`error`） | -| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是轻量级的完整入口前启动/设置窗口 | -| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 | +| `api.pluginConfig` | `Record` | 来自 `plugins.entries..config` 的插件特定配置 | +| `api.runtime` | `PluginRuntime` | [运行时辅助工具](/zh-CN/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | 作用域日志记录器（`debug`、`info`、`warn`、`error`） | +| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是轻量级的完整入口前启动/设置窗口 | +| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根的路径 | ## 内部模块约定 -在你的插件中，使用本地桶文件进行内部导入： +在你的插件内，使用本地桶文件进行内部导入： ``` my-plugin/ @@ -290,50 +277,43 @@ my-plugin/ 切勿在生产代码中通过 `openclaw/plugin-sdk/` 导入你自己的插件。请通过 `./api.ts` 或 - `./runtime-api.ts` 路由内部导入。SDK 路径仅是外部契约。 + `./runtime-api.ts` 路由内部导入。SDK 路径仅用于外部契约。 -由门面加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、 -`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）会在 OpenClaw 已经运行时优先使用 -活动运行时配置快照。如果运行时快照尚不存在，它们会回退到磁盘上解析出的配置文件。 -打包后的内置插件门面应通过 OpenClaw 的插件门面加载器加载；直接从 `dist/extensions/...` -导入会绕过清单和运行时 sidecar 检查，而这些检查是打包安装为插件拥有代码使用的。 +由门面加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）在 OpenClaw 已运行时优先使用活动运行时配置快照。如果尚不存在运行时快照，它们会回退到磁盘上已解析的配置文件。打包的内置插件门面应通过 OpenClaw 的插件门面加载器加载；直接从 `dist/extensions/...` 导入会绕过打包安装用于插件拥有代码的清单和运行时 sidecar 检查。 -当某个助手有意是提供商特定的，并且尚不属于通用 SDK -子路径时，提供商插件可以暴露一个很窄的插件本地契约桶文件。内置示例： +当某个辅助工具有意特定于提供商，并且尚不属于通用 SDK 子路径时，提供商插件可以暴露一个狭窄的插件本地契约桶文件。内置示例： -- **Anthropic**：用于 Claude beta-header 和 `service_tier` 流助手的公共 `api.ts` / `contract-api.ts` 接缝。 -- **`@openclaw/openai-provider`**：`api.ts` 导出提供商构建器、 - 默认模型助手和实时提供商构建器。 -- **`@openclaw/openrouter-provider`**：`api.ts` 导出提供商构建器 - 以及新手引导/配置助手。 +- **Anthropic**：用于 Claude beta-header 和 `service_tier` 流辅助工具的公共 `api.ts` / `contract-api.ts` 接缝。 +- **`@openclaw/openai-provider`**：`api.ts` 导出提供商构建器、默认模型辅助工具和实时提供商构建器。 +- **`@openclaw/openrouter-provider`**：`api.ts` 导出提供商构建器以及新手引导/配置辅助工具。 - 插件生产代码也应避免 `openclaw/plugin-sdk/` - 导入。如果某个助手确实是共享的，请将它提升到中立的 SDK 子路径， - 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或另一个 - 面向能力的表面，而不是把两个插件耦合在一起。 + 插件生产代码也应避免导入 `openclaw/plugin-sdk/`。 + 如果某个辅助工具确实是共享的，请将它提升到中立的 SDK 子路径， + 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或其他 + 面向能力的表面，而不是将两个插件耦合在一起。 -## 相关内容 +## 相关 - + `definePluginEntry` 和 `defineChannelPluginEntry` 选项。 - + 完整的 `api.runtime` 命名空间参考。 - - 打包、清单和配置 schema。 + + 打包、清单和配置架构。 - + 测试工具和 lint 规则。 - - 从已弃用表面迁移。 + + 从已弃用的表面迁移。 - - 深入架构和能力模型。 + + 深层架构和能力模型。 diff --git a/docs/zh-CN/plugins/sdk-setup.md b/docs/zh-CN/plugins/sdk-setup.md index ecda25812..d02dcfdca 100644 --- a/docs/zh-CN/plugins/sdk-setup.md +++ b/docs/zh-CN/plugins/sdk-setup.md @@ -2,31 +2,31 @@ read_when: - 你正在为插件添加设置向导 - 你需要理解 setup-entry.ts 与 index.ts 的区别 - - 你正在定义插件配置 schema 或 package.json 的 openclaw 元数据 + - 你正在定义插件配置架构或 package.json openclaw 元数据 sidebarTitle: Setup and config -summary: 设置向导、setup-entry.ts、配置模式和 package.json 元数据 +summary: 设置向导、setup-entry.ts、配置 schema 和 package.json 元数据 title: 插件设置和配置 x-i18n: - generated_at: "2026-05-01T20:40:09Z" + generated_at: "2026-05-02T02:49:10Z" model: gpt-5.5 provider: openai - source_hash: d61cbbeb3e9e303d098fcddf4ba101ff6717c232d5db4b36c28008c84bd32be8 + source_hash: 322cf8988da686d5bf7577f9825f6f8decb738f91563e4022c14bf16dca22824 source_path: plugins/sdk-setup.md workflow: 16 --- -Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.plugin.json`)、设置入口和配置架构的参考。 +插件打包（`package.json` 元数据）、清单（`openclaw.plugin.json`）、设置入口和配置架构的参考。 -**想找演练？** 操作指南会在上下文中介绍打包：[渠道插件](/zh-CN/plugins/sdk-channel-plugins#step-1-package-and-manifest) 和 [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-1-package-and-manifest)。 +**想要演练教程？** 操作指南在上下文中介绍了打包：[渠道插件](/zh-CN/plugins/sdk-channel-plugins#step-1-package-and-manifest) 和 [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-1-package-and-manifest)。 ## 包元数据 -你的 `package.json` 需要一个 `openclaw` 字段，用来告诉插件系统你的插件提供什么： +你的 `package.json` 需要一个 `openclaw` 字段，用于告诉插件系统你的插件提供什么： - + ```json { "name": "@myorg/openclaw-my-channel", @@ -44,7 +44,7 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl } ``` - + ```json openclaw-clawhub-package.json { "name": "@myorg/openclaw-my-plugin", @@ -67,7 +67,7 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl -如果你在 ClawHub 上外部发布该插件，这些 `compat` 和 `build` 字段是必需的。规范发布片段位于 `docs/snippets/plugin-publish/`。 +如果你在 ClawHub 上对外发布插件，则这些 `compat` 和 `build` 字段是必需的。规范发布片段位于 `docs/snippets/plugin-publish/`。 ### `openclaw` 字段 @@ -76,10 +76,10 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl 入口点文件（相对于包根目录）。 - 轻量级的仅设置入口（可选）。 + 轻量级、仅用于设置的入口（可选）。 - 用于设置、选择器、快速开始和 Status 界面的渠道目录元数据。 + 用于设置、选择器、快速开始和状态界面的渠道目录元数据。 此插件注册的提供商 ID。 @@ -93,28 +93,28 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl ### `openclaw.channel` -`openclaw.channel` 是用于在运行时加载前支持渠道发现和设置界面的低成本包元数据。 +`openclaw.channel` 是用于在运行时加载前进行渠道设备发现和设置界面的轻量级包元数据。 | 字段 | 类型 | 含义 | | -------------------------------------- | ---------- | ----------------------------------------------------------------------------- | | `id` | `string` | 规范渠道 ID。 | | `label` | `string` | 主要渠道标签。 | | `selectionLabel` | `string` | 当需要不同于 `label` 时使用的选择器/设置标签。 | -| `detailLabel` | `string` | 用于更丰富的渠道目录和 Status 界面的次级详情标签。 | +| `detailLabel` | `string` | 用于更丰富渠道目录和状态界面的次要详情标签。 | | `docsPath` | `string` | 用于设置和选择链接的文档路径。 | -| `docsLabel` | `string` | 当需要不同于渠道 ID 时，用于文档链接的覆盖标签。 | +| `docsLabel` | `string` | 当文档链接标签需要不同于渠道 ID 时使用的覆盖标签。 | | `blurb` | `string` | 简短的新手引导/目录描述。 | | `order` | `number` | 渠道目录中的排序顺序。 | | `aliases` | `string[]` | 用于渠道选择的额外查找别名。 | -| `preferOver` | `string[]` | 此渠道应优先于的低优先级插件/渠道 ID。 | -| `systemImage` | `string` | 渠道 UI 目录的可选图标/系统图片名称。 | +| `preferOver` | `string[]` | 此渠道应优先于的较低优先级插件/渠道 ID。 | +| `systemImage` | `string` | 用于渠道 UI 目录的可选图标/系统图像名称。 | | `selectionDocsPrefix` | `string` | 选择界面中文档链接前的前缀文本。 | -| `selectionDocsOmitLabel` | `boolean` | 在选择文案中直接显示文档路径，而不是带标签的文档链接。 | +| `selectionDocsOmitLabel` | `boolean` | 在选择文案中直接显示文档路径，而不是带标签的文档链接。 | | `selectionExtras` | `string[]` | 追加到选择文案中的额外短字符串。 | -| `markdownCapable` | `boolean` | 将该渠道标记为支持 Markdown，用于出站格式化决策。 | +| `markdownCapable` | `boolean` | 将渠道标记为支持 Markdown，用于出站格式决策。 | | `exposure` | `object` | 用于设置、已配置列表和文档界面的渠道可见性控制。 | -| `quickstartAllowFrom` | `boolean` | 将此渠道纳入标准快速开始 `allowFrom` 设置流程。 | -| `forceAccountBinding` | `boolean` | 即使只有一个账号，也要求显式绑定账号。 | +| `quickstartAllowFrom` | `boolean` | 让此渠道加入标准快速开始 `allowFrom` 设置流程。 | +| `forceAccountBinding` | `boolean` | 即使只有一个账号也要求显式绑定账号。 | | `preferSessionLookupForAnnounceTarget` | `boolean` | 为此渠道解析公告目标时优先使用会话查找。 | 示例： @@ -149,7 +149,7 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl `exposure` 支持： -- `configured`：在已配置/Status 风格的列表界面中包含该渠道 +- `configured`：在已配置/状态样式的列表界面中包含该渠道 - `setup`：在交互式设置/配置选择器中包含该渠道 - `docs`：在文档/导航界面中将该渠道标记为面向公众 @@ -161,24 +161,24 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl `openclaw.install` 是包元数据，不是清单元数据。 -| 字段 | 类型 | 含义 | -| ---------------------------- | -------------------- | -------------------------------------------------------------------------------- | -| `npmSpec` | `string` | 用于安装/更新流程的规范 npm 规格。 | -| `localPath` | `string` | 本地开发或内置安装路径。 | -| `defaultChoice` | `"npm"` \| `"local"` | 两者都可用时的首选安装来源。 | -| `minHostVersion` | `string` | 最低支持的 OpenClaw 版本，形式为 `>=x.y.z`。 | -| `expectedIntegrity` | `string` | 预期的 npm 分发完整性字符串，通常为 `sha512-...`，用于固定版本安装。 | -| `allowInvalidConfigRecovery` | `boolean` | 允许内置插件重新安装流程从特定的陈旧配置失败中恢复。 | +| 字段 | 类型 | 含义 | +| ---------------------------- | -------------------- | ------------------------------------------------------------------------------------ | +| `npmSpec` | `string` | 用于安装/更新流程的规范 npm spec。 | +| `localPath` | `string` | 本地开发或内置安装路径。 | +| `defaultChoice` | `"npm"` \| `"local"` | 当两者都可用时首选的安装源。 | +| `minHostVersion` | `string` | 支持的最低 OpenClaw 版本，形式为 `>=x.y.z` 或 `>=x.y.z-prerelease`。 | +| `expectedIntegrity` | `string` | 预期的 npm dist 完整性字符串，通常为 `sha512-...`，用于固定版本安装。 | +| `allowInvalidConfigRecovery` | `boolean` | 允许内置插件重新安装流程从特定的陈旧配置失败中恢复。 | - - 交互式新手引导也会将 `openclaw.install` 用于按需安装界面。如果你的插件在运行时加载前公开提供商认证选择或渠道设置/目录元数据，新手引导可以显示该选项，提示选择 npm 或本地安装，安装或启用该插件，然后继续所选流程。npm 新手引导选项需要带有注册表 `npmSpec` 的可信目录元数据；精确版本和 `expectedIntegrity` 是可选固定值。如果存在 `expectedIntegrity`，安装/更新流程会强制校验它。将“显示什么”的元数据保留在 `openclaw.plugin.json` 中，将“如何安装它”的元数据保留在 `package.json` 中。 + + 交互式新手引导也会将 `openclaw.install` 用于按需安装界面。如果你的插件在运行时加载前暴露提供商认证选项或渠道设置/目录元数据，新手引导可以显示该选项，提示选择 npm 或本地安装，安装或启用插件，然后继续所选流程。Npm 新手引导选项需要受信任的目录元数据和注册表 `npmSpec`；精确版本和 `expectedIntegrity` 是可选固定项。如果存在 `expectedIntegrity`，安装/更新流程会强制校验它。请将“显示什么”的元数据放在 `openclaw.plugin.json` 中，将“如何安装它”的元数据放在 `package.json` 中。 - - 如果设置了 `minHostVersion`，安装和清单注册表加载都会强制执行它。旧版主机会跳过该插件；无效的版本字符串会被拒绝。 + + 如果设置了 `minHostVersion`，安装和非内置清单注册表加载都会强制执行它。较旧的宿主会跳过外部插件；无效的版本字符串会被拒绝。内置源插件会被假定为与宿主检出版本一致。 - - 对于固定版本的 npm 安装，请在 `npmSpec` 中保留精确版本，并添加预期的工件完整性： + + 对于固定版本 npm 安装，请在 `npmSpec` 中保留精确版本，并添加预期的构件完整性： ```json { @@ -193,14 +193,14 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl ``` - - `allowInvalidConfigRecovery` 不是破损配置的通用绕过开关。它仅用于狭窄的内置插件恢复场景，让重新安装/设置可以修复已知升级残留，例如缺失的内置插件路径，或同一插件的陈旧 `channels.` 条目。如果配置因无关原因损坏，安装仍会以失败关闭，并提示操作员运行 `openclaw doctor --fix`。 + + `allowInvalidConfigRecovery` 不是针对损坏配置的通用绕过机制。它仅用于狭义的内置插件恢复，因此重新安装/设置可以修复已知的升级残留，例如缺失的内置插件路径，或同一插件的陈旧 `channels.` 条目。如果配置因无关原因损坏，安装仍会失败关闭，并提示操作员运行 `openclaw doctor --fix`。 ### 延迟完整加载 -渠道插件可以通过以下配置选择延迟加载： +渠道插件可以通过以下方式选择延迟加载： ```json { @@ -214,17 +214,17 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl } ``` -启用后，即使对于已经配置的渠道，OpenClaw 在监听前启动阶段也只加载 `setupEntry`。完整入口会在 Gateway 网关开始监听后加载。 +启用后，即使对于已经配置的渠道，OpenClaw 也只会在监听前启动阶段加载 `setupEntry`。完整入口会在 Gateway 网关开始监听后加载。 -仅当你的 `setupEntry` 在 Gateway 网关开始监听前注册了 Gateway 网关所需的一切（渠道注册、HTTP 路由、Gateway 网关方法）时，才启用延迟加载。如果完整入口拥有必需的启动能力，请保留默认行为。 +只有当你的 `setupEntry` 注册了 Gateway 网关在开始监听前所需的一切（渠道注册、HTTP 路由、Gateway 网关方法）时，才启用延迟加载。如果完整入口拥有必需的启动能力，请保留默认行为。 -如果你的设置/完整入口注册 Gateway 网关 RPC 方法，请将它们放在插件专用前缀下。保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍由核心拥有，并始终解析为 `operator.admin`。 +如果你的设置/完整入口注册了 Gateway 网关 RPC 方法，请将它们放在插件专属前缀下。保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍归核心所有，并且始终解析为 `operator.admin`。 ## 插件清单 -每个原生插件都必须在包根目录中随附一个 `openclaw.plugin.json`。OpenClaw 使用它在不执行插件代码的情况下验证配置。 +每个原生插件都必须在包根目录中附带一个 `openclaw.plugin.json`。OpenClaw 会使用它在不执行插件代码的情况下验证配置。 ```json { @@ -244,7 +244,7 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl } ``` -对于渠道插件，添加 `kind` 和 `channels`： +对于渠道插件，请添加 `kind` 和 `channels`： ```json { @@ -259,7 +259,7 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl } ``` -即使没有配置的插件也必须随附一个架构。空架构是有效的： +即使没有配置的插件也必须附带架构。空架构是有效的： ```json { @@ -271,7 +271,7 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl } ``` -完整架构参考见[插件清单](/zh-CN/plugins/manifest)。 +完整架构参考请参阅 [插件清单](/zh-CN/plugins/manifest)。 ## ClawHub 发布 @@ -283,12 +283,12 @@ clawhub package publish your-org/your-plugin ``` -旧版的仅 Skills 发布别名用于 Skills。插件包应始终使用 `clawhub package publish`。 +旧版仅 Skills 发布别名用于 Skills。插件包应始终使用 `clawhub package publish`。 ## 设置入口 -`setup-entry.ts` 文件是 `index.ts` 的轻量级替代项，OpenClaw 在只需要设置界面时加载它（新手引导、配置修复、已禁用渠道检查）。 +`setup-entry.ts` 文件是 `index.ts` 的轻量替代入口，OpenClaw 仅需要设置界面（新手引导、配置修复、已禁用渠道检查）时会加载它。 ```typescript // setup-entry.ts @@ -298,9 +298,9 @@ import { myChannelPlugin } from "./src/channel.js"; export default defineSetupPluginEntry(myChannelPlugin); ``` -这可以避免在设置流程中加载繁重的运行时代码（加密库、CLI 注册、后台服务）。 +这避免在设置流程中加载繁重的运行时代码（加密库、CLI 注册、后台服务）。 -将设置安全导出保存在辅助模块中的内置工作区渠道，可以使用来自 `openclaw/plugin-sdk/channel-entry-contract` 的 `defineBundledChannelSetupEntry(...)`，而不是 `defineSetupPluginEntry(...)`。该内置契约还支持可选的 `runtime` 导出，因此设置期间的运行时接线可以保持轻量且明确。 +将设置安全导出放在伴随模块中的内置工作区渠道，可以使用来自 `openclaw/plugin-sdk/channel-entry-contract` 的 `defineBundledChannelSetupEntry(...)`，而不是 `defineSetupPluginEntry(...)`。该内置契约还支持可选的 `runtime` 导出，因此设置时的运行时接线可以保持轻量且显式。 @@ -321,42 +321,42 @@ export default defineSetupPluginEntry(myChannelPlugin); - CLI 注册。 - 后台服务。 - 繁重的运行时导入（加密、SDK）。 - - 仅在启动后需要的 Gateway 网关方法。 + - 仅在启动后才需要的 Gateway 网关方法。 -### 窄范围设置辅助导入 +### 窄设置辅助导入 -对于热门的仅设置路径，如果你只需要设置界面的一部分，优先使用窄范围设置辅助接缝，而不是更宽泛的 `plugin-sdk/setup` 总入口： +对于高频设置专用路径，当你只需要设置界面的一部分时，优先使用窄设置辅助接缝，而不是更宽泛的 `plugin-sdk/setup` 总入口： -| 导入路径 | 用途 | 关键导出 | -| ---------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/setup-runtime` | 在 `setupEntry` / 延迟渠道启动中仍可用的设置期间运行时辅助工具 | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | -| `plugin-sdk/setup-adapter-runtime` | 感知环境的账号设置适配器 | `createEnvPatchedAccountSetupAdapter` | -| `plugin-sdk/setup-tools` | 设置/安装 CLI/归档/文档辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | +| 导入路径 | 用途 | 关键导出 | +| ---------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/setup-runtime` | 在 `setupEntry` / 延迟渠道启动中仍可用的设置时运行时辅助工具 | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | +| `plugin-sdk/setup-adapter-runtime` | 感知环境的账号设置适配器 | `createEnvPatchedAccountSetupAdapter` | +| `plugin-sdk/setup-tools` | 设置/安装 CLI/归档/文档辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | -当你需要完整的共享设置工具箱时，请使用更宽泛的 `plugin-sdk/setup` 接缝，包括 `moveSingleAccountChannelSectionToDefaultAccount(...)` 等配置补丁辅助工具。 +当你需要完整的共享设置工具箱时，使用更宽泛的 `plugin-sdk/setup` 接缝，包括 `moveSingleAccountChannelSectionToDefaultAccount(...)` 等配置补丁辅助工具。 -设置补丁适配器在导入时保持热路径安全。它们的内置单账号提升契约界面查找是惰性的，因此导入 `plugin-sdk/setup-runtime` 不会在实际使用适配器前急切加载内置契约界面发现逻辑。 +设置补丁适配器在导入时保持热路径安全。它们的内置单账号提升契约界面查找是惰性的，因此导入 `plugin-sdk/setup-runtime` 不会在适配器实际使用前就提前加载内置契约界面发现。 -### 渠道拥有的单账号提升 +### 渠道自有的单账号提升 -当渠道从单账号顶层配置升级到 `channels..accounts.*` 时，默认共享行为是将提升后的账号范围值移动到 `accounts.default`。 +当渠道从单账号顶层配置升级到 `channels..accounts.*` 时，默认共享行为是将已提升的账号作用域值移动到 `accounts.default`。 -内置渠道可以通过其设置契约界面缩小或覆盖该提升行为： +内置渠道可以通过它们的设置契约界面收窄或覆盖该提升行为： -- `singleAccountKeysToMove`：应移动到提升后账号中的额外顶层键 -- `namedAccountPromotionKeys`：当命名账号已存在时，只有这些键会移动到提升后的账号；共享策略/投递键仍保留在渠道根部 -- `resolveSingleAccountPromotionTarget(...)`：选择哪个现有账号接收提升后的值 +- `singleAccountKeysToMove`：应移动到已提升账号中的额外顶层键 +- `namedAccountPromotionKeys`：当具名账号已存在时，只有这些键会移动到已提升账号中；共享策略/投递键保留在渠道根级别 +- `resolveSingleAccountPromotionTarget(...)`：选择哪个现有账号接收已提升值 -Matrix 是当前的内置示例。如果已经恰好存在一个命名 Matrix 账号，或者 `defaultAccount` 指向现有的非规范键（例如 `Ops`），提升会保留该账号，而不是创建新的 `accounts.default` 条目。 +Matrix 是当前的内置示例。如果恰好已存在一个具名 Matrix 账号，或者 `defaultAccount` 指向了现有的非规范键（例如 `Ops`），提升会保留该账号，而不是创建新的 `accounts.default` 条目。 -## 配置架构 +## 配置 schema -插件配置会根据你清单中的 JSON Schema 进行验证。用户通过以下方式配置插件： +插件配置会根据你的 manifest 中的 JSON Schema 进行验证。用户通过以下方式配置插件： ```json5 { @@ -374,7 +374,7 @@ Matrix 是当前的内置示例。如果已经恰好存在一个命名 Matrix 你的插件会在注册期间以 `api.pluginConfig` 接收此配置。 -对于渠道专属配置，请改用渠道配置部分： +对于渠道特定配置，请改用渠道配置区段： ```json5 { @@ -387,9 +387,9 @@ Matrix 是当前的内置示例。如果已经恰好存在一个命名 Matrix } ``` -### 构建渠道配置架构 +### 构建渠道配置 schema -使用 `buildChannelConfigSchema` 将 Zod 架构转换为插件拥有的配置工件所使用的 `ChannelConfigSchema` 包装器： +使用 `buildChannelConfigSchema` 将 Zod schema 转换为插件自有配置产物使用的 `ChannelConfigSchema` 包装器： ```typescript import { z } from "zod"; @@ -405,11 +405,11 @@ const accountSchema = z.object({ const configSchema = buildChannelConfigSchema(accountSchema); ``` -对于第三方插件，冷路径契约仍然是插件清单：将生成的 JSON Schema 镜像到 `openclaw.plugin.json#channelConfigs`，这样配置架构、设置和 UI 界面就可以在不加载运行时代码的情况下检查 `channels.`。 +对于第三方插件，冷路径契约仍然是插件 manifest：将生成的 JSON Schema 镜像到 `openclaw.plugin.json#channelConfigs`，这样配置 schema、设置和 UI 界面就能在不加载运行时代码的情况下检查 `channels.`。 ## 设置向导 -渠道插件可以为 `openclaw onboard` 提供交互式设置向导。该向导是 `ChannelPlugin` 上的一个 `ChannelSetupWizard` 对象： +渠道插件可以为 `openclaw onboard` 提供交互式设置向导。该向导是 `ChannelPlugin` 上的 `ChannelSetupWizard` 对象： ```typescript import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup"; @@ -442,17 +442,17 @@ const setupWizard: ChannelSetupWizard = { }; ``` -`ChannelSetupWizard` 类型支持 `credentials`、`textInputs`、`dmPolicy`、`allowFrom`、`groupAccess`、`prepare`、`finalize` 等。完整示例请参见内置插件包（例如 Discord 插件 `src/channel.setup.ts`）。 +`ChannelSetupWizard` 类型支持 `credentials`、`textInputs`、`dmPolicy`、`allowFrom`、`groupAccess`、`prepare`、`finalize` 等。完整示例请参阅内置插件包（例如 Discord 插件的 `src/channel.setup.ts`）。 对于只需要标准 `note -> prompt -> parse -> merge -> patch` 流程的私信允许列表提示，优先使用来自 `openclaw/plugin-sdk/setup` 的共享设置辅助工具：`createPromptParsedAllowFromForAccount(...)`、`createTopLevelChannelParsedAllowFromPrompt(...)` 和 `createNestedChannelParsedAllowFromPrompt(...)`。 - 对于只按标签、分数和可选额外行变化的渠道设置 Status 块，优先使用来自 `openclaw/plugin-sdk/setup` 的 `createStandardChannelSetupStatus(...)`，而不是在每个插件中手写相同的 `status` 对象。 + 对于仅因标签、分数和可选额外行而变化的渠道设置 Status 块，优先使用来自 `openclaw/plugin-sdk/setup` 的 `createStandardChannelSetupStatus(...)`，而不是在每个插件中手写相同的 `status` 对象。 - 对于只应在特定上下文中出现的可选设置界面，请使用来自 `openclaw/plugin-sdk/channel-setup` 的 `createOptionalChannelSetupSurface`： + 对于只应在特定上下文中出现的可选设置界面，使用来自 `openclaw/plugin-sdk/channel-setup` 的 `createOptionalChannelSetupSurface`： ```typescript import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; @@ -466,16 +466,16 @@ const setupWizard: ChannelSetupWizard = { // Returns { setupAdapter, setupWizard } ``` - 当你只需要该可选安装界面的一半时，`plugin-sdk/channel-setup` 还公开了更低层的 `createOptionalChannelSetupAdapter(...)` 和 `createOptionalChannelSetupWizard(...)` 构建器。 + 当你只需要该可选安装界面的一半时，`plugin-sdk/channel-setup` 还暴露了更底层的 `createOptionalChannelSetupAdapter(...)` 和 `createOptionalChannelSetupWizard(...)` 构建器。 - 生成的可选适配器/向导会在真实配置写入时关闭失败。它们在 `validateInput`、`applyAccountConfig` 和 `finalize` 中复用同一条需要安装的消息，并在设置了 `docsPath` 时附加文档链接。 + 生成的可选适配器/向导会在真实配置写入时默认失败。它们在 `validateInput`、`applyAccountConfig` 和 `finalize` 中复用同一条需要安装的消息，并在设置了 `docsPath` 时附加文档链接。 - - 对于二进制支持的设置 UI，优先使用共享的委托辅助工具，而不是将相同的二进制/Status 胶水复制到每个渠道中： + + 对于二进制文件驱动的设置 UI，优先使用共享的委托辅助工具，而不是把相同的二进制文件/Status 粘合逻辑复制到每个渠道中： - - `createDetectedBinaryStatus(...)` 用于只按标签、提示、分数和二进制检测变化的 Status 块 - - `createCliPathTextInput(...)` 用于路径支持的文本输入 + - `createDetectedBinaryStatus(...)` 用于只因标签、提示、分数和二进制文件检测而变化的 Status 块 + - `createCliPathTextInput(...)` 用于基于路径的文本输入 - 当 `setupEntry` 需要惰性转发到更重的完整向导时，使用 `createDelegatedSetupWizardStatusResolvers(...)`、`createDelegatedPrepare(...)`、`createDelegatedFinalize(...)` 和 `createDelegatedResolveConfigured(...)` - 当 `setupEntry` 只需要委托 `textInputs[*].shouldPrompt` 决策时，使用 `createDelegatedTextInputShouldPrompt(...)` @@ -501,7 +501,7 @@ const setupWizard: ChannelSetupWizard = { ``` - 当包尚未迁移到 ClawHub，或者你在迁移期间需要直接的 npm 安装路径时，请使用 npm： + 当包尚未迁移到 ClawHub，或者迁移期间需要直接 npm 安装路径时，使用 npm： ```bash openclaw plugins install npm:@myorg/openclaw-my-plugin @@ -510,7 +510,7 @@ const setupWizard: ChannelSetupWizard = { -**仓库内插件：**放置在内置插件工作区树下，它们会在构建期间被自动发现。 +**仓库内插件：**放在内置插件工作区树下，它们会在构建期间被自动发现。 **用户可以安装：** @@ -519,17 +519,17 @@ openclaw plugins install ``` -对于来自 npm 的安装，`openclaw plugins install` 会在禁用生命周期脚本的情况下将包安装到 `~/.openclaw/npm` 下。请保持插件依赖树为纯 JS/TS，并避免使用需要 `postinstall` 构建的包。 +对于来自 npm 的安装，`openclaw plugins install` 会在禁用生命周期脚本的情况下将包安装到 `~/.openclaw/npm` 下。保持插件依赖树为纯 JS/TS，并避免使用需要 `postinstall` 构建的包。 -Gateway 网关启动不会安装插件依赖。npm/git/ClawHub 安装流程负责依赖收敛；本地插件必须已经安装好其依赖。 +Gateway 网关启动不会安装插件依赖。npm/git/ClawHub 安装流程负责依赖收敛；本地插件必须已安装其依赖。 -内置包元数据是显式的，不是在 Gateway 网关启动时从构建后的 JavaScript 推断出来的。运行时依赖项应放在拥有它们的插件包中；打包版 OpenClaw 启动流程绝不会修复或镜像插件依赖项。 +内置包元数据是显式的，不是在 Gateway 网关启动时从构建后的 JavaScript 中推断出来的。运行时依赖应放在拥有这些依赖的插件包中；打包版 OpenClaw 启动过程永远不会修复或镜像插件依赖。 ## 相关内容 - [构建插件](/zh-CN/plugins/building-plugins) — 分步入门指南 -- [插件清单](/zh-CN/plugins/manifest) — 完整的清单 schema 参考 +- [插件清单](/zh-CN/plugins/manifest) — 完整清单架构参考 - [SDK 入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 和 `defineChannelPluginEntry` diff --git a/docs/zh-CN/providers/google.md b/docs/zh-CN/providers/google.md index 6661e6878..8dc4a6a69 100644 --- a/docs/zh-CN/providers/google.md +++ b/docs/zh-CN/providers/google.md @@ -2,37 +2,36 @@ read_when: - 你想在 OpenClaw 中使用 Google Gemini 模型 - 你需要 API 密钥或 OAuth 认证流程 -summary: Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、TTS、网页搜索） -title: Google (Gemini) +summary: Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、TTS、Web 搜索） +title: Google（Gemini） x-i18n: - generated_at: "2026-04-28T12:01:47Z" + generated_at: "2026-05-02T02:49:07Z" model: gpt-5.5 provider: openai - source_hash: ea4b53dcea10fef67920da3baca4c85325ee4d4da780fbf708b67bc618e064a6 + source_hash: 17d7694408dd02ea87d71530a544ad45e0284a973803f76313338a5065b3f7d5 source_path: providers/google.md workflow: 16 --- -Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，另外还支持 -图像生成、媒体理解（图像/音频/视频）、文本转语音，以及通过 -Gemini Grounding 进行 Web 搜索。 +Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并通过 +Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）、文本转语音和 Web 搜索。 - 提供商：`google` -- 凭证：`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` +- 认证：`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` - API：Google Gemini API - 运行时选项：`agents.defaults.agentRuntime.id: "google-gemini-cli"` 会复用 Gemini CLI OAuth，同时将模型引用保持为规范的 `google/*`。 ## 入门指南 -选择你偏好的凭证方式，并按照设置步骤操作。 +选择你偏好的认证方式，并按照设置步骤操作。 - **最适合：**通过 Google AI Studio 进行标准 Gemini API 访问。 + **适用于：**通过 Google AI Studio 进行标准 Gemini API 访问。 - + ```bash openclaw onboard --auth-choice gemini-api-key ``` @@ -46,7 +45,7 @@ Gemini Grounding 进行 Web 搜索。 --gemini-api-key "$GEMINI_API_KEY" ``` - + ```json5 { agents: { @@ -57,7 +56,7 @@ Gemini Grounding 进行 Web 搜索。 } ``` - + ```bash openclaw models list --provider google ``` @@ -65,22 +64,21 @@ Gemini Grounding 进行 Web 搜索。 - 环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都受支持。使用你已经配置好的那个即可。 + 环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都可以使用。使用你已经配置好的那个即可。 - **最适合：**通过 PKCE OAuth 复用现有 Gemini CLI 登录，而不是使用单独的 API key。 + **适用于：**通过 PKCE OAuth 复用现有的 Gemini CLI 登录，而不是单独使用 API key。 - `google-gemini-cli` 提供商是一个非官方集成。一些用户 - 反馈以这种方式使用 OAuth 时会遇到账户限制。请自行承担风险。 + `google-gemini-cli` 提供商是非官方集成。有些用户报告以这种方式使用 OAuth 时会遇到账户限制。请自行承担风险。 - - 本地 `gemini` 命令必须在 `PATH` 上可用。 + + 本地 `gemini` 命令必须可在 `PATH` 上使用。 ```bash # Homebrew @@ -93,12 +91,12 @@ Gemini Grounding 进行 Web 搜索。 OpenClaw 同时支持 Homebrew 安装和全局 npm 安装，包括 常见的 Windows/npm 布局。 - + ```bash openclaw models auth login --provider google-gemini-cli --set-default ``` - + ```bash openclaw models list --provider google ``` @@ -109,7 +107,7 @@ Gemini Grounding 进行 Web 搜索。 - 运行时：`google-gemini-cli` - 别名：`gemini-cli` - Gemini 3.1 Pro 的 Gemini API 模型 ID 是 `gemini-3.1-pro-preview`。OpenClaw 接受更短的 `google/gemini-3.1-pro` 作为便利别名，并在调用提供商前将其规范化。 + Gemini 3.1 Pro 的 Gemini API 模型 ID 是 `gemini-3.1-pro-preview`。OpenClaw 接受较短的 `google/gemini-3.1-pro` 作为便捷别名，并会在提供商调用前对其进行规范化。 **环境变量：** @@ -124,12 +122,12 @@ Gemini Grounding 进行 Web 搜索。 - 如果登录在浏览器流程启动前失败，请确保本地 `gemini` - 命令已安装并在 `PATH` 上。 + 如果登录在浏览器流程开始前失败，请确保本地 `gemini` + 命令已安装并位于 `PATH` 上。 `google-gemini-cli/*` 模型引用是旧版兼容别名。新的 - 配置应使用 `google/*` 模型引用，并在需要本地 Gemini CLI 执行时配合使用 `google-gemini-cli` + 配置应使用 `google/*` 模型引用，并在需要本地 Gemini CLI 执行时搭配 `google-gemini-cli` 运行时。 @@ -151,20 +149,47 @@ Gemini Grounding 进行 Web 搜索。 | 思考/推理 | 是（Gemini 2.5+ / Gemini 3+） | | Gemma 4 模型 | 是 | +## Web 搜索 + +内置的 `gemini` Web 搜索提供商使用 Gemini Google Search grounding。 +在 `plugins.entries.google.config.webSearch` 下配置它： + +```json5 +{ + plugins: { + entries: { + google: { + config: { + webSearch: { + apiKey: "AIza...", // optional if GEMINI_API_KEY is set + baseUrl: "https://generativelanguage.googleapis.com/v1beta", + model: "gemini-2.5-flash", + }, + }, + }, + }, + }, +} +``` + +`webSearch.baseUrl` 是可选项，用于操作方代理或兼容的 +Gemini API 端点。请参阅 [Gemini 搜索](/zh-CN/tools/gemini-search) 了解 +提供商特定的工具行为。 + -Gemini 3 模型使用 `thinkingLevel`，而不是 `thinkingBudget`。OpenClaw 会将 +Gemini 3 模型使用 `thinkingLevel` 而不是 `thinkingBudget`。OpenClaw 会将 Gemini 3、Gemini 3.1 和 `gemini-*-latest` 别名的推理控制映射到 `thinkingLevel`，因此默认/低延迟运行不会发送已禁用的 `thinkingBudget` 值。 -`/think adaptive` 会保留 Google 的动态思考语义，而不是选择一个 +`/think adaptive` 会保留 Google 的动态思考语义，而不是选择 固定的 OpenClaw 级别。Gemini 3 和 Gemini 3.1 会省略固定的 `thinkingLevel`，以便 Google 可以选择级别；Gemini 2.5 会发送 Google 的动态哨兵值 `thinkingBudget: -1`。 Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会为 Gemma 4 将 `thinkingBudget` 重写为受支持的 Google `thinkingLevel`。 -将思考设置为 `off` 会保持思考禁用，而不是映射到 +将思考设置为 `off` 会保持思考禁用状态，而不是映射到 `MINIMAL`。 @@ -198,11 +223,11 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw ## 视频生成 -内置的 `google` 插件还会通过共享的 +内置的 `google` 插件还通过共享的 `video_generate` 工具注册视频生成。 - 默认视频模型：`google/veo-3.1-fast-generate-preview` -- 模式：文本到视频、图像到视频，以及单视频引用流程 +- 模式：文本转视频、图像转视频，以及单视频参考流程 - 支持 `aspectRatio`、`resolution` 和 `audio` - 当前时长限制：**4 到 8 秒** @@ -226,15 +251,15 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw ## 音乐生成 -内置的 `google` 插件还会通过共享的 +内置的 `google` 插件还通过共享的 `music_generate` 工具注册音乐生成。 - 默认音乐模型：`google/lyria-3-clip-preview` - 还支持 `google/lyria-3-pro-preview` - 提示词控制：`lyrics` 和 `instrumental` -- 输出格式：默认 `mp3`，`google/lyria-3-pro-preview` 另支持 `wav` +- 输出格式：默认 `mp3`，在 `google/lyria-3-pro-preview` 上还支持 `wav` - 参考输入：最多 10 张图像 -- 基于会话的运行会通过共享的任务/Status 流程分离，包括 `action: "status"` +- 由会话支撑的运行会通过共享的任务/Status 流程分离，包括 `action: "status"` 要将 Google 用作默认音乐提供商： @@ -260,9 +285,9 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw `gemini-3.1-flash-tts-preview`。 - 默认语音：`Kore` -- 凭证：`messages.tts.providers.google.apiKey`、`models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` -- 输出：常规 TTS 附件使用 WAV，语音备注目标使用 Opus，Talk/电话使用 PCM -- 语音备注输出：Google PCM 会封装为 WAV，并通过 `ffmpeg` 转码为 48 kHz Opus +- 认证：`messages.tts.providers.google.apiKey`、`models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` +- 输出：常规 TTS 附件使用 WAV，语音笔记目标使用 Opus，Talk/电话使用 PCM +- 语音笔记输出：Google PCM 会被包装为 WAV，并用 `ffmpeg` 转码为 48 kHz Opus 要将 Google 用作默认 TTS 提供商： @@ -285,12 +310,12 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw ``` Gemini API TTS 使用自然语言提示词进行风格控制。设置 -`audioProfile` 可在朗读文本前添加可复用的风格提示词。若你的提示词文本提到具名说话人，请设置 +`audioProfile` 可在朗读文本前添加一个可复用的风格提示词。当你的提示词文本提到具名说话人时，请设置 `speakerName`。 Gemini API TTS 还接受文本中的表现性方括号音频标签， -例如 `[whispers]` 或 `[laughs]`。若要在将标签发送给 TTS 的同时避免它们出现在可见聊天回复中， -请将它们放入 `[[tts:text]]...[[/tts:text]]` +例如 `[whispers]` 或 `[laughs]`。要在将标签发送给 TTS 的同时，让标签不出现在可见聊天回复中， +请把它们放在 `[[tts:text]]...[[/tts:text]]` 块内： ```text @@ -306,21 +331,21 @@ Here is the clean reply text. ## 实时语音 -内置的 `google` 插件会注册一个由 -Gemini Live API 支持的实时语音提供商，用于 Voice Call 和 Google Meet 等后端音频桥接。 +内置的 `google` 插件注册了一个由 +Gemini Live API 支撑的实时语音提供商，用于 Voice Call 和 Google Meet 等后端音频桥接。 | 设置 | 配置路径 | 默认值 | | --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | 模型 | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` | | 语音 | `...google.voice` | `Kore` | | 温度 | `...google.temperature` | （未设置） | -| VAD 起始灵敏度 | `...google.startSensitivity` | （未设置） | -| VAD 结束灵敏度 | `...google.endSensitivity` | （未设置） | +| VAD 开始敏感度 | `...google.startSensitivity` | （未设置） | +| VAD 结束敏感度 | `...google.endSensitivity` | （未设置） | | 静音时长 | `...google.silenceDurationMs` | （未设置） | -| 活动处理 | `...google.activityHandling` | Google 默认值，`start-of-activity-interrupts` | +| 活动处理 | `...google.activityHandling` | Google 默认值，`start-of-activity-interrupts` | | 轮次覆盖 | `...google.turnCoverage` | Google 默认值，`only-activity` | | 禁用自动 VAD | `...google.automaticActivityDetectionDisabled` | `false` | -| API key | `...google.apiKey` | 回退到 `models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | +| API key | `...google.apiKey` | 回退到 `models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | Voice Call 实时配置示例： @@ -353,21 +378,22 @@ Voice Call 实时配置示例： Google Live API 通过 WebSocket 使用双向音频和函数调用。 OpenClaw 会将电话/Meet 桥接音频适配到 Gemini 的 PCM Live API 流，并 -让工具调用继续使用共享的实时语音契约。除非你需要更改采样，否则不要设置 `temperature`； -OpenClaw 会省略非正值，因为 Google Live 在 `temperature: 0` 时可能返回没有音频的转录文本。 -Gemini API 转录在不使用 `languageCodes` 的情况下启用；当前 Google +让工具调用继续使用共享的实时语音契约。除非需要更改采样，否则保持 `temperature` +未设置；OpenClaw 会省略非正值， +因为 Google Live 可能会在 `temperature: 0` 时返回没有音频的转写内容。 +Gemini API 转写会在没有 `languageCodes` 的情况下启用；当前 Google SDK 会拒绝此 API 路径上的语言代码提示。 -Control UI Talk 支持使用受限一次性令牌的 Google Live 浏览器会话。 -仅后端的实时语音提供商也可以通过通用 +Control UI Talk 支持带受限一次性 +令牌的 Google Live 浏览器会话。仅后端的实时语音提供商也可以通过通用 Gateway 网关中继传输运行，这会将提供商凭证保留在 Gateway 网关上。 -对于维护者实时验证，运行 +对于维护者实时验证，请运行 `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`。 -Google 分支会铸造 Control +Google 分支会签发与 Control UI Talk 使用的相同受限 Live API 令牌形态，打开浏览器 WebSocket 端点，发送初始设置载荷， 并等待 `setupComplete`。 @@ -378,10 +404,12 @@ UI Talk 使用的相同受限 Live API 令牌形态，打开浏览器 WebSocket 对于直接 Gemini API 运行（`api: "google-generative-ai"`），OpenClaw 会将配置的 `cachedContent` 句柄传递给 Gemini 请求。 - - 使用 `cachedContent` 或旧版 `cached_content` 配置按模型或全局参数 - - 如果两者都存在，`cachedContent` 优先 + - 使用 `cachedContent` 或旧版 `cached_content` + 配置按模型或全局参数 + - 如果两者同时存在，`cachedContent` 优先 - 示例值：`cachedContents/prebuilt-context` - - Gemini 缓存命中用量会从上游 `cachedContentTokenCount` 规范化为 OpenClaw `cacheRead` + - Gemini 缓存命中用量会从上游 `cachedContentTokenCount` + 规范化为 OpenClaw `cacheRead` ```json5 { @@ -401,7 +429,7 @@ UI Talk 使用的相同受限 Live API 令牌形态，打开浏览器 WebSocket - + 使用 `google-gemini-cli` OAuth 提供商时，OpenClaw 会按如下方式规范化 CLI JSON 输出： @@ -413,8 +441,8 @@ UI Talk 使用的相同受限 Live API 令牌形态，打开浏览器 WebSocket - - 如果 Gateway 网关作为守护进程运行（launchd/systemd），请确保 `GEMINI_API_KEY` + + 如果 Gateway 网关作为守护进程（launchd/systemd）运行，请确保 `GEMINI_API_KEY` 可供该进程使用（例如，在 `~/.openclaw/.env` 中，或通过 `env.shellEnv`）。 diff --git a/docs/zh-CN/providers/xai.md b/docs/zh-CN/providers/xai.md index 090fea174..935042cb8 100644 --- a/docs/zh-CN/providers/xai.md +++ b/docs/zh-CN/providers/xai.md @@ -1,19 +1,19 @@ --- read_when: - 你想在 OpenClaw 中使用 Grok 模型 - - 你正在配置 xAI 身份验证或模型 ID + - 你正在配置 xAI 凭证或模型 ID summary: 在 OpenClaw 中使用 xAI Grok 模型 title: xAI x-i18n: - generated_at: "2026-05-02T01:45:07Z" + generated_at: "2026-05-02T02:49:00Z" model: gpt-5.5 provider: openai - source_hash: 9366d6a053fb515d843bbb984ee0fce2eb342a022a6d9aa60df983fc0f8d5745 + source_hash: 7f36b597fd5c47b61724080deb0d545bca024aca17744fc8aa6a0eb4872d12d2 source_path: providers/xai.md workflow: 16 --- -OpenClaw 内置了一个用于 Grok 模型的 `xai` 提供商插件。 +OpenClaw 随附内置的 `xai` 提供商插件，用于 Grok 模型。 ## 入门指南 @@ -39,11 +39,13 @@ OpenClaw 内置了一个用于 Grok 模型的 `xai` 提供商插件。 -OpenClaw 使用 xAI Responses API 作为内置的 xAI 传输协议。同一个 -`XAI_API_KEY` 也可以驱动由 Grok 支持的 `web_search`、一等 `x_search` -以及远程 `code_execution`。 +OpenClaw 使用 xAI Responses API 作为内置 xAI 传输协议。同一个 +`XAI_API_KEY` 还可以驱动基于 Grok 的 `web_search`、一等 `x_search` +和远程 `code_execution`。 如果你在 `plugins.entries.xai.config.webSearch.apiKey` 下存储 xAI key， -内置的 xAI 模型提供商也会复用该 key 作为回退。 +内置 xAI 模型提供商也会将该 key 作为回退复用。 +设置 `plugins.entries.xai.config.webSearch.baseUrl`，可将 Grok `web_search` +以及默认情况下的 `x_search` 路由到操作方的 xAI Responses 代理。 `code_execution` 调优位于 `plugins.entries.xai.config.codeExecution` 下。 @@ -51,7 +53,7 @@ OpenClaw 使用 xAI Responses API 作为内置的 xAI 传输协议。同一个 OpenClaw 开箱即包含这些 xAI 模型系列： -| 系列 | 模型 ID | +| 系列 | 模型 id | | -------------- | ------------------------------------------------------------------------ | | Grok 3 | `grok-3`, `grok-3-fast`, `grok-3-mini`, `grok-3-mini-fast` | | Grok 4.3 | `grok-4.3` | @@ -61,41 +63,41 @@ OpenClaw 开箱即包含这些 xAI 模型系列： | Grok 4.20 Beta | `grok-4.20-beta-latest-reasoning`, `grok-4.20-beta-latest-non-reasoning` | | Grok Code | `grok-code-fast-1` | -当较新的 `grok-4*` 和 `grok-code-fast*` ID 遵循相同 API 形态时，该插件也会 -向前解析它们。 +当新的 `grok-4*` 和 `grok-code-fast*` id 遵循相同 API 形态时， +该插件也会前向解析这些 id。 -`grok-4.3`、`grok-4-fast`、`grok-4-1-fast` 以及 `grok-4.20-beta-*` -变体是内置目录中当前支持图像能力的 Grok 引用。 +`grok-4.3`、`grok-4-fast`、`grok-4-1-fast` 和 `grok-4.20-beta-*` +变体是内置目录中当前支持图像的 Grok 引用。 ## OpenClaw 功能覆盖范围 -内置插件会将 xAI 当前的公开 API 表面映射到 OpenClaw 共享的 -提供商和工具契约上。不适合共享契约的能力 -（例如流式 TTS 和实时语音）不会暴露，请参见下表。 +内置插件会将 xAI 当前的公开 API 表面映射到 OpenClaw 的共享 +提供商和工具契约。不适配共享契约的能力 +（例如流式 TTS 和实时语音）不会暴露；见下表。 -| xAI 能力 | OpenClaw 表面 | Status | -| -------------------------- | ----------------------------------------- | ------------------------------------------------------------------- | -| 聊天 / Responses | `xai/` 模型提供商 | 是 | -| 服务端网页搜索 | `web_search` 提供商 `grok` | 是 | -| 服务端 X 搜索 | `x_search` 工具 | 是 | -| 服务端代码执行 | `code_execution` 工具 | 是 | -| 图像 | `image_generate` | 是 | -| 视频 | `video_generate` | 是 | -| 批量文本转语音 | `messages.tts.provider: "xai"` / `tts` | 是 | -| 流式 TTS | — | 未暴露；OpenClaw 的 TTS 契约返回完整音频缓冲区 | -| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 | -| 流式语音转文本 | Voice Call `streaming.provider: "xai"` | 是 | -| 实时语音 | — | 尚未暴露；使用不同的会话/WebSocket 契约 | -| 文件 / 批处理 | 仅通用模型 API 兼容性 | 不是一等 OpenClaw 工具 | +| xAI 能力 | OpenClaw 表面 | Status | +| ------------------------- | ----------------------------------------- | ------------------------------------------------------------------- | +| 聊天 / Responses | `xai/` 模型提供商 | 是 | +| 服务端 Web 搜索 | `web_search` 提供商 `grok` | 是 | +| 服务端 X 搜索 | `x_search` 工具 | 是 | +| 服务端代码执行 | `code_execution` 工具 | 是 | +| 图像 | `image_generate` | 是 | +| 视频 | `video_generate` | 是 | +| 批量文本转语音 | `messages.tts.provider: "xai"` / `tts` | 是 | +| 流式 TTS | — | 未暴露；OpenClaw 的 TTS 契约返回完整音频缓冲区 | +| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 | +| 流式语音转文本 | Voice Call `streaming.provider: "xai"` | 是 | +| 实时语音 | — | 暂未暴露；使用不同的会话/WebSocket 契约 | +| 文件 / 批处理 | 仅通用模型 API 兼容性 | 不是一等 OpenClaw 工具 | OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、 语音和批量转录，使用 xAI 的流式 STT WebSocket 进行实时 -语音通话转录，并使用 Responses API 处理模型、搜索和 +语音通话转录，并使用 Responses API 进行模型、搜索和 代码执行工具。需要不同 OpenClaw 契约的功能，例如 -实时语音会话，在此记录为上游能力，而不是隐藏的插件行为。 +实时语音会话，在此作为上游能力记录，而不是隐藏的插件行为。 ### 快速模式映射 @@ -112,9 +114,9 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、 ### 旧版兼容别名 -旧版别名仍会规范化为内置的规范 ID： +旧版别名仍会归一化为规范的内置 id： -| 旧版别名 | 规范 ID | +| 旧版别名 | 规范 id | | ------------------------- | ------------------------------------- | | `grok-4-fast-reasoning` | `grok-4-fast` | | `grok-4-1-fast-reasoning` | `grok-4-1-fast` | @@ -124,8 +126,8 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、 ## 功能 - - 内置的 `grok` 网页搜索提供商也使用 `XAI_API_KEY`： + + 内置 `grok` Web 搜索提供商也使用 `XAI_API_KEY`： ```bash openclaw config set tools.web.search.provider grok @@ -134,22 +136,23 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、 - 内置的 `xai` 插件通过共享的 + 内置 `xai` 插件通过共享的 `video_generate` 工具注册视频生成。 - 默认视频模型：`xai/grok-imagine-video` - 模式：文本转视频、图像转视频、参考图像生成、远程 - 视频编辑和远程视频延展 - - 宽高比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3` + 视频编辑和远程视频扩展 + - 纵横比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3` - 分辨率：`480P`、`720P` - - 时长：生成/图像转视频为 1-15 秒，使用 `reference_image` 角色时为 1-10 秒， - 延展为 2-10 秒 - - 参考图像生成：为每张提供的图像将 `imageRoles` 设置为 `reference_image`； - xAI 最多接受 7 张此类图像 + - 时长：生成/图像转视频为 1-15 秒，使用 + `reference_image` 角色时为 1-10 秒，扩展为 2-10 秒 + - 参考图像生成：将每个提供的图像的 `imageRoles` 设置为 + `reference_image`；xAI 最多接受 7 张此类图像 - 不接受本地视频缓冲区。视频编辑/延展输入请使用远程 `http(s)` URL。 - 图像转视频接受本地图像缓冲区，因为 OpenClaw 可以将它们编码为供 xAI 使用的数据 URL。 + 不接受本地视频缓冲区。视频编辑/扩展输入请使用远程 `http(s)` URL。 + 图像转视频接受本地图像缓冲区，因为 OpenClaw 可以将其编码为 + xAI 的数据 URL。 要将 xAI 用作默认视频提供商： @@ -167,27 +170,26 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、 ``` - 参见[视频生成](/zh-CN/tools/video-generation)，了解共享工具参数、 - 提供商选择和故障转移行为。 + 有关共享工具参数、提供商选择和故障转移行为，请参阅[视频生成](/zh-CN/tools/video-generation)。 - 内置的 `xai` 插件通过共享的 + 内置 `xai` 插件通过共享的 `image_generate` 工具注册图像生成。 - 默认图像模型：`xai/grok-imagine-image` - 其他模型：`xai/grok-imagine-image-pro` - - 模式：文生图和参考图像编辑 + - 模式：文本转图像和参考图像编辑 - 参考输入：一个 `image` 或最多五个 `images` - - 宽高比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`2:3`、`3:2` + - 纵横比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`2:3`、`3:2` - 分辨率：`1K`、`2K` - 数量：最多 4 张图像 - OpenClaw 会向 xAI 请求 `b64_json` 图像响应，以便生成的媒体可以通过 - 常规渠道附件路径存储和投递。本地参考图像会转换为 data URL；远程 - `http(s)` 参考会原样传递。 + OpenClaw 向 xAI 请求 `b64_json` 图像响应，以便生成的媒体可以通过 + 常规渠道附件路径存储和交付。本地参考图像会转换为数据 URL；远程 + `http(s)` 引用会原样传递。 要将 xAI 用作默认图像提供商： @@ -204,24 +206,24 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、 ``` - xAI 还记录了 `quality`、`mask`、`user` 以及其他原生比例， + xAI 还记录了 `quality`、`mask`、`user`，以及其他原生比例， 例如 `1:2`、`2:1`、`9:20` 和 `20:9`。OpenClaw 目前只转发 - 跨提供商共享的图像控制项；不支持的仅原生旋钮会有意不通过 + 共享的跨提供商图像控制项；不受支持的原生专用旋钮会有意不通过 `image_generate` 暴露。 - 内置的 `xai` 插件通过共享的 `tts` + 内置 `xai` 插件通过共享的 `tts` 提供商表面注册文本转语音。 - 语音：`eve`、`ara`、`rex`、`sal`、`leo`、`una` - 默认语音：`eve` - 格式：`mp3`、`wav`、`pcm`、`mulaw`、`alaw` - 语言：BCP-47 代码或 `auto` - - 速度：提供商原生速度覆盖 - - 不支持原生 Opus 语音留言格式 + - 语速：提供商原生语速覆盖 + - 不支持原生 Opus 语音备注格式 要将 xAI 用作默认 TTS 提供商： @@ -241,25 +243,24 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、 ``` - OpenClaw 使用 xAI 的批量 `/v1/tts` 端点。xAI 也提供通过 WebSocket - 进行的流式 TTS，但 OpenClaw 语音提供商契约目前要求在投递回复前 - 获得完整的音频缓冲区。 + OpenClaw 使用 xAI 的批量 `/v1/tts` 端点。xAI 也通过 WebSocket + 提供流式 TTS，但 OpenClaw 语音提供商契约目前要求在交付回复前 + 获得完整音频缓冲区。 - 内置的 `xai` 插件通过 OpenClaw 的 - 媒体理解转写表面注册批量语音转文本。 + 内置 `xai` 插件通过 OpenClaw 的 + 媒体理解转录表面注册批量语音转文本。 - 默认模型：`grok-stt` - 端点：xAI REST `/v1/stt` - 输入路径：multipart 音频文件上传 - - 在 OpenClaw 中，只要入站音频转写使用 - `tools.media.audio`，就支持该功能，包括 Discord 语音渠道片段和 - 渠道音频附件 + - OpenClaw 中凡是入站音频转录使用 `tools.media.audio` 的地方都支持， + 包括 Discord 语音渠道片段和渠道音频附件 - 要强制将 xAI 用于入站音频转写： + 要强制 xAI 用于入站音频转录： ```json5 { @@ -279,22 +280,22 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、 } ``` - 语言可以通过共享音频媒体配置或按调用的转写请求提供。共享的 OpenClaw - 表面接受提示提示词，但 xAI REST STT 集成只转发文件、模型和语言， - 因为这些可以清晰映射到当前公开的 xAI 端点。 + 语言可以通过共享音频媒体配置或逐次调用的转录请求提供。共享的 OpenClaw + 表面接受提示词提示，但 xAI REST STT 集成只转发文件、模型和 + 语言，因为这些可以清晰映射到当前公开的 xAI 端点。 - 内置的 `xai` 插件还为实时语音通话音频注册了实时转写提供商。 + 内置 `xai` 插件还为实时语音通话音频注册了实时转录提供商。 - 端点：xAI WebSocket `wss://api.x.ai/v1/stt` - 默认编码：`mulaw` - 默认采样率：`8000` - 默认端点检测：`800ms` - - 临时转写结果：默认启用 + - 临时转录：默认启用 - Voice Call 的 Twilio 媒体流会发送 G.711 µ-law 音频帧，因此 + Voice Call 的 Twilio 媒体流发送 G.711 µ-law 音频帧，因此 xAI 提供商可以直接转发这些帧，无需转码： ```json5 @@ -321,14 +322,14 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、 } ``` - 提供商自有配置位于 + Provider 拥有的配置位于 `plugins.entries.voice-call.config.streaming.providers.xai` 下。支持的 - 键为 `apiKey`、`baseUrl`、`sampleRate`、`encoding`（`pcm`、`mulaw` 或 + 键名包括 `apiKey`、`baseUrl`、`sampleRate`、`encoding`（`pcm`、`mulaw` 或 `alaw`）、`interimResults`、`endpointingMs` 和 `language`。 - 此流式传输提供商用于语音通话的实时转录路径。 - Discord 语音目前会录制短片段，并改用批量 + 这个流式 provider 用于 Voice Call 的实时转录路径。 + Discord 语音目前会录制短片段，并改用批处理 `tools.media.audio` 转录路径。 @@ -340,14 +341,15 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、 配置路径：`plugins.entries.xai.config.xSearch` - | 键 | 类型 | 默认值 | 描述 | + | 键名 | 类型 | 默认值 | 描述 | | ------------------ | ------- | ------------------ | ------------------------------------ | - | `enabled` | boolean | — | 启用或停用 x_search | - | `model` | string | `grok-4-1-fast` | 用于 x_search 请求的模型 | - | `inlineCitations` | boolean | — | 在结果中包含内联引用 | - | `maxTurns` | number | — | 最大对话轮数 | - | `timeoutSeconds` | number | — | 请求超时时间（秒） | - | `cacheTtlMinutes` | number | — | 缓存生存时间（分钟） | + | `enabled` | boolean | — | 启用或禁用 x_search | + | `model` | string | `grok-4-1-fast` | 用于 x_search 请求的模型 | + | `baseUrl` | string | — | xAI Responses 基础 URL 覆盖值 | + | `inlineCitations` | boolean | — | 在结果中包含内联引用 | + | `maxTurns` | number | — | 最大对话轮数 | + | `timeoutSeconds` | number | — | 请求超时时间（秒） | + | `cacheTtlMinutes` | number | — | 缓存存活时间（分钟） | ```json5 { @@ -358,6 +360,7 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、 xSearch: { enabled: true, model: "grok-4-1-fast", + baseUrl: "https://api.x.ai/v1", inlineCitations: true, }, }, @@ -370,16 +373,17 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、 - 内置 xAI 插件将 `code_execution` 作为 OpenClaw 工具公开，用于在 xAI 的沙箱环境中执行远程代码。 + 内置 xAI 插件将 `code_execution` 作为 OpenClaw 工具公开，用于在 xAI 的沙箱环境中进行 + 远程代码执行。 配置路径：`plugins.entries.xai.config.codeExecution` - | 键 | 类型 | 默认值 | 描述 | - | ----------------- | ------- | ------------------ | ---------------------------------------- | - | `enabled` | boolean | `true`（如果密钥可用） | 启用或停用代码执行 | - | `model` | string | `grok-4-1-fast` | 用于代码执行请求的模型 | - | `maxTurns` | number | — | 最大对话轮数 | - | `timeoutSeconds` | number | — | 请求超时时间（秒） | + | 键名 | 类型 | 默认值 | 描述 | + | ----------------- | ------- | ------------------------ | ------------------------------------ | + | `enabled` | boolean | `true`（如果键可用） | 启用或禁用代码执行 | + | `model` | string | `grok-4-1-fast` | 用于代码执行请求的模型 | + | `maxTurns` | number | — | 最大对话轮数 | + | `timeoutSeconds` | number | — | 请求超时时间（秒） | 这是远程 xAI 沙箱执行，不是本地 [`exec`](/zh-CN/tools/exec)。 @@ -405,20 +409,28 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、 - - 目前身份验证仅支持 API key。OpenClaw 尚无 xAI OAuth 或设备代码流程。 - - `grok-4.20-multi-agent-experimental-beta-0304` 不支持普通 xAI 提供商路径，因为它需要与标准 OpenClaw xAI 传输不同的上游 API 表面。 - - xAI Realtime 语音尚未注册为 OpenClaw 提供商。它需要与批量 STT 或流式转录不同的双向语音会话契约。 - - 在共享 `image_generate` 工具具备对应的跨提供商控制项之前，不会公开 xAI 图像 `quality`、图像 `mask` 以及额外的仅原生宽高比。 - + - 目前 Auth 仅支持 API key。OpenClaw 尚未提供 xAI OAuth 或设备代码流程。 + - `grok-4.20-multi-agent-experimental-beta-0304` 在常规 xAI provider 路径上不受支持，因为它需要的上游 API + 表面不同于标准 OpenClaw xAI 传输协议。 + - xAI Realtime 语音尚未注册为 OpenClaw provider。它需要一种不同于批处理 STT 或 + 流式转录的双向语音会话契约。 + - xAI 图像 `quality`、图像 `mask` 和额外的仅原生纵横比 + 在共享 `image_generate` 工具具备相应的跨 provider 控制项之前不会公开。 - OpenClaw 会在共享 runner 路径上自动应用 xAI 专用的工具 schema 和工具调用兼容性修复。 - 原生 xAI 请求默认使用 `tool_stream: true`。将 - `agents.defaults.models["xai/"].params.tool_stream` 设为 `false` 可停用它。 - - 内置 xAI 包装器会在发送原生 xAI 请求之前，移除不支持的严格工具 schema 标志和推理载荷键。 - - `web_search`、`x_search` 和 `code_execution` 作为 OpenClaw 工具公开。OpenClaw 会在每个工具请求中启用所需的具体 xAI 内置能力，而不是把所有原生工具附加到每一轮聊天。 - - `x_search` 和 `code_execution` 归内置 xAI 插件所有，而不是硬编码到核心模型运行时中。 + `agents.defaults.models["xai/"].params.tool_stream` 设为 `false` 可将其禁用。 + - 内置 xAI wrapper 会在发送原生 xAI 请求之前移除不受支持的严格工具 schema 标志和 + reasoning payload 键。 + - `web_search`、`x_search` 和 `code_execution` 会作为 OpenClaw + 工具公开。OpenClaw 会在每个工具请求中启用它所需的特定 xAI 内置能力，而不是将所有原生工具附加到每一轮聊天。 + - Grok `web_search` 读取 `plugins.entries.xai.config.webSearch.baseUrl`。 + `x_search` 读取 `plugins.entries.xai.config.xSearch.baseUrl`，然后 + 回退到 Grok Web 搜索基础 URL。 + - `x_search` 和 `code_execution` 由内置 xAI 插件拥有， + 而不是硬编码到核心模型运行时中。 - `code_execution` 是远程 xAI 沙箱执行，不是本地 [`exec`](/zh-CN/tools/exec)。 @@ -426,7 +438,9 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、 ## 实时测试 -xAI 媒体路径由单元测试和可选择启用的实时套件覆盖。实时命令会先从你的登录 shell 加载密钥，包括 `~/.profile`，然后再探测 `XAI_API_KEY`。 +xAI 媒体路径由单元测试和可选择启用的实时测试套件覆盖。实时 +命令会先从你的登录 shell（包括 `~/.profile`）加载密钥，然后再 +探测 `XAI_API_KEY`。 ```bash pnpm test extensions/xai @@ -434,19 +448,22 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_TEST_QUIET=1 pnpm test:live -- extensions/xai OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_TEST_QUIET=1 OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS=xai pnpm test:live -- test/image-generation.runtime.live.test.ts ``` -提供商专用实时文件会合成普通 TTS、适合电话场景的 PCM TTS，通过 xAI 批量 STT 转录音频，通过 xAI 实时 STT 流式传输同一份 PCM，生成文生图输出，并编辑一张参考图像。共享图像实时文件会通过 OpenClaw 的运行时选择、回退、归一化和媒体附件路径验证同一个 xAI 提供商。 +provider 专用实时文件会合成常规 TTS、适合电话语音的 PCM +TTS，通过 xAI 批处理 STT 转录音频，通过 xAI +实时 STT 流式传输同一段 PCM，生成文生图输出，并编辑参考图像。共享图像实时文件会通过 OpenClaw 的 +运行时选择、回退、规范化和媒体附件路径验证同一个 xAI provider。 -## 相关内容 +## 相关 - 选择提供商、模型引用和故障转移行为。 + 选择 provider、模型引用和故障转移行为。 - 共享视频工具参数和提供商选择。 + 共享视频工具参数和 provider 选择。 - - 更广泛的提供商概览。 + + 更广泛的 provider 概览。 常见问题和修复方法。 diff --git a/docs/zh-CN/tools/gemini-search.md b/docs/zh-CN/tools/gemini-search.md index aad562242..f3021a200 100644 --- a/docs/zh-CN/tools/gemini-search.md +++ b/docs/zh-CN/tools/gemini-search.md @@ -1,22 +1,22 @@ --- read_when: - - 你希望将 Gemini 用于 `web_search` - - 你需要一个 `GEMINI_API_KEY` - - 你希望使用 Google Search grounding -summary: 通过 Google Search grounding 实现的 Gemini Web 搜索 + - 你想使用 Gemini 进行 web_search + - 你需要一个 GEMINI_API_KEY + - 你想要 Google Search grounding +summary: 使用 Google Search 作为依据的 Gemini 网页搜索 title: Gemini 搜索 x-i18n: - generated_at: "2026-04-23T21:08:00Z" - model: gpt-5.4 + generated_at: "2026-05-02T02:49:13Z" + model: gpt-5.5 provider: openai - source_hash: 0778ae326e23ea1bb719fdc694b2accc5a6651e08658a695d4d70e20fc5943a4 + source_hash: 5e36382dc6a4f9a30f12025cc81bb7ed4999e56a236fc85ee7a37444674bf798 source_path: tools/gemini-search.md - workflow: 15 + workflow: 16 --- OpenClaw 支持带有内置 -[Google Search grounding](https://ai.google.dev/gemini-api/docs/grounding) -的 Gemini 模型，它会返回由实时 Google 搜索结果支撑、带有引用的 AI 综合答案。 +[Google Search 依据增强](https://ai.google.dev/gemini-api/docs/grounding) +的 Gemini 模型，它会返回由实时 Google Search 结果支持并附带引用的 AI 综合生成答案。 ## 获取 API 密钥 @@ -26,7 +26,7 @@ OpenClaw 支持带有内置 API 密钥。 - 在 Gateway 网关环境中设置 `GEMINI_API_KEY`，或者通过以下方式配置： + 在 Gateway 网关环境中设置 `GEMINI_API_KEY`，或通过以下方式配置： ```bash openclaw configure --section web @@ -44,8 +44,9 @@ OpenClaw 支持带有内置 google: { config: { webSearch: { - apiKey: "AIza...", // 如果已设置 GEMINI_API_KEY，则可选 - model: "gemini-2.5-flash", // 默认值 + apiKey: "AIza...", // optional if GEMINI_API_KEY is set + baseUrl: "https://generativelanguage.googleapis.com/v1beta", // optional proxy/base URL override + model: "gemini-2.5-flash", // default }, }, }, @@ -61,42 +62,47 @@ OpenClaw 支持带有内置 } ``` -**环境变量替代方式：** 在 Gateway 网关环境中设置 `GEMINI_API_KEY`。 -对于 gateway 安装，请将其放到 `~/.openclaw/.env` 中。 +**环境替代方案：**在 Gateway 网关环境中设置 `GEMINI_API_KEY`。 +对于 gateway 安装，请将其放入 `~/.openclaw/.env`。 ## 工作原理 -与返回链接和摘要列表的传统搜索 providers 不同， -Gemini 使用 Google Search grounding 生成带有 -内联引用的 AI 综合答案。结果同时包含综合答案和源 +与返回链接和摘要列表的传统搜索提供商不同， +Gemini 使用 Google Search 依据增强来生成带有 +内联引用的 AI 综合答案。结果同时包含综合生成的答案和来源 URL。 -- 来自 Gemini grounding 的引用 URL 会自动从 Google - 重定向 URL 解析为直链 URL。 -- 重定向解析会在返回最终引用 URL 之前，先通过 SSRF 防护路径（HEAD + 重定向检查 + - http/https 验证）。 -- 重定向解析使用严格的 SSRF 默认值，因此指向 - 私有/内部目标的重定向会被阻止。 +- 来自 Gemini 依据增强的引用 URL 会自动从 Google + 重定向 URL 解析为直接 URL。 +- 重定向解析使用 SSRF 防护路径（HEAD + 重定向检查 + + http/https 验证），然后再返回最终引用 URL。 +- 重定向解析使用严格的 SSRF 默认设置，因此会阻止重定向到 + 私有/内部目标。 ## 支持的参数 Gemini 搜索支持 `query`。 -出于共享 `web_search` 兼容性，也接受 `count`，但 Gemini grounding -仍然返回一个带引用的综合答案，而不是 N 条结果的 +为兼容共享的 `web_search`，会接受 `count`，但 Gemini 依据增强 +仍然返回一个带引用的综合生成答案，而不是 N 个结果的 列表。 -不支持 provider 专用过滤器，例如 `country`、`language`、`freshness` 和 +不支持特定于提供商的过滤器，例如 `country`、`language`、`freshness` 和 `domain_filter`。 ## 模型选择 -默认模型是 `gemini-2.5-flash`（速度快且性价比高）。任何支持 grounding 的 Gemini +默认模型是 `gemini-2.5-flash`（快速且成本效益高）。任何支持依据增强的 Gemini 模型都可以通过 `plugins.entries.google.config.webSearch.model` 使用。 +## Base URL 覆盖 + +当 Gemini Web 搜索必须通过操作方代理或自定义的 Gemini 兼容端点路由时，设置 `plugins.entries.google.config.webSearch.baseUrl`。普通的 `https://generativelanguage.googleapis.com` 值会规范化为 +`https://generativelanguage.googleapis.com/v1beta`；自定义代理路径会在去除末尾斜杠后按提供的形式保留。 + ## 相关内容 -- [Web 搜索概览](/zh-CN/tools/web) —— 所有 providers 与自动检测 -- [Brave Search](/zh-CN/tools/brave-search) —— 带摘要的结构化结果 -- [Perplexity Search](/zh-CN/tools/perplexity-search) —— 结构化结果 + 内容提取 +- [Web Search 概览](/zh-CN/tools/web) -- 所有提供商和自动检测 +- [Brave Search](/zh-CN/tools/brave-search) -- 带摘要的结构化结果 +- [Perplexity Search](/zh-CN/tools/perplexity-search) -- 结构化结果 + 内容提取 diff --git a/docs/zh-CN/tools/grok-search.md b/docs/zh-CN/tools/grok-search.md index cea732574..7dc8d7e43 100644 --- a/docs/zh-CN/tools/grok-search.md +++ b/docs/zh-CN/tools/grok-search.md @@ -2,31 +2,31 @@ read_when: - 你想使用 Grok 进行 web_search - 你需要 XAI_API_KEY 才能进行网页搜索 -summary: 通过 xAI 基于网页检索的响应实现 Grok 网页搜索 +summary: 通过 xAI 基于 Web 事实的响应进行 Grok Web 搜索 title: Grok 搜索 x-i18n: - generated_at: "2026-05-02T01:59:39Z" + generated_at: "2026-05-02T02:49:05Z" model: gpt-5.5 provider: openai - source_hash: ab38ee8614ba4bab9a3bf91cb14d4565f1766513594fd2d1a280ff4b2fed1478 + source_hash: 7238be2b488ba285c948065f5c1deff21898409aa11bdaa9ec893274d0eadd4a source_path: tools/grok-search.md workflow: 16 --- -OpenClaw 支持将 Grok 作为 `web_search` 提供商，使用 xAI 基于网页的响应来生成由实时搜索结果和引用支撑的 AI 综合回答。 +OpenClaw 支持将 Grok 作为 `web_search` 提供商，使用 xAI 基于网页依据的响应生成由实时搜索结果支持并带有引用的 AI 合成答案。 -同一个 `XAI_API_KEY` 也可以为内置的 `x_search` 工具提供支持，用于搜索 X（前身为 Twitter）帖子。如果你将 key 存储在 `plugins.entries.xai.config.webSearch.apiKey` 下，OpenClaw 现在也会将它作为内置 xAI 模型提供商的备用值复用。 +同一个 `XAI_API_KEY` 也可以为内置的 `x_search` 工具提供支持，用于 X（原 Twitter）帖子搜索。如果你将密钥存储在 `plugins.entries.xai.config.webSearch.apiKey` 下，OpenClaw 现在也会将它作为内置 xAI 模型提供商的备用密钥复用。 -对于帖子级 X 指标，例如转帖、回复、书签或浏览量，优先使用带有确切帖子 URL 或状态 ID 的 `x_search`，而不是宽泛的搜索查询。 +对于帖子级 X 指标，例如转发、回复、书签或浏览量，请优先使用带有确切帖子 URL 或 status ID 的 `x_search`，而不是宽泛的搜索查询。 ## 新手引导和配置 -如果你在以下流程中选择 **Grok**： +如果你在以下过程中选择 **Grok**： - `openclaw onboard` - `openclaw configure --section web` -OpenClaw 可以显示一个单独的后续步骤，用同一个 `XAI_API_KEY` 启用 `x_search`。该后续步骤： +OpenClaw 可以显示一个单独的后续步骤，使用同一个 `XAI_API_KEY` 启用 `x_search`。该后续步骤： - 只会在你为 `web_search` 选择 Grok 后出现 - 不是单独的顶层网页搜索提供商选项 @@ -37,10 +37,10 @@ OpenClaw 可以显示一个单独的后续步骤，用同一个 `XAI_API_KEY` ## 获取 API key - + 从 [xAI](https://console.x.ai/) 获取 API key。 - + 在 Gateway 网关环境中设置 `XAI_API_KEY`，或通过以下命令配置： ```bash @@ -60,6 +60,7 @@ OpenClaw 可以显示一个单独的后续步骤，用同一个 `XAI_API_KEY` config: { webSearch: { apiKey: "xai-...", // optional if XAI_API_KEY is set + baseUrl: "https://api.x.ai/v1", // optional Responses API proxy/base URL override }, }, }, @@ -75,25 +76,29 @@ OpenClaw 可以显示一个单独的后续步骤，用同一个 `XAI_API_KEY` } ``` -**环境替代方案：**在 Gateway 网关环境中设置 `XAI_API_KEY`。 -对于 Gateway 网关安装，将它放在 `~/.openclaw/.env` 中。 +**环境替代方式：**在 Gateway 网关环境中设置 `XAI_API_KEY`。 +对于 Gateway 网关安装，请将它放在 `~/.openclaw/.env` 中。 ## 工作原理 -Grok 使用 xAI 基于网页的响应来综合带有行内引用的回答，类似于 Gemini 的 Google 搜索 grounding 方法。 +Grok 使用 xAI 基于网页依据的响应生成带有内联引用的答案，类似于 Gemini 的 Google Search grounding 方法。 ## 支持的参数 Grok 搜索支持 `query`。 -`count` 会被接受，以兼容共享的 `web_search`，但 Grok 仍会返回一个带引用的综合回答，而不是 N 条结果列表。 +`count` 会被接受，以兼容共享的 `web_search`，但 Grok 仍会返回一个带有引用的合成答案，而不是 N 条结果列表。 目前不支持提供商特定的过滤器。 -Grok 使用提供商特定的 60 秒默认超时时间，因为 xAI Responses 基于网页的搜索可能比共享的 `web_search` 默认时间运行更久。设置 `tools.web.search.timeoutSeconds` 可覆盖它。 +Grok 使用提供商特定的 60 秒默认超时，因为 xAI Responses 基于网页依据的搜索可能比共享的 `web_search` 默认值运行更久。设置 `tools.web.search.timeoutSeconds` 可以覆盖它。 + +## Base URL 覆盖 + +当 Grok 网页搜索应通过操作员代理或 xAI 兼容的 Responses 端点路由时，设置 `plugins.entries.xai.config.webSearch.baseUrl`。OpenClaw 会在去除尾随斜杠后向 `/responses` 发送请求。除非设置了 `plugins.entries.xai.config.xSearch.baseUrl`，否则 `x_search` 使用同一个 `webSearch.baseUrl` 作为备用值。 ## 相关内容 -- [网页搜索概览](/zh-CN/tools/web) -- 所有提供商和自动检测 -- [网页搜索中的 x_search](/zh-CN/tools/web#x_search) -- 通过 xAI 提供一等 X 搜索 -- [Gemini 搜索](/zh-CN/tools/gemini-search) -- 通过 Google grounding 提供 AI 综合回答 +- [Web Search 概览](/zh-CN/tools/web) -- 所有提供商和自动检测 +- [Web Search 中的 x_search](/zh-CN/tools/web#x_search) -- 通过 xAI 实现的一等 X 搜索 +- [Gemini Search](/zh-CN/tools/gemini-search) -- 通过 Google grounding 生成的 AI 合成答案 diff --git a/docs/zh-CN/tools/slash-commands.md b/docs/zh-CN/tools/slash-commands.md index f311daf81..6aa7b438f 100644 --- a/docs/zh-CN/tools/slash-commands.md +++ b/docs/zh-CN/tools/slash-commands.md @@ -3,20 +3,20 @@ read_when: - 使用或配置聊天命令 - 调试命令路由或权限 sidebarTitle: Slash commands -summary: 斜杠命令：文本与原生、配置和支持的命令 +summary: 斜杠命令：文本与原生形式、配置和支持的命令 title: 斜杠命令 x-i18n: - generated_at: "2026-05-01T10:03:13Z" + generated_at: "2026-05-02T02:49:01Z" model: gpt-5.5 provider: openai - source_hash: cfa4c8e294080e824b15f0b54842718f7913cf6d42b7edd4ca9695c3d4113924 + source_hash: 00a00619cc0eff25b81b475eab5b0b3d808bf067e6e004a491a90ec3982149b7 source_path: tools/slash-commands.md workflow: 16 --- -命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机 bash 聊天命令使用 `! `（`/bash ` 是别名）。 +命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机的 bash 聊天命令使用 `! `（`/bash ` 是其别名）。 -当对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍保留在本地：`/acp ...` 始终到达 OpenClaw ACP 命令处理器，并且只要该界面启用了命令处理，`/status` 和 `/unfocus` 就会保留在本地。 +当对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍保留在本地：`/acp ...` 始终到达 OpenClaw ACP 命令处理器；只要该表面的命令处理已启用，`/status` 和 `/unfocus` 也会保留在本地。 有两个相关系统： @@ -27,16 +27,16 @@ x-i18n: `/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。 - - 指令会在模型看到消息之前从消息中移除。 - - 在普通聊天消息中（不是仅包含指令的消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。 - - 在仅包含指令的消息中（消息只包含指令），它们会持久化到会话，并回复确认信息。 - - 指令只会应用于**已授权的发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的 allowlist；否则授权来自渠道 allowlist/配对以及 `commands.useAccessGroups`。未授权的发送者会看到指令被当作普通文本处理。 + - 指令会在模型看到消息前从消息中移除。 + - 在普通聊天消息（非纯指令消息）中，它们会被视为“行内提示”，并且**不会**持久化会话设置。 + - 在纯指令消息（消息只包含指令）中，它们会持久化到会话，并回复确认。 + - 指令只会应用于**已授权发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。未授权发送者的指令会被视为纯文本。 - - 仅限 allowlist/已授权的发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 + + 仅限允许列表内/已授权发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 - 它们会立即运行，在模型看到消息之前被移除，剩余文本继续走正常流程。 + 它们会立即运行，在模型看到消息前被移除，剩余文本会继续走正常流程。 @@ -69,19 +69,20 @@ x-i18n: ``` - 在聊天消息中启用 `/...` 解析。在没有原生命令的界面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你将它设为 `false`，文本命令仍然有效。 + 启用聊天消息中的 `/...` 解析。在没有原生命令的表面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你将此项设置为 `false`，文本命令仍然可用。 - 注册原生命令。Auto：对 Discord/Telegram 启用；对 Slack 关闭（直到你添加斜杠命令）；对没有原生支持的提供商会被忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。`false` 会在启动时清除 Discord/Telegram 上先前注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。 + 注册原生命令。Auto：对 Discord/Telegram 启用；对 Slack 关闭（直到你添加斜杠命令）；对不支持原生命令的提供商忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。`false` 会在启动时清除 Discord/Telegram 上先前注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。 +在 Discord 上，原生命令规范可以包含 `descriptionLocalizations`，OpenClaw 会将其发布为 Discord `description_localizations`，并纳入协调比较。 - 在支持时以原生方式注册 **skill** 命令。Auto：对 Discord/Telegram 启用；对 Slack 关闭（Slack 需要为每个 skill 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。 + 在支持时以原生方式注册 **Skills** 命令。Auto：对 Discord/Telegram 启用；对 Slack 关闭（Slack 要求为每个 Skills 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。 - 启用 `! ` 来运行主机 shell 命令（`/bash ` 是别名；需要 `tools.elevated` allowlist）。 + 启用 `! ` 以运行主机 shell 命令（`/bash ` 是别名；需要 `tools.elevated` 允许列表）。 - 控制 bash 等待多久后切换到后台模式（`0` 表示立即转到后台）。 + 控制 bash 在切换到后台模式前等待多久（`0` 表示立即后台运行）。 启用 `/config`（读取/写入 `openclaw.json`）。 @@ -90,31 +91,31 @@ x-i18n: 启用 `/mcp`（读取/写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。 - 启用 `/plugins`（插件发现/Status，以及安装 + 启用/禁用控制）。 + 启用 `/plugins`（插件发现/Status 以及安装 + 启用/禁用控件）。 启用 `/debug`（仅运行时覆盖）。 - 启用 `/restart` 以及 gateway 网关重启工具操作。 + 启用 `/restart` 以及 Gateway 网关重启工具操作。 - 为仅所有者可用的命令/工具界面设置显式所有者 allowlist。这是可以批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账号。它与 `commands.allowFrom` 以及私信配对访问是分开的。 + 为仅所有者命令/工具表面设置显式所有者允许列表。这是可以批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账号。它独立于 `commands.allowFrom`，也独立于私信配对访问。 - 按渠道设置：要求仅所有者命令在该界面上必须以**所有者身份**运行。当为 `true` 时，发送者必须匹配已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上持有内部 `operator.admin` scope。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**满足要求 —— 仅所有者命令会在该渠道上默认拒绝。如果你希望仅所有者命令只由 `ownerAllowFrom` 和标准命令 allowlist 守卫，请保持关闭。 + 按渠道设置：要求仅所有者命令必须以**所有者身份**在该表面运行。当为 `true` 时，发送者必须匹配已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上拥有内部 `operator.admin` 作用域。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**满足要求——仅所有者命令会在该渠道上默认关闭。如果你希望仅所有者命令只受 `ownerAllowFrom` 和标准命令允许列表保护，请保持此项关闭。 - 控制所有者 id 在系统提示中的显示方式。 + 控制所有者 ID 在系统提示中的显示方式。 - 可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC secret。 + 可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。 - 命令授权的按提供商 allowlist。配置后，它就是命令和指令的唯一授权来源（渠道 allowlist/配对和 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；特定提供商键会覆盖它。 + 用于命令授权的按提供商允许列表。配置后，它就是命令和指令唯一的授权来源（渠道允许列表/配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。 - 当未设置 `commands.allowFrom` 时，对命令强制执行 allowlist/策略。 + 在未设置 `commands.allowFrom` 时，对命令强制执行允许列表/策略。 ## 命令列表 @@ -122,89 +123,88 @@ x-i18n: 当前事实来源： - 核心内置命令来自 `src/auto-reply/commands-registry.shared.ts` -- 生成的停靠命令来自 `src/auto-reply/commands-registry.data.ts` -- 插件命令来自插件 `registerCommand()` 调用 -- 你的 gateway 网关上的实际可用性仍取决于配置标志、渠道界面，以及已安装/已启用的插件 +- 生成的 dock 命令来自 `src/auto-reply/commands-registry.data.ts` +- 插件命令来自插件的 `registerCommand()` 调用 +- 你 Gateway 网关上的实际可用性仍取决于配置标志、渠道表面以及已安装/已启用的插件 ### 核心内置命令 - `/new [model]` 启动新会话；`/reset` 是重置别名。 - - `/reset soft [message]` 保留当前 transcript，丢弃复用的 CLI 后端会话 id，并在原地重新运行启动/系统提示加载。 - - `/compact [instructions]` 压缩会话上下文。参见[压缩](/zh-CN/concepts/compaction)。 + - `/reset soft [message]` 保留当前转录记录，丢弃复用的 CLI 后端会话 ID，并在原地重新运行启动/系统提示加载。 + - `/compact [instructions]` 压缩会话上下文。参见 [Compaction](/zh-CN/concepts/compaction)。 - `/stop` 中止当前运行。 - `/session idle ` 和 `/session max-age ` 管理线程绑定过期时间。 - `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。 - - `/export-trajectory [path]` 请求 exec 批准，然后为当前会话导出 JSONL [轨迹包](/zh-CN/tools/trajectory)。当你需要一个 OpenClaw 会话的提示、工具和 transcript 时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：`/trajectory`。 + - `/export-trajectory [path]` 请求 exec 批准，然后为当前会话导出 JSONL [轨迹包](/zh-CN/tools/trajectory)。当你需要一个 OpenClaw 会话的提示、工具和转录时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：`/trajectory`。 - - - `/think ` 设置 thinking 级别。选项来自活动模型的提供商 profile；常见级别是 `off`、`minimal`、`low`、`medium` 和 `high`，只有受支持的地方才有 `xhigh`、`adaptive`、`max` 等自定义级别，或二元 `on`。别名：`/thinking`、`/t`。 + + - `/think ` 设置思考级别。选项来自活动模型的提供商配置文件；常见级别包括 `off`、`minimal`、`low`、`medium` 和 `high`，而 `xhigh`、`adaptive`、`max` 等自定义级别或二进制 `on` 只在受支持的位置可用。别名：`/thinking`、`/t`。 - `/verbose on|off|full` 切换详细输出。别名：`/v`。 - `/trace on|off` 切换当前会话的插件 trace 输出。 - - `/fast [status|on|off]` 显示或设置 fast 模式。 - - `/reasoning [on|off|stream]` 切换 reasoning 可见性。别名：`/reason`。 - - `/elevated [on|off|ask|full]` 切换 elevated 模式。别名：`/elev`。 + - `/fast [status|on|off]` 显示或设置快速模式。 + - `/reasoning [on|off|stream]` 切换推理可见性。别名：`/reason`。 + - `/elevated [on|off|ask|full]` 切换提升模式。别名：`/elev`。 - `/exec host= security= ask= node=` 显示或设置 exec 默认值。 - `/model [name|#|status]` 显示或设置模型。 - - `/models [provider] [page] [limit=|size=|all]` 列出已配置/有可用凭证的提供商，或列出某个提供商的模型；添加 `all` 可浏览该提供商的完整目录。 - - `/queue ` 管理队列行为（`steer`、旧版 `queue`、`followup`、`collect`、`steer-backlog`、`interrupt`），以及 `debounce:0.5s cap:25 drop:summarize` 等选项；`/queue default` 或 `/queue reset` 会清除会话覆盖。参见[命令队列](/zh-CN/concepts/queue)和 [Steering queue](/zh-CN/concepts/queue-steering)。 + - `/models [provider] [page] [limit=|size=|all]` 列出已配置/可用凭证的提供商，或某个提供商的模型；添加 `all` 可浏览该提供商的完整目录。 + - `/queue ` 管理队列行为（`steer`、旧版 `queue`、`followup`、`collect`、`steer-backlog`、`interrupt`）以及 `debounce:0.5s cap:25 drop:summarize` 等选项；`/queue default` 或 `/queue reset` 会清除会话覆盖。参见 [命令队列](/zh-CN/concepts/queue) 和 [Steering queue](/zh-CN/concepts/queue-steering)。 - `/help` 显示简短帮助摘要。 - `/commands` 显示生成的命令目录。 - - `/tools [compact|verbose]` 显示当前智能体现在可以使用什么。 - - `/status` 显示执行/运行时 Status，包括 `Execution`/`Runtime` 标签以及可用时的提供商用量/配额。 - - `/diagnostics [note]` 是针对 Gateway 网关 bug 和 Codex harness 运行的仅所有者支持报告流程。它每次都会在运行 `openclaw gateway diagnostics export --json` 之前请求明确的 exec 批准；不要用允许全部的规则批准诊断。批准后，它会发送一份可粘贴的报告，其中包含本地包路径、manifest 摘要、隐私说明和相关会话 id。在群聊中，批准提示和报告会私下发送给所有者。当活动会话使用 OpenAI Codex harness 时，同一批准也会将相关 Codex 反馈发送到 OpenAI 服务器，并且完成后的回复会列出 OpenClaw 会话 id、Codex thread id 和 `codex resume ` 命令。参见[诊断导出](/zh-CN/gateway/diagnostics)。 + - `/tools [compact|verbose]` 显示当前智能体现在可以使用的内容。 + - `/status` 显示执行/运行时 Status，包括可用时的 `Execution`/`Runtime` 标签以及提供商用量/配额。 + - `/diagnostics [note]` 是 Gateway 网关 bug 和 Codex harness 运行的仅所有者支持报告流程。它每次都会在运行 `openclaw gateway diagnostics export --json` 前请求明确的 exec 批准；不要使用允许所有的规则批准诊断。批准后，它会发送一份可粘贴的报告，其中包含本地包路径、清单摘要、隐私说明和相关会话 ID。在群聊中，批准提示和报告会私下发送给所有者。当活动会话使用 OpenAI Codex harness 时，同一个批准也会将相关 Codex 反馈发送到 OpenAI 服务器，完成后的回复会列出 OpenClaw 会话 ID、Codex 线程 ID 和 `codex resume ` 命令。参见 [诊断导出](/zh-CN/gateway/diagnostics)。 - `/crestodian ` 从所有者私信运行 Crestodian 设置和修复助手。 - - `/tasks` 列出当前会话的活动/近期后台任务。 - - `/context [list|detail|json]` 解释上下文如何组装。 - - `/whoami` 显示你的发送者 id。别名：`/id`。 + - `/tasks` 列出当前会话的活动/最近后台任务。 + - `/context [list|detail|json]` 说明上下文如何组装。 + - `/whoami` 显示你的发送者 ID。别名：`/id`。 - `/usage off|tokens|full|cost` 控制每条回复的用量页脚，或打印本地成本摘要。 - - - `/skill [input]` 按名称运行一个 skill。 - - `/allowlist [list|add|remove] ...` 管理 allowlist 条目。仅文本。 + + - `/skill [input]` 按名称运行一个 Skills。 + - `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。 - `/approve ` 解决 exec 批准提示。 - - `/btw ` 提出一个旁支问题，不改变未来会话上下文。参见 [BTW](/zh-CN/tools/btw)。 + - `/btw ` 提出一个旁路问题，而不会更改未来会话上下文。参见 [BTW](/zh-CN/tools/btw)。 - - - `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的 sub-agent 运行。 + + - `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。 - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。 - - `/focus ` 将当前 Discord 线程或 Telegram 话题/对话绑定到会话目标。 + - `/focus ` 将当前 Discord 线程或 Telegram 主题/对话绑定到会话目标。 - `/unfocus` 移除当前绑定。 - `/agents` 列出当前会话的线程绑定智能体。 - - `/kill ` 中止一个或所有正在运行的 sub-agent。 - - `/steer ` 向正在运行的 sub-agent 发送 steering。别名：`/tell`。 + - `/kill ` 中止一个或所有正在运行的子智能体。 + - `/steer ` 向正在运行的子智能体发送 steering。别名：`/tell`。 - - - `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅限所有者。需要 `commands.config: true`。 - - `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅限所有者。需要 `commands.mcp: true`。 - - `/plugins list|inspect|show|get|install|enable|disable` 检查或变更插件状态。`/plugin` 是别名。写入仅限所有者。需要 `commands.plugins: true`。 - - `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅限所有者。需要 `commands.debug: true`。 - - `/restart` 在启用时重启 OpenClaw。默认：已启用；设置 `commands.restart: false` 可将其禁用。 - - `/send on|off|inherit` 设置发送策略。仅限所有者。 + + - `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅所有者可用。需要 `commands.config: true`。 + - `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅所有者可用。需要 `commands.mcp: true`。 + - `/plugins list|inspect|show|get|install|enable|disable` 检查或更改插件状态。`/plugin` 是别名。写入仅所有者可用。需要 `commands.plugins: true`。 + - `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅所有者可用。需要 `commands.debug: true`。 + - `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用它。 + - `/send on|off|inherit` 设置发送策略。仅所有者可用。 - `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` 控制 TTS。参见 [TTS](/zh-CN/tools/tts)。 - `/activation mention|always` 设置群组激活模式。 - `/bash ` 运行主机 shell 命令。仅文本。别名：`! `。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。 - - `!poll [sessionId]` 检查后台 bash 作业。 - - `!stop [sessionId]` 停止后台 bash 作业。 + - `!poll [sessionId]` 检查后台 bash 任务。 + - `!stop [sessionId]` 停止后台 bash 任务。 ### 生成的 dock 命令 -Dock 命令会将当前会话的回复路由切换到另一个已链接的 -渠道。设置、示例和故障排除请参见 [渠道 docking](/zh-CN/concepts/channel-docking)。 +Dock 命令会将当前会话的回复路由切换到另一个已关联的渠道。设置、示例和故障排除见[渠道 dock](/zh-CN/concepts/channel-docking)。 Dock 命令由支持原生命令的渠道插件生成。当前内置集合： @@ -213,23 +213,23 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合： - `/dock-slack`（别名：`/dock_slack`） - `/dock-telegram`（别名：`/dock_telegram`） -在直接聊天中使用 dock 命令，将当前会话的回复路由切换到另一个已链接的渠道。智能体会保留同一个会话上下文，但该会话之后的回复会发送到选定的渠道对端。 +在直接聊天中使用 dock 命令，将当前会话的回复路由切换到另一个已关联的渠道。智能体保持相同的会话上下文，但该会话之后的回复会发送到所选的渠道对端。 -Dock 命令需要 `session.identityLinks`。来源发送者和目标对端必须位于同一个身份组中，例如 `["telegram:123", "discord:456"]`。如果 ID 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活动会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未链接到 Discord 对端，该命令会回复设置提示，而不是落入普通聊天。 +Dock 命令需要 `session.identityLinks`。来源发送者和目标对端必须位于同一个身份组中，例如 `["telegram:123", "discord:456"]`。如果 id 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活动会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未关联到 Discord 对端，该命令会回复设置提示，而不是落入普通聊天。 -Docking 只会更改活动会话路由。它不会创建渠道账户、授予访问权限、绕过渠道允许列表，也不会把转录历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或另一个生成的 dock 命令再次切换路由。 +Dock 只会更改活动会话路由。它不会创建渠道账号、授予访问权限、绕过渠道允许列表，或将转录历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或另一个生成的 dock 命令再次切换路由。 ### 内置插件命令 -内置插件可以添加更多斜杠命令。此仓库中当前的内置命令： +内置插件可以添加更多斜杠命令。此仓库中的当前内置命令： - `/dreaming [on|off|status|help]` 切换记忆 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。 -- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见 [配对](/zh-CN/channels/pairing)。 -- `/phone status|arm [duration]|disarm` 临时授权高风险手机节点命令。 +- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见[配对](/zh-CN/channels/pairing)。 +- `/phone status|arm [duration]|disarm` 临时武装高风险手机节点命令。 - `/voice status|list [limit]|set ` 管理 Talk 语音配置。在 Discord 上，原生命令名称是 `/talkvoice`。 - `/card ...` 发送 LINE 富卡片预设。参见 [LINE](/zh-CN/channels/line)。 - `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` 检查并控制内置 Codex 应用服务器 harness。参见 [Codex harness](/zh-CN/plugins/codex-harness)。 -- 仅 QQBot 命令： +- 仅 QQBot 的命令： - `/bot-ping` - `/bot-version` - `/bot-help` @@ -238,91 +238,92 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访 ### 动态 skill 命令 -用户可调用的 Skills 也会作为斜杠命令暴露： +用户可调用的 Skills 也会作为斜杠命令公开： -- `/skill [input]` 始终可作为通用入口点使用。 -- 当 skill/插件注册时，skills 也可能以 `/prose` 这样的直接命令形式出现。 +- `/skill [input]` 始终可用，作为通用入口点。 +- 当 skill/插件注册直接命令时，Skills 也可能显示为 `/prose` 这样的直接命令。 - 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 +- 命令规格可以为支持本地化描述的原生界面提供 `descriptionLocalizations`，包括 Discord。 - - 命令接受命令和参数之间可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 + - 命令和参数之间可接受可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 - `/new ` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配，文本会被视为消息正文。 - - 如需完整的提供商使用情况明细，请使用 `openclaw status --usage`。 + - 要查看完整提供商用量明细，请使用 `openclaw status --usage`。 - `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。 - - 在多账户渠道中，面向配置目标的 `/allowlist --account ` 和 `/config set channels..accounts....` 也会遵循目标账户的 `configWrites`。 - - `/usage` 控制每条回复的用量页脚；`/usage cost` 从 OpenClaw 会话日志打印本地成本摘要。 - - `/restart` 默认启用；设置 `commands.restart: false` 可将其禁用。 + - 在多账号渠道中，面向配置的 `/allowlist --account ` 和 `/config set channels..accounts....` 也遵循目标账号的 `configWrites`。 + - `/usage` 控制每条回复的用量页脚；`/usage cost` 会从 OpenClaw 会话日志打印本地成本摘要。 + - `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。 - `/plugins install ` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包、`git:` 或 `clawhub:`。 - `/plugins enable|disable` 会更新插件配置，并可能提示重启。 - - 仅 Discord 原生命令：`/vc join|leave|status` 控制语音渠道（不可作为文本使用）。`join` 需要 guild 和已选择的语音/舞台渠道。需要 `channels.discord.voice` 和原生命令。 - - Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要启用有效线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。 + - 仅 Discord 的原生命令：`/vc join|leave|status` 控制语音渠道（不能作为文本使用）。`join` 需要一个 guild 和已选择的语音/舞台渠道。需要 `channels.discord.voice` 和原生命令。 + - Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要启用有效的线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。 - ACP 命令参考和运行时行为：[ACP 智能体](/zh-CN/tools/acp-agents)。 - `/verbose` 用于调试和提供额外可见性；正常使用时保持**关闭**。 - - `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace/debug 行，并保持普通 verbose 工具噪声关闭。 - - `/fast on|off` 会持久化会话覆盖。使用会话 UI 的 `inherit` 选项清除它，并回退到配置默认值。 - - `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射到 `service_tier=priority`，而直接的公共 Anthropic 请求（包括发送到 `api.anthropic.com` 的 OAuth 认证流量）会将其映射到 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。 + - `/trace` 比 `/verbose` 范围更窄：它只显示插件拥有的 trace/debug 行，并保持普通详细工具噪声关闭。 + - `/fast on|off` 会持久化会话覆盖。使用会话 UI 的 `inherit` 选项清除它并回退到配置默认值。 + - `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射到 `service_tier=priority`，而直接的公共 Anthropic 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，会将其映射到 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。 - 相关时仍会显示工具失败摘要，但详细失败文本只会在 `/verbose` 为 `on` 或 `full` 时包含。 - - `/reasoning`、`/verbose` 和 `/trace` 在群组设置中有风险：它们可能暴露你无意公开的内部推理、工具输出或插件诊断信息。建议保持关闭，尤其是在群聊中。 + - `/reasoning`、`/verbose` 和 `/trace` 在群组环境中有风险：它们可能暴露你无意公开的内部推理、工具输出或插件诊断。建议保持关闭，尤其是在群聊中。 - `/model` 会立即持久化新的会话模型。 - 如果智能体处于空闲状态，下一次运行会立即使用它。 - - 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并只会在干净的重试点重启到新模型。 - - 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续重试机会或下一次用户回合。 - - 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回 Crestodian。这独立于消息渠道救援模式，并且不会授予远程配置权限。 + - 如果运行已经活动，OpenClaw 会将实时切换标记为待处理，并且只会在干净的重试点重启到新模型。 + - 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到之后的重试机会或下一次用户轮次。 + - 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回 Crestodian。这与消息渠道救援模式分开，并且不会授予远程配置权限。 - - **快速路径：** 来自允许列表发送者的仅命令消息会立即处理（绕过队列 + 模型）。 - - **群组提及门控：** 来自允许列表发送者的仅命令消息会绕过提及要求。 - - **内联快捷方式（仅限允许列表发送者）：** 某些命令嵌入普通消息时也能工作，并会在模型看到剩余文本前被剥离。 - - 示例：`hey /status` 触发 Status 回复，剩余文本继续走普通流程。 + - **快速路径：** 来自允许列表发送者的纯命令消息会立即处理（绕过队列 + 模型）。 + - **群组提及门控：** 来自允许列表发送者的纯命令消息会绕过提及要求。 + - **内联快捷方式（仅限允许列表发送者）：** 某些命令嵌入普通消息时也能工作，并会在模型看到剩余文本之前被剥离。 + - 示例：`hey /status` 触发状态回复，剩余文本继续走普通流程。 - 当前：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 - - 未授权的仅命令消息会被静默忽略，内联 `/...` token 会被视为纯文本。 + - 未授权的纯命令消息会被静默忽略，内联 `/...` token 会被视为纯文本。 - - **Skill 命令：** `user-invocable` Skills 会作为斜杠命令暴露。名称会清理为 `a-z0-9_`（最多 32 个字符）；冲突会获得数字后缀（例如 `_2`）。 + - **Skill 命令：** `user-invocable` Skills 会作为斜杠命令公开。名称会被规范化为 `a-z0-9_`（最多 32 个字符）；冲突会获得数字后缀（例如 `_2`）。 - `/skill [input]` 按名称运行 skill（当原生命令限制阻止为每个 skill 创建命令时很有用）。 - 默认情况下，skill 命令会作为普通请求转发给模型。 - Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性，无模型）。 - 示例：`/prose`（OpenProse 插件）— 参见 [OpenProse](/zh-CN/prose)。 - - **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必需参数时使用按钮菜单）。Telegram 和 Slack 会在命令支持选项且你省略参数时显示按钮菜单。动态选项会针对目标会话模型解析，因此模型特定选项（例如 `/think` 级别）会跟随该会话的 `/model` 覆盖。 + - **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必需参数时使用按钮菜单）。Telegram 和 Slack 在命令支持选择项且你省略参数时显示按钮菜单。动态选择项会根据目标会话模型解析，因此 `/think` 级别等模型特定选项会遵循该会话的 `/model` 覆盖。 ## `/tools` -`/tools` 回答的是运行时问题，而不是配置问题：**这个智能体现在在此对话中可以使用什么**。 +`/tools` 回答的是运行时问题，而不是配置问题：**这个智能体在当前对话中现在可以使用什么**。 -- 默认 `/tools` 很紧凑，并针对快速浏览优化。 +- 默认 `/tools` 很紧凑，并为快速扫描优化。 - `/tools verbose` 添加简短描述。 -- 支持参数的原生命令界面暴露同样的模式开关：`compact|verbose`。 +- 支持参数的原生命令界面会公开相同的模式开关：`compact|verbose`。 - 结果限定于会话范围，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。 -- `/tools` 包含运行时实际可达的工具，包括核心工具、已连接的插件工具和渠道拥有的工具。 +- `/tools` 包括运行时实际可达的工具，包括核心工具、已连接插件工具和渠道拥有的工具。 -如需编辑配置文件和覆盖，请使用 Control UI Tools 面板或配置/目录界面，而不是将 `/tools` 视为静态目录。 +要编辑 profile 和覆盖，请使用 Control UI Tools 面板或配置/catalog 界面，而不是把 `/tools` 当作静态 catalog。 -## 用量界面（何处显示什么） +## 用量界面（哪里显示什么） -- **提供商用量/配额**（示例：“Claude 剩余 80%”）在启用用量跟踪时会出现在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口规范化为“剩余百分比”；对于 MiniMax，只返回剩余量的百分比字段会在显示前取反，而 `model_remains` 响应会优先使用聊天模型条目和带模型标签的计划标签。 -- **Token/缓存行** 在 `/status` 中可能会在实时会话快照稀疏时回退到最新的转录用量条目。现有非零实时值仍然优先，转录回退还可以恢复活动运行时模型标签，以及在存储总量缺失或较小时恢复更大的面向提示词的总量。 -- **执行与运行时：** `/status` 对有效沙箱路径报告 `Execution`，并对实际运行会话的主体报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 后端或 ACP 后端。 -- **每条回复的 token/成本** 由 `/usage off|tokens|full` 控制（追加到普通回复）。 -- `/model status` 关注的是**模型/凭证/端点**，不是用量。 +- **提供商用量/配额**（示例：“Claude 剩余 80%”）会在启用用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口标准化为 `% left`；对于 MiniMax，仅剩余的百分比字段会在显示前反转，`model_remains` 响应优先使用聊天模型条目以及带模型标签的 plan 标签。 +- **Token/缓存行**在 `/status` 中可以在实时会话快照稀疏时回退到最新的转录用量条目。现有的非零实时值仍然优先，转录回退还可以恢复活动运行时模型标签，以及在存储总数缺失或更小时恢复更大的面向提示词的总数。 +- **执行 vs 运行时：** `/status` 会为有效的沙箱路径报告 `Execution`，并为实际运行会话的一方报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 后端或 ACP 后端。 +- **每条回复的 token/成本**由 `/usage off|tokens|full` 控制（追加到普通回复）。 +- `/model status` 关注的是**模型/认证/端点**，不是用量。 ## 模型选择（`/model`） -`/model` 作为指令实现。 +`/model` 实现为 directive。 示例： @@ -337,14 +338,14 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访 说明： -- `/model` 和 `/model list` 显示紧凑的编号选择器（模型家族 + 可用提供商）。 -- 在 Discord 上，`/model` 和 `/models` 会打开带有提供商和模型下拉菜单以及 Submit 步骤的交互式选择器。 -- `/model <#>` 从该选择器中选择（并在可能时优先使用当前提供商）。 -- `/model status` 显示详细视图，包括可用时已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。 +- `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型系列 + 可用提供商）。 +- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个提交步骤。 +- `/model <#>` 会从该选择器中选择（并在可能时优先使用当前提供商）。 +- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`，如果可用）。 -## Debug 覆盖 +## 调试覆盖 -`/debug` 允许你设置**仅运行时**的配置覆盖（内存中，不写入磁盘）。仅限所有者使用。默认禁用；使用 `commands.debug: true` 启用。 +`/debug` 允许你设置**仅运行时**配置覆盖（存于内存，而非磁盘）。仅限所有者。默认禁用；使用 `commands.debug: true` 启用。 示例： @@ -360,9 +361,9 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访 覆盖会立即应用到新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖并返回磁盘上的配置。 -## 插件 trace 输出 +## 插件跟踪输出 -`/trace` 允许你切换**会话范围的插件 trace/debug 行**，而不启用完整详细模式。 +`/trace` 允许你切换**会话范围的插件跟踪/调试行**，而无需开启完整详细模式。 示例： @@ -374,16 +375,16 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访 注意： -- 不带参数的 `/trace` 会显示当前会话的 trace 状态。 -- `/trace on` 为当前会话启用插件 trace 行。 +- 不带参数的 `/trace` 会显示当前会话的跟踪状态。 +- `/trace on` 会为当前会话启用插件跟踪行。 - `/trace off` 会再次禁用它们。 -- 插件 trace 行可以出现在 `/status` 中，也可以在正常的助手回复后作为后续诊断消息出现。 +- 插件跟踪行可以出现在 `/status` 中，也可以在普通助手回复后作为后续诊断消息出现。 - `/trace` 不会替代 `/debug`；`/debug` 仍然管理仅运行时的配置覆盖。 -- `/trace` 不会替代 `/verbose`；正常的详细工具/Status 输出仍然属于 `/verbose`。 +- `/trace` 不会替代 `/verbose`；普通详细工具/Status 输出仍然属于 `/verbose`。 ## 配置更新 -`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限所有者使用。默认禁用；使用 `commands.config: true` 启用。 +`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限所有者。默认禁用；使用 `commands.config: true` 启用。 示例： @@ -401,7 +402,7 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访 ## MCP 更新 -`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅限所有者使用。默认禁用；使用 `commands.mcp: true` 启用。 +`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅限所有者。默认禁用；使用 `commands.mcp: true` 启用。 示例： @@ -413,7 +414,7 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访 ``` -`/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。运行时适配器决定哪些传输协议实际可执行。 +`/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 所属的项目设置中。运行时适配器决定哪些传输协议实际可执行。 ## 插件更新 @@ -431,8 +432,8 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访 ``` -- `/plugins list` 和 `/plugins show` 会基于当前工作区和磁盘配置执行真实的插件发现。 -- `/plugins enable|disable` 只更新插件配置；它不会安装或卸载插件。 +- `/plugins list` 和 `/plugins show` 会针对当前工作区以及磁盘上的配置执行真实的插件发现。 +- `/plugins enable|disable` 只会更新插件配置；它不会安装或卸载插件。 - 启用/禁用更改后，请重启 Gateway 网关以应用它们。 @@ -441,35 +442,35 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访 - - **文本命令**在正常聊天会话中运行（私信共享 `main`，群组有自己的会话）。 + - **文本命令**会在普通聊天会话中运行（私信共享 `main`，群组有自己的会话）。 - **原生命令**使用隔离会话： - Discord：`agent::discord:slash:` - Slack：`agent::slack:slash:`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置） - - Telegram：`telegram:slash:`（通过 `CommandTargetSessionKey` 定位到聊天会话） - - **`/stop`** 定位到活动聊天会话，以便它可以中止当前运行。 + - Telegram：`telegram:slash:`（通过 `CommandTargetSessionKey` 定位聊天会话） + - **`/stop`** 会定位到活动聊天会话，因此它可以中止当前运行。 - 对于单个 `/openclaw` 风格命令，仍然支持 `channels.slack.slashCommand`。如果启用 `commands.native`，你必须为每个内置命令创建一个 Slack slash command（名称与 `/help` 相同）。Slack 的命令参数菜单以临时 Block Kit 按钮形式发送。 + `channels.slack.slashCommand` 仍支持单个 `/openclaw` 风格命令。如果启用 `commands.native`，你必须为每个内置命令创建一个 Slack slash command（名称与 `/help` 相同）。Slack 的命令参数菜单会以临时 Block Kit 按钮形式发送。 - Slack 原生例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然可用。 + Slack 原生例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然有效。 -## BTW 附带问题 +## BTW 旁路问题 -`/btw` 是关于当前会话的快速**附带问题**。 +`/btw` 是关于当前会话的快速**旁路问题**。 -不同于普通聊天： +与普通聊天不同： - 它使用当前会话作为背景上下文， - 它作为单独的**无工具**一次性调用运行， - 它不会改变未来的会话上下文， - 它不会写入转录历史， -- 它会作为实时附带结果发送，而不是普通的助手消息。 +- 它会作为实时旁路结果发送，而不是普通助手消息。 -当你希望在主任务继续进行时获得临时澄清，`/btw` 会很有用。 +这使得 `/btw` 在你想要临时澄清，同时让主任务继续进行时很有用。 示例： @@ -477,9 +478,9 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访 /btw what are we doing right now? ``` -参见 [BTW 附带问题](/zh-CN/tools/btw) 了解完整行为和客户端 UX 细节。 +请参阅 [BTW 旁路问题](/zh-CN/tools/btw)，了解完整行为和客户端 UX 细节。 -## 相关 +## 相关内容 - [创建 Skills](/zh-CN/tools/creating-skills) - [Skills](/zh-CN/tools/skills) diff --git a/docs/zh-CN/tools/web.md b/docs/zh-CN/tools/web.md index acd811924..2082e356f 100644 --- a/docs/zh-CN/tools/web.md +++ b/docs/zh-CN/tools/web.md @@ -1,45 +1,43 @@ --- read_when: - - 你想启用或配置 `web_search` - - 你想启用或配置 `x_search` + - 你想启用或配置 web_search + - 你想启用或配置 x_search - 你需要选择一个搜索提供商 - - 你想了解自动检测和提供商回退机制 + - 你想了解自动检测和提供商回退 sidebarTitle: Web Search -summary: '`web_search`、`x_search` 和 `web_fetch` —— 搜索 Web、搜索 X 帖子，或抓取页面内容' -title: Web 搜索 +summary: web_search、x_search 和 web_fetch -- 搜索网页、搜索 X 帖文，或获取页面内容 +title: 网页搜索 x-i18n: - generated_at: "2026-04-27T06:07:19Z" - model: gpt-5.4 + generated_at: "2026-05-02T02:49:54Z" + model: gpt-5.5 provider: openai - source_hash: 9f8233a33f0729c6413eda59c4ebc3338a1e398e8280eb12650197225ef8981e + source_hash: 4de24a2430bbdfb0926dcec9dc3b44cc3a0af07f06ff2926e486168eac3d76d0 source_path: tools/web.md - workflow: 15 + workflow: 16 --- -`web_search` 工具会使用你配置的提供商搜索 Web 并返回结果。结果会按查询缓存 15 分钟（可配置）。 +`web_search` 工具会使用你配置的提供商搜索网页并返回结果。结果会按查询缓存 15 分钟（可配置）。 -OpenClaw 还包含用于搜索 X（原 Twitter）帖子的 `x_search`，以及用于轻量抓取 URL 内容的 `web_fetch`。在当前阶段，`web_fetch` 保持本地执行，而 `web_search` 和 `x_search` 可以在底层使用 xAI Responses。 +OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于轻量 URL 抓取的 `web_fetch`。在此阶段，`web_fetch` 保持本地运行，而 `web_search` 和 `x_search` 底层可以使用 xAI Responses。 - `web_search` 是一个轻量级 HTTP 工具，不是浏览器自动化。对于 - 重度依赖 JS 的网站或需要登录的场景，请使用 [Web Browser](/zh-CN/tools/browser)。对于 - 抓取特定 URL，请使用 [Web Fetch](/zh-CN/tools/web-fetch)。 + `web_search` 是一个轻量 HTTP 工具，不是浏览器自动化。对于大量依赖 JS 的站点或登录场景，请使用[网页浏览器](/zh-CN/tools/browser)。要抓取特定 URL，请使用 [Web Fetch](/zh-CN/tools/web-fetch)。 ## 快速开始 - 选择一个提供商并完成所需设置。有些提供商不需要密钥，而有些则需要 API key。详情请参见下方各提供商页面。 + 选择一个提供商，并完成任何必需设置。有些提供商不需要密钥，而其他提供商使用 API key。详情请参阅下面的提供商页面。 ```bash openclaw configure --section web ``` - 这会保存提供商以及所需的凭证。对于基于 API 的提供商，你也可以设置环境变量（例如 `BRAVE_API_KEY`）并跳过此步骤。 + 这会存储提供商和任何所需凭证。你也可以设置一个环境变量（例如 `BRAVE_API_KEY`），并跳过面向 API 支持提供商的此步骤。 - - 现在智能体可以调用 `web_search`： + + 智能体现在可以调用 `web_search`： ```javascript await web_search({ query: "OpenClaw plugin SDK" }); @@ -58,72 +56,72 @@ OpenClaw 还包含用于搜索 X（原 Twitter）帖子的 `x_search`，以及 - 带摘要片段的结构化结果。支持 `llm-context` 模式、国家/语言过滤。提供免费层级。 + 带摘要的结构化结果。支持 `llm-context` 模式、国家/地区和语言过滤器。提供免费层级。 - 无密钥回退。无需 API key。基于非官方 HTML 集成。 + 免密钥后备方案。无需 API key。基于非官方 HTML 的集成。 - 神经搜索 + 关键词搜索，并支持内容提取（高亮、文本、摘要）。 + 带内容提取（高亮、文本、摘要）的神经网络 + 关键词搜索。 - 结构化结果。最适合与 `firecrawl_search` 和 `firecrawl_scrape` 配合使用，以进行深度提取。 + 结构化结果。最适合与 `firecrawl_search` 和 `firecrawl_scrape` 搭配用于深度提取。 - 通过 Google Search grounding 提供带引用的 AI 综合答案。 + 通过 Google Search grounding 提供带引用的 AI 合成答案。 - 通过 xAI Web grounding 提供带引用的 AI 综合答案。 + 通过 xAI web grounding 提供带引用的 AI 合成答案。 - 通过 Moonshot Web 搜索提供带引用的 AI 综合答案。 + 通过 Moonshot 网页搜索提供带引用的 AI 合成答案。 通过 MiniMax Coding Plan 搜索 API 提供结构化结果。 - 通过已登录的本地 Ollama 主机或托管的 Ollama API 进行搜索。 + 通过已登录的本地 Ollama 主机或托管的 Ollama API 搜索。 带内容提取控制和域名过滤的结构化结果。 - 自托管元搜索。无需 API key。聚合 Google、Bing、DuckDuckGo 等来源。 + 自托管元搜索。无需 API key。聚合 Google、Bing、DuckDuckGo 等。 - 带搜索深度、主题过滤的结构化结果，并支持 `tavily_extract` 进行 URL 提取。 + 带搜索深度、主题过滤和用于 URL 提取的 `tavily_extract` 的结构化结果。 ### 提供商对比 -| 提供商 | 结果样式 | 过滤器 | API key | +| 提供商 | 结果风格 | 过滤器 | API key | | ----------------------------------------- | -------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------- | -| [Brave](/zh-CN/tools/brave-search) | 结构化摘要片段 | 国家、语言、时间、`llm-context` 模式 | `BRAVE_API_KEY` | -| [DuckDuckGo](/zh-CN/tools/duckduckgo-search) | 结构化摘要片段 | -- | 无（免密钥） | -| [Exa](/zh-CN/tools/exa-search) | 结构化 + 提取内容 | 神经/关键词模式、日期、内容提取 | `EXA_API_KEY` | -| [Firecrawl](/zh-CN/tools/firecrawl) | 结构化摘要片段 | 通过 `firecrawl_search` 工具 | `FIRECRAWL_API_KEY` | -| [Gemini](/zh-CN/tools/gemini-search) | AI 综合答案 + 引用 | -- | `GEMINI_API_KEY` | -| [Grok](/zh-CN/tools/grok-search) | AI 综合答案 + 引用 | -- | `XAI_API_KEY` | -| [Kimi](/zh-CN/tools/kimi-search) | AI 综合答案 + 引用 | -- | `KIMI_API_KEY` / `MOONSHOT_API_KEY` | -| [MiniMax Search](/zh-CN/tools/minimax-search) | 结构化摘要片段 | 区域（`global` / `cn`） | `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` | -| [Ollama Web Search](/zh-CN/tools/ollama-search) | 结构化摘要片段 | -- | 已登录的本地主机无需；直接使用 `https://ollama.com` 搜索时需 `OLLAMA_API_KEY` | -| [Perplexity](/zh-CN/tools/perplexity-search) | 结构化摘要片段 | 国家、语言、时间、域名、内容限制 | `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` | -| [SearXNG](/zh-CN/tools/searxng-search) | 结构化摘要片段 | 分类、语言 | 无（自托管） | -| [Tavily](/zh-CN/tools/tavily) | 结构化摘要片段 | 通过 `tavily_search` 工具 | `TAVILY_API_KEY` | +| [Brave](/zh-CN/tools/brave-search) | 结构化摘要 | 国家/地区、语言、时间、`llm-context` 模式 | `BRAVE_API_KEY` | +| [DuckDuckGo](/zh-CN/tools/duckduckgo-search) | 结构化摘要 | -- | 无（免密钥） | +| [Exa](/zh-CN/tools/exa-search) | 结构化 + 已提取内容 | 神经网络/关键词模式、日期、内容提取 | `EXA_API_KEY` | +| [Firecrawl](/zh-CN/tools/firecrawl) | 结构化摘要 | 通过 `firecrawl_search` 工具 | `FIRECRAWL_API_KEY` | +| [Gemini](/zh-CN/tools/gemini-search) | AI 合成 + 引用 | -- | `GEMINI_API_KEY` | +| [Grok](/zh-CN/tools/grok-search) | AI 合成 + 引用 | -- | `XAI_API_KEY` | +| [Kimi](/zh-CN/tools/kimi-search) | AI 合成 + 引用 | -- | `KIMI_API_KEY` / `MOONSHOT_API_KEY` | +| [MiniMax Search](/zh-CN/tools/minimax-search) | 结构化摘要 | 地区（`global` / `cn`） | `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` | +| [Ollama Web Search](/zh-CN/tools/ollama-search) | 结构化摘要 | -- | 已登录的本地主机无需；直接 `https://ollama.com` 搜索使用 `OLLAMA_API_KEY` | +| [Perplexity](/zh-CN/tools/perplexity-search) | 结构化摘要 | 国家/地区、语言、时间、域名、内容限制 | `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` | +| [SearXNG](/zh-CN/tools/searxng-search) | 结构化摘要 | 类别、语言 | 无（自托管） | +| [Tavily](/zh-CN/tools/tavily) | 结构化摘要 | 通过 `tavily_search` 工具 | `TAVILY_API_KEY` | ## 自动检测 -## 原生 OpenAI Web 搜索 +## 原生 OpenAI 网页搜索 -当启用了 OpenClaw Web 搜索且未固定托管提供商时，直接的 OpenAI Responses 模型会自动使用 OpenAI 托管的 `web_search` 工具。这是内置 OpenAI 插件中的提供商自有行为，仅适用于原生 OpenAI API 流量，不适用于 OpenAI 兼容代理 base URL 或 Azure 路由。将 `tools.web.search.provider` 设置为其他提供商（例如 `brave`），可让 OpenAI 模型继续使用托管的 `web_search` 工具；将 `tools.web.search.enabled: false` 则会同时禁用托管搜索和原生 OpenAI 搜索。 +当 OpenClaw 网页搜索已启用且未固定托管提供商时，直接 OpenAI Responses 模型会自动使用 OpenAI 托管的 `web_search` 工具。这是内置 OpenAI 插件中由提供商拥有的行为，并且只适用于原生 OpenAI API 流量，不适用于 OpenAI 兼容代理 base URL 或 Azure 路由。将 `tools.web.search.provider` 设置为另一个提供商（例如 `brave`），即可为 OpenAI 模型保留托管的 `web_search` 工具；或设置 `tools.web.search.enabled: false` 以同时禁用托管搜索和原生 OpenAI 搜索。 -## 原生 Codex Web 搜索 +## 原生 Codex 网页搜索 -支持 Codex 的模型可以选择使用提供商原生的 Responses `web_search` 工具，而不是 OpenClaw 托管的 `web_search` 函数。 +支持 Codex 的模型可以选择使用提供商原生 Responses `web_search` 工具，而不是 OpenClaw 的托管 `web_search` 函数。 -- 在 `tools.web.search.openaiCodex` 下配置 -- 它仅对支持 Codex 的模型生效（`openai-codex/*` 或使用 `api: "openai-codex-responses"` 的提供商） +- 在 `tools.web.search.openaiCodex` 下配置它 +- 它只会为支持 Codex 的模型激活（`openai-codex/*` 或使用 `api: "openai-codex-responses"` 的提供商） - 托管的 `web_search` 仍适用于非 Codex 模型 - `mode: "cached"` 是默认且推荐的设置 - `tools.web.search.enabled: false` 会同时禁用托管搜索和原生搜索 @@ -151,15 +149,15 @@ OpenClaw 还包含用于搜索 X（原 Twitter）帖子的 `x_search`，以及 } ``` -如果启用了原生 Codex 搜索，但当前模型并不支持 Codex，OpenClaw 会保留正常的托管 `web_search` 行为。 +如果原生 Codex 搜索已启用，但当前模型不支持 Codex，OpenClaw 会保持普通托管 `web_search` 行为。 -## 设置 Web 搜索 +## 设置网页搜索 文档和设置流程中的提供商列表按字母顺序排列。自动检测使用单独的优先级顺序。 如果未设置 `provider`，OpenClaw 会按以下顺序检查提供商，并使用第一个已就绪的提供商： -优先检查基于 API 的提供商： +首先是 API 支持的提供商： 1. **Brave** -- `BRAVE_API_KEY` 或 `plugins.entries.brave.config.webSearch.apiKey`（顺序 10） 2. **MiniMax Search** -- `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` 或 `plugins.entries.minimax.config.webSearch.apiKey`（顺序 15） @@ -171,21 +169,16 @@ OpenClaw 还包含用于搜索 X（原 Twitter）帖子的 `x_search`，以及 8. **Exa** -- `EXA_API_KEY` 或 `plugins.entries.exa.config.webSearch.apiKey`（顺序 65） 9. **Tavily** -- `TAVILY_API_KEY` 或 `plugins.entries.tavily.config.webSearch.apiKey`（顺序 70） -然后是免密钥回退： +之后是免密钥后备方案： -10. **DuckDuckGo** -- 无需账户或 API key 的免密钥 HTML 回退（顺序 100） -11. **Ollama Web 搜索** -- 当你配置的本地 Ollama 主机可访问且已通过 `ollama signin` 登录时，可作为免密钥回退；如果主机需要，也可以复用 Ollama provider 的 bearer 认证；在配置了 `OLLAMA_API_KEY` 时，也可以直接调用 `https://ollama.com` 搜索（顺序 110） +10. **DuckDuckGo** -- 无需账户或 API key 的免密钥 HTML 后备方案（顺序 100） +11. **Ollama Web Search** -- 当你配置的本地 Ollama 主机可访问并通过 `ollama signin` 登录时，通过该主机提供免密钥后备方案；当主机需要时可复用 Ollama 提供商 bearer auth，并且在配置了 `OLLAMA_API_KEY` 时可调用直接 `https://ollama.com` 搜索（顺序 110） 12. **SearXNG** -- `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`（顺序 200） -如果未检测到任何提供商，它会回退到 Brave（你会收到缺少密钥的错误提示，要求你进行配置）。 +如果未检测到提供商，它会回退到 Brave（你会收到缺少密钥的错误，提示你配置一个）。 - 所有提供商密钥字段都支持 SecretRef 对象。位于 - `plugins.entries..config.webSearch.apiKey` 下的插件作用域 SecretRef - 可用于内置的基于 API 的 Web 搜索提供商，包括 Brave、Exa、Firecrawl、 - Gemini、Grok、Kimi、MiniMax、Perplexity 和 Tavily， - 无论该提供商是通过 `tools.web.search.provider` 显式选择， - 还是通过自动检测选中。在自动检测模式下，OpenClaw 只会解析已选提供商的密钥——未选中的 SecretRef 保持未激活，因此你可以同时配置多个提供商，而无需为未使用的提供商支付解析成本。 + 所有提供商密钥字段都支持 SecretRef 对象。对于内置的 API 支持网页搜索提供商，`plugins.entries..config.webSearch.apiKey` 下的插件作用域 SecretRef 会被解析，包括 Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax、Perplexity 和 Tavily，无论该提供商是通过 `tools.web.search.provider` 显式选择，还是通过自动检测选中。在自动检测模式下，OpenClaw 只解析所选提供商密钥 -- 未选中的 SecretRef 保持非活跃状态，因此你可以配置多个提供商，而无需为未使用的提供商支付解析成本。 ## 配置 @@ -195,8 +188,8 @@ OpenClaw 还包含用于搜索 X（原 Twitter）帖子的 `x_search`，以及 tools: { web: { search: { - enabled: true, // 默认：true - provider: "brave", // 或省略以使用自动检测 + enabled: true, // default: true + provider: "brave", // or omit for auto-detection maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, @@ -206,30 +199,28 @@ OpenClaw 还包含用于搜索 X（原 Twitter）帖子的 `x_search`，以及 } ``` -提供商特定配置（API key、base URL、模式）位于 -`plugins.entries..config.webSearch.*` 下。示例请参见各提供商页面。 +提供商特定配置（API key、base URL、模式）位于 `plugins.entries..config.webSearch.*` 下。示例请参阅提供商页面。 -`web_fetch` 的回退提供商选择是独立的： +`web_fetch` 后备提供商选择是独立的： -- 通过 `tools.web.fetch.provider` 选择 -- 或省略该字段，让 OpenClaw 从可用凭证中自动检测第一个已就绪的 web-fetch 提供商 -- 当前内置的 web-fetch 提供商是 Firecrawl，配置位于 - `plugins.entries.firecrawl.config.webFetch.*` +- 使用 `tools.web.fetch.provider` 选择它 +- 或省略该字段，让 OpenClaw 根据可用凭证自动检测第一个已就绪的 web-fetch 提供商 +- 目前内置的 web-fetch 提供商是 Firecrawl，配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下 -当你在 `openclaw onboard` 或 -`openclaw configure --section web` 中选择 **Kimi** 时，OpenClaw 还可以询问： +当你在 `openclaw onboard` 或 `openclaw configure --section web` 期间选择 **Kimi** 时，OpenClaw 还可以询问： - Moonshot API 区域（`https://api.moonshot.ai/v1` 或 `https://api.moonshot.cn/v1`） -- 默认 Kimi Web 搜索模型（默认是 `kimi-k2.6`） +- 默认 Kimi 网页搜索模型（默认值为 `kimi-k2.6`） -对于 `x_search`，请配置 `plugins.entries.xai.config.xSearch.*`。它使用与 Grok Web 搜索相同的 `XAI_API_KEY` 回退。 -旧版 `tools.web.x_search.*` 配置可通过 `openclaw doctor --fix` 自动迁移。 -当你在 `openclaw onboard` 或 `openclaw configure --section web` 中选择 Grok 时， -OpenClaw 还可以使用同一个密钥提供可选的 `x_search` 设置。 -这是 Grok 路径中的一个单独后续步骤，不是单独的顶级 -Web 搜索提供商选项。如果你选择了其他提供商，OpenClaw 不会显示 `x_search` 提示。 +对于 `x_search`，配置 `plugins.entries.xai.config.xSearch.*`。它使用与 Grok web 搜索相同的 `XAI_API_KEY` 回退。 +旧版 `tools.web.x_search.*` 配置会由 `openclaw doctor --fix` 自动迁移。 +当你在 `openclaw onboard` 或 `openclaw configure --section web` 期间选择 Grok 时， +OpenClaw 也可以使用同一个密钥提供可选的 `x_search` 设置。 +这是 Grok 路径中的一个独立后续步骤，不是一个独立的顶层 +web 搜索提供商选项。如果你选择其他提供商，OpenClaw 不会 +显示 `x_search` 提示。 -### 存储 API key +### 存储 API 密钥 @@ -253,61 +244,62 @@ Web 搜索提供商选项。如果你选择了其他提供商，OpenClaw 不会 - 在 Gateway 网关 进程环境中设置提供商环境变量： + 在 Gateway 网关进程环境中设置提供商环境变量： ```bash export BRAVE_API_KEY="YOUR_KEY" ``` - 对于 Gateway 网关 安装，请将其放在 `~/.openclaw/.env` 中。 - 请参见 [环境变量](/zh-CN/help/faq#env-vars-and-env-loading)。 + 对于 Gateway 网关安装，请将它放在 `~/.openclaw/.env` 中。 + 参见[环境变量](/zh-CN/help/faq#env-vars-and-env-loading)。 ## 工具参数 -| 参数 | 说明 | +| 参数 | 描述 | | --------------------- | ----------------------------------------------------- | -| `query` | 搜索查询（必填） | -| `count` | 返回结果数（1-10，默认：5） | -| `country` | 2 位 ISO 国家代码（例如 `"US"`、`"DE"`） | -| `language` | ISO 639-1 语言代码（例如 `"en"`、`"de"`） | -| `search_lang` | 搜索语言代码（仅 Brave） | -| `freshness` | 时间过滤：`day`、`week`、`month` 或 `year` | -| `date_after` | 返回此日期之后的结果（YYYY-MM-DD） | -| `date_before` | 返回此日期之前的结果（YYYY-MM-DD） | -| `ui_lang` | UI 语言代码（仅 Brave） | -| `domain_filter` | 域名 allowlist/denylist 数组（仅 Perplexity） | -| `max_tokens` | 总内容预算，默认 25000（仅 Perplexity） | -| `max_tokens_per_page` | 每页 token 上限，默认 2048（仅 Perplexity） | +| `query` | 搜索查询（必填） | +| `count` | 要返回的结果数（1-10，默认值：5） | +| `country` | 2 字母 ISO 国家代码（例如 "US"、"DE"） | +| `language` | ISO 639-1 语言代码（例如 "en"、"de"） | +| `search_lang` | 搜索语言代码（仅 Brave） | +| `freshness` | 时间过滤器：`day`、`week`、`month` 或 `year` | +| `date_after` | 此日期之后的结果（YYYY-MM-DD） | +| `date_before` | 此日期之前的结果（YYYY-MM-DD） | +| `ui_lang` | UI 语言代码（仅 Brave） | +| `domain_filter` | 域名允许列表/拒绝列表数组（仅 Perplexity） | +| `max_tokens` | 总内容预算，默认值 25000（仅 Perplexity） | +| `max_tokens_per_page` | 每页 token 限制，默认值 2048（仅 Perplexity） | - 并非所有参数都适用于所有提供商。Brave 的 `llm-context` 模式 - 不接受 `ui_lang`、`freshness`、`date_after` 和 `date_before`。 - Gemini、Grok 和 Kimi 会返回一个带引用的综合答案。 - 它们接受 `count` 以兼容共享工具，但这不会改变 - grounding 答案的形状。 - 当你使用 Sonar/OpenRouter - 兼容路径（`plugins.entries.perplexity.config.webSearch.baseUrl` / - `model` 或 `OPENROUTER_API_KEY`）时，Perplexity 的行为也是如此。 - SearXNG 仅对受信任的私有网络或 loopback 主机接受 `http://`； - 公开的 SearXNG 端点必须使用 `https://`。 - Firecrawl 和 Tavily 仅通过 `web_search` - 支持 `query` 和 `count`——如需高级选项，请使用它们各自的专用工具。 + 并非所有参数都适用于所有提供商。Brave `llm-context` 模式 + 会拒绝 `ui_lang`、`freshness`、`date_after` 和 `date_before`。 + Gemini、Grok 和 Kimi 会返回一个带引用的合成答案。它们 + 接受 `count` 以兼容共享工具，但它不会改变有依据答案的形态。 + 当你使用 Sonar/OpenRouter 兼容路径（`plugins.entries.perplexity.config.webSearch.baseUrl` / + `model` 或 `OPENROUTER_API_KEY`）时，Perplexity 的行为相同。 + SearXNG 仅对受信任的专用网络或 loopback 主机接受 `http://`； + 公共 SearXNG 端点必须使用 `https://`。 + Firecrawl 和 Tavily 通过 `web_search` 仅支持 `query` 和 `count` + -- 如需高级选项，请使用它们的专用工具。 ## x_search `x_search` 使用 xAI 查询 X（原 Twitter）帖子，并返回 -带引用的 AI 综合答案。它接受自然语言查询和 -可选的结构化过滤器。OpenClaw 仅会在服务此工具调用的请求上启用内置 xAI `x_search` +带引用的 AI 合成答案。它接受自然语言查询和 +可选的结构化过滤器。OpenClaw 只会在服务此工具调用的请求中启用内置 xAI `x_search` 工具。 - xAI 文档说明 `x_search` 支持关键词搜索、语义搜索、用户 - 搜索和线程抓取。对于单条帖子的互动统计数据，例如转发、回复、收藏或浏览量，请优先对确切帖子 URL - 或状态 ID 进行定向查找。广泛的关键词搜索可能找到正确的帖子，但返回的单帖元数据会不够完整。一个好的模式是：先定位帖子，然后对该确切帖子运行第二次 `x_search` 查询。 + xAI 将 `x_search` 记录为支持关键词搜索、语义搜索、用户 + 搜索和线程获取。对于转发、回复、书签或浏览量等单帖互动统计， + 请优先对精确帖子 URL 或状态 ID 进行定向查找。 + 宽泛的关键词搜索可能找到正确帖子，但返回的单帖元数据可能不够 + 完整。一个好的模式是：先定位帖子，然后 + 运行第二次聚焦该精确帖子的 `x_search` 查询。 ### x_search 配置 @@ -321,13 +313,15 @@ Web 搜索提供商选项。如果你选择了其他提供商，OpenClaw 不会 xSearch: { enabled: true, model: "grok-4-1-fast-non-reasoning", + baseUrl: "https://api.x.ai/v1", // optional, overrides webSearch.baseUrl inlineCitations: false, maxTurns: 2, timeoutSeconds: 30, cacheTtlMinutes: 15, }, webSearch: { - apiKey: "xai-...", // 如果已设置 XAI_API_KEY，则可选 + apiKey: "xai-...", // optional if XAI_API_KEY is set + baseUrl: "https://api.x.ai/v1", // optional shared xAI Responses base URL }, }, }, @@ -336,17 +330,22 @@ Web 搜索提供商选项。如果你选择了其他提供商，OpenClaw 不会 } ``` +当设置了 `plugins.entries.xai.config.xSearch.baseUrl` 时， +`x_search` 会发布到 `/responses`。如果省略该字段， +它会回退到 `plugins.entries.xai.config.webSearch.baseUrl`，然后是 +旧版 `tools.web.search.grok.baseUrl`，最后是公共 xAI 端点。 + ### x_search 参数 -| 参数 | 说明 | -| ---------------------------- | ------------------------------------------------------ | -| `query` | 搜索查询（必填） | -| `allowed_x_handles` | 将结果限制为特定 X 账号 | -| `excluded_x_handles` | 排除特定 X 账号 | -| `from_date` | 仅包含该日期及之后的帖子（YYYY-MM-DD） | -| `to_date` | 仅包含该日期及之前的帖子（YYYY-MM-DD） | -| `enable_image_understanding` | 允许 xAI 检查匹配帖子附带的图片 | -| `enable_video_understanding` | 允许 xAI 检查匹配帖子附带的视频 | +| 参数 | 描述 | +| ---------------------------- | ----------------------------------------------------- | +| `query` | 搜索查询（必填） | +| `allowed_x_handles` | 将结果限制为特定 X handle | +| `excluded_x_handles` | 排除特定 X handle | +| `from_date` | 仅包含此日期当天或之后的帖子（YYYY-MM-DD） | +| `to_date` | 仅包含此日期当天或之前的帖子（YYYY-MM-DD） | +| `enable_image_understanding` | 让 xAI 检查匹配帖子附带的图片 | +| `enable_video_understanding` | 让 xAI 检查匹配帖子附带的视频 | ### x_search 示例 @@ -359,7 +358,7 @@ await x_search({ ``` ```javascript -// 单帖统计：尽可能使用确切的状态 URL 或状态 ID +// Per-post stats: use the exact status URL or status ID when possible await x_search({ query: "https://x.com/huntharo/status/1905678901234567890", }); @@ -368,45 +367,45 @@ await x_search({ ## 示例 ```javascript -// 基本搜索 +// Basic search await web_search({ query: "OpenClaw plugin SDK" }); -// 德语定向搜索 +// German-specific search await web_search({ query: "TV online schauen", country: "DE", language: "de" }); -// 最近结果（过去一周） +// Recent results (past week) await web_search({ query: "AI developments", freshness: "week" }); -// 日期范围 +// Date range await web_search({ query: "climate research", date_after: "2024-01-01", date_before: "2024-06-30", }); -// 域名过滤（仅 Perplexity） +// Domain filtering (Perplexity only) await web_search({ query: "product reviews", domain_filter: ["-reddit.com", "-pinterest.com"], }); ``` -## 工具配置档 +## 工具配置文件 -如果你使用工具配置档或 allowlist，请添加 `web_search`、`x_search` 或 `group:web`： +如果你使用工具配置文件或允许列表，请添加 `web_search`、`x_search` 或 `group:web`： ```json5 { tools: { allow: ["web_search", "x_search"], - // 或：allow: ["group:web"] （包含 web_search、x_search 和 web_fetch） + // or: allow: ["group:web"] (includes web_search, x_search, and web_fetch) }, } ``` -## 相关 +## 相关内容 -- [Web Fetch](/zh-CN/tools/web-fetch) -- 抓取 URL 并提取可读内容 -- [Web Browser](/zh-CN/tools/browser) -- 面向重度 JS 网站的完整浏览器自动化 +- [Web Fetch](/zh-CN/tools/web-fetch) -- 获取 URL 并提取可读内容 +- [Web Browser](/zh-CN/tools/browser) -- 面向 JS 密集型站点的完整浏览器自动化 - [Grok Search](/zh-CN/tools/grok-search) -- 将 Grok 用作 `web_search` 提供商 -- [Ollama Web Search](/zh-CN/tools/ollama-search) -- 通过你的 Ollama 主机进行免密钥 Web 搜索 +- [Ollama Web Search](/zh-CN/tools/ollama-search) -- 通过你的 Ollama 主机进行免密钥 web 搜索