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:54:57 +00:00
parent da8e6f2d66
commit 2a79055bb9
1 changed files with 110 additions and 138 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,15 +1,15 @@
---
read_when:
- 你想在 OpenClaw 中使用 OpenAI 模型
- 你想使用 Codex 订阅认证而不是 API 密钥
- 你想使用 Codex 订阅认证，而不是 API 密钥
- 你需要更严格的 GPT-5 智能体执行行为
summary: 在 OpenClaw 中使用 OpenAI 的 API 密钥或 Codex 订阅
summary: 在 OpenClaw 中使用 OpenAI，可通过 API 密钥或 Codex 订阅。
title: OpenAI
x-i18n:
generated_at: "2026-04-23T12:50:54Z"
generated_at: "2026-04-23T16:53:28Z"
model: gpt-5.4
provider: openai
source_hash: ac42660234e1971440f6de3b04adb1d3a1fddca20219fb68936c36e4c2f95265
source_hash: a7655fec1e986ccbd01a34f0434e4a88d08c672e0e0cba6c2a8978f11f5f519d
source_path: providers/openai.md
workflow: 15
---
@ -18,25 +18,25 @@ x-i18n:
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>` 模型提供商 | 是 |
| 服务器端网页搜索 | 原生 OpenAI Responses 工具 | 是，在启用网页搜索且未固定提供商时可用 |
| 图像 | `image_generate` | 是 |
| 视频 | `video_generate` | 是 |
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 |
| 实时语音 | Voice Call `realtime.provider: "openai"` | 是 |
| Embeddings | memory 嵌入提供商 | 是 |
| 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
| Codex 订阅模型 | `openai-codex/<model>` 模型提供商 | 是 |
| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，当启用 Web 搜索且未固定提供商时 |
| 图像 | `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 提供商 | 是 |
## 入门指南
@ -44,11 +44,11 @@ x-i18n:
<Tabs>
<Tab title="API 密钥（OpenAI Platform）">
**最适合：** 直接 API 访问和按使用量计费。
**最适合：** 直接 API 访问和按量计费。
<Steps>
<Step title="获取你的 API 密钥">
在 [OpenAI Platform 控制台](https://platform.openai.com/api-keys) 创建或复制一个 API 密钥。
在 [OpenAI Platform dashboard](https://platform.openai.com/api-keys) 中创建或复制一个 API 密钥。
</Step>
<Step title="运行新手引导">
```bash
@ -61,7 +61,7 @@ x-i18n:
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
```
</Step>
<Step title="验证模型可用">
<Step title="验证模型是否可用">
```bash
openclaw models list --provider openai
```
@ -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 cloud 需要通过 ChatGPT 登录。
<Steps>
<Step title="运行 Codex OAuth">
@ -109,7 +109,7 @@ x-i18n:
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,7 +120,7 @@ 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
```
@ -132,10 +132,10 @@ x-i18n:
| 模型引用 | 路由 | 认证 |
|-----------|-------|------|
| `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 登录（取决于授权资格） |
<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
{
@ -186,11 +186,11 @@ x-i18n:
| 能力 | 值 |
| ------------------------- | ---------------------------------- |
| 默认模型 | `openai/gpt-image-2` |
| 每次请求的最大图像数 | 4 |
| 编辑模式 | 已启用（最多 5 张参考图像） |
| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 |
| 宽高比 / 分辨率 | 不会转发给 OpenAI Images API |
| 默认模型 | `openai/gpt-image-2` |
| 每次请求的最大图像数 | 4 |
| 编辑模式 | 已启用（最多 5 张参考图像） |
| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 |
| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API |
```json5
{
@ -203,21 +203,21 @@ x-i18n:
```
<Note>
有关共享工具参数、提供商选择和故障切换行为，请参阅 [图像生成](/zh-CN/tools/image-generation)。
有关共享工具参数、提供商选择和故障转移行为，请参阅 [图像生成](/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="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1
/tool image_generate model=openai/gpt-image-2 prompt="为 macOS 上的 OpenClaw 制作一张精美的发布海报" size=3840x2160 count=1
```
编辑：
```
/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536
/tool image_generate model=openai/gpt-image-2 prompt="保留物体形状，将材质改为半透明玻璃" image=/path/to/reference.png size=1024x1536
```
## 视频生成
@ -226,11 +226,11 @@ x-i18n:
| 能力 | 值 |
| ---------------- | --------------------------------------------------------------------------------- |
| 默认模型 | `openai/sora-2` |
| 模式 | 文生视频、图生视频、单视频编辑 |
| 参考输入 | 1 张图像或 1 个视频 |
| 尺寸覆盖 | 支持 |
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并显示工具警告 |
| 默认模型 | `openai/sora-2` |
| 模式 | 文本生成视频、图像生成视频、单视频编辑 |
| 参考输入 | 1 张图像或 1 个视频 |
| 尺寸覆盖 | 支持 |
| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并显示工具警告 |
```json5
{
@ -243,22 +243,22 @@ x-i18n:
```
<Note>
有关共享工具参数、提供商选择和故障切换行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。
有关共享工具参数、提供商选择和故障转移行为，请参阅 [视频生成](/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 会为跨提供商的 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 行为和 heartbeat 覆盖层，因此即使其余 harness 提示词由 Codex 自行控制，`codex/gpt-5.x` 会话仍会保持相同的后续跟进和主动 heartbeat 指导。
内置的原生 Codex harness 提供商（`codex/*`）通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳叠加层，因此即使 Codex 拥有 harness 提示词的其余部分，`codex/gpt-5.x` 会话仍会保持相同的后续跟进和主动心跳指导。
GPT-5 贡献增加了一个带标签的行为契约，用于定义 persona 持续性、执行安全性、工具纪律、输出形状、完成检查和验证。特定于渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。对于匹配的模型，GPT-5 指导始终启用。友好的交互风格层则是独立且可配置的。
GPT-5 贡献增加了一个带标签的行为契约，用于人格持久性、执行安全、工具纪律、输出形态、完成检查和验证。特定于渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。GPT-5 指导始终会为匹配的模型启用。友好的交互风格层是独立的，并且可配置。
| 值 | 效果 |
| ---------------------- | ------------------------------------------- |
| `"friendly"`（默认） | 启用友好的交互风格层 |
| `"on"` | `"friendly"` 的别名 |
| `"off"` | 仅禁用友好风格层 |
| `"friendly"`（默认） | 启用友好的交互风格层 |
| `"on"` | `"friendly"` 的别名 |
| `"off"` | 仅禁用友好风格层 |
<Tabs>
<Tab title="配置">
@ -282,30 +282,30 @@ GPT-5 贡献增加了一个带标签的行为契约，用于定义 persona 持
</Tabs>
<Tip>
这些值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
在运行时，这些值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
</Tip>
<Note>
当共享设置 `agents.defaults.promptOverlays.gpt5.personality` 未设置时，仍会读取旧版的 `plugins.entries.openai.config.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.voice` | `coral` |
| 语速 | `messages.tts.providers.openai.speed` | （未设置） |
| 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） |
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺为 `opus`，文件为 `mp3` |
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音笔记为 `opus`，文件为 `mp3` |
| API 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` |
| Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用音色：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。
可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用声音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。
```json5
{
@ -326,14 +326,14 @@ GPT-5 贡献增加了一个带标签的行为契约，用于定义 persona 持
</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 +353,7 @@ GPT-5 贡献增加了一个带标签的行为契约，用于定义 persona 持
}
```
如果通过共享音频媒体配置或单次调用的转录请求提供了语言和提示信息，这些提示会转发给 OpenAI。
当共享音频媒体配置或按次调用的转录请求提供了语言和提示信息时，这些信息会转发给 OpenAI。
</Accordion>
@ -370,7 +370,7 @@ GPT-5 贡献增加了一个带标签的行为契约，用于定义 persona 持
| 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`）音频。此流式提供商用于 Voice Call 的实时转录路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。
</Note>
</Accordion>
@ -381,7 +381,7 @@ GPT-5 贡献增加了一个带标签的行为契约，用于定义 persona 持
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
| 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime` |
| 音色 | `...openai.voice` | `alloy` |
| 声音 | `...openai.voice` | `alloy` |
| Temperature | `...openai.temperature` | `0.8` |
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
| 静音时长 | `...openai.silenceDurationMs` | `500` |
@ -396,27 +396,21 @@ GPT-5 贡献增加了一个带标签的行为契约，用于定义 persona 持
## Azure OpenAI 端点
内置的 `openai` 提供商可通过覆盖 base URL，将图像生成请求定向到 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换为 Azure 的请求格式。
内置的 `openai` 提供商可以通过覆盖 base 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 提供的区域数据驻留或合规控制
- 你希望将流量保留在现有的 Azure 租户内
- 你希望将流量保留在现有的 Azure 租户内部
### 配置
如需通过内置的 `openai` 提供商使用 Azure 图像生成，请将
`models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设为
Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：
若要通过内置 `openai` 提供商使用 Azure 图像生成，请将 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：
```json5
{
@ -431,31 +425,27 @@ Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：
}
```
OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成路由：
OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成路径：
- `*.openai.azure.com`
- `*.services.ai.azure.com`
- `*.cognitiveservices.azure.com`
对于在已识别 Azure 主机上发起的图像生成请求，OpenClaw 会：
对于发往已识别 Azure 主机的图像生成请求，OpenClaw 会：
- 发送 `api-key` 头，而不是 `Authorization: Bearer`
- 使用按 deployment 划分的路径（`/openai/deployments/{deployment}/...`）
- 使用按部署限定的路径（`/openai/deployments/{deployment}/...`）
- 为每个请求追加 `?api-version=...`
其他 base URL（公共 OpenAI、OpenAI 兼容代理）会继续使用标准的
OpenAI 图像请求格式。
其他 base URL（公共 OpenAI、兼容 OpenAI 的代理）会继续使用标准 OpenAI 图像请求格式。
<Note>
`openai` 提供商图像生成路径的 Azure 路由要求
OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义
`openai.baseUrl` 视为公共 OpenAI 端点，因此会在 Azure
图像 deployment 上失败。
`openai` 提供商的图像生成路径 Azure 路由需要 OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义 `openai.baseUrl` 视为公共 OpenAI 端点，因此在 Azure 图像部署上会失败。
</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"
@ -463,59 +453,43 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
当该变量未设置时，默认值为 `2024-12-01-preview`。
### 模型名称就是 deployment 名称
### 模型名称就是部署名称
Azure OpenAI 会将模型绑定到 deployment。对于通过内置 `openai` 提供商路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure deployment 名称**，而不是公共 OpenAI 模型 id。
Azure OpenAI 将模型绑定到部署。对于通过内置 `openai` 提供商路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的**Azure 部署名称**，而不是公共 OpenAI 模型 id。
如果你创建了一个名为 `gpt-image-2-prod` 的 deployment，并由它提供 `gpt-image-2`：
如果你创建了一个名为 `gpt-image-2-prod` 的部署，用于提供 `gpt-image-2`：
```
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
/tool image_generate model=openai/gpt-image-2-prod prompt="一张简洁的海报" size=1024x1024 count=1
```
同样的 deployment 名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。
同样的部署名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。
### 区域可用性
Azure 图像生成目前仅在部分区域可用
（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、
`uaenorth`）。在创建 deployment 之前，请先查看 Microsoft 的最新区域列表，并确认你的区域提供了相应的具体模型。
Azure 图像生成当前仅在部分区域可用（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、`uaenorth`）。创建部署前，请先查看 Microsoft 当前的区域列表，并确认你的区域提供对应的具体模型。
### 参数差异
Azure OpenAI 与公共 OpenAI 并不总是接受相同的图像参数。
Azure 可能会拒绝公共 OpenAI 允许的某些选项（例如 `gpt-image-2` 上某些
`background` 值），或者仅在特定模型版本上提供这些选项。这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 Azure 门户中检查你的具体 deployment 和 API 版本所支持的参数集合。
Azure OpenAI 与公共 OpenAI 并不总是接受相同的图像参数。Azure 可能会拒绝公共 OpenAI 允许的选项（例如 `gpt-image-2` 上某些 `background` 值），或者仅在特定模型版本上提供这些选项。这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 Azure 门户中检查你的特定部署和 API 版本所支持的参数集。
<Note>
Azure OpenAI 使用原生传输和兼容行为，但不会接收
OpenClaw 的隐藏归因头。详情请参阅 [高级配置](#advanced-configuration)
下的 **原生与 OpenAI 兼容路由**
折叠面板。
</Note>
Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configuration) 下 **原生与兼容 OpenAI 路由** 折叠项。
<Tip>
如需使用单独的 Azure OpenAI Responses 提供商（不同于 `openai`
提供商），请参阅
[服务器端压缩](#server-side-compaction-responses-api) 折叠面板中的
`azure-openai-responses/*` 模型引用。
</Tip>
<Note>
Azure 聊天和 Responses 流量除了覆盖 base URL 外，还需要 Azure 特定的提供商/API 配置。如果你希望在图像生成之外使用 Azure 模型调用，请使用新手引导流程或提供商配置来设置正确的 Azure API/认证格式，而不要假设仅 `openai.baseUrl` 就足够。
对于 Azure 上的聊天或 Responses 流量（除图像生成之外），请使用新手引导流程或专用的 Azure 提供商配置 —— 单独设置 `openai.baseUrl` 不会自动采用 Azure 的 API/认证格式。另有单独的 `azure-openai-responses/*` 提供商；请参阅 [服务端压缩](#server-side-compaction-responses-api)。
</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
- 在回退到 SSE 之前，重试一次早期 WebSocket 故障
- 在发生故障后，将 WebSocket 标记为约 60 秒的降级状态，并在冷却期间使用 SSE
- 为重试和重连附加稳定的会话与轮次标识头
- 在不同传输变体之间标准化使用计数器（`input_tokens` / `prompt_tokens`）
- 在不同传输变体之间标准化用量计数器（`input_tokens` / `prompt_tokens`）
| 值 | 行为 |
|-------|----------|
@ -563,15 +537,13 @@ Azure 聊天和 Responses 流量除了覆盖 base URL 外，还需要 Azure 特
</Accordion>
<a id="openai-fast-mode"></a>
<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
{
@ -587,7 +559,7 @@ Azure 聊天和 Responses 流量除了覆盖 base URL 外，还需要 Azure 特
```
<Note>
会话级覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话将恢复为配置的默认值。
会话覆盖优先于配置。清除 Sessions UI 中的会话覆盖后，会话将恢复为配置中的默认值。
</Note>
</Accordion>
@ -616,16 +588,16 @@ Azure 聊天和 Responses 流量除了覆盖 base URL 外，还需要 Azure 特
</Accordion>
<Accordion title="服务器端压缩（Responses API）">
对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用服务器端压缩：
<Accordion title="服务端压缩（Responses API）">
对于直接 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
{
@ -677,13 +649,13 @@ Azure 聊天和 Responses 流量除了覆盖 base URL 外，还需要 Azure 特
</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
{
@ -696,10 +668,10 @@ Azure 聊天和 Responses 流量除了覆盖 base URL 外，还需要 Azure 特
```
使用 `strict-agentic` 时，OpenClaw 会：
- 当工具操作可用时，不再将“仅计划”的轮次视为成功进展
- 使用“立即执行”的引导重试该轮次
- 对于较重大的工作，自动启用 `update_plan`
- 如果模型持续规划而不执行，则显式显示阻塞状态
- 当工具操作可用时，不再将仅规划的轮次视为成功进展
- 通过“立即执行”的引导重试该轮次
- 对于实质性工作自动启用 `update_plan`
- 如果模型持续规划而不执行，则显示明确的受阻状态
<Note>
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列保持默认行为。
@ -707,19 +679,19 @@ Azure 聊天和 Responses 流量除了覆盖 base URL 外，还需要 Azure 特
</Accordion>
<Accordion title="原生与 OpenAI 兼容路由">
OpenClaw 对直接 OpenAI、Codex 和 Azure OpenAI 端点与通用 OpenAI 兼容 `/v1` 代理采用不同处理方式：
<Accordion title="原生与兼容 OpenAI 路由">
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 使用原生传输和兼容行为，但不会接收隐藏归因头。
@ -730,7 +702,7 @@ Azure 聊天和 Responses 流量除了覆盖 base URL 外，还需要 Azure 特
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障切换行为。
选择提供商、模型引用和故障转移行为。
</Card>
<Card title="图像生成" href="/zh-CN/tools/image-generation" icon="image">
共享图像工具参数和提供商选择。
@ -738,7 +710,7 @@ Azure 聊天和 Responses 流量除了覆盖 base URL 外，还需要 Azure 特
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
共享视频工具参数和提供商选择。
</Card>
<Card title="OAuth 与认证" href="/zh-CN/gateway/authentication" icon="key">
<Card title="OAuth 和认证" href="/zh-CN/gateway/authentication" icon="key">
认证细节和凭证复用规则。
</Card>
</CardGroup>