古法编程

Appearance

站长自营API 中转

国内开发者可试试 ZZSwitch

统一 Base URL、Key 和余额，适合 OpenCode / Claude Code / Codex 等工具接入。

打开 ZZSwitch
站长自营API 中转

正在比较模型套餐？可以把多个 AI API 接到一个网关里

ZZSwitch 是我自己运营的统一 API 网关，适合需要国内支付、兑换码充值、多模型切换和 OpenAI 兼容接口的开发者。不是 OpenCode 官方服务。

打开 ZZSwitch

在 OpenClaw 中使用 OpenAI 模型，首选两种认证方式：直接 API Key（按量计费）和 Codex 订阅 OAuth（需 ChatGPT 登录）。模型前缀统一为 openai/*，agent 模型默认走原生 Codex 运行时，无需手动指定运行时。旧式 openai-codex/* 前缀需要运行 openclaw doctor --fix 自动修复。关键限制：默认运行时上下文上限 272000 tokens（可通过 contextTokens 调整），图像透明背景需使用 gpt-image-1.5 并指定 outputFormat=png 和 background=transparent。完成认证后通过 /codex status 确认运行时状态。

OpenClaw 集成 OpenAI：API Key 与 Codex 订阅配置指南 ​

OpenAI 为 GPT 模型提供开发者 API，Codex 也可以通过 ChatGPT 订阅方案作为 Agent 使用。OpenClaw 将这两条路径分开管理，配置更可预测。

OpenClaw 使用 openai/* 作为 OpenAI 模型的标准路由。Agent 模型默认走原生 Codex 应用服务器运行时；直接 AI Platform API Key 认证对非 Agent 的 OpenAI 功能（图像、嵌入、语音、实时交互）仍然可用。

  • Agent 模型：openai/* 模型通过 Codex 运行时运行；使用 Codex OAuth 认证的 ChatGPT/Codex 订阅，或配置 Codex 兼容的 API Key 备份。
  • 非 Agent 的 OpenAI API：直接使用 OpenAI AI Platform 基于用量计费的 OPENAI_API_KEY 或 OpenAI API Key 引导配置。
  • 旧配置修复：openai-codex/* 模型引用可通过 openclaw doctor --fix 自动修复为 openai/* 加上 Codex 运行时。

OpenAI 明确支持在 OpenClaw 等外部工具中使用订阅 OAuth 接入。

Provider、Model、Runtime 和 Channel 是独立层级。如果概念混淆，建议先阅读 Agent 运行时 再修改配置。

快速选择指南 ​

目标使用说明
ChatGPT/Codex 订阅 + 原生 Codex 运行时openai/gpt-5.5默认 OpenAI Agent 配置，使用 Codex OAuth 登录
直接 API Key 计费（Agent 模型）openai/gpt-5.5 + Codex 兼容的 API Key 配置文件通过 auth.order.openai 将 API Key 放在订阅认证之后
直接 API Key 计费（明确使用 PI 运行时）openai/gpt-5.5 + provider/model runtime pi选择普通 openai API Key 配置文件
最新 ChatGPT Instant API 别名openai/chat-latest仅 API Key 模式，移动别名，不建议生产默认
ChatGPT/Codex 订阅认证 + 明确 PI 运行时openai/gpt-5.5 + provider/model runtime pi选择 openai-codex 认证配置文件（兼容路由）
图像生成或编辑openai/gpt-image-2支持 OPENAI_API_KEY 或 OpenAI Codex OAuth
透明背景图像openai/gpt-image-1.5必须使用 outputFormat=png 或 webp，并设置 openai.background=transparent

命名映射 ​

名字相似但不可互换：

你看到的名称层级含义
openaiProvider 前缀标准 OpenAI 模型路由；Agent 走 Codex 运行时
openai-codex旧认证/配置文件前缀旧式 OpenAI Codex OAuth/订阅配置文件命名空间。现有配置文件和 auth.order.openai-codex 仍然有效
codex 插件插件OpenClaw 内置插件，提供原生 Codex 应用服务器运行时和 /codex 聊天控制
provider/model agentRuntime.id: codexAgent 运行时强制使用原生 Codex 应用服务器 harness 处理匹配 Agent 的会话
/codex ...聊天命令集在对话中绑定/控制 Codex 应用服务器线程
runtime: "acp", agentId: "codex"ACP 会话路由显式回退路径，通过 ACP/acpx 运行 Codex

上述意味着配置可以有意使用 openai/* 模型引用，而认证配置文件仍指向 Codex 兼容的凭据。新建配置推荐使用 auth.order.openai；现有 openai-codex:* 配置文件和 auth.order.openai-codex 仍受支持。openclaw doctor --fix 将旧式 openai-codex/* 模型引用重写为标准 OpenAI 模型路由。

INFO

GPT-5.5 可通过直接 OpenAI AI Platform API Key 和订阅/OAuth 两种方式访问。要使用 ChatGPT/Codex 订阅 + 原生 Codex 运行时，使用 openai/gpt-5.5；不设置运行时配置则自动选择 Codex harness。仅当你想要直接 API Key 认证时才使用 OpenAI API Key 配置文件。

INFO

OpenAI Agent 模型会话需要内置的 Codex 应用服务器插件。显式的 PI 运行时配置作为可选兼容路由保留。当显式选择 PI 并配合 openai-codex 认证配置文件时，OpenClaw 保持公共模型引用为 openai/*，内部通过旧式 Codex-auth 传输将请求路由到 PI。运行 openclaw doctor --fix 可修复过时的 openai-codex/*、codex-cli/* 或旧 PI 会话 pin（非来自显式运行时配置）。

OpenClaw 功能覆盖 ​

OpenAI 能力OpenClaw 层面状态
Chat / Responsesopenai/<model> model provider支持
Codex 订阅模型openai/<model> + openai-codex OAuth支持
旧式 Codex 模型引用openai-codex/<model> 或 codex-cli/<model>通过 doctor 修复为 openai/<model>
Codex 应用服务器 harnessopenai/<model> 省略运行时或 provider/model agentRuntime.id: codex支持
服务端网络搜索原生 OpenAI Responses 工具支持，当 web search 启用且未固定 provider 时
图像image_generate支持
视频video_generate支持
文本转语音messages.tts.provider: "openai" / tts支持
批量语音转文本tools.media.audio / 媒体理解支持
流式语音转文本Voice Call streaming.provider: "openai"支持
实时语音Voice Call realtime.provider: "openai" / Control UI Talk支持
嵌入memory embedding provider支持

Memory 嵌入 ​

OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点进行 memory_search 索引和查询嵌入：

json5
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
      },
    },
  },
}

对于需要不对称嵌入标签的 OpenAI 兼容端点，在 memorySearch 下设置 queryInputType 和 documentInputType。OpenClaw 将这些作为 provider 特定的 input_type 请求字段转发：查询嵌入使用 queryInputType；索引的记忆块和批量索引使用 documentInputType。完整示例请参考 Memory 配置参考。

开始使用 ​

选择你偏好的认证方式，按步骤配置。

API Key（OpenAI AI Platform）

**适合：** 直接 API 访问，按用量计费。

获取 API Key

    从 [OpenAI AI Platform 后台](https://platform.openai.com/api-keys) 创建或复制 API Key。

运行引导向导

    ```bash
    openclaw onboard --auth-choice openai-api-key
    ```

    或直接传入 Key：

    ```bash
    openclaw onboard --openai-api-key "$OPENAI_API_KEY"
    ```

验证模型可用性

    ```bash
    openclaw models list --provider openai
    ```



### 路由汇总

| 模型引用 | 运行时配置 | 路由 | 认证 |
| --- | --- | --- | --- |
| `openai/gpt-5.5` | 省略 / provider/model `agentRuntime.id: "codex"` | Codex 应用服务器 harness | Codex 兼容的 OpenAI 配置文件 |
| `openai/gpt-5.4-mini` | 省略 / provider/model `agentRuntime.id: "codex"` | Codex 应用服务器 harness | Codex 兼容的 OpenAI 配置文件 |
| `openai/gpt-5.5` | provider/model `agentRuntime.id: "pi"` | PI 嵌入式运行时 | `openai` 配置文件或选定的 `openai-codex` 配置文件 |

INFO

`openai/*` Agent 模型使用 Codex 应用服务器 harness。要对 Agent 模型使用 API Key 认证，创建 Codex 兼容的 API Key 配置文件并通过 `auth.order.openai` 排序；`OPENAI_API_KEY` 仍作为非 Agent OpenAI API 层面的直接回退。旧的 `auth.order.openai-codex` 条目仍然有效。

### 配置示例

```json5
{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
}
```

要从 OpenAI API 尝试 ChatGPT 的当前 Instant 模型，将模型设置为 `openai/chat-latest`：

```json5
{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/chat-latest" } } },
}
```

`chat-latest` 是移动别名。OpenAI 文档声明该别名对应 ChatGPT 中使用的 Latest Instant 模型，并推荐 `gpt-5.5` 用于生产 API 使用，因此除非你明确需要该别名行为，否则保持 `openai/gpt-5.5` 作为稳定默认值。该别名目前只接受 `medium` 文本详尽度，因此 OpenClaw 会为此模型规范化不兼容的 OpenAI 文本详尽度覆盖。

WARNING

OpenClaw **不**暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，当前 Codex 目录也未暴露它。

Codex 订阅

**适合：** 使用 ChatGPT/Codex 订阅，且不需要额外 API Key，直接享有原生 Codex 应用服务器执行。Codex 云需要 ChatGPT 登录。

运行 Codex OAuth

    ```bash
    openclaw onboard --auth-choice openai-codex
    ```

    或直接运行 OAuth：

    ```bash
    openclaw models auth login --provider openai-codex
    ```

    对于无头或回调受限的环境，添加 `--device-code` 以使用 ChatGPT 设备码流程而非本地回环浏览器回调：

    ```bash
    openclaw models auth login --provider openai-codex --device-code
    ```

使用标准 OpenAI 模型路由

    ```bash
    openclaw config set agents.defaults.model.primary openai/gpt-5.5
    ```

    默认路径不需要运行时配置。OpenAI Agent 会话自动选择原生 Codex 应用服务器运行时，OpenClaw 会在选择该路由时安装或修复内置的 Codex 插件。

验证 Codex 认证是否可用

    ```bash
    openclaw models list --provider openai-codex
    ```

    Gateway 启动后，在聊天中发送 `/codex status` 或 `/codex models` 验证原生应用服务器运行时。



### 路由汇总

| 模型引用 | 运行时配置 | 路由 | 认证 |
| --- | --- | --- | --- |
| `openai/gpt-5.5` | 省略 / provider/model `agentRuntime.id: "codex"` | 原生 Codex 应用服务器 harness | Codex 登录或排序后的 `openai` 认证配置文件 |
| `openai/gpt-5.5` | provider/model `agentRuntime.id: "pi"` | PI 嵌入式运行时（内部 Codex-auth 传输） | 选定的 `openai-codex` 配置文件 |
| `openai-codex/gpt-5.5` | 由 doctor 修复 | 旧路由重写为 `openai/gpt-5.5` | 现有 `openai-codex` 配置文件 |
| `codex-cli/gpt-5.5` | 由 doctor 修复 | 旧 CLI 路由重写为 `openai/gpt-5.5` | Codex 应用服务器认证 |

WARNING

新建订阅 Agent 配置推荐使用 `openai/gpt-5.5`。旧的 `openai-codex/gpt-*` 引用是旧式 PI 路由，不是原生 Codex 运行时路径；需要迁移到标准 `openai/*` 引用时运行 `openclaw doctor --fix`。

INFO

`openai-codex/*` 模型前缀是旧式配置，由 doctor 修复。对于常见的订阅 + 原生运行时设置，使用 Codex 认证登录但保持模型引用为 `openai/gpt-5.5`。新建配置应将 OpenAI Agent 认证排序放在 `auth.order.openai` 下；旧的 `auth.order.openai-codex` 条目仍然有效。

### 配置示例

```json5
{
  plugins: { entries: { codex: { enabled: true } } },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.5" },
    },
  },
}
```

带有 API Key 备份的情况，保持模型为 `openai/gpt-5.5`，将认证排序放在 `openai` 下。OpenClaw 会先尝试订阅，再尝试 API Key，同时保持在 Codex harness 上：

```json5
{
  plugins: { entries: { codex: { enabled: true } } },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.5" },
    },
  },
  auth: {
    order: {
      openai: [
        "openai-codex:user@example.com",
        "openai:api-key-backup",
      ],
    },
  },
}
```

INFO

引导向导不再从 `~/.codex` 导入 OAuth 材料。使用浏览器 OAuth（默认）或上面提到的设备码流程——OpenClaw 在其自己的 Agent 认证存储中管理生成的凭据。

### 检查并恢复 Codex OAuth 路由

使用以下命令查看默认 Agent 正在使用的模型、运行时和认证路由：

```bash
openclaw models status
openclaw models auth list --provider openai-codex
openclaw config get agents.defaults.model --json
openclaw config get models.providers.openai.agentRuntime --json
```

对特定 Agent，添加 `--agent <id>`：

```bash
openclaw models status --agent <id>
openclaw models auth list --agent <id> --provider openai-codex
```

如果旧配置仍然包含 `openai-codex/gpt-*` 或过时的 OpenAI PI 会话 pin（没有显式运行时配置），修复它：

```bash
openclaw doctor --fix
openclaw config validate
```

如果 `models auth list --provider openai-codex` 显示没有可用配置文件，重新登录：

```bash
openclaw models auth login --provider openai-codex
openclaw models status --probe --probe-provider openai-codex
```

`openai/*` 是 OpenAI Agent 会话通过 Codex 的模型路由。`openai-codex` 认证/配置文件 provider ID 对现有配置文件和 CLI 列出仍然有效。

### 状态指示器

聊天 `/status` 显示当前会话激活的模型运行时。内置的 Codex 应用服务器 harness 在 OpenAI Agent 模型会话中显示为 `Runtime: OpenAI Codex`。除非配置显式固定 PI，否则过时的 PI 会话 pin 会被修复为 Codex。

### Doctor 警告

如果 `openai-codex/*` 路由或过时的 OpenAI PI pin 仍然在配置或会话状态中，`openclaw doctor --fix` 会将其重写为 `openai/*` 及 Codex 运行时，除非显式配置了 PI。

### 上下文窗口上限

OpenClaw 将模型元数据和运行时上下文上限视为不同值。

对于 `openai/gpt-5.5` 通过 Codex OAuth 目录：

- 原生 `contextWindow`：`1000000`
- 默认运行时 `contextTokens` 上限：`272000`

较小的默认上限在实践中能提供更优的延迟和质量。可通过 `contextTokens` 覆盖：

```json5
{
  models: {
    providers: {
      "openai-codex": {
        models: [{ id: "gpt-5.5", contextTokens: 160000 }],
      },
    },
  },
}
```

INFO

使用 `contextWindow` 声明原生模型元数据。使用 `contextTokens` 限制运行时上下文预算。

### 目录恢复

当上游 Codex 目录存在时，OpenClaw 使用其 `gpt-5.5` 的元数据。如果实时 Codex 发现过程省略了 `gpt-5.5` 行但账户已认证，OpenClaw 会合成该 OAuth 模型行，以免 cron、子 Agent 和配置的默认模型运行因 `Unknown model` 失败。

原生 Codex 应用服务器认证 ​

原生 Codex 应用服务器 harness 使用 openai/* 模型引用加上省略的运行时配置或 provider/model agentRuntime.id: "codex"，但其认证仍然是基于账户的。OpenClaw 按以下顺序选择认证：

  1. 按顺序配置的 OpenAI 认证配置文件（优先使用 auth.order.openai）。现有 openai-codex:* 配置文件和 auth.order.openai-codex 对旧安装仍有效。
  2. 应用服务器现有的账户，例如本地 Codex CLI ChatGPT 登录。
  3. 仅对本地 stdio 应用服务器启动，当应用服务器报告没有账户但仍需要 OpenAI 认证时，使用 CODEX_API_KEY，然后 OPENAI_API_KEY。

这意味着本地 ChatGPT/Codex 订阅登录不会因为 gateway 进程也设置了 OPENAI_API_KEY（用于直接 OpenAI 模型或嵌入）而被替换。环境变量 API Key 回退仅是本地 stdio 无账户路径；不会发送到 WebSocket 应用服务器连接。当选择了订阅风格的 Codex 配置文件时，OpenClaw 也会将 CODEX_API_KEY 和 OPENAI_API_KEY 排除在生成的 stdio 应用服务器子进程之外，并通过应用服务器登录 RPC 发送选定的凭据。当该订阅配置文件被 Codex 使用限制阻止时，OpenClaw 可以轮转到下一个排序的 openai:* API Key 配置文件，而无需更改选定的模型或跳出 Codex harness。一旦订阅重置时间过去，订阅配置文件就再次可用。

图像生成 ​

内置的 openai 插件通过 image_generate 工具注册图像生成。它通过同一个 openai/gpt-image-2 模型引用同时支持 OpenAI API Key 图像生成和 Codex OAuth 图像生成。

能力OpenAI API KeyCodex OAuth
模型引用openai/gpt-image-2openai/gpt-image-2
认证OPENAI_API_KEYOpenAI Codex OAuth 登录
传输OpenAI Images APICodex Responses 后端
每次请求最大图像数44
编辑模式支持（最多 5 张参考图像）支持（最多 5 张参考图像）
尺寸覆盖支持，包括 2K/4K 尺寸支持，包括 2K/4K 尺寸
宽高比 / 分辨率不转发给 OpenAI Images API安全时映射到支持的尺寸
json5
{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-2" },
    },
  },
}

INFO

查看 图像生成 了解共享工具参数、provider 选择和故障转移行为。

gpt-image-2 是 OpenAI 文本到图像生成和图像编辑的默认模型。gpt-image-1.5、gpt-image-1 和 gpt-image-1-mini 仍然可以作为显式模型覆盖使用。使用 openai/gpt-image-1.5 进行透明背景 PNG/WebP 输出；当前 gpt-image-2 API 拒绝 background: "transparent"。

对于透明背景请求，Agent 应调用 image_generate 并设置 model: "openai/gpt-image-1.5"、outputFormat: "png" 或 "webp"、background: "transparent"；旧的 openai.background provider 选项仍然受支持。OpenClaw 还会保护公共 OpenAI 和 OpenAI Codex OAuth 路由，将默认的 openai/gpt-image-2 透明请求重写为 gpt-image-1.5；Azure 和自定义 OpenAI 兼容端点保留其配置的 deployment/model 名称。

同样的设置在无头 CLI 中也适用：

bash
openclaw infer image generate \
  --model openai/gpt-image-1.5 \
  --output-format png \
  --background transparent \
  --prompt "A simple red circle sticker on a transparent background" \
  --json

从输入文件开始使用 openclaw infer image edit 时，使用相同的 --output-format 和 --background 标志。--openai-background 作为 OpenAI 特定的别名仍然可用。

对于 Codex OAuth 安装，保持相同的 openai/gpt-image-2 引用。当配置了 openai-codex OAuth 配置文件时，OpenClaw 会解析存储的 OAuth 访问令牌并通过 Codex Responses 后端发送图像请求。它不会首先尝试 OPENAI_API_KEY 或静默回退到该请求的 API Key。当你希望直接使用 OpenAI Images API 路由时，显式配置 models.providers.openai 并设置 API Key、自定义 base URL 或 Azure 端点。 如果该自定义图像端点在受信任的 LAN/私有地址上，还需设置 browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true；OpenClaw 默认阻止私有/内部的 OpenAI 兼容图像端点，除非设置了此选项。

生成：

/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1

生成透明 PNG：

/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent

编辑：

/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

视频生成 ​

内置的 openai 插件通过 video_generate 工具注册视频生成。

能力值
默认模型openai/sora-2
模式文本转视频、图像转视频、单视频编辑
参考输入1 张图像或 1 段视频
尺寸覆盖支持
其他覆盖aspectRatio、resolution、audio、watermark 被忽略，并给出工具警告
json5
{
  agents: {
    defaults: {
      videoGenerationModel: { primary: "openai/sora-2" },
    },
  },
}

INFO

查看 视频生成 了解共享工具参数、provider 选择和故障转移行为。

GPT-5 Prompt 贡献 ​

OpenClaw 为 GPT-5 系列模型在 OpenClaw 组装的推理表面上添加一个共享的 GPT-5 Prompt 贡献。它根据模型 ID 应用，因此 PI/provider 路由（如旧修复前的 openai-codex/gpt-5.5、openrouter/openai/gpt-5.5、opencode/gpt-5.5 和其他兼容的 GPT-5 引用）都会收到相同的叠加。旧的 GPT-4.x 模型不受影响。

内置的原生 Codex harness 不会通过 Codex 应用服务器开发者指令接收到这个 OpenClaw GPT-5 叠加层。原生 Codex 保留 Codex 自身的基础、模型、个性化和项目文档行为；OpenClaw 只贡献运行时上下文，如渠道投递、OpenClaw 动态工具、ACP 委托、工作区上下文和 OpenClaw 技能。

GPT-5 贡献添加了一个标记化的行为契约，用于个性持久化、执行安全性、工具纪律、输出形状、完成检查以及对匹配的 OpenClaw 组装推理表面进行验证。渠道特定的回复和静默消息行为保留在共享的 OpenClaw 系统 prompt 和外发投递策略中。友好的交互风格层是独立的且可配置。

值效果
"friendly"（默认）启用友好的交互风格层
"on""friendly" 的别名
"off"仅禁用友好风格层

配置

```json5
{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: { personality: "friendly" },
      },
    },
  },
}
```

CLI

```bash
openclaw config set agents.defaults.promptOverlays.gpt5.personality off
```

TIP

值在运行时大小写不敏感，因此 "Off" 和 "off" 都会禁用友好风格层。

INFO

旧的 plugins.entries.openai.config.personality 作为兼容性回退仍然会被读取，当共享的 agents.defaults.promptOverlays.gpt5.personality 设置未定义时使用。

语音和语音 ​

语音合成（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.instructions` | （未设置，仅 `gpt-4o-mini-tts`） |
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音笔记为 `opus`，文件为 `mp3` |
| API Key | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` |
| Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
| 额外 body | `messages.tts.providers.openai.extraBody` / `extra_body` | （未设置） |

可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用音色：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。

`extraBody` 会合并到 `/audio/speech` 请求 JSON 中（在 OpenClaw 生成的字段之后），因此可用于需要额外键（如 `lang`）的 OpenAI 兼容端点。原型键会被忽略。

```json5
{
  messages: {
    tts: {
      providers: {
        openai: { model: "gpt-4o-mini-tts", voice: "coral" },
      },
    },
  },
}
```

INFO

设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 基础 URL，而不影响聊天 API 端点。OpenAI TTS 仍然通过 API Key 配置；对于仅 OAuth 的实时对话回讲，请使用 Realtime 语音路径而不是 Agent 模式 STT → TTS 语音。

语音转文本

内置的 `openai` 插件通过 OpenClaw 的媒体理解转录表面注册了批量语音转文本。

- 默认模型：`gpt-4o-transcribe`
- 端点：OpenAI REST `/v1/audio/transcriptions`
- 输入路径：多部分音频文件上传
- OpenClaw 在需要入站音频转录的地方都支持，包括 Discord 语音频道片段和频道音频附件

强制 OpenAI 用于入站音频转录：

```json5
{
  tools: {
    media: {
      audio: {
        models: [
          {
            type: "provider",
            provider: "openai",
            model: "gpt-4o-transcribe",
          },
        ],
      },
    },
  },
}
```

当共享音频媒体配置或每次调用转录请求提供语言和提示时，它们会转发给 OpenAI。

实时转录

内置的 `openai` 插件为 Voice Call 插件注册了实时转录。

| 设置 | 配置路径 | 默认值 |
| --- | --- | --- |
| 模型 | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
| 语言 | `...openai.language` | （未设置） |
| 提示 | `...openai.prompt` | （未设置） |
| 静音持续时间 | `...openai.silenceDurationMs` | `800` |
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
| 认证 | `...openai.apiKey`、`OPENAI_API_KEY` 或 `openai-codex` OAuth | API Key 直接连接；OAuth 生成一个实时转录客户端密钥 |

INFO

使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，音频格式为 G.711 μ-law（`g711_ulaw` / `audio/pcmu`）。当仅配置了 `openai-codex` OAuth 时，Gateway 在打开 WebSocket 之前会生成一个临时实时转录客户端密钥。此流式 provider 用于 Voice Call 的实时转录路径；Discord 语音当前记录短片段并改用批量 `tools.media.audio` 转录路径。

实时语音

内置的 `openai` 插件为 Voice Call 插件注册了实时语音。

| 设置 | 配置路径 | 默认值 |
| --- | --- | --- |
| 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-2` |
| 音色 | `...openai.voice` | `alloy` |
| 温度（Azure 部署桥接） | `...openai.temperature` | `0.8` |
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
| 静音持续时间 | `...openai.silenceDurationMs` | `500` |
| 前缀填充 | `...openai.prefixPaddingMs` | `300` |
| 推理努力 | `...openai.reasoningEffort` | （未设置） |
| 认证 | `...openai.apiKey`、`OPENAI_API_KEY` 或 `openai-codex` OAuth | 浏览器 Talk 和非 Azure 后端桥接可以使用 Codex OAuth |

`gpt-realtime-2` 可用的内置实时音色：`alloy`、`ash`、`ballad`、`coral`、`echo`、`sage`、`shimmer`、`verse`、`marin`、`cedar`。OpenAI 推荐 `marin` 和 `cedar` 以获得最佳实时质量。这是与文本转语音音色不同的集合；不要假定 TTS 音色（如 `fable`、`nova`、`onyx`）对实时会话有效。

INFO

后端 OpenAI 实时桥接使用 GA Realtime WebSocket 会话形状，该形状不接受 `session.temperature`。Azure OpenAI 部署仍然可通过 `azureEndpoint` 和 `azureDeployment` 使用，并保留部署兼容的会话形状。支持双向工具调用和 G.711 μ-law 音频。

INFO

实时语音在会话创建时选定。OpenAI 允许之后更改大多数字段，但一旦模型在该会话中发出音频，音色就无法更改。OpenClaw 当前以字符串形式暴露内置的实时音色 ID。

INFO

Control UI Talk 使用 OpenAI 浏览器实时会话，通过 Gateway 生成的临时客户端密钥和直接浏览器 WebRTC SDP 交换与 OpenAI Realtime API 通信。当未配置直接 OpenAI API Key 时，Gateway 可以使用选定的 `openai-codex` OAuth 配置文件生成该客户端密钥。Gateway 中继和 Voice Call 后端实时 WebSocket 桥接使用相同的 OAuth 回退用于原生 OpenAI 端点。维护者实时验证可用命令：`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`；OpenAI 部分同时验证后端 WebSocket 桥接和浏览器 WebRTC SDP 交换，不会记录机密信息。

Azure OpenAI 端点 ​

内置的 openai provider 可以针对 Azure OpenAI 资源进行图像生成，通过覆盖 base URL。在图像生成路径上，OpenClaw 检测 models.providers.openai.baseUrl 中的 Azure 主机名，并自动切换到 Azure 的请求形状。

INFO

实时语音使用单独的配置路径（plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint），不受 models.providers.openai.baseUrl 影响。请参阅 语音和语音 下的 实时语音 折叠面板了解其 Azure 设置。

在以下情况下使用 Azure OpenAI：

  • 你已有 Azure OpenAI 订阅、配额或企业协议
  • 你需要 Azure 提供的区域数据驻留或合规控制
  • 你希望将流量保持在现有 Azure 租户内

配置 ​

通过内置的 openai provider 进行 Azure 图像生成，将 models.providers.openai.baseUrl 指向你的 Azure 资源并设置 apiKey 为 Azure OpenAI Key（不是 OpenAI AI Platform Key）：

json5
{
  models: {
    providers: {
      openai: {
        baseUrl: "https://<your-resource>.openai.azure.com",
        apiKey: "<azure-openai-api-key>",
      },
    },
  },
}

OpenClaw 识别以下 Azure 主机后缀用于 Azure 图像生成路由：

  • *.openai.azure.com
  • *.services.ai.azure.com
  • *.cognitiveservices.azure.com

对于已识别的 Azure 主机上的图像生成请求，OpenClaw：

  • 发送 api-key 头部而非 Authorization: Bearer
  • 使用部署作用域路径（/openai/deployments/{deployment}/...）
  • 向每个请求追加 ?api-version=...
  • 使用 600s 默认请求超时用于 Azure 图像生成调用。每次调用的 timeoutMs 值仍然会覆盖此默认值。

其他 base URL（公共 OpenAI、OpenAI 兼容代理）保持标准 OpenAI 图像请求形状。

INFO

openai provider 的图像生成路径的 Azure 路由需要 OpenClaw 2026.4.22 或更高版本。旧版本将任何自定义 openai.baseUrl 当作公共 OpenAI 端点处理，并会在 Azure 图像部署上失败。

API 版本 ​

设置 AZURE_OPENAI_API_VERSION 可固定特定 Azure 预览版或正式版用于 Azure 图像生成路径：

bash
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"

当变量未设置时，默认值为 2024-12-01-preview。

模型名称就是部署名称 ​

Azure OpenAI 将模型绑定到部署。对于通过内置 openai provider 路由的 Azure 图像生成请求，OpenClaw 中的 model 字段必须是你在 Azure 门户中配置的部署名称，而非公共 OpenAI 模型 ID。

例如，你创建了一个名为 gpt-image-2-prod 的部署来服务 gpt-image-2：

/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1

相同的部署名称规则适用于通过内置 openai provider 路由的图像生成调用。

区域可用性 ​

Azure 图像生成目前仅在部分区域可用（例如 eastus2、swedencentral、polandcentral、westus3、uaenorth）。在创建部署之前检查 Microsoft 当前的区域列表，并确认特定模型在你所在区域可用。

参数差异 ​

Azure OpenAI 和公共 OpenAI 并非总是接受相同的图像参数。Azure 可能拒绝公共 OpenAI 允许的某些选项（例如 gpt-image-2 上的某些 background 值），或仅在特定模型版本上暴露它们。这些差异来自 Azure 和底层模型，而非 OpenClaw。如果 Azure 请求因验证错误失败，请在 Azure 门户中检查你的特定部署和 API 版本支持的参数集。

INFO

Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐藏属性头部——请参阅 高级配置 下的 Native vs OpenAI-compatible routes 折叠面板。

对于非图像生成的聊天或 Responses 流量（在 Azure 上），使用引导流程或专门的 Azure provider 配置——仅设置 openai.baseUrl 不会拾取 Azure API/认证形状。存在单独的 azure-openai-responses/* provider；请参阅下面的服务端压缩折叠面板。

高级配置 ​

传输方式（WebSocket vs SSE）

OpenClaw 使用 WebSocket 优先，SSE 回退（`"auto"`）用于 `openai/*`。

在 `"auto"` 模式下，OpenClaw：
- 在回退到 SSE 之前重试一次早期 WebSocket 失败
- 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
- 为重试和重连附加稳定的会话和会话身份头部
- 标准化跨传输变体的使用计数（`input_tokens` / `prompt_tokens`）

| 值 | 行为 |
| --- | --- |
| `"auto"`（默认） | WebSocket 优先，SSE 回退 |
| `"sse"` | 强制仅 SSE |
| `"websocket"` | 强制仅 WebSocket |

```json5
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { transport: "auto" },
        },
      },
    },
  },
}
```

相关 OpenAI 文档：
- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)

Fast Mode

OpenClaw 为 `openai/*` 暴露了共享的 Fast Mode 切换：

- **聊天/UI：** `/fast status|on|off`
- **配置：** `agents.defaults.models["&lt;provider&gt;/&lt;model&gt;"].params.fastMode`

启用后，OpenClaw 将 Fast Mode 映射到 OpenAI 优先级处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，Fast Mode 不会重写 `reasoning` 或 `text.verbosity`。

```json5
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": { params: { fastMode: true } },
      },
    },
  },
}
```

INFO

会话覆盖优先于配置。在会话 UI 中清除会话覆盖会将会话恢复为配置的默认值。

优先级处理（service_tier）

OpenAI API 通过 `service_tier` 暴露优先级处理。在 OpenClaw 中按模型设置：

```json5
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": { params: { serviceTier: "priority" } },
      },
    },
  },
}
```

支持的值：`auto`、`default`、`flex`、`priority`。

WARNING

`serviceTier` 仅转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你将任一 provider 通过代理路由，OpenClaw 不会注入 `service_tier`。

服务端压缩（Responses API）

对于直接 OpenAI Responses 模型（`openai/*` 在 `api.openai.com` 上），OpenAI 插件的 Pi-harness 流包装器自动启用服务端压缩：

- 强制 `store: true`（除非模型兼容性设置 `supportsStore: false`）
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
- 默认 `compact_threshold`：模型 `contextWindow` 的 70%（若不可用则为 `80000`）

这适用于内置 Pi harness 路径和嵌入式运行使用的 OpenAI provider 钩子。原生 Codex 应用服务器 harness 通过 Codex 管理自己的上下文，并由 OpenAI 默认 Agent 路由或 provider/model 运行时策略配置。

显式启用

    对兼容端点（如 Azure OpenAI Responses）有用：

    ```json5
    {
      agents: {
        defaults: {
          models: {
            "azure-openai-responses/gpt-5.5": {
              params: { responsesServerCompaction: true },
            },
          },
        },
      },
    }
    ```

自定义阈值

    ```json5
    {
      agents: {
        defaults: {
          models: {
            "openai/gpt-5.5": {
              params: {
                responsesServerCompaction: true,
                responsesCompactThreshold: 120000,
              },
            },
          },
        },
      },
    }
    ```

禁用

    ```json5
    {
      agents: {
        defaults: {
          models: {
            "openai/gpt-5.5": {
              params: { responsesServerCompaction: false },
            },
          },
        },
      },
    }
    ```

INFO

`responsesServerCompaction` 仅控制 `context_management` 注入。直接 OpenAI Responses 模型仍然强制 `store: true`，除非兼容性设置 `supportsStore: false`。

Strict-agentic GPT 模式

对于 `openai/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行契约：

```json5
{
  agents: {
    defaults: {
      embeddedPi: { executionContract: "strict-agentic" },
    },
  },
}
```

使用 `strict-agentic`，OpenClaw：
- 不再将有工具动作可用时的仅计划会话视为成功进展
- 使用“立即行动”提示重试会话
- 自动启用 `update_plan` 用于实质性工作
- 如果模型持续计划而不行动，则显示显式阻塞状态

INFO

仅适用于 OpenAI 和 Codex GPT-5 系列运行。其他 provider 和旧模型系列保持默认行为。

原生 vs OpenAI 兼容路由

OpenClaw 将直接 OpenAI、Codex 和 Azure OpenAI 端点与通用 OpenAI 兼容 `/v1` 代理区别对待：

**原生路由**（`openai/*`、Azure OpenAI）：
- 仅对支持 OpenAI `none` 努力的模型保留 `reasoning: { effort: "none" }`
- 省略对拒绝 `reasoning.effort: "none"` 的模型或代理的禁用推理
- 默认工具 schema 为严格模式
- 仅在验证的原生主机上附加隐藏属性头部
- 保留 OpenAI 专属请求形状（`service_tier`、`store`、推理兼容性、prompt-cache 提示）

**代理/兼容路由**：
- 使用更宽松的兼容性行为
- 从非原生 `openai-completions` 载荷中剥离 Completions `store`
- 接受高级 `params.extra_body`/`params.extraBody` 传递 JSON 用于 OpenAI 兼容 Completions 代理
- 接受 `params.chat_template_kwargs` 用于 OpenAI 兼容 Completions 代理（如 vLLM）
- 不强制严格工具 schema 或原生专属头部

Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏属性头部。

相关文档 ​

模型选择

选择 Provider、模型引用和故障转移行为。

图像生成

共享图像工具参数和 Provider 选择。

视频生成

共享视频工具参数和 Provider 选择。

OAuth 和认证

认证细节和凭据复用规则。

常见问题 ​

API Key 方式和 Codex 订阅 OAuth 有什么区别？ ​

API Key 按实际 token 用量计费，适合生产环境和高频使用。Codex 订阅 OAuth 消耗 ChatGPT 订阅配额，适合已有订阅且用量不大的场景。两者的模型前缀相同（openai/*），但认证配置不同：API Key 使用 OPENAI_API_KEY 或 AI Platform Key 配置文件，Codex 使用 openai-codex OAuth 配置文件并通过 auth.order.openai 排序。

openai-codex/* 模型前缀报错怎么解决？ ​

旧式 openai-codex/* 模型引用是旧配置，推荐运行 openclaw doctor --fix 自动修复为标准 openai/* 模型路由。修复后配置中的模型引用会更新为 openai/gpt-5.5 等，认证仍然是 Codex OAuth 配置文件。如果修复后仍不可用，检查 openclaw models auth list --provider openai-codex 是否有可用配置文件，若没有则重新运行 openclaw models auth login --provider openai-codex。

OpenClaw 中 OpenAI 图像的透明背景怎么配置？ ​

当前 gpt-image-2 API 拒绝 background: "transparent"。要生成透明背景图像，必须使用 openai/gpt-image-1.5 模型，并在调用 image_generate 时设置 outputFormat=png（或 webp）和 background=transparent。OpenClaw 会自动将默认 gpt-image-2 的透明请求重写为 gpt-image-1.5，但建议在代码中显式指定。CLI 命令示例：openclaw infer image generate --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "..."。

站长自营API 中转

ZZSwitch API 中转

统一接入多家模型，支持兑换码充值。

打开 ZZSwitch

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策