Skip to main content
OpenAI 为 GPT 模型提供开发者 API，Codex 也可通过 OpenAI 的 Codex 客户端以 ChatGPT 方案代码代理的形式使用。OpenClaw 对这两种认证形式都使用同一个 提供方 id：openai。 OpenClaw 使用 openai/* 作为 OpenAI 的规范模型路由。嵌入式代理转为 OpenAI 模型时，默认通过原生 Codex 应用服务器运行时；对于图像、嵌入、语音和实时等 非代理 OpenAI 界面，仍可直接使用 OpenAI API 密钥认证。
  • 代理模型 - 通过 Codex 运行时使用 openai/* 模型；使用 Codex 认证登录以支持 ChatGPT/Codex 订阅，或者在你明确想要 API 密钥认证时 配置一个兼容 Codex 的 OpenAI API 密钥备用方案。
  • 非代理 OpenAI API - 通过 OPENAI_API_KEY 或 OpenAI API 密钥引导 直接访问 OpenAI Platform，采用按使用量计费。
  • 旧配置 - 旧版 Codex 模型引用会通过 openclaw doctor --fix 修复为 openai/* 以及 Codex 运行时。
OpenAI 明确支持在 OpenClaw 之类的外部工具和工作流中使用订阅 OAuth。 提供方、模型、运行时和通道是分开的层。如果这些标签 混在一起了，请在更改配置前先阅读 代理运行时。

​
快速选择

目标使用方式说明
使用原生 Codex 运行时的 ChatGPT/Codex 订阅openai/gpt-5.5默认 OpenAI 代理设置。使用 Codex 认证登录。
代理模型的直接 API 密钥计费openai/gpt-5.5 加上兼容 Codex 的 API 密钥配置文件使用 auth.order.openai 将备用方案排在订阅认证之后。
通过显式 OpenClaw 的直接 API 密钥计费openai/gpt-5.5 加上 provider/model 运行时 openclaw选择普通的 openai API 密钥配置文件。
最新的 ChatGPT Instant API 别名openai/chat-latest仅支持直接 API 密钥。用于实验的移动别名，不是默认值。
通过 OpenClaw 使用 ChatGPT/Codex 订阅认证openai/gpt-5.5 加上 provider/model 运行时 openclaw选择一个 openai OAuth 配置文件以走兼容路线。
图像生成或编辑openai/gpt-image-2可使用 OPENAI_API_KEY 或 OpenAI Codex OAuth。
透明背景图像openai/gpt-image-1.5使用 outputFormat=png 或 webp，并设置 openai.background=transparent。

​
命名映射

这些名称相似，但不能互换：
你看到的名称所属层含义
openai提供方前缀OpenAI 的规范模型路由；代理回合使用 Codex 运行时。
旧版 OpenAI Codex 前缀旧前缀较旧的模型/配置文件命名空间。openclaw doctor --fix 会将其迁移为 openai。
codex 插件插件内置的 OpenClaw 插件，提供原生 Codex 应用服务器运行时和 /codex 聊天控制。
provider/model agentRuntime.id: codex代理运行时为匹配的嵌入式回合强制使用原生 Codex 应用服务器宿主。
/codex ...聊天命令集从对话中绑定/控制 Codex 应用服务器线程。
runtime: "acp", agentId: "codex"ACP 会话路由通过 ACP/acpx 运行 Codex 的显式备用路径。
这意味着一个配置可以有意包含 openai/* 模型引用，同时认证配置文件指向 API 密钥 或 ChatGPT/Codex OAuth 凭据。配置时使用 auth.order.openai；openclaw doctor --fix 会重写旧的 旧版 Codex 模型引用、旧的 Codex 认证配置文件 id，以及 旧的 Codex 认证顺序，改为规范的 OpenAI 路由。
GPT-5.5 可通过直接 OpenAI Platform API 密钥访问以及 订阅/OAuth 路由获取。对于 ChatGPT/Codex 订阅加原生 Codex 执行，请使用 openai/gpt-5.5；未设置运行时配置时会为 OpenAI 代理回合选择 Codex 执行环境。仅当你想为 OpenAI 代理模型使用直接 API 密钥认证时，才使用 OpenAI API 密钥配置文件。
OpenAI 代理模型回合需要内置的 Codex 应用服务器插件。显式 OpenClaw 运行时配置仍可作为可选的兼容路线使用。当 OpenClaw 与 openai OAuth 配置文件 显式配合使用时，OpenClaw 会保留公开模型引用为 openai/*，并在内部通过 Codex 认证 传输路由。运行 openclaw doctor --fix 可修复过时的 旧版 Codex 模型引用、codex-cli/*，或并非来自 显式运行时配置的旧运行时会话固定。

​
OpenClaw 功能覆盖

OpenAI 功能OpenClaw 暴露方式状态
聊天 / Responsesopenai/<model> 模型提供方是
Codex 订阅模型使用 OpenAI OAuth 的 openai/<model>是
旧版 Codex 模型引用旧版 Codex 模型引用或 codex-cli/<model>由 doctor 修复为 openai/<model>
Codex 应用服务器宿主openai/<model>，未指定运行时，或 provider/model agentRuntime.id: codex是
服务端网页搜索原生 OpenAI Responses 工具是，在启用网页搜索且未固定提供方时可用
图像image_generate是
视频video_generate是
文本转语音messages.tts.provider: "openai" / tts是
批量语音转文本tools.media.audio / media understanding是
流式语音转文本Voice Call streaming.provider: "openai"是
实时语音Voice Call realtime.provider: "openai" / Control UI Talk talk.realtime.provider: "openai"是（需要 OpenAI Platform credits，不是 Codex/ChatGPT 订阅）
嵌入内存嵌入提供方是
OpenAI Realtime 语音（由 Voice Call 的 realtime.provider: "openai" 和 使用 talk.realtime.provider: "openai" 的 Control UI Talk）通过 公开的 OpenAI Platform Realtime API 运行，费用计入 OpenAI Platform credits，而不是 Codex/ChatGPT 订阅额度。即使一个账户的 OpenAI OAuth 正常， 能够无问题运行基于 Codex 的聊天模型，若同一个 OpenAI 组织没有设置 Platform 计费， 在第一次 Realtime 回合时仍然可能遇到 insufficient_quota / “You exceeded your current quota”。修复方法：为支持你的 realtime 凭据的组织在 platform.openai.com/account/billing 补充 Platform credits。Realtime 既可以接受 Platform OPENAI_API_KEY（通过 talk.realtime.providers.openai.apiKey 为 Control UI Talk 配置，或通过 plugins.entries.voice-call.config.realtime.providers.openai.apiKey 为 Voice Call 配置），也可以接受底层组织已开通 Platform 计费的 openai OAuth 配置文件——两种路径都会通过 Platform API 生成 Realtime 客户端密钥，因此无论哪种方式，组织都需要有足额的 Platform credits。对于聊天回合，你仍然可以在同一个 OpenClaw 安装中使用基于 Codex 的 openai/* 模型；Realtime 是唯一需要 Platform 计费的路径。

​
内存嵌入

OpenClaw 可以使用 OpenAI，或 OpenAI 兼容的嵌入端点，来进行 memory_search 索引和查询嵌入： 
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
      },
    },
  },
}
对于需要非对称嵌入标签的 OpenAI 兼容端点，请在 memorySearch 下设置 queryInputType 和 documentInputType。OpenClaw 会将这些作为特定提供方的 input_type 请求字段转发：查询嵌入使用 queryInputType；已索引的内存块和批量索引使用 documentInputType。完整示例请参见 内存配置参考。

​
快速开始

选择你偏好的认证方式并按照设置步骤操作。
最适合： 直接 API 访问和按使用量计费。
1

获取你的 API 密钥

从 OpenAI Platform 控制台 创建或复制一个 API 密钥。
2

运行引导

openclaw onboard --auth-choice openai-api-key
或直接传入密钥：
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
3

验证模型可用

openclaw models list --provider openai

​
路由摘要

模型引用运行时配置路由认证
openai/gpt-5.5omitted / provider/model agentRuntime.id: "codex"Codex app-server harness与 Codex 兼容的 OpenAI 配置文件
openai/gpt-5.4-miniomitted / provider/model agentRuntime.id: "codex"Codex app-server harness与 Codex 兼容的 OpenAI 配置文件
openai/gpt-5.5provider/model agentRuntime.id: "openclaw"OpenClaw embedded runtime选定的 openai 配置文件
openai/* 代理模型使用 Codex app-server 宿主。若要为代理模型使用 API 密钥 认证，请创建一个兼容 Codex 的 API 密钥配置文件，并通过 auth.order.openai 进行排序；OPENAI_API_KEY 仍然是非代理 OpenAI API 接口的直接备用方案。运行 openclaw doctor --fix 以迁移旧的 旧版 Codex 认证顺序条目。

​
配置示例

{
  env: { OPENAI_API_KEY: "example-openai-key-not-real" },
  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
}
要通过 OpenAI API 尝试 ChatGPT 当前的 Instant 模型，请将模型 设置为 openai/chat-latest：
{
  env: { OPENAI_API_KEY: "example-openai-key-not-real" },
  agents: { defaults: { model: { primary: "openai/chat-latest" } } },
}
chat-latest 是一个移动别名。OpenAI 将其描述为 ChatGPT 中使用的最新 Instant 模型，并建议在生产 API 用途中使用 gpt-5.5，因此 除非你明确需要该别名行为，否则请将 openai/gpt-5.5 作为稳定默认值。该别名当前只接受 medium 文本冗长度，因此 OpenClaw 会为此模型规范化不兼容的 OpenAI 文本冗长度覆盖。
OpenClaw 不会在直接 OpenAI API 密钥路线中暴露 gpt-5.3-codex-spark。它仅在你登录账户所暴露的 Codex 订阅目录条目中可用。

​
原生 Codex app-server 认证

原生 Codex app-server harness 使用 openai/* 模型引用以及省略的 运行时配置，或使用 provider/model agentRuntime.id: "codex"，但其认证 仍然基于账户。OpenClaw 按以下顺序选择认证方式：
  1. 为 agent 排序的 OpenAI auth profiles，优先位于 auth.order.openai。运行 openclaw doctor --fix 以迁移旧版 legacy Codex auth profile ids 和 legacy Codex auth order。
  2. app-server 现有的账户，例如本地 Codex CLI ChatGPT 登录。
  3. 仅对于本地 stdio app-server 启动，当 app-server 报告没有账户且仍需要 OpenAI auth 时，使用 CODEX_API_KEY，然后是 OPENAI_API_KEY。
这意味着，仅仅因为网关进程也有用于直接 OpenAI 模型或嵌入的 OPENAI_API_KEY， 本地 ChatGPT/Codex 订阅登录并不会被替代。环境变量 API key 回退 只适用于本地 stdio 的无账户路径；它不会发送到 WebSocket app-server 连接。 当选择了订阅式 Codex 配置文件时，OpenClaw 也会将 CODEX_API_KEY 和 OPENAI_API_KEY 排除在生成的 stdio app-server 子进程之外，并通过 app-server 登录 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在安全时映射为受支持的尺寸
{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-2" },
    },
  },
}
有关共享工具参数、提供方选择和故障转移行为，请参见 图像生成。
gpt-image-2 是 OpenAI 文本生成图像和图像编辑的默认模型。gpt-image-1.5、gpt-image-1 和 gpt-image-1-mini 仍然可以作为显式模型覆盖使用。要输出透明背景的 PNG/WebP，请使用 openai/gpt-image-1.5；当前的 gpt-image-2 API 会拒绝 background: "transparent"。 对于透明背景请求，agent 应调用 image_generate，并设置 model: "openai/gpt-image-1.5"、outputFormat: "png" 或 "webp"，以及 background: "transparent"；旧的 openai.background 提供方选项 仍然被接受。OpenClaw 也会通过将默认的 openai/gpt-image-2 透明 请求重写为 gpt-image-1.5 来保护公共 OpenAI 和 OpenAI Codex OAuth 路由；Azure 和自定义 OpenAI 兼容端点则保留 其已配置的部署/模型名称。 相同设置也可用于无头 CLI 运行： 
openclaw infer image generate \
  --model openai/gpt-image-1.5 \
  --output-format png \
  --background transparent \
  --prompt "一张放在透明背景上的简洁红色圆形贴纸" \
  --json
当从输入文件开始进行编辑时，请在 openclaw infer image edit 中使用相同的 --output-format 和 --background 标志。 --openai-background 仍然可作为 OpenAI 专用别名使用。 对于 ChatGPT/Codex OAuth 安装，请保持相同的 openai/gpt-image-2 引用。当 配置了 openai OAuth 配置文件时，OpenClaw 会解析该存储的 OAuth 访问令牌，并通过 Codex Responses 后端发送图像请求。它 不会先尝试 OPENAI_API_KEY，也不会在该请求中静默回退到 API key。 当你希望直接使用 OpenAI Images API 路由时，请显式配置 models.providers.openai，并提供 API key、 自定义 base URL 或 Azure endpoint。 如果该自定义图像端点位于受信任的 LAN/私有地址，也请设置 browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true；OpenClaw 会保持 私有/内部的 OpenAI 兼容图像端点被阻止，除非启用此项。 生成： 
/tool image_generate model=openai/gpt-image-2 prompt="OpenClaw 在 macOS 上的精致发布海报" size=3840x2160 count=1
生成透明 PNG： 
/tool image_generate model=openai/gpt-image-1.5 prompt="一个放在透明背景上的简洁红色圆形贴纸" outputFormat=png background=transparent
编辑： 
/tool image_generate model=openai/gpt-image-2 prompt="保留物体形状，将材质改为半透明玻璃" image=/path/to/reference.png size=1024x1536

​
视频生成

捆绑的 openai 插件通过 video_generate 工具注册视频生成。
能力值
默认模型openai/sora-2
模式文本生成视频、图像生成视频、单视频编辑
参考输入1 张图像或 1 个视频
尺寸覆盖支持文本生成视频和图像生成视频
其他覆盖aspectRatio、resolution、audio、watermark 会被忽略，并给出工具警告
OpenAI 图像生成视频请求使用 POST /v1/videos，并带有图像 input_reference。单视频编辑使用 POST /v1/videos/edits，并将 上传的视频放在 video 字段中。 
{
  agents: {
    defaults: {
      videoGenerationModel: { primary: "openai/sora-2" },
    },
  },
}
有关共享工具参数、提供方选择和故障转移行为，请参见 视频生成。

​
GPT-5 提示贡献

OpenClaw 为 OpenClaw 组装的提示表面上的 GPT-5 系列运行添加了一个共享的 GPT-5 提示贡献。它按模型 id 生效，因此诸如 legacy pre-repair refs（legacy Codex GPT-5.5 ref）、openrouter/openai/gpt-5.5、opencode/gpt-5.5 以及其他兼容的 GPT-5 refs 都会接收相同的叠加层。较旧的 GPT-4.x 模型不会。 捆绑的原生 Codex harness 不会通过 Codex app-server 开发者指令接收这个 OpenClaw GPT-5 叠加层。原生 Codex 保持 Codex 自有的基础、模型和项目文档行为，而 OpenClaw 会为原生线程禁用 Codex 内置的人格，以便 agent 工作区人格文件保持权威。OpenClaw 只贡献运行时上下文，例如通道投递、OpenClaw 动态工具、ACP 委派、工作区上下文以及 OpenClaw 技能。 GPT-5 贡献为在人格持久性、执行安全、工具纪律、输出形态、完成检查以及与 OpenClaw 组装的提示匹配时的验证方面，增加了一个带标签的行为契约。通道特定的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示和出站投递策略中。友好交互风格层是独立且可配置的。
值效果
"friendly"（默认）启用友好交互风格层
"on""friendly" 的别名
"off"仅禁用友好风格层
{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: { personality: "friendly" },
      },
    },
  },
}
运行时值不区分大小写，因此 "Off" 和 "off" 都会禁用友好风格层。
当共享的 agents.defaults.promptOverlays.gpt5.personality 设置未配置时，旧版 plugins.entries.openai.config.personality 仍会作为兼容性回退被读取。

​
语音与音频

捆绑的 openai 插件为 messages.tts 表面注册语音合成。
设置配置路径默认值
Modelmessages.tts.providers.openai.modelgpt-4o-mini-tts
Voicemessages.tts.providers.openai.speakerVoicecoral
Speedmessages.tts.providers.openai.speed(unset)
Instructionsmessages.tts.providers.openai.instructions(unset, gpt-4o-mini-tts only)
Formatmessages.tts.providers.openai.responseFormatopus for voice notes, mp3 for files
API keymessages.tts.providers.openai.apiKey回退到 OPENAI_API_KEY
Base URLmessages.tts.providers.openai.baseUrlhttps://api.openai.com/v1
额外正文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 会在 OpenClaw 生成字段之后合并到 /audio/speech 请求 JSON 中，因此可用于需要额外键（如 lang）的 OpenAI 兼容端点。原型键会被忽略。
{
  messages: {
    tts: {
      providers: {
        openai: { model: "gpt-4o-mini-tts", speakerVoice: "coral" },
      },
    },
  },
}
将 OPENAI_TTS_BASE_URL 设置为可在不影响聊天 API 端点的情况下覆盖 TTS base URL。OpenAI TTS 仍通过 API key 配置；对于仅 OAuth 的实时对话，请改用 Realtime 语音路径，而不是 agent 模式的 STT -> TTS 语音。
捆绑的 openai 插件通过 OpenClaw 的媒体理解转录表面注册批量语音转文本。
  • 默认模型：gpt-4o-transcribe
  • 端点：OpenAI REST /v1/audio/transcriptions
  • 输入路径：multipart 音频文件上传
  • 由 OpenClaw 在所有入站音频转录使用 tools.media.audio 的地方支持，包括 Discord 语音频道片段和频道音频附件
要强制入站音频转录使用 OpenAI：
{
  tools: {
    media: {
      audio: {
        models: [
          {
            type: "provider",
            provider: "openai",
            model: "gpt-4o-transcribe",
          },
        ],
      },
    },
  },
}
当共享的音频媒体配置或单次转录请求提供语言和提示提示时，它们会被转发给 OpenAI。
捆绑的 openai 插件为 Voice Call 插件注册实时转录。
设置配置路径默认值
Modelplugins.entries.voice-call.config.streaming.providers.openai.modelgpt-4o-transcribe
Language...openai.language(unset)
Prompt...openai.prompt(unset)
Silence duration...openai.silenceDurationMs800
VAD threshold...openai.vadThreshold0.5
Auth...openai.apiKey, OPENAI_API_KEY，或 openai OAuthAPI key 会直接连接；OAuth 会生成 Realtime transcription client secret
使用到 wss://api.openai.com/v1/realtime 的 WebSocket 连接，以及 G.711 u-law (g711_ulaw / audio/pcmu) 音频。当仅配置了 openai OAuth 时，Gateway 会在打开 WebSocket 之前生成一个临时的 Realtime transcription client secret。此流式提供方用于 Voice Call 的 realtime transcription 路径；Discord voice 目前会录制短片段并改用批量 tools.media.audio transcription 路径。
捆绑的 openai 插件为 Voice Call 插件注册实时语音。
设置配置路径默认值
Modelplugins.entries.voice-call.config.realtime.providers.openai.modelgpt-realtime-2
Voice...openai.voicealloy
Temperature (Azure deployment bridge)...openai.temperature0.8
VAD threshold...openai.vadThreshold0.5
Silence duration...openai.silenceDurationMs500
Prefix padding...openai.prefixPaddingMs300
Reasoning effort...openai.reasoningEffort(unset)
Auth...openai.apiKey, OPENAI_API_KEY，或 openai OAuthBrowser Talk 和非 Azure backend bridges 可使用 OpenAI OAuth
gpt-realtime-2 可用的内置 Realtime 声音：alloy、ash、 ballad、coral、echo、sage、shimmer、verse、marin、cedar。 OpenAI 推荐使用 marin 和 cedar 以获得最佳 Realtime 质量。这 与上面的文本转语音声音是不同的一组；不要假设类似 fable、 nova 或 onyx 的 TTS 声音也可用于 Realtime 会话。
后端 OpenAI realtime 桥接使用 GA Realtime WebSocket 会话形态，不接受 session.temperature。Azure OpenAI 部署仍可通过 azureEndpoint 和 azureDeployment 使用，并保持与部署兼容的会话形态。支持双向工具调用和 G.711 u-law 音频。
Realtime 声音在会话创建时选定。OpenAI 允许大多数 会话字段在之后更改，但一旦模型在该会话中发出过音频，就不能再 更改声音。OpenClaw 当前将内置 Realtime 声音 id 作为字符串暴露。
Control UI Talk 使用 OpenAI 浏览器 realtime 会话，配合 Gateway 生成的 临时 client secret，以及直接浏览器 WebRTC SDP 与 OpenAI Realtime API 的交换。当未配置直接的 OpenAI API key 时， Gateway 可以使用所选的 openai OAuth 配置文件生成该 client secret。 Gateway relay 和 Voice Call backend realtime WebSocket 桥接在原生 OpenAI 端点上使用相同的 OAuth 回退。维护者可通过 OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts; 进行在线验证；OpenAI 路径会在不记录密钥的情况下验证后端 WebSocket 桥接和浏览器 WebRTC SDP 交换。

​
Azure OpenAI 端点

捆绑的 openai 提供程序可以通过覆盖基础 URL，将 Azure OpenAI 资源用于图像 生成。在图像生成路径上，OpenClaw 会在 models.providers.openai.baseUrl 上检测 Azure 主机名，并自动切换为 Azure 的请求格式。
实时语音使用单独的配置路径 （plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint）， 不受 models.providers.openai.baseUrl 影响。有关其 Azure 设置，请参见 语音与语音合成 下的 实时语音 折叠面板。
在以下情况下使用 Azure OpenAI：
  • 你已经拥有 Azure OpenAI 订阅、配额或企业协议
  • 你需要 Azure 提供的区域性数据驻留或合规控制
  • 你希望将流量保留在现有的 Azure 租户内

​
配置

对于通过捆绑的 openai 提供程序进行的 Azure 图像生成，请将 models.providers.openai.baseUrl 指向你的 Azure 资源，并将 apiKey 设置为 Azure OpenAI 密钥（不是 OpenAI Platform 密钥）： 
{
  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=...
  • 对 Azure 图像生成调用使用默认 600 秒请求超时。 单次调用的 timeoutMs 仍然会覆盖此默认值。
其他基础 URL（公共 OpenAI、OpenAI 兼容代理）会保持标准的 OpenAI 图像请求格式。
openai 提供程序图像生成路径的 Azure 路由要求 OpenClaw 2026.4.22 或更高版本。较早版本会将任何自定义的 openai.baseUrl 当作公共 OpenAI 端点处理，并在 Azure 图像部署上失败。

​
API 版本

设置 AZURE_OPENAI_API_VERSION 以为 Azure 图像生成路径固定一个特定的 Azure 预览版或 GA 版本： 
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
当该变量未设置时，默认值为 2024-12-01-preview。

​
模型名称是部署名称

Azure OpenAI 将模型绑定到部署。对于通过捆绑的 openai 提供程序路由的 Azure 图像生成请求， OpenClaw 中的 model 字段必须是你在 Azure 门户中配置的 Azure 部署名称， 而不是公共 OpenAI 模型 id。 如果你创建了一个名为 gpt-image-2-prod 的部署，用于提供 gpt-image-2： 
/tool image_generate model=openai/gpt-image-2-prod prompt="一张干净的海报" size=1024x1024 count=1
相同的部署名称规则也适用于通过捆绑的 openai 提供程序路由的图像生成调用。

​
区域可用性

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

​
参数差异

Azure OpenAI 和公共 OpenAI 并不总是接受相同的图像参数。 Azure 可能会拒绝公共 OpenAI 允许的选项（例如 gpt-image-2 上的某些 background 值），或者仅在特定模型版本上提供这些选项。这些差异来自 Azure 及其底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 Azure 门户中检查你的特定部署和 API 版本所支持的参数集合。
Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐藏归因请求头——请参见 高级配置 下的 原生 vs OpenAI 兼容路由 折叠面板。对于 Azure 上的聊天或 Responses 流量（不只是图像生成），请使用 入门流程或专用的 Azure 提供程序配置——仅 openai.baseUrl 并不会自动使用 Azure 的 API/身份验证格式。 另有一个单独的 azure-openai-responses/* 提供程序；请参见下面的服务器端压缩折叠面板。

​
高级配置

OpenClaw 对 openai/* 默认采用 WebSocket 优先，并在失败时回退到 SSE（"auto"）。在 "auto" 模式下，OpenClaw：
  • 在回退到 SSE 之前，会重试一次早期的 WebSocket 失败
  • 失败后，会将 WebSocket 标记为约降级 60 秒，并在冷却期间使用 SSE
  • 为重试和重新连接附加稳定的会话和轮次身份请求头
  • 在不同传输变体之间规范化用量计数器（input_tokens / prompt_tokens）
值行为
"auto"（默认）WebSocket 优先，SSE 回退
"sse"仅强制使用 SSE
"websocket"仅强制使用 WebSocket
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { transport: "auto" },
        },
      },
    },
  },
}
相关 OpenAI 文档：
OpenClaw 为 openai/* 提供一个共享的快速模式开关：
  • 聊天/UI： /fast status|on|off
  • 配置： agents.defaults.models["<provider>/<model>"].params.fastMode
启用后，OpenClaw 会将快速模式映射为 OpenAI 的优先处理（service_tier = "priority"）。现有的 service_tier 值会被保留，并且快速模式不会重写 reasoning 或 text.verbosity。
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": { params: { fastMode: true } },
      },
    },
  },
}
会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会使该会话恢复为配置的默认值。
OpenAI 的 API 通过 service_tier 暴露优先处理功能。在 OpenClaw 中按模型设置：
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": { params: { serviceTier: "priority" } },
      },
    },
  },
}
支持的值：auto、default、flex、priority。
serviceTier 只会转发到原生 OpenAI 端点（api.openai.com）和原生 Codex 端点（chatgpt.com/backend-api）。如果你通过代理路由任一提供程序，OpenClaw 会保留 service_tier 不变。
对于直接的 OpenAI Responses 模型（api.openai.com 上的 openai/*），OpenAI 插件的 OpenClaw 流包装器会自动启用服务器端压缩：
  • 强制 store: true（除非模型兼容性设置了 supportsStore: false）
  • 注入 context_management: [{ type: "compaction", compact_threshold: ... }]
  • 默认 compact_threshold：contextWindow 的 70%（如果不可用则为 80000）
这适用于内置的 OpenClaw 运行时路径，以及嵌入式运行所使用的 OpenAI 提供程序钩子。原生 Codex 应用服务器宿主通过 Codex 管理自己的上下文，并由 OpenAI 的默认代理路由或提供程序/模型运行时策略进行配置。
适用于兼容端点，例如 Azure OpenAI Responses：
{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.5": {
          params: { responsesServerCompaction: true },
        },
      },
    },
  },
}
responsesServerCompaction 仅控制 context_management 的注入。直接的 OpenAI Responses 模型仍会强制 store: true，除非兼容性设置了 supportsStore: false。
对于 openai/* 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行契约：
{
  agents: {
    defaults: {
      embeddedAgent: { executionContract: "strict-agentic" },
    },
  },
}
使用 strict-agentic 时，OpenClaw：
  • 当存在可用工具操作时，不再将仅规划的一轮视为成功进展
  • 使用“立即执行”引导重试该轮
  • 为较大的工作自动启用 update_plan
  • 如果模型持续规划而不执行，则显示明确的阻塞状态
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供程序和较旧的模型系列保持默认行为。
OpenClaw 会将直接 OpenAI、Codex 和 Azure OpenAI 端点，与通用的 OpenAI 兼容 /v1 代理区别对待：原生路由（openai/*、Azure OpenAI）：
  • 仅对支持 OpenAI none effort 的模型保留 reasoning: { effort: "none" }
  • 对拒绝 reasoning.effort: "none" 的模型或代理省略已禁用的 reasoning
  • 默认将工具 schema 设为严格模式
  • 仅在已验证的原生主机上附加隐藏归因请求头
  • 保留仅 OpenAI 的请求形状（service_tier、store、reasoning 兼容性、prompt-cache 提示）
代理/兼容路由：
  • 使用更宽松的兼容行为
  • 从非原生的 openai-completions 负载中去除 Completions 的 store
  • 接受用于 OpenAI 兼容 Completions 代理的高级 params.extra_body/params.extraBody 透传 JSON
  • 接受用于 OpenAI 兼容 Completions 代理（如 vLLM）的 params.chat_template_kwargs
  • 不强制严格工具 schema 或仅原生请求头
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因请求头。

​
相关内容

模型选择

选择提供程序、模型引用和故障转移行为。

图像生成

共享的图像工具参数和提供程序选择。

视频生成

共享的视频工具参数和提供程序选择。

OAuth 和身份验证

身份验证详情和凭据复用规则。