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-21 05:17:34 +00:00
parent 4cf9aff46d
commit 8961d26631
1 changed files with 61 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,22 +1,22 @@
---
read_when:
- 你想在 OpenClaw 中使用 OpenAI 模型
- 你想使用 Codex 订阅身份验证，而不是 API 密钥
- 你希望使用 Codex 订阅认证，而不是 API 密钥
- 你需要更严格的 GPT-5 智能体执行行为
summary: 在 OpenClaw 中使用 API 密钥或 Codex 订阅来使用 OpenAI
title: OpenAI
x-i18n:
generated_at: "2026-04-21T04:00:25Z"
generated_at: "2026-04-21T05:16:43Z"
model: gpt-5.4
provider: openai
source_hash: e9ed926ed4d3cd7a0fd4e9e9859fcd81ab62134de625ccf0c66fc92c4273449f
source_hash: 172beb28b099e3d71998458408c9a6b32b03790d2b016351f724bc3f0d9d3245
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/*` 模型）
@ -25,7 +25,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
## 入门指南
选择你偏好的身份验证方式，并按照设置步骤操作。
选择你偏好的认证方式，并按照设置步骤操作。
<Tabs>
<Tab title="API 密钥（OpenAI Platform）">
@ -40,7 +40,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
openclaw onboard --auth-choice openai-api-key
```
或者直接传入密钥：
或直接传入密钥：
```bash
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
@ -55,7 +55,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
### 路由摘要
| 模型引用 | 路由 | 身份验证 |
| 模型引用 | 路由 | 认证 |
|-----------|-------|------|
| `openai/gpt-5.4` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.4-pro` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
@ -74,13 +74,13 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
```
<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">
@ -88,7 +88,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
openclaw onboard --auth-choice openai-codex
```
或者直接运行 OAuth：
或直接运行 OAuth：
```bash
openclaw models auth login --provider openai-codex
@ -108,13 +108,13 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
### 路由摘要
| 模型引用 | 路由 | 身份验证 |
| 模型引用 | 路由 | 认证 |
|-----------|-------|------|
| `openai-codex/gpt-5.4` | 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>
### 配置示例
@ -126,7 +126,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
```
<Tip>
如果新手引导复用了现有的 Codex CLI 登录，这些凭证将继续由 Codex CLI 管理。凭证过期时，OpenClaw 会先重新读取外部 Codex 来源，再将刷新的凭证写回 Codex 存储。
如果新手引导复用了现有的 Codex CLI 登录，这些凭证仍由 Codex CLI 管理。凭证过期时，OpenClaw 会先重新读取外部 Codex 来源，再将刷新后的凭证写回 Codex 存储。
</Tip>
### 上下文窗口上限
@ -138,7 +138,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
- 原生 `contextWindow`：`1050000`
- 默认运行时 `contextTokens` 上限：`272000`
较小的默认上限在实践中通常具有更好的延迟和质量表现。你可以用 `contextTokens` 覆盖它：
在实际使用中，较小的默认上限通常具有更好的延迟和质量表现。你可以使用 `contextTokens` 覆盖它：
```json5
{
@ -153,7 +153,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
```
<Note>
使用 `contextWindow` 声明模型的原生元数据。使用 `contextTokens` 限制运行时上下文预算。
使用 `contextWindow` 来声明模型的原生元数据。使用 `contextTokens` 来限制运行时上下文预算。
</Note>
</Tab>
@ -163,7 +163,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
内置的 `openai` 插件通过 `image_generate` 工具注册图像生成功能。
| 能力 | 值 |
| 功能 | 值 |
| ------------------------- | ---------------------------------- |
| 默认模型 | `openai/gpt-image-1` |
| 每次请求的最大图像数 | 4 |
@ -182,20 +182,20 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
```
<Note>
有关共享工具参数、提供商选择和故障切换行为，请参阅 [图像生成](/zh-CN/tools/image-generation)。
有关共享工具参数、提供商选择和故障转移行为，请参阅 [图像生成](/zh-CN/tools/image-generation)。
</Note>
## 视频生成
内置的 `openai` 插件通过 `video_generate` 工具注册视频生成功能。
| 能力 | 值 |
| 功能 | 值 |
| ---------------- | --------------------------------------------------------------------------------- |
| 默认模型 | `openai/sora-2` |
| 模式 | 文本生成视频、图像生成视频、单视频编辑 |
| 模式 | 文生视频、图生视频、单视频编辑 |
| 参考输入 | 1 张图像或 1 个视频 |
| 尺寸覆盖 | 支持 |
| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并产生工具警告 |
| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并附带工具警告 |
```json5
{
@ -208,18 +208,18 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
```
<Note>
有关共享工具参数、提供商选择和故障切换行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。
有关共享工具参数、提供商选择和故障转移行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。
</Note>
## GPT-5 提示词贡献
OpenClaw 会为 `openai/*` 和 `openai-codex/*` 的 GPT-5 系列运行添加一个 OpenAI 专用的 GPT-5 提示词贡献。它位于内置的 OpenAI 插件中，适用于 `gpt-5`、`gpt-5.2`、`gpt-5.4` 和 `gpt-5.4-mini` 等模型 id，不适用于较旧的 GPT-4.x 模型。
GPT-5 提示词贡献默认会添加一个带标签的行为契约，涵盖输出形态、工具持续性、依赖检查、并行查找、完成检查、验证和自主性。这些指导对于匹配的 GPT-5 模型始终启用。友好交互风格层则是独立的，并且可配置。
GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人格持续性、执行安全、工具纪律、输出形态、完成检查和验证。渠道特定的回复行为和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站投递策略中。对于匹配的模型，GPT-5 指导始终启用。友好互动风格层是独立的，并且可配置。
| 值 | 效果 |
| ---------------------- | ------------------------------------------- |
| `"friendly"`（默认） | 启用友好交互风格层 |
| `"friendly"`（默认） | 启用友好互动风格层 |
| `"on"` | `"friendly"` 的别名 |
| `"off"` | 仅禁用友好风格层 |
@ -250,19 +250,19 @@ GPT-5 提示词贡献默认会添加一个带标签的行为契约，涵盖输
<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` |
| 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
{
@ -277,13 +277,13 @@ GPT-5 提示词贡献默认会添加一个带标签的行为契约，涵盖输
```
<Note>
设置 `OPENAI_TTS_BASE_URL` 可以覆盖 TTS 的基础 URL，而不影响聊天 API 端点。
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 Base URL，而不会影响聊天 API 端点。
</Note>
</Accordion>
<Accordion title="实时转写">
内置的 `openai` 插件为 Voice Call 插件注册了实时转写功能。
<Accordion title="实时转录">
内置的 `openai` 插件为 Voice Call 插件注册实时转录功能。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
@ -293,18 +293,18 @@ GPT-5 提示词贡献默认会添加一个带标签的行为契约，涵盖输
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
<Note>
使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，并采用 G.711 u-law 音频。
使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law 音频。
</Note>
</Accordion>
<Accordion title="实时语音">
内置的 `openai` 插件为 Voice Call 插件注册了实时语音功能。
内置的 `openai` 插件为 Voice Call 插件注册实时语音功能。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
| 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime` |
| 声音 | `...openai.voice` | `alloy` |
| 音色 | `...openai.voice` | `alloy` |
| 温度 | `...openai.temperature` | `0.8` |
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
| 静音时长 | `...openai.silenceDurationMs` | `500` |
@ -321,19 +321,19 @@ GPT-5 提示词贡献默认会添加一个带标签的行为契约，涵盖输
<AccordionGroup>
<Accordion title="传输方式（WebSocket 与 SSE）">
对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都默认采用 WebSocket 优先并在失败时回退到 SSE（`"auto"`）。
对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都默认使用 WebSocket 优先并在失败时回退到 SSE（`"auto"`）。
在 `"auto"` 模式下，OpenClaw 会：
- 在回退到 SSE 之前，对一次早期 WebSocket 失败进行重试
- 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
- 发生失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
- 为重试和重连附加稳定的会话与轮次标识头
- 在不同传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`）
- 在不同传输变体之间规范化使用量计数器（`input_tokens` / `prompt_tokens`）
| 值 | 行为 |
|-------|----------|
| `"auto"`（默认） | WebSocket 优先，SSE 回退 |
| `"sse"` | 仅强制使用 SSE |
| `"websocket"` | 仅强制使用 WebSocket |
| `"auto"`（默认） | WebSocket 优先，失败回退到 SSE |
| `"sse"` | 强制仅使用 SSE |
| `"websocket"` | 强制仅使用 WebSocket |
```json5
{
@ -356,7 +356,7 @@ GPT-5 提示词贡献默认会添加一个带标签的行为契约，涵盖输
</Accordion>
<Accordion title="WebSocket 预热">
对于 `openai/*`，OpenClaw 默认启用 WebSocket 预热，以降低首次轮次延迟。
OpenClaw 默认对 `openai/*` 启用 WebSocket 预热，以降低首轮延迟。
```json5
// 禁用预热
@ -376,12 +376,12 @@ GPT-5 提示词贡献默认会添加一个带标签的行为契约，涵盖输
</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
{
@ -397,13 +397,13 @@ GPT-5 提示词贡献默认会添加一个带标签的行为契约，涵盖输
```
<Note>
会话级覆盖优先于配置。在会话 UI 中清除会话级覆盖后，会话将恢复为配置中的默认值。
会话级覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，该会话会恢复为配置的默认值。
</Note>
</Accordion>
<Accordion title="优先处理（service_tier）">
OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置它：
OpenAI 的 API 通过 `service_tier` 提供优先处理能力。你可以在 OpenClaw 中按模型进行设置：
```json5
{
@ -421,7 +421,7 @@ GPT-5 提示词贡献默认会添加一个带标签的行为契约，涵盖输
支持的值：`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`）。如果你通过代理路由任一提供商，OpenClaw 将保持 `service_tier` 不变。
</Warning>
</Accordion>
@ -429,13 +429,13 @@ GPT-5 提示词贡献默认会添加一个带标签的行为契约，涵盖输
<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
{
@ -487,7 +487,7 @@ GPT-5 提示词贡献默认会添加一个带标签的行为契约，涵盖输
</Tabs>
<Note>
`responsesServerCompaction` 仅控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性将 `supportsStore: false`。
`responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。
</Note>
</Accordion>
@ -505,31 +505,31 @@ GPT-5 提示词贡献默认会添加一个带标签的行为契约，涵盖输
}
```
在 `strict-agentic` 下，OpenClaw 会：
- 当工具操作可用时，不再将“仅计划”的轮次视为成功进展
- 使用“立即行动”的引导重试该轮次
- 对于较大工作自动启用 `update_plan`
- 如果模型持续规划却不执行，则显示明确的受阻状态
使用 `strict-agentic` 时，OpenClaw 会：
- 当工具操作可用时，不再将仅规划的轮次视为成功进展
- 使用“立即执行”的引导重试该轮次
- 对于实质性工作自动启用 `update_plan`
- 如果模型持续规划而不执行，则显式呈现阻塞状态
<Note>
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列保持默认行为。
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型家族仍保持默认行为。
</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 使用原生传输和兼容行为，但不会接收隐藏归因头。
@ -540,7 +540,7 @@ GPT-5 提示词贡献默认会添加一个带标签的行为契约，涵盖输
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障切换行为。
选择提供商、模型引用和故障转移行为。
</Card>
<Card title="图像生成" href="/zh-CN/tools/image-generation" icon="image">
共享图像工具参数和提供商选择。
@ -548,7 +548,7 @@ GPT-5 提示词贡献默认会添加一个带标签的行为契约，涵盖输
<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>