openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-23 16:58:40 +00:00
parent 753ad24757
commit cfc5072ff8
2 changed files with 302 additions and 287 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

352
docs/zh-CN/plugins/manifest.md
View File

@ -1,65 +1,55 @@
---
read_when:
- 你正在构建一个 OpenClaw 插件
- 你需要发布插件配置 schema，或调试插件校验错误
- 你需要发布一个插件配置 schema，或调试插件校验错误
summary: 插件清单 + JSON schema 要求（严格配置校验）
title: 插件清单
x-i18n:
generated_at: "2026-04-23T07:42:11Z"
generated_at: "2026-04-23T16:56:50Z"
model: gpt-5.4
provider: openai
source_hash: d48810f604aa0c3ff8553528cfa4cb735d1d5e7a15b1bbca6152070d6c8f9cce
source_hash: e9e7bca47b076cc49080bd6921ef9d295c840e9a19c5271dbfea83d9882ea404
source_path: plugins/manifest.md
workflow: 15
---
# 插件清单（`openclaw.plugin.json`）
本页仅介绍 **原生 OpenClaw 插件清单**。
本页仅适用于 **OpenClaw 原生插件清单**。
有关兼容的 bundle 布局，请参阅 [Plugin bundles](/zh-CN/plugins/bundles)。
有关兼容的 bundle 布局，请参阅 [插件 bundle](/zh-CN/plugins/bundles)。
兼容的 bundle 格式使用不同的清单文件：
- Codex bundle：`.codex-plugin/plugin.json`
- Claude bundle：`.claude-plugin/plugin.json`，或不带清单文件的默认 Claude 组件布局
- Claude bundle：`.claude-plugin/plugin.json`，或不带清单的默认 Claude 组件布局
- Cursor bundle：`.cursor-plugin/plugin.json`
OpenClaw 也会自动检测这些 bundle 布局，但不会按照这里介绍的 `openclaw.plugin.json` schema 对它们进行校验。
OpenClaw 也会自动检测这些 bundle 布局，但不会根据此处描述的 `openclaw.plugin.json` schema 对它们进行校验。
对于兼容 bundle，当其布局符合 OpenClaw 运行时预期时，OpenClaw 目前会读取 bundle 元数据，以及声明的 skill 根目录、Claude 命令根目录、Claude bundle `settings.json` 默认值、Claude bundle LSP 默认值，以及受支持的 hook pack。
对于兼容 bundle，OpenClaw 当前会在布局符合 OpenClaw 运行时预期时，读取 bundle 元数据，以及已声明的 skill 根目录、Claude 命令根目录、Claude bundle `settings.json` 默认值、Claude bundle LSP 默认值和受支持的 hook 包。
每个原生 OpenClaw 插件**都必须**在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单在**不执行插件代码的情况下**校验配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。
每个原生 OpenClaw 插件都 **必须** 在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单在**不执行插件代码的情况下**验证配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。
查看完整的插件系统指南：[Plugins](/zh-CN/tools/plugin)。
有关原生能力模型和当前外部兼容性指导，请参阅：
[Capability model](/zh-CN/plugins/architecture#public-capability-model)。
查看完整的插件系统指南：[插件](/zh-CN/tools/plugin)。
有关原生能力模型以及当前外部兼容性指导，请参阅：
[能力模型](/zh-CN/plugins/architecture#public-capability-model)。
## 此文件的作用
`openclaw.plugin.json` 是 OpenClaw 在加载你的插件代码之前读取的元数据。
`openclaw.plugin.json` 是 OpenClaw 在**加载你的插件代码之前**读取的元数据。以下所有内容都必须足够轻量，以便在不启动插件运行时的情况下进行检查。
可将其用于：
**用于：**
- 插件标识
- 配置校验
- 无需启动插件运行时即可获取的认证和新手引导元数据
- 控制平面界面可在运行时加载前检查的轻量激活提示
- 设置/新手引导界面可在运行时加载前检查的轻量设置描述符
- 应在插件运行时加载前解析的别名和自动启用元数据
- 应在插件运行时加载前自动激活插件的简写模型家族归属元数据
- 用于内置兼容接线和契约覆盖的静态能力归属快照
- 共享 `openclaw qa` 主机可在插件运行时加载前检查的轻量 QA 运行器元数据
- 可在不加载运行时的情况下合并到目录和校验界面的渠道专用配置元数据
- 配置 UI 提示
- 插件标识、配置校验和配置 UI 提示
- 认证、新手引导和设置元数据（别名、自动启用、提供商环境变量、认证选项）
- 控制平面界面的激活提示
- 简写模型家族归属
- 静态能力归属快照（`contracts`）
- 共享 `openclaw qa` 主机可检查的 QA 运行器元数据
- 合并到目录和校验界面中的渠道专用配置元数据
不要将其用于：
- 注册运行时行为
- 声明代码入口点
- npm 安装元数据
这些内容属于你的插件代码和 `package.json`。
**不要用于：** 注册运行时行为、声明代码入口点，或 npm 安装元数据。这些应放在你的插件代码和 `package.json` 中。
## 最小示例
@ -108,19 +98,19 @@ OpenClaw 也会自动检测这些 bundle 布局，但不会按照这里介绍的
"provider": "openrouter",
"method": "api-key",
"choiceId": "openrouter-api-key",
"choiceLabel": "OpenRouter API 密钥",
"choiceLabel": "OpenRouter API key",
"groupId": "openrouter",
"groupLabel": "OpenRouter",
"optionKey": "openrouterApiKey",
"cliFlag": "--openrouter-api-key",
"cliOption": "--openrouter-api-key <key>",
"cliDescription": "OpenRouter API 密钥",
"cliDescription": "OpenRouter API key",
"onboardingScopes": ["text-inference"]
}
],
"uiHints": {
"apiKey": {
"label": "API 密钥",
"label": "API key",
"placeholder": "sk-or-v1-...",
"sensitive": true
}
@ -141,63 +131,63 @@ OpenClaw 也会自动检测这些 bundle 布局，但不会按照这里介绍的
| 字段 | 必填 | 类型 | 含义 |
| ------------------------------------ | -------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | 是 | `string` | 规范的插件 id。这是在 `plugins.entries.<id>` 中使用的 id。 |
| `id` | 是 | `string` | 规范插件 id。这是在 `plugins.entries.<id>` 中使用的 id。 |
| `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 |
| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略此字段，或设置为任何非 `true` 的值，则插件默认保持禁用。 |
| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略此字段，或将其设为任何非 `true` 的值，则该插件默认保持禁用。 |
| `legacyPluginIds` | 否 | `string[]` | 会规范化为此规范插件 id 的旧版 id。 |
| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当认证、配置或模型引用提及这些 provider id 时，应自动启用此插件。 |
| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明由 `plugins.slots.*` 使用的排他性插件类型。 |
| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当认证、配置或模型引用提到这些提供商 id 时，应自动启用此插件。 |
| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明一个由 `plugins.slots.*` 使用的互斥插件类型。 |
| `channels` | 否 | `string[]` | 由此插件拥有的渠道 id。用于设备发现和配置校验。 |
| `providers` | 否 | `string[]` | 由此插件拥有的 provider id。 |
| `providers` | 否 | `string[]` | 由此插件拥有的提供商 id。 |
| `modelSupport` | 否 | `object` | 由清单拥有的简写模型家族元数据，用于在运行时之前自动加载插件。 |
| `providerEndpoints` | 否 | `object[]` | 由清单拥有的端点 host/baseUrl 元数据，用于核心在 provider 运行时加载前对 provider 路由进行分类。 |
| `cliBackends` | 否 | `string[]` | 由此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 |
| `syntheticAuthRefs` | 否 | `string[]` | 在运行时加载前的冷启动模型发现期间，应探测其由插件拥有的合成认证 hook 的 provider 或 CLI 后端引用。 |
| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件拥有的占位 API 密钥值，用于表示非机密的本地、OAuth 或环境凭据状态。 |
| `commandAliases` | 否 | `object[]` | 由此插件拥有的命令名称，应在运行时加载前生成带有插件感知能力的配置和 CLI 诊断信息。 |
| `providerAuthEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 可在不加载插件代码的情况下检查的轻量 provider 认证环境变量元数据。 |
| `providerAuthAliases` | 否 | `Record<string, string>` | 应复用另一个 provider id 进行认证查找的 provider id，例如共享基础 provider API 密钥和认证配置文件的编码 provider。 |
| `channelEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 可在不加载插件代码的情况下检查的轻量渠道环境变量元数据。将其用于由环境变量驱动的渠道设置或认证界面，以便通用启动/配置辅助工具能够识别。 |
| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选 provider 解析和简单 CLI 标志接线的轻量认证选项元数据。 |
| `activation` | 否 | `object` | 面向 provider、命令、渠道、路由和能力触发加载的轻量激活提示。仅是元数据；实际行为仍由插件运行时负责。 |
| `setup` | 否 | `object` | 设备发现和设置界面可在不加载插件运行时的情况下检查的轻量设置/新手引导描述符。 |
| `qaRunners` | 否 | `object[]` | 共享 `openclaw qa` 主机在插件运行时加载前使用的轻量 QA 运行器描述符。 |
| `contracts` | 否 | `object` | 面向外部认证 hook、speech、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、web-fetch、Web 搜索和工具归属的静态内置能力快照。 |
| `mediaUnderstandingProviderMetadata` | 否 | `Record<string, object>` | 为 `contracts.mediaUnderstandingProviders` 中声明的 provider id 提供的轻量媒体理解默认值。 |
| `providerEndpoints` | 否 | `object[]` | 由清单拥有的 endpoint 主机 / `baseUrl` 元数据，用于核心在提供商运行时加载前对提供商路由进行分类。 |
| `cliBackends` | 否 | `string[]` | 由此插件拥有的 CLI 推理后端 id。用于在显式配置引用时于启动阶段自动激活。 |
| `syntheticAuthRefs` | 否 | `string[]` | 在运行时加载前的冷启动模型发现期间，应探测其插件自有 synthetic auth hook 的提供商或 CLI 后端引用。 |
| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件拥有的占位 API key 值，表示非秘密的本地、OAuth 或环境凭证状态。 |
| `commandAliases` | 否 | `object[]` | 由此插件拥有的命令名称，应在运行时加载前产生具备插件感知的配置和 CLI 诊断信息。 |
| `providerAuthEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 可在不加载插件代码的情况下检查的轻量提供商认证环境变量元数据。 |
| `providerAuthAliases` | 否 | `Record<string, string>` | 应复用另一个提供商 id 进行认证查找的提供商 id，例如共享基础提供商 API key 和认证配置文件的编码提供商。 |
| `channelEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 可在不加载插件代码的情况下检查的轻量渠道环境变量元数据。将其用于由环境变量驱动的渠道设置或认证界面，以便通用启动 / 配置辅助逻辑能够识别。 |
| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选提供商解析和简单 CLI 标志接线的轻量认证选项元数据。 |
| `activation` | 否 | `object` | 用于提供商、命令、渠道、路由和能力触发加载的轻量激活提示。仅为元数据；插件运行时仍拥有实际行为。 |
| `setup` | 否 | `object` | 供设备发现和设置界面在不加载插件运行时的情况下检查的轻量设置 / 新手引导描述符。 |
| `qaRunners` | 否 | `object[]` | 由共享 `openclaw qa` 主机在插件运行时加载前使用的轻量 QA 运行器描述符。 |
| `contracts` | 否 | `object` | 外部认证 hook、speech、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、网页抓取、网页搜索和工具归属的静态内置能力快照。 |
| `mediaUnderstandingProviderMetadata` | 否 | `Record<string, object>` | 为 `contracts.mediaUnderstandingProviders` 中声明的提供商 id 提供的轻量媒体理解默认元数据。 |
| `channelConfigs` | 否 | `Record<string, object>` | 由清单拥有的渠道配置元数据，在运行时加载前合并到设备发现和校验界面中。 |
| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 |
| `name` | 否 | `string` | 人类可读的插件名称。 |
| `description` | 否 | `string` | 显示在插件界面中的简短摘要。 |
| `version` | 否 | `string` | 仅供参考的插件版本。 |
| `version` | 否 | `string` | 信息性插件版本。 |
| `uiHints` | 否 | `Record<string, object>` | 配置字段的 UI 标签、占位符和敏感性提示。 |
## `providerAuthChoices` 参考
每个 `providerAuthChoices` 条目描述一个新手引导或认证选项。
OpenClaw 会在 provider 运行时加载前读取这些内容。
OpenClaw 会在提供商运行时加载前读取它。
| 字段 | 必填 | 类型 | 含义 |
| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `provider` | 是 | `string` | 此选项所属的 provider id。 |
| `method` | 是 | `string` | 要分发到的认证方法 id。 |
| `choiceId` | 是 | `string` | 由新手引导和 CLI 流程使用的稳定认证选项 id。 |
| `choiceLabel` | 否 | `string` | 面向用户的标签。如省略，OpenClaw 会回退到 `choiceId`。 |
| `provider` | 是 | `string` | 此选项所属的提供商 id。 |
| `method` | 是 | `string` | 要分派到的认证方法 id。 |
| `choiceId` | 是 | `string` | 供新手引导和 CLI 流程使用的稳定认证选项 id。 |
| `choiceLabel` | 否 | `string` | 面向用户的标签。如果省略，OpenClaw 会回退到 `choiceId`。 |
| `choiceHint` | 否 | `string` | 选择器的简短辅助文本。 |
| `assistantPriority` | 否 | `number` | 在由助手驱动的交互式选择器中，值越小越靠前。 |
| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在助手选择器中隐藏此选项，但仍允许通过手动 CLI 进行选择。 |
| `assistantPriority` | 否 | `number` | 在由助手驱动的交互式选择器中，值越小排序越靠前。 |
| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在助手选择器中隐藏该选项，但仍允许手动通过 CLI 选择。 |
| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选项的旧版选项 id。 |
| `groupId` | 否 | `string` | 用于分组相关选项的可选分组 id。 |
| `groupLabel` | 否 | `string` | 该分组面向用户的标签。 |
| `groupHint` | 否 | `string` | 该分组的简短辅助文本。 |
| `groupId` | 否 | `string` | 用于对相关选项分组的可选组 id。 |
| `groupLabel` | 否 | `string` | 该组的面向用户标签。 |
| `groupHint` | 否 | `string` | 该组的简短辅助文本。 |
| `optionKey` | 否 | `string` | 用于简单单标志认证流程的内部选项键。 |
| `cliFlag` | 否 | `string` | CLI 标志名称，例如 `--openrouter-api-key`。 |
| `cliOption` | 否 | `string` | 完整的 CLI 选项形式，例如 `--openrouter-api-key <key>`。 |
| `cliDescription` | 否 | `string` | CLI 帮助中使用的说明。 |
| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 此选项应出现在哪些新手引导界面中。如省略，默认值为 `["text-inference"]`。 |
| `cliOption` | 否 | `string` | 完整 CLI 选项形式，例如 `--openrouter-api-key <key>`。 |
| `cliDescription` | 否 | `string` | 用于 CLI 帮助中的说明。 |
| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 此选项应出现在哪些新手引导界面中。如果省略，默认值为 `["text-inference"]`。 |
## `commandAliases` 参考
当某个插件拥有一个运行时命令名称，而用户可能会误将其放入 `plugins.allow`，或尝试将其作为根级 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用此元数据进行诊断，而无需导入插件运行时代码。
当插件拥有一个运行时命令名称，而用户可能会误将其放入 `plugins.allow`，或尝试将其作为根 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用此元数据在不导入插件运行时代码的情况下提供诊断信息。
```json
{
@ -214,16 +204,16 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。
| 字段 | 必填 | 类型 | 含义 |
| ------------ | -------- | ----------------- | ----------------------------------------------------------------------- |
| `name` | 是 | `string` | 属于此插件的命令名称。 |
| `kind` | 否 | `"runtime-slash"` | 将该别名标记为聊天斜杠命令，而不是根级 CLI 命令。 |
| `cliCommand` | 否 | `string` | 如果存在，用于建议 CLI 操作的相关根级 CLI 命令。 |
| `kind` | 否 | `"runtime-slash"` | 将该别名标记为聊天斜杠命令，而不是根 CLI 命令。 |
| `cliCommand` | 否 | `string` | 若存在相关根 CLI 命令，则建议用于 CLI 操作的该命令。 |
## `activation` 参考
当插件能够以低成本声明哪些控制平面事件应在后续激活它时，请使用 `activation`。
当插件可以以低成本声明哪些控制平面事件应在之后激活它时，请使用 `activation`。
## `qaRunners` 参考
当插件在共享 `openclaw qa` 根命令下贡献一个或多个传输运行器时，请使用 `qaRunners`。保持这些元数据轻量且静态；插件运行时仍通过导出 `qaRunnerCliRegistrations` 的轻量 `runtime-api.ts` 接口负责实际的 CLI 注册。
当插件在共享的 `openclaw qa` 根命令下提供一个或多个传输运行器时，请使用 `qaRunners`。保持此元数据轻量且静态；插件运行时仍通过导出 `qaRunnerCliRegistrations` 的轻量 `runtime-api.ts` 界面拥有实际 CLI 注册逻辑。
```json
{
@ -239,10 +229,11 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。
| 字段 | 必填 | 类型 | 含义 |
| ------------- | -------- | -------- | ------------------------------------------------------------------ |
| `commandName` | 是 | `string` | 挂载在 `openclaw qa` 下的子命令，例如 `matrix`。 |
| `description` | 否 | `string` | 当共享主机需要一个占位命令时使用的回退帮助文本。 |
| `description` | 否 | `string` | 当共享主机需要一个存根命令时使用的回退帮助文本。 |
此块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时/插件入口点。
当前使用方将其作为更广泛插件加载前的缩小范围提示，因此缺少激活元数据通常只会带来性能损耗；在旧版清单归属回退机制仍存在时，它不应改变正确性。
此块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时 / 插件入口点。
当前消费者会将其用作在更广泛插件加载前的缩小范围提示，因此缺少激活元数据通常只会带来性能成本；只要旧版清单归属回退仍然存在，它就不应影响正确性。
```json
{
@ -258,21 +249,21 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。
| 字段 | 必填 | 类型 | 含义 |
| ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
| `onProviders` | 否 | `string[]` | 请求这些 provider id 时应激活此插件。 |
| `onProviders` | 否 | `string[]` | 请求这些提供商 id 时应激活此插件。 |
| `onCommands` | 否 | `string[]` | 应激活此插件的命令 id。 |
| `onChannels` | 否 | `string[]` | 应激活此插件的渠道 id。 |
| `onRoutes` | 否 | `string[]` | 应激活此插件的路由类型。 |
| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的宽泛能力提示。 |
| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的广义能力提示。 |
当前的在线使用方：
当前在线使用方：
- 由命令触发的 CLI 规划会回退到旧版的 `commandAliases[].cliCommand` 或 `commandAliases[].name`
- 由渠道触发的设置/渠道规划会在缺少显式渠道激活元数据时，回退到旧版 `channels[]` 归属
- 由 provider 触发的设置/运行时规划会在缺少显式 provider 激活元数据时，回退到旧版的 `providers[]` 和顶层 `cliBackends[]` 归属
- 由命令触发的 CLI 规划会回退到旧版 `commandAliases[].cliCommand` 或 `commandAliases[].name`
- 当缺少显式渠道激活元数据时，由渠道触发的设置 / 渠道规划会回退到旧版 `channels[]` 归属
- 当缺少显式提供商激活元数据时，由提供商触发的设置 / 运行时规划会回退到旧版 `providers[]` 和顶层 `cliBackends[]` 归属
## `setup` 参考
当设置和新手引导界面在运行时加载前需要轻量的插件自有元数据时，请使用 `setup`。
当设置和新手引导界面需要在运行时加载前读取轻量、由插件拥有的元数据时，请使用 `setup`。
```json
{
@ -291,32 +282,32 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。
}
```
顶层 `cliBackends` 仍然有效，并继续描述 CLI 推理后端。`setup.cliBackends` 是面向控制平面/设置流程的设置专用描述符界面，应保持为纯元数据。
顶层 `cliBackends` 仍然有效，并继续描述 CLI 推理后端。`setup.cliBackends` 是控制平面 / 设置流程的设置专用描述符界面，应保持为纯元数据。
存在时，`setup.providers` 和 `setup.cliBackends` 是设置发现的首选“描述符优先”查找界面。如果该描述符仅用于缩小候选插件范围，而设置仍需要更丰富的设置期运行时 hook，请将 `requiresRuntime` 设为 `true`，并保留 `setup-api` 作为回退执行路径。
如果存在，`setup.providers` 和 `setup.cliBackends` 是设置发现时首选的描述符优先查找界面。如果该描述符只用于缩小候选插件范围，而设置仍需要更丰富的设置期运行时 hook，请将 `requiresRuntime` 设为 `true`，并保留 `setup-api` 作为回退执行路径。
由于设置查找可能会执行插件自有的 `setup-api` 代码，规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值必须在所有已发现插件之间保持唯一。若归属不明确，系统会采用失败关闭，而不是按发现顺序选出一个胜者。
由于设置查找可能会执行插件拥有的 `setup-api` 代码，规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值必须在已发现插件之间保持唯一。归属不明确时会默认失败关闭，而不是按发现顺序选出一个赢家。
### `setup.providers` 参考
| 字段 | 必填 | 类型 | 含义 |
| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ |
| `id` | 是 | `string` | 在设置或新手引导期间公开的 provider id。保持规范化 id 在全局范围内唯一。 |
| `authMethods` | 否 | `string[]` | 此 provider 在不加载完整运行时的情况下支持的设置/认证方法 id。 |
| `envVars` | 否 | `string[]` | 通用设置/状态界面可在插件运行时加载前检查的环境变量。 |
| `id` | 是 | `string` | 在设置或新手引导期间暴露的提供商 id。保持规范化 id 在全局唯一。 |
| `authMethods` | 否 | `string[]` | 此提供商在不加载完整运行时的情况下支持的设置 / 认证方法 id。 |
| `envVars` | 否 | `string[]` | 通用设置 / 状态界面可在插件运行时加载前检查的环境变量。 |
### `setup` 字段
| 字段 | 必填 | 类型 | 含义 |
| ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- |
| `providers` | 否 | `object[]` | 在设置和新手引导期间公开的 provider 设置描述符。 |
| `cliBackends` | 否 | `string[]` | 用于“描述符优先”设置查找的设置期后端 id。保持规范化 id 在全局范围内唯一。 |
| `configMigrations` | 否 | `string[]` | 由此插件的设置界面拥有的配置迁移 id。 |
| `providers` | 否 | `object[]` | 在设置和新手引导期间暴露的提供商设置描述符。 |
| `cliBackends` | 否 | `string[]` | 用于描述符优先设置查找的设置期后端 id。保持规范化 id 在全局唯一。 |
| `configMigrations` | 否 | `string[]` | 由此插件设置界面拥有的配置迁移 id。 |
| `requiresRuntime` | 否 | `boolean` | 在描述符查找之后，设置是否仍需要执行 `setup-api`。 |
## `uiHints` 参考
`uiHints` 是一个从配置字段名映射到小型渲染提示的映射表。
`uiHints` 是从配置字段名称到小型渲染提示的映射。
```json
{
@ -337,14 +328,14 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。
| ------------- | ---------- | --------------------------------------- |
| `label` | `string` | 面向用户的字段标签。 |
| `help` | `string` | 简短辅助文本。 |
| `tags` | `string[]` | 可选的 UI 标签。 |
| `advanced` | `boolean` | 将该字段标记为高级字段。 |
| `sensitive` | `boolean` | 将该字段标记为机密或敏感。 |
| `tags` | `string[]` | 可选 UI 标签。 |
| `advanced` | `boolean` | 将该字段标记为高级。 |
| `sensitive` | `boolean` | 将该字段标记为密钥或敏感信息。 |
| `placeholder` | `string` | 表单输入的占位文本。 |
## `contracts` 参考
仅当 `contracts` 用于 OpenClaw 可在不导入插件运行时的情况下读取的静态能力归属元数据时，才应使用它。
仅将 `contracts` 用于 OpenClaw 可在不导入插件运行时的情况下读取的静态能力归属元数据。
```json
{
@ -369,22 +360,22 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。
| 字段 | 类型 | 含义 |
| -------------------------------- | ---------- | ----------------------------------------------------------------- |
| `embeddedExtensionFactories` | `string[]` | 内置插件可为其注册工厂的嵌入式运行时 id。 |
| `externalAuthProviders` | `string[]` | 此插件拥有其外部认证配置文件 hook 的 provider id。 |
| `speechProviders` | `string[]` | 此插件拥有的 speech provider id。 |
| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转录 provider id。 |
| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音 provider id。 |
| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解 provider id。 |
| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成 provider id。 |
| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成 provider id。 |
| `webFetchProviders` | `string[]` | 此插件拥有的 Web-fetch provider id。 |
| `webSearchProviders` | `string[]` | 此插件拥有的 Web 搜索 provider id。 |
| `tools` | `string[]` | 此插件拥有、用于内置契约检查的智能体工具名称。 |
| `externalAuthProviders` | `string[]` | 此插件拥有其外部认证配置文件 hook 的提供商 id。 |
| `speechProviders` | `string[]` | 此插件拥有的 speech 提供商 id。 |
| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转录提供商 id。 |
| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音提供商 id。 |
| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解提供商 id。 |
| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成提供商 id。 |
| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成提供商 id。 |
| `webFetchProviders` | `string[]` | 此插件拥有的网页抓取提供商 id。 |
| `webSearchProviders` | `string[]` | 此插件拥有的网页搜索提供商 id。 |
| `tools` | `string[]` | 此插件为内置合约检查所拥有的智能体工具名称。 |
实现了 `resolveExternalAuthProfiles` 的 provider 插件应声明 `contracts.externalAuthProviders`。未声明该项的插件仍会通过已弃用的兼容性回退路径运行，但该回退路径更慢，并将在迁移窗口结束后移除。
实现 `resolveExternalAuthProfiles` 的提供商插件应声明 `contracts.externalAuthProviders`。未声明的插件仍会通过已弃用的兼容性回退路径运行，但该回退更慢，并将在迁移窗口结束后移除。
## `mediaUnderstandingProviderMetadata` 参考
当某个媒体理解 provider 具有默认模型、自动认证回退优先级，或通用核心辅助工具在运行时加载前所需的原生文档支持时，请使用 `mediaUnderstandingProviderMetadata`。其键也必须在 `contracts.mediaUnderstandingProviders` 中声明。
当媒体理解提供商具有默认模型、自动认证回退优先级，或通用核心辅助逻辑在运行时加载前所需的原生文档支持时，请使用 `mediaUnderstandingProviderMetadata`。键名也必须在 `contracts.mediaUnderstandingProviders` 中声明。
```json
{
@ -407,18 +398,18 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。
}
```
每个 provider 条目可包含：
每个提供商条目可包含：
| 字段 | 类型 | 含义 |
| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- |
| `capabilities` | `("image" \| "audio" \| "video")[]` | 此 provider 提供的媒体能力。 |
| `defaultModels` | `Record<string, string>` | 当配置未指定模型时使用的“能力到模型”默认值。 |
| `autoPriority` | `Record<string, number>` | 用于基于凭据的自动 provider 回退时，数字越小越靠前。 |
| `nativeDocumentInputs` | `"pdf"[]` | 此 provider 支持的原生文档输入。 |
| `capabilities` | `("image" \| "audio" \| "video")[]` | 此提供商公开的媒体能力。 |
| `defaultModels` | `Record<string, string>` | 当配置未指定模型时使用的“能力到模型”默认映射。 |
| `autoPriority` | `Record<string, number>` | 用于基于凭证的自动提供商回退时，数值越小排序越靠前。 |
| `nativeDocumentInputs` | `"pdf"[]` | 该提供商支持的原生文档输入。 |
## `channelConfigs` 参考
当某个渠道插件在运行时加载前需要轻量配置元数据时，请使用 `channelConfigs`。
当渠道插件在运行时加载前需要轻量配置元数据时，请使用 `channelConfigs`。
```json
{
@ -450,14 +441,14 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。
| 字段 | 类型 | 含义 |
| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
| `schema` | `object` | `channels.<id>` 的 JSON Schema。每个已声明的渠道配置条目都必须提供。 |
| `uiHints` | `Record<string, object>` | 该渠道配置部分的可选 UI 标签/占位符/敏感性提示。 |
| `uiHints` | `Record<string, object>` | 该渠道配置部分的可选 UI 标签 / 占位符 / 敏感性提示。 |
| `label` | `string` | 当运行时元数据尚未就绪时，合并到选择器和检查界面中的渠道标签。 |
| `description` | `string` | 用于检查和目录界面的简短渠道描述。 |
| `description` | `string` | 用于检查和目录界面的简短渠道说明。 |
| `preferOver` | `string[]` | 在选择界面中，此渠道应优先于的旧版或较低优先级插件 id。 |
## `modelSupport` 参考
当 OpenClaw 应在插件运行时加载前，根据 `gpt-5.4` 或 `claude-sonnet-4.6` 之类的简写模型 id 推断你的 provider 插件时，请使用 `modelSupport`。
当 OpenClaw 应在插件运行时加载前，根据 `gpt-5.4` 或 `claude-sonnet-4.6` 之类的简写模型 id 推断你的提供商插件时，请使用 `modelSupport`。
```json
{
@ -468,39 +459,39 @@ OpenClaw 会在 provider 运行时加载前读取这些内容。
}
```
OpenClaw 应用以下优先级：
OpenClaw 按以下优先级处理：
- 显式 `provider/model` 引用使用其所属 `providers` 清单元数据
- 显式 `provider/model` 引用使用所属 `providers` 清单元数据
- `modelPatterns` 优先于 `modelPrefixes`
- 如果一个非内置插件和一个内置插件同时匹配，则非内置插件胜出
- 剩余歧义会被忽略，直到用户或配置显式指定 provider
- 如果一个非内置插件和一个内置插件都匹配，则非内置插件胜出
- 其余歧义会被忽略，直到用户或配置明确指定提供商
字段：
| 字段 | 类型 | 含义 |
| --------------- | ---------- | ------------------------------------------------------------------------------- |
| `modelPrefixes` | `string[]` | 使用 `startsWith` 针对简写模型 id 进行匹配的前缀。 |
| `modelPatterns` | `string[]` | 在移除配置文件后缀之后，针对简写模型 id 进行匹配的正则表达式源码。 |
| `modelPrefixes` | `string[]` | 对简写模型 id 使用 `startsWith` 进行匹配的前缀。 |
| `modelPatterns` | `string[]` | 在移除配置文件后缀后，对简写模型 id 进行匹配的正则表达式源码。 |
旧版顶层能力键已弃用。请使用 `openclaw doctor --fix` 将 `speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；常规清单加载不再将这些顶层字段视为能力归属声明。
旧版顶层能力键已弃用。使用 `openclaw doctor --fix` 将 `speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；常规清单加载不再将这些顶层字段视为能力归属。
## 清单与 `package.json` 的区别
## 清单与 `package.json`
这两个文件承担不同职责：
| 文件 | 用途 |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | 设备发现、配置校验、认证选项元数据，以及必须在插件代码运行前存在的 UI 提示 |
| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 块 |
| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 代码块 |
如果你不确定某段元数据应该放在哪里，请遵循以下规则：
如果你不确定某项元数据应该放在哪里，请使用以下规则：
- 如果 OpenClaw 必须在加载插件代码前知道它，就将它放在 `openclaw.plugin.json`
- 如果它与打包、入口文件或 npm 安装行为有关，就将它放在 `package.json`
- 如果 OpenClaw 必须在加载插件代码前知道它，就放入 `openclaw.plugin.json`
- 如果它与打包、入口文件或 npm 安装行为有关，就放入 `package.json`
### 会影响设备发现的 `package.json` 字段
### 影响设备发现的 `package.json` 字段
某些运行时前插件元数据有意放在 `package.json` 的 `openclaw` 块下，而不是 `openclaw.plugin.json` 中。
某些运行时前的插件元数据会有意放在 `package.json` 的 `openclaw` 代码块下，而不是 `openclaw.plugin.json` 中。
重要示例：
@ -508,30 +499,29 @@ OpenClaw 应用以下优先级：
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `openclaw.extensions` | 声明原生插件入口点。必须保持在插件包目录内。 |
| `openclaw.runtimeExtensions` | 为已安装包声明构建后的 JavaScript 运行时入口点。必须保持在插件包目录内。 |
| `openclaw.setupEntry` | 在新手引导、延迟渠道启动和只读渠道状态/SecretRef 发现期间使用的轻量仅设置入口点。必须保持在插件包目录内。 |
| `openclaw.setupEntry` | 在新手引导、延迟渠道启动和只读渠道状态 / SecretRef 发现期间使用的轻量仅设置入口点。必须保持在插件包目录内。 |
| `openclaw.runtimeSetupEntry` | 为已安装包声明构建后的 JavaScript 设置入口点。必须保持在插件包目录内。 |
| `openclaw.channel` | 轻量的渠道目录元数据，例如标签、文档路径、别名和选择文案。 |
| `openclaw.channel.configuredState` | 轻量的已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅环境变量设置？”。 |
| `openclaw.channel.persistedAuthState` | 轻量的持久化认证状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已经有任何登录状态？”。 |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 面向内置插件和外部发布插件的安装/更新提示。 |
| `openclaw.channel` | 轻量渠道目录元数据，例如标签、文档路径、别名和选择文案。 |
| `openclaw.channel.configuredState` | 轻量已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅环境变量的设置？”。 |
| `openclaw.channel.persistedAuthState` | 轻量持久化认证状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何内容登录？”。 |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 内置和外部发布插件的安装 / 更新提示。 |
| `openclaw.install.defaultChoice` | 当有多个安装来源可用时的首选安装路径。 |
| `openclaw.install.minHostVersion` | 支持的最低 OpenClaw 主机版本，使用类似 `>=2026.3.22` 的 semver 下限。 |
| `openclaw.install.expectedIntegrity` | 预期的 npm 分发完整性字符串，例如 `sha512-...`；安装和更新流程会据此校验获取到的制品。 |
| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个受限的内置插件重装恢复路径。 |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间先加载仅设置的渠道界面，再加载完整渠道插件。 |
| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 主机版本，使用如 `>=2026.3.22` 这样的 semver 下限。 |
| `openclaw.install.expectedIntegrity` | 预期的 npm 分发完整性字符串，例如 `sha512-...`；安装和更新流程会据此校验获取的制品。 |
| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个受限的内置插件重新安装恢复路径。 |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间，完整渠道插件之前先加载仅设置的渠道界面。 |
清单元数据决定了在运行时加载前，新手引导中会出现哪些 provider/渠道/设置选项。`package.json#openclaw.install` 则告诉新手引导，当用户选择其中某个选项时，应如何获取或启用该插件。不要将安装提示移到 `openclaw.plugin.json` 中。
清单元数据决定在运行时加载前，新手引导中会出现哪些提供商 / 渠道 / 设置选项。`package.json#openclaw.install` 告诉新手引导在用户选择其中某项时，如何获取或启用该插件。不要将安装提示移动到 `openclaw.plugin.json` 中。
`openclaw.install.minHostVersion` 会在安装期间和清单注册表加载期间强制执行。无效值会被拒绝；合法但更新的值会让旧主机跳过该插件。
`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间强制执行。无效值会被拒绝；较新但有效的值会使旧主机跳过该插件。
精确的 npm 版本固定已经存在于 `npmSpec` 中，例如
`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`。当你希望如果获取到的 npm 制品不再匹配固定版本时，让更新流程以失败关闭方式终止，请将其与 `expectedIntegrity` 搭配使用。交互式新手引导会提供受信任注册表的 npm spec，包括裸包名和 dist-tag。存在 `expectedIntegrity` 时，安装/更新流程会强制校验它；省略时，会记录注册表解析结果，但不带完整性固定。
精确的 npm 版本固定已存在于 `npmSpec` 中，例如 `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`。如果你希望在获取的 npm 制品不再匹配固定发布版本时，让更新流程默认失败关闭，请将其与 `expectedIntegrity` 搭配使用。交互式新手引导会提供受信任注册表 npm 规格，包括裸包名和 dist-tag。存在 `expectedIntegrity` 时，安装 / 更新流程会强制执行它；省略时，注册表解析结果会被记录，但不会附带完整性固定。
当状态、渠道列表或 SecretRef 扫描需要在不加载完整运行时的情况下识别已配置账户时，渠道插件应提供 `openclaw.setupEntry`。设置入口点应公开渠道元数据，以及适用于设置阶段的安全配置、状态和 secrets 适配器；网络客户端、Gateway 网关监听器和传输运行时应保留在主扩展入口点中。
当状态、渠道列表或 SecretRef 扫描需要在不加载完整运行时的情况下识别已配置账号时，渠道插件应提供 `openclaw.setupEntry`。设置入口点应公开渠道元数据，以及对设置安全的配置、状态和 secrets 适配器；将网络客户端、Gateway 网关监听器和传输运行时保留在主扩展入口点中。
运行时入口点字段不会覆盖源码入口点字段的包边界检查。例如，`openclaw.runtimeExtensions` 不能让一个越界的 `openclaw.extensions` 路径变得可加载。
运行时入口点字段不会绕过针对源码入口点字段的包边界检查。例如，`openclaw.runtimeExtensions` 不能让一个越界的 `openclaw.extensions` 路径变得可加载。
`openclaw.install.allowInvalidConfigRecovery` 的设计范围是刻意受限的。它不会让任意损坏配置都变得可安装。当前它只允许安装流程从某些特定的过时内置插件升级失败中恢复，例如缺失的内置插件路径，或该同一内置插件对应的过时 `channels.<id>` 条目。无关的配置错误仍会阻止安装，并将操作人员引导至 `openclaw doctor --fix`。
`openclaw.install.allowInvalidConfigRecovery` 的设计范围是刻意收窄的。它不会让任意损坏的配置变得可安装。当前它只允许安装流程从特定的陈旧内置插件升级失败中恢复，例如缺失的内置插件路径，或同一内置插件对应的陈旧 `channels.<id>` 条目。无关的配置错误仍会阻止安装，并引导运维人员执行 `openclaw doctor --fix`。
`openclaw.channel.persistedAuthState` 是一个微型检查器模块的包元数据：
@ -549,9 +539,9 @@ OpenClaw 应用以下优先级：
}
```
当设置、Doctor 或已配置状态流程需要在完整渠道插件加载前进行一个轻量的“是/否”认证探测时，请使用它。目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 转发它。
当设置、Doctor 或已配置状态流程需要在完整渠道插件加载前执行一个低成本的“是 / 否”认证探测时，请使用它。目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 转发它。
`openclaw.channel.configuredState` 对轻量的仅环境变量已配置检查使用相同结构：
`openclaw.channel.configuredState` 对低成本的仅环境变量已配置检查采用相同结构：
```json
{
@ -567,63 +557,61 @@ OpenClaw 应用以下优先级：
}
```
当某个渠道能够通过环境变量或其他轻量级非运行时输入回答已配置状态时，请使用它。如果该检查需要完整配置解析或真实渠道运行时，请改为将该逻辑保留在插件 `config.hasConfiguredState` hook 中。
当一个渠道可以根据环境变量或其他微型非运行时输入回答已配置状态时，请使用它。如果检查需要完整配置解析或真实渠道运行时，请将该逻辑保留在插件 `config.hasConfiguredState` hook 中。
## 设备发现优先级（重复插件 id）
OpenClaw 会从多个根位置发现插件（内置、全局安装、工作区、配置中显式选择的路径）。如果两次发现共享同一个 `id`，则只保留**优先级最高**的清单；较低优先级的重复项会被丢弃，而不是与其并行加载。
OpenClaw 会从多个根目录发现插件（内置、全局安装、工作区、配置中显式选择的路径）。如果两个发现结果共享相同的 `id`，则只保留**优先级最高**的清单；低优先级的重复项会被丢弃，而不会与其并列加载。
优先级从高到低如下：
1. **配置选择** —— 在 `plugins.entries.<id>` 中显式固定的路径
1. **配置中选定** —— 在 `plugins.entries.<id>` 中显式固定的路径
2. **内置** —— 随 OpenClaw 一起发布的插件
3. **全局安装** —— 安装到全局 OpenClaw 插件根目录中的插件
4. **工作区** —— 相对于当前工作区发现的插件
影响：
- 位于工作区中的某个内置插件分叉版本或过时副本，不会遮蔽内置构建。
- 如果你确实要用本地插件覆盖内置插件，请通过 `plugins.entries.<id>` 固定它，以便它凭借优先级获胜，而不是依赖工作区发现。
- 被丢弃的重复项会被记录日志，以便 Doctor 和启动诊断能够指向被舍弃的副本。
- 工作区中放置的某个内置插件分叉版本或陈旧副本，不会覆盖内置构建版本。
- 若要真正用本地插件覆盖内置插件，请通过 `plugins.entries.<id>` 固定它，使其依靠优先级获胜，而不是依赖工作区发现。
- 被丢弃的重复项会被记录日志，以便 Doctor 和启动诊断能指向被舍弃的副本。
## JSON Schema 要求
- **每个插件都必须提供一个 JSON Schema**，即使它不接受任何配置。
- 空 schema 也是可以接受的（例如 `{ "type": "object", "additionalProperties": false }`）。
- Schema 会在配置读取/写入时校验，而不是在运行时校验。
- 可以使用空 schema（例如 `{ "type": "object", "additionalProperties": false }`）。
- Schema 会在配置读写时校验，而不是在运行时校验。
## 校验行为
- 未知的 `channels.*` 键会被视为**错误**，除非该渠道 id 已由插件清单声明。
- `plugins.entries.<id>`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现的**插件 id。未知 id 会被视为**错误**。
- 如果某个插件已安装，但其清单或 schema 损坏或缺失，则校验会失败，Doctor 会报告该插件错误。
- 如果插件配置存在，但插件处于**禁用**状态，则配置会被保留，并在 Doctor + 日志中显示**警告**。
- 未知的 `channels.*` 键是**错误**，除非该渠道 id 由某个插件清单声明。
- `plugins.entries.<id>`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现的**插件 id。未知 id 是**错误**。
- 如果某个插件已安装，但其清单或 schema 损坏或缺失，校验会失败，Doctor 会报告该插件错误。
- 如果插件配置存在，但插件处于**禁用**状态，该配置会被保留，并且 Doctor + 日志中会显示**警告**。
完整的 `plugins.*` schema，请参阅[配置参考](/zh-CN/gateway/configuration)。
## 说明
- **原生 OpenClaw 插件必须提供清单**，包括本地文件系统加载的插件。
- 运行时仍会单独加载插件模块；清单仅用于设备发现 + 校验。
- 原生清单使用 JSON5 解析，因此只要最终值仍然是一个对象，就接受注释、尾随逗号和未加引号的键。
- 清单加载器只会读取文档中说明的清单字段。避免在这里添加自定义顶层键。
- `providerAuthEnvVars` 是认证探测、环境变量标记校验以及类似 provider 认证界面的轻量元数据路径，这些场景不应仅为检查环境变量名称就启动插件运行时。
- `providerAuthAliases` 允许 provider 变体复用另一个 provider 的认证环境变量、认证配置文件、基于配置的认证和 API 密钥新手引导选项，而无需在核心中硬编码这种关系。
- `providerEndpoints` 允许 provider 插件拥有简单的端点 host/baseUrl 匹配元数据。仅将其用于核心已支持的端点类别；运行时行为仍由插件负责。
- `syntheticAuthRefs` 是 provider 自有合成认证 hook 的轻量元数据路径，这些 hook 必须在运行时注册表存在之前就对冷启动模型发现可见。只列出其运行时 provider 或 CLI 后端实际实现了 `resolveSyntheticAuth` 的引用。
- `nonSecretAuthMarkers` 是内置插件自有占位 API 密钥（例如本地、OAuth 或环境凭据标记）的轻量元数据路径。核心会将这些值视为非机密，以用于认证展示和 secret 审计，而无需硬编码其所属 provider。
- `channelEnvVars` 是 shell 环境变量回退、设置提示和类似渠道界面的轻量元数据路径，这些场景不应仅为检查环境变量名称就启动插件运行时。环境变量名称只是元数据，本身并不会触发激活：状态、审计、cron 投递校验和其他只读界面在将某个环境变量视为已配置渠道之前，仍会应用插件信任和生效激活策略。
- `providerAuthChoices` 是认证选项选择器、`--auth-choice` 解析、首选 provider 映射，以及 provider 运行时加载前简单新手引导 CLI 标志注册的轻量元数据路径。对于需要 provider 代码的运行时向导元数据，请参阅
[Provider runtime hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。
- 排他性插件类型通过 `plugins.slots.*` 选择。
- `kind: "memory"` 由 `plugins.slots.memory` 选择。
- `kind: "context-engine"` 由 `plugins.slots.contextEngine` 选择（默认：内置 `legacy`）。
- 对于原生 OpenClaw 插件，包括本地文件系统加载，清单都是**必需的**。运行时仍会单独加载插件模块；清单仅用于设备发现 + 校验。
- 原生清单使用 JSON5 解析，因此允许注释、尾随逗号和未加引号的键，只要最终值仍然是一个对象即可。
- 清单加载器只读取文档中说明的清单字段。避免使用自定义顶层键。
- 当插件不需要时，可以省略 `channels`、`providers`、`cliBackends` 和 `skills`。
- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器 allowlist 要求（例如 pnpm `allow-build-scripts`
- `pnpm rebuild <package>`）。
- 互斥插件类型通过 `plugins.slots.*` 选择：`kind: "memory"` 对应 `plugins.slots.memory`，`kind: "context-engine"` 对应 `plugins.slots.contextEngine`（默认 `legacy`）。
- 环境变量元数据（`providerAuthEnvVars`、`channelEnvVars`）仅是声明式的。状态、审计、cron 投递校验及其他只读界面在将某个环境变量视为已配置之前，仍会应用插件信任和有效激活策略。
- 有关需要提供商代码的运行时向导元数据，请参阅[提供商运行时 hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。
- 如果你的插件依赖原生模块，请记录构建步骤以及所有包管理器 allowlist 要求（例如 pnpm `allow-build-scripts` + `pnpm rebuild <package>`）。
## 相关内容
- [Building Plugins](/zh-CN/plugins/building-plugins) — 插件入门
- [Plugin Architecture](/zh-CN/plugins/architecture) — 内部架构
- [SDK Overview](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考
<CardGroup cols={3}>
<Card title="构建插件" href="/zh-CN/plugins/building-plugins" icon="rocket">
插件入门指南。
</Card>
<Card title="插件架构" href="/zh-CN/plugins/architecture" icon="diagram-project">
内部架构和能力模型。
</Card>
<Card title="SDK 概览" href="/zh-CN/plugins/sdk-overview" icon="book">
插件 SDK 参考和子路径导入。
</Card>
</CardGroup>

237
docs/zh-CN/providers/openai.md
View File

@ -3,40 +3,40 @@ read_when:
- 你想在 OpenClaw 中使用 OpenAI 模型
- 你想使用 Codex 订阅认证，而不是 API 密钥
- 你需要更严格的 GPT-5 智能体执行行为
summary: 在 OpenClaw 中使用 OpenAI，可通过 API 密钥或 Codex 订阅。
summary: 在 OpenClaw 中使用 API 密钥或 Codex 订阅来使用 OpenAI
title: OpenAI
x-i18n:
generated_at: "2026-04-23T16:53:28Z"
generated_at: "2026-04-23T16:57:03Z"
model: gpt-5.4
provider: openai
source_hash: a7655fec1e986ccbd01a34f0434e4a88d08c672e0e0cba6c2a8978f11f5f519d
source_hash: 4e03126c2b47514c1bfa364feb5c0c2d452d0e389030c70edd5d9dc7dee3264e
source_path: providers/openai.md
workflow: 15
---
# OpenAI
OpenAI 提供用于 GPT 模型的开发者 API。OpenClaw 支持两种认证方式：
OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持两种认证方式：
- **API 密钥** — 直接访问 OpenAI Platform，并采用按量计费（`openai/*` 模型）
- **Codex 订阅** — 通过 ChatGPT/Codex 登录并使用订阅访问（`openai-codex/*` 模型）
- **API 密钥** —— 直接访问 OpenAI Platform，并按使用量计费（`openai/*` 模型）
- **Codex 订阅** —— 使用 ChatGPT/Codex 登录，并通过订阅访问（`openai-codex/*` 模型）
OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。
OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 OAuth。
## OpenClaw 功能覆盖范围
| OpenAI 能力 | OpenClaw 表面 | 状态 |
| OpenAI 能力 | OpenClaw 界面 | 状态 |
| ------------------------- | ----------------------------------------- | ------------------------------------------------------ |
| 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
| Codex 订阅模型 | `openai-codex/<model>` 模型提供商 | 是 |
| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，当启用 Web 搜索且未固定提供商时 |
| 服务端网页搜索 | 原生 OpenAI Responses 工具 | 是，启用网页搜索且未固定 provider 时可用 |
| 图像 | `image_generate` | 是 |
| 视频 | `video_generate` | 是 |
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 |
| 实时语音 | Voice Call `realtime.provider: "openai"` | 是 |
| Embeddings | memory embedding 提供商 | 是 |
| Embeddings | memory embedding provider | 是 |
## 入门指南
@ -44,33 +44,33 @@ x-i18n:
<Tabs>
<Tab title="API 密钥（OpenAI Platform）">
**最适合：** 直接 API 访问和按量计费。
**最适合：** 直接访问 API 并按使用量计费。
<Steps>
<Step title="获取你的 API 密钥">
在 [OpenAI Platform dashboard](https://platform.openai.com/api-keys) 中创建或复制一个 API 密钥。
在 [OpenAI Platform 控制台](https://platform.openai.com/api-keys) 创建或复制一个 API 密钥。
</Step>
<Step title="运行新手引导">
```bash
openclaw onboard --auth-choice openai-api-key
```
或直接传入密钥：
或者直接传入密钥：
```bash
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
```
</Step>
<Step title="验证模型是否可用">
<Step title="验证模型可用">
```bash
openclaw models list --provider openai
```
</Step>
</Steps>
### 路由摘要
### 路径摘要
| 模型引用 | 路由 | 认证 |
| Model ref | 路径 | 认证 |
|-----------|-------|------|
| `openai/gpt-5.4` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.4-pro` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
@ -89,13 +89,13 @@ x-i18n:
```
<Warning>
OpenClaw **不会** 在直接 API 路径中公开 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。
OpenClaw **不会** 在直接 API 路径中暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。
</Warning>
</Tab>
<Tab title="Codex 订阅">
**最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要通过 ChatGPT 登录。
**最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex 云端需要通过 ChatGPT 登录。
<Steps>
<Step title="运行 Codex OAuth">
@ -103,13 +103,13 @@ x-i18n:
openclaw onboard --auth-choice openai-codex
```
或直接运行 OAuth：
或者直接运行 OAuth：
```bash
openclaw models auth login --provider openai-codex
```
对于无头环境或不适合回调的设置，可添加 `--device-code`，通过 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调：
对于无头环境或不适合回调的设置，可添加 `--device-code`，通过 ChatGPT 的设备码流程登录，而不是使用 localhost 浏览器回调：
```bash
openclaw models auth login --provider openai-codex --device-code
@ -120,22 +120,22 @@ x-i18n:
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.4
```
</Step>
<Step title="验证模型是否可用">
<Step title="验证模型可用">
```bash
openclaw models list --provider openai-codex
```
</Step>
</Steps>
### 路由摘要
### 路径摘要
| 模型引用 | 路由 | 认证 |
| Model ref | 路径 | 认证 |
|-----------|-------|------|
| `openai-codex/gpt-5.4` | ChatGPT/Codex OAuth | Codex 登录 |
| `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于授权资格） |
| `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于 entitlement） |
<Note>
这一路径与 `openai/gpt-5.4` 有意分离。若要直接访问 Platform，请使用带 API 密钥的 `openai/*`；若要使用 Codex 订阅访问，请使用 `openai-codex/*`。
这一路径与 `openai/gpt-5.4` 是刻意分开的。直接 Platform 访问请使用带 API 密钥的 `openai/*`，Codex 订阅访问请使用 `openai-codex/*`。
</Note>
### 配置示例
@ -147,7 +147,7 @@ x-i18n:
```
<Note>
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上述设备码流程登录 —— OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录——OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。
</Note>
### 上下文窗口上限
@ -159,7 +159,7 @@ x-i18n:
- 原生 `contextWindow`：`1050000`
- 默认运行时 `contextTokens` 上限：`272000`
在实际使用中，较小的默认上限通常具有更好的延迟和质量表现。你可以使用 `contextTokens` 覆盖它：
更小的默认上限在实践中通常具有更好的延迟和质量表现。你可以使用 `contextTokens` 覆盖它：
```json5
{
@ -187,7 +187,7 @@ x-i18n:
| 能力 | 值 |
| ------------------------- | ---------------------------------- |
| 默认模型 | `openai/gpt-image-2` |
| 每次请求的最大图像数 | 4 |
| 每次请求的最大图像数量 | 4 |
| 编辑模式 | 已启用（最多 5 张参考图像） |
| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 |
| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API |
@ -203,15 +203,15 @@ x-i18n:
```
<Note>
有关共享工具参数、提供商选择和故障转移行为，请参阅 [图像生成](/zh-CN/tools/image-generation)。
有关共享工具参数、provider 选择和故障转移行为，请参见 [图像生成](/zh-CN/tools/image-generation)。
</Note>
`gpt-image-2` 是 OpenAI 文生图生成和图像编辑的默认模型。`gpt-image-1` 仍可作为显式模型覆盖使用，但新的 OpenAI 图像工作流应使用 `openai/gpt-image-2`。
`gpt-image-2` 是 OpenAI 文本生成图像和图像编辑的默认模型。`gpt-image-1` 仍可作为显式模型覆盖继续使用，但新的 OpenAI 图像工作流应使用 `openai/gpt-image-2`。
生成：
```
/tool image_generate model=openai/gpt-image-2 prompt="为 macOS 上的 OpenClaw 制作一张精美的发布海报" size=3840x2160 count=1
/tool image_generate model=openai/gpt-image-2 prompt="一张适用于 macOS 上 OpenClaw 的精致发布海报" size=3840x2160 count=1
```
编辑：
@ -230,7 +230,7 @@ x-i18n:
| 模式 | 文本生成视频、图像生成视频、单视频编辑 |
| 参考输入 | 1 张图像或 1 个视频 |
| 尺寸覆盖 | 支持 |
| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并显示工具警告 |
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并显示工具警告 |
```json5
{
@ -243,20 +243,20 @@ x-i18n:
```
<Note>
有关共享工具参数、提供商选择和故障转移行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。
有关共享工具参数、provider 选择和故障转移行为，请参见 [视频生成](/zh-CN/tools/video-generation)。
</Note>
## GPT-5 提示词贡献
OpenClaw 会为跨提供商的 GPT-5 系列运行添加共享的 GPT-5 提示词贡献。它按模型 id 应用，因此 `openai/gpt-5.4`、`openai-codex/gpt-5.4`、`openrouter/openai/gpt-5.4`、`opencode/gpt-5.4` 以及其他兼容的 GPT-5 引用都会收到相同的叠加层。较旧的 GPT-4.x 模型则不会。
OpenClaw 为跨 provider 的 GPT-5 系列运行添加了共享的 GPT-5 提示词贡献。它按模型 id 生效，因此 `openai/gpt-5.4`、`openai-codex/gpt-5.4`、`openrouter/openai/gpt-5.4`、`opencode/gpt-5.4` 以及其他兼容的 GPT-5 引用都会接收相同的叠加层。较旧的 GPT-4.x 模型则不会。
内置的原生 Codex harness 提供商（`codex/*`）通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳叠加层，因此即使 Codex 拥有 harness 提示词的其余部分，`codex/gpt-5.x` 会话仍会保持相同的后续跟进和主动心跳指导。
内置的原生 Codex harness provider（`codex/*`）通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳叠加层，因此即使 Codex 负责其余 harness 提示词，`codex/gpt-5.x` 会话仍会保持相同的后续跟进和主动心跳指导。
GPT-5 贡献增加了一个带标签的行为契约，用于人格持久性、执行安全、工具纪律、输出形态、完成检查和验证。特定于渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。GPT-5 指导始终会为匹配的模型启用。友好的交互风格层是独立的，并且可配置。
GPT-5 贡献为角色持续性、执行安全、工具纪律、输出结构、完成检查和验证添加了带标签的行为契约。特定渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。GPT-5 指导始终会为匹配的模型启用。友好交互风格层则是独立且可配置的。
| 值 | 效果 |
| ---------------------- | ------------------------------------------- |
| `"friendly"`（默认） | 启用友好的交互风格层 |
| `"friendly"`（默认） | 启用友好交互风格层 |
| `"on"` | `"friendly"` 的别名 |
| `"off"` | 仅禁用友好风格层 |
@ -282,24 +282,24 @@ GPT-5 贡献增加了一个带标签的行为契约，用于人格持久性、
</Tabs>
<Tip>
在运行时，这些值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
这些值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
</Tip>
<Note>
旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退读取，当共享设置 `agents.defaults.promptOverlays.gpt5.personality` 未设置时生效。
旧版 `plugins.entries.openai.config.personality` 在未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 时，仍会作为兼容性回退读取。
</Note>
## 语音和音频
## 语音和语音识别
<AccordionGroup>
<Accordion title="语音合成（TTS）">
内置的 `openai` 插件为 `messages.tts` 表面注册了语音合成功能。
内置的 `openai` 插件为 `messages.tts` 界面注册了语音合成功能。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
| 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
| 声音 | `messages.tts.providers.openai.voice` | `coral` |
| 语速 | `messages.tts.providers.openai.speed` | （未设置） |
| 速度 | `messages.tts.providers.openai.speed` | （未设置） |
| 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） |
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音笔记为 `opus`，文件为 `mp3` |
| API 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` |
@ -320,20 +320,22 @@ GPT-5 贡献增加了一个带标签的行为契约，用于人格持久性、
```
<Note>
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 Base URL，而不会影响聊天 API 端点。
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的基础 URL，而不会影响聊天 API 端点。
</Note>
</Accordion>
<Accordion title="语音转文本">
内置的 `openai` 插件通过 OpenClaw 的媒体理解转录表面注册了批量语音转文本功能。
内置的 `openai` 插件通过 OpenClaw 的媒体理解转录界面注册了批量语音转文本功能。
- 默认模型：`gpt-4o-transcribe`
- 端点：OpenAI REST `/v1/audio/transcriptions`
- 输入路径：multipart 音频文件上传
- 在 OpenClaw 中，只要入站音频转录使用 `tools.media.audio`，就支持该功能，包括 Discord 语音频道片段和渠道音频附件
- 在 OpenClaw 中，凡是入站音频转录使用
`tools.media.audio` 的地方都支持，包括 Discord 语音频道片段和渠道
音频附件
如需强制对入站音频转录使用 OpenAI：
要强制对入站音频转录使用 OpenAI：
```json5
{
@ -353,7 +355,7 @@ GPT-5 贡献增加了一个带标签的行为契约，用于人格持久性、
}
```
当共享音频媒体配置或按次调用的转录请求提供了语言和提示信息时，这些信息会转发给 OpenAI。
当共享音频媒体配置或每次调用的转录请求提供了语言和提示信息时，这些信息会转发给 OpenAI。
</Accordion>
@ -365,12 +367,12 @@ GPT-5 贡献增加了一个带标签的行为契约，用于人格持久性、
| 模型 | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
| 语言 | `...openai.language` | （未设置） |
| 提示 | `...openai.prompt` | （未设置） |
| 静音时长 | `...openai.silenceDurationMs` | `800` |
| 静默时长 | `...openai.silenceDurationMs` | `800` |
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
<Note>
使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。此流式提供商用于 Voice Call 的实时转录路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。
使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这个流式 provider 用于 Voice Call 的实时转录路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。
</Note>
</Accordion>
@ -384,7 +386,7 @@ GPT-5 贡献增加了一个带标签的行为契约，用于人格持久性、
| 声音 | `...openai.voice` | `alloy` |
| Temperature | `...openai.temperature` | `0.8` |
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
| 静音时长 | `...openai.silenceDurationMs` | `500` |
| 静默时长 | `...openai.silenceDurationMs` | `500` |
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
<Note>
@ -396,21 +398,27 @@ GPT-5 贡献增加了一个带标签的行为契约，用于人格持久性、
## Azure OpenAI 端点
内置的 `openai` 提供商可以通过覆盖 base URL，将图像生成请求发送到 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换为 Azure 的请求格式。
内置的 `openai` provider 可以通过覆盖基础 URL，将图像生成请求定向到 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 中的 Azure 主机名，并自动切换到 Azure 的请求格式。
<Note>
实时语音使用单独的配置路径（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），不受 `models.providers.openai.baseUrl` 影响。其 Azure 设置请参阅 [语音和音频](#voice-and-speech) 下的 **实时语音** 折叠项。
实时语音使用单独的配置路径
（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），
不会受到 `models.providers.openai.baseUrl` 的影响。其 Azure
设置请参见 [语音和语音识别](#voice-and-speech) 下 **实时语音**
手风琴项。
</Note>
在以下情况下使用 Azure OpenAI：
以下情况适合使用 Azure OpenAI：
- 你已经拥有 Azure OpenAI 订阅、配额或企业协议
- 你需要 Azure 提供的区域数据驻留或合规控制
- 你希望将流量保留在现有的 Azure 租户内部
- 你希望将流量保留在现有的 Azure 租户内
### 配置
若要通过内置 `openai` 提供商使用 Azure 图像生成，请将 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：
若要通过内置 `openai` provider 使用 Azure 图像生成，请将
`models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为
Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：
```json5
{
@ -425,75 +433,94 @@ GPT-5 贡献增加了一个带标签的行为契约，用于人格持久性、
}
```
OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成路径：
OpenClaw 会识别以下 Azure 主机后缀，并为 Azure 图像生成路径启用 Azure 路由：
- `*.openai.azure.com`
- `*.services.ai.azure.com`
- `*.cognitiveservices.azure.com`
对于发往已识别 Azure 主机的图像生成请求，OpenClaw 会：
对于识别出的 Azure 主机上的图像生成请求，OpenClaw 会：
- 发送 `api-key` 头，而不是 `Authorization: Bearer`
- 使用按部署限定的路径（`/openai/deployments/{deployment}/...`）
- 为每个请求追加 `?api-version=...`
- 发送 `api-key` 请求头，而不是 `Authorization: Bearer`
- 使用以 deployment 为范围的路径（`/openai/deployments/{deployment}/...`）
- 为每个请求附加 `?api-version=...`
其他 base URL（公共 OpenAI、兼容 OpenAI 的代理）会继续使用标准 OpenAI 图像请求格式。
其他基础 URL（公共 OpenAI、兼容 OpenAI 的代理）会继续使用标准的
OpenAI 图像请求格式。
<Note>
`openai` 提供商的图像生成路径 Azure 路由需要 OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义 `openai.baseUrl` 视为公共 OpenAI 端点，因此在 Azure 图像部署上会失败。
`openai` provider 的图像生成路径对 Azure 路由的支持要求
OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义
`openai.baseUrl` 视为公共 OpenAI 端点，因此在 Azure
图像 deployment 上会失败。
</Note>
### API 版本
设置 `AZURE_OPENAI_API_VERSION` 以固定 Azure 图像生成路径所使用的特定 Azure 预览版或 GA 版本：
设置 `AZURE_OPENAI_API_VERSION` 可为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本：
```bash
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
```
当该变量未设置时，默认值为 `2024-12-01-preview`。
如果未设置该变量，默认值为 `2024-12-01-preview`。
### 模型名称就是部署名称
### 模型名称就是 deployment 名称
Azure OpenAI 将模型绑定到部署。对于通过内置 `openai` 提供商路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的**Azure 部署名称**，而不是公共 OpenAI 模型 id。
Azure OpenAI 将模型绑定到 deployment。对于通过内置 `openai` provider
路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的
**Azure deployment 名称**，而不是公开的 OpenAI 模型 id。
如果你创建了一个名为 `gpt-image-2-prod` 的部署，用于提供 `gpt-image-2`：
如果你创建了一个名为 `gpt-image-2-prod` 的 deployment，用于提供 `gpt-image-2`：
```
/tool image_generate model=openai/gpt-image-2-prod prompt="一张简洁的海报" size=1024x1024 count=1
```
同样的部署名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。
同样的 deployment 名称规则也适用于通过内置 `openai` provider 路由的图像生成调用。
### 区域可用性
Azure 图像生成当前仅在部分区域可用（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、`uaenorth`）。创建部署前，请先查看 Microsoft 当前的区域列表，并确认你的区域提供对应的具体模型。
Azure 图像生成目前仅在部分区域可用
（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、
`uaenorth`）。在创建 deployment 之前，请先查看 Microsoft 当前的区域列表，
并确认你的区域中提供该特定模型。
### 参数差异
Azure OpenAI 与公共 OpenAI 并不总是接受相同的图像参数。Azure 可能会拒绝公共 OpenAI 允许的选项（例如 `gpt-image-2` 上某些 `background` 值），或者仅在特定模型版本上提供这些选项。这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 Azure 门户中检查你的特定部署和 API 版本所支持的参数集。
Azure OpenAI 与公共 OpenAI 并不总是接受相同的图像参数。
Azure 可能会拒绝公共 OpenAI 允许的某些选项（例如 `gpt-image-2` 上的某些
`background` 值），或只在特定模型版本上公开这些选项。这些差异来自 Azure 和底层模型，
而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 Azure 门户中检查你的特定 deployment 和 API 版本所支持的参数集。
<Note>
Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configuration) 下 **原生与兼容 OpenAI 路由** 折叠项。
Azure OpenAI 使用原生传输和兼容行为，但不会接收
OpenClaw 的隐藏归因请求头——请参见 [高级配置](#advanced-configuration) 下
**原生与兼容 OpenAI 路由**
手风琴项。
对于 Azure 上的聊天或 Responses 流量（除图像生成之外），请使用新手引导流程或专用的 Azure 提供商配置 —— 单独设置 `openai.baseUrl` 不会自动采用 Azure 的 API/认证格式。另有单独的 `azure-openai-responses/*` 提供商；请参阅 [服务端压缩](#server-side-compaction-responses-api)。
若要在 Azure 上处理聊天或 Responses 流量（不仅仅是图像生成），请使用
新手引导流程或专用的 Azure provider 配置——仅设置 `openai.baseUrl`
并不会采用 Azure 的 API/认证格式。另有一个单独的
`azure-openai-responses/*` provider；请参见下方的
服务端压缩手风琴项。
</Note>
## 高级配置
<AccordionGroup>
<Accordion title="传输协议（WebSocket 与 SSE）">
对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都默认采用 WebSocket 优先并带有 SSE 回退（`"auto"`）。
<Accordion title="传输方式（WebSocket 与 SSE）">
对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都采用 WebSocket 优先，并在失败时回退到 SSE（`"auto"`）。
在 `"auto"` 模式下，OpenClaw 会：
- 在回退到 SSE 之前，重试一次早期 WebSocket 故障
- 在发生故障后，将 WebSocket 标记为约 60 秒的降级状态，并在冷却期间使用 SSE
- 为重试和重连附加稳定的会话与轮次标识头
- 在不同传输变体之间标准化用量计数器（`input_tokens` / `prompt_tokens`）
- 在回退到 SSE 之前，重试一次早期 WebSocket 失败
- 发生失败后，将 WebSocket 标记为降级状态约 60 秒，并在冷却期间使用 SSE
- 为重试和重连附加稳定的会话和轮次标识请求头
- 在不同传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`）
| 值 | 行为 |
|-------|----------|
| `"auto"`（默认） | WebSocket 优先，SSE 回退 |
| `"auto"`（默认） | WebSocket 优先，失败时回退到 SSE |
| `"sse"` | 仅强制使用 SSE |
| `"websocket"` | 仅强制使用 WebSocket |
@ -518,7 +545,7 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
</Accordion>
<Accordion title="WebSocket 预热">
OpenClaw 默认对 `openai/*` 启用 WebSocket 预热，以降低首轮延迟。
OpenClaw 默认对 `openai/*` 启用 WebSocket 预热，以减少首轮延迟。
```json5
// 禁用预热
@ -538,12 +565,12 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
</Accordion>
<Accordion title="快速模式">
OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供共享的快速模式开关：
OpenClaw 为 `openai/*` 和 `openai-codex/*` 都提供了共享的快速模式开关：
- **聊天/UI：** `/fast status|on|off`
- **配置：** `agents.defaults.models["<provider>/<model>"].params.fastMode`
启用后，OpenClaw 会将快速模式映射为 OpenAI 的优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会改写 `reasoning` 或 `text.verbosity`。
启用后，OpenClaw 会将快速模式映射为 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。
```json5
{
@ -559,13 +586,13 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
```
<Note>
会话覆盖优先于配置。清除 Sessions UI 中的会话覆盖后，会话将恢复为配置中的默认值。
会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话会恢复为配置的默认值。
</Note>
</Accordion>
<Accordion title="优先处理（service_tier）">
OpenAI 的 API 通过 `service_tier` 提供优先处理能力。你可以在 OpenClaw 中按模型设置它：
OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置它：
```json5
{
@ -583,21 +610,21 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
支持的值：`auto`、`default`、`flex`、`priority`。
<Warning>
`serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。
`serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一 provider，OpenClaw 会保持 `service_tier` 原样不变。
</Warning>
</Accordion>
<Accordion title="服务端压缩（Responses API）">
对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用服务端压缩：
对于直接的 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用服务端压缩：
- 强制设置 `store: true`（除非模型兼容性设置 `supportsStore: false`）
- 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
- 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`）
<Tabs>
<Tab title="显式启用">
对于 Azure OpenAI Responses 等兼容端点，这很有用：
适用于 Azure OpenAI Responses 等兼容端点：
```json5
{
@ -649,13 +676,13 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
</Tabs>
<Note>
`responsesServerCompaction` 仅控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置将 `supportsStore` 设为 `false`。
`responsesServerCompaction` 只控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。
</Note>
</Accordion>
<Accordion title="严格智能体式 GPT 模式">
对于 `openai/*` 和 `openai-codex/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行契约：
<Accordion title="严格智能体 GPT 模式">
对于 `openai/*` 和 `openai-codex/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的内嵌执行契约：
```json5
{
@ -668,32 +695,32 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
```
使用 `strict-agentic` 时，OpenClaw 会：
- 当工具操作可用时，不再将仅规划的轮次视为成功进展
- 通过“立即执行”的引导重试该轮次
- 对于实质性工作自动启用 `update_plan`
- 如果模型持续规划而不执行，则显示明确的受阻状态
- 当工具操作可用时，不再将“仅有计划”的轮次视为成功推进
- 使用“立即行动”的引导重试该轮次
- 对于较大工作量自动启用 `update_plan`
- 如果模型持续只做计划而不行动，则显示明确的阻塞状态
<Note>
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列保持默认行为。
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他 provider 和较旧模型系列会保持默认行为。
</Note>
</Accordion>
<Accordion title="原生与兼容 OpenAI 路由">
OpenClaw 会将直接 OpenAI、Codex 和 Azure OpenAI 端点，与通用兼容 OpenAI 的 `/v1` 代理区别对待：
OpenClaw 对直连 OpenAI、Codex 和 Azure OpenAI 端点，与通用兼容 OpenAI 的 `/v1` 代理采用不同处理方式：
**原生路由**（`openai/*`、`openai-codex/*`、Azure OpenAI）：
- 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
- 对会拒绝 `reasoning.effort: "none"` 的模型或代理，省略已禁用的 reasoning
- 对拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用的 reasoning
- 默认将工具 schema 设为严格模式
- 仅在经过验证的原生主机上附加隐藏归因头
- 保留 OpenAI 专用的请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示）
- 仅在已验证的原生主机上附加隐藏归因请求头
- 保留 OpenAI 专用请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示）
**代理/兼容路由：**
- 使用更宽松的兼容行为
- 不会强制使用严格工具 schema 或原生专用头
- 不会强制严格工具 schema 或仅限原生的请求头
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因头。
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因请求头。
</Accordion>
</AccordionGroup>
@ -702,13 +729,13 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障转移行为。
选择 provider、模型引用和故障转移行为。
</Card>
<Card title="图像生成" href="/zh-CN/tools/image-generation" icon="image">
共享图像工具参数和提供商选择。
共享图像工具参数和 provider 选择。
</Card>
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
共享视频工具参数和提供商选择。
共享视频工具参数和 provider 选择。
</Card>
<Card title="OAuth 和认证" href="/zh-CN/gateway/authentication" icon="key">
认证细节和凭证复用规则。