openclaw/docs/providers/openai.md

summary, read_when, title

summary	read_when	title
Use OpenAI via API keys or Codex subscription in OpenClaw	You want to use OpenAI models in OpenClaw You want Codex subscription auth instead of API keys You need stricter GPT-5 agent execution behavior	OpenAI

OpenClaw uses one provider id, openai, for both direct API-key auth and ChatGPT/Codex subscription auth. openai/* is the canonical model route. Embedded agent turns on openai/* run through the bundled Codex app-server runtime by default; direct API-key auth stays available for non-agent OpenAI surfaces (images, video, embeddings, speech, realtime) and as an explicit compatibility route for agent turns.

• Agent models - openai/* through the Codex runtime. Sign in with Codex auth for ChatGPT/Codex subscription use, or configure an API-key auth profile when you want key-based billing.
• Non-agent OpenAI APIs - direct OpenAI Platform access, billed per use, through OPENAI_API_KEY or an openai API-key auth profile.
• Legacy config - old Codex model refs and profile ids are repaired to openai/* by openclaw doctor --fix.

OpenAI explicitly supports subscription OAuth usage in external tools and workflows like OpenClaw.

Usage and cost tracking

OpenClaw keeps subscription quota and Platform API billing distinct:

• ChatGPT/Codex OAuth shows the subscription plan, quota windows, and credit balance.
• OPENAI_ADMIN_KEY shows 30 days of provider-reported organization cost and completions usage in Control UI Usage, including daily spend, request/token totals, top models, and cost categories.
• OPENAI_PROJECT_ID optionally scopes Admin API history to one project.
• OpenClaw never sends OPENAI_API_KEY or an openai inference profile to organization APIs; those credentials may belong to custom, Azure, or agent-local endpoints.

An explicit Admin key takes precedence over OAuth. Provider-reported history is not merged with OpenClaw's session-derived estimated cost; it can include API activity from other clients and provider-side billing adjustments.

OpenAI's API Usage Dashboard documentation describes the organization-owner and explicit Usage Dashboard permission requirements for usage data.

Provider, model, runtime, and channel are separate layers. If those labels are getting mixed together, read Agent runtimes before changing config.

Quick choice

Goal	Use	Notes
ChatGPT/Codex subscription, native Codex runtime	openai/gpt-5.5	Default setup. Sign in with Codex auth.
GPT-5.6 limited preview	openai/gpt-5.6-sol, -terra, or -luna	Needs an OpenAI-approved API org or Codex workspace allowlist entry.
Direct API-key billing for agent turns	openai/gpt-5.5 plus an ordered API-key auth profile	Set auth.order.openai to put the key profile after subscription auth.
Direct API-key billing, explicit OpenClaw runtime	openai/gpt-5.5 plus provider/model agentRuntime.id: "openclaw"	Select a normal openai API-key profile.
Latest ChatGPT Instant model alias	openai/chat-latest	Direct API-key only; moving alias, not the stable default.
Image generation or editing	openai/gpt-image-2	Works with OPENAI_API_KEY or Codex OAuth.
Transparent-background images	openai/gpt-image-1.5	Set outputFormat to png or webp and background=transparent.

Naming map

Name you see	Layer	Meaning
openai	Provider prefix	Canonical OpenAI model route; agent turns default to the Codex runtime.
codex plugin	Plugin	Bundled plugin providing the native Codex app-server runtime and /codex chat controls.
provider/model agentRuntime.id: codex	Agent runtime	Force the native Codex app-server harness for matching embedded turns.
/codex ...	Chat command set	Bind/control Codex app-server threads from a conversation.
runtime: "acp", agentId: "codex"	ACP session route	Explicit fallback path that runs Codex through ACP/acpx.

openclaw doctor --fix migrates legacy Codex model refs, legacy Codex auth profile ids, and legacy Codex auth-order entries to the canonical openai route. Use auth.order.openai for new auth-order config.

GPT-5.5 is available through both direct OpenAI Platform API-key access and subscription/OAuth routes. For ChatGPT/Codex subscription with native Codex execution, use `openai/gpt-5.5` and leave runtime config unset; that already selects the Codex harness. Use an API-key auth profile only when you want direct API-key auth for an agent model.

GPT-5.6 limited preview

OpenClaw recognizes three public GPT-5.6 model ids: openai/gpt-5.6-sol, openai/gpt-5.6-terra, and openai/gpt-5.6-luna. All three expose xhigh and max reasoning in the current catalog. OpenAI describes Sol as the flagship tier, Terra as the balanced tier, and Luna as the fast, lower-cost tier. See the GPT-5.6 launch announcement and preview access guide.

Access is allowlisted during the preview and can be granted separately for the API and Codex; a paid ChatGPT plan alone does not grant access. OpenClaw keeps openai/gpt-5.5 as the default and does not special-case the access error, so selecting a GPT-5.6 ref without access surfaces the upstream error directly instead of falling back silently.

Agent model turns on `openai/*` require the bundled Codex app-server plugin by default. Explicit OpenClaw runtime config remains available as an opt-in compatibility route: when OpenClaw is explicitly selected with an `openai` OAuth profile, the model ref stays `openai/*` but requests route through the Codex-auth transport internally. Run `openclaw doctor --fix` to repair stale legacy Codex model refs, `codex-cli/*` refs, or old runtime session pins that were not set by explicit runtime config.

OpenClaw feature coverage

OpenAI capability	OpenClaw surface	Status
Chat / Responses	openai/<model> model provider	Yes
Codex subscription models	openai/<model> with OpenAI OAuth	Yes
Legacy Codex model refs	old Codex model refs, codex-cli/<model>	Repaired by doctor to openai/<model>
Codex app-server harness	openai/<model> with runtime unset, or provider/model agentRuntime.id: codex	Yes
Server-side web search	Native OpenAI Responses tool	Yes, when web search is enabled and no other provider is pinned
Images	image_generate	Yes
Videos	video_generate	Yes
Text-to-speech	messages.tts.provider: "openai" / tts	Yes
Batch speech-to-text	tools.media.audio / media understanding	Yes
Streaming speech-to-text	Voice Call streaming.provider: "openai"	Yes
Realtime voice	Voice Call realtime.provider: "openai" / Control UI Talk talk.realtime.provider: "openai"	Yes (OpenAI API key or Codex OAuth)
Embeddings	memory embedding provider	Yes

OpenAI Realtime voice goes through the public **OpenAI Platform Realtime API**. It accepts either a Platform API key or an `openai` OAuth profile, including an automatically discovered external Codex login. API-key sessions use the key's Platform billing; OAuth availability and billing follow the authenticated account's Realtime entitlement.

If API-key auth reports missing billing, top up Platform credits at platform.openai.com/account/billing for the organization backing your realtime credentials when using API-key auth. Realtime voice accepts the openai API-key auth profile created by openclaw onboard --auth-choice openai-api-key, an openai OAuth profile or external Codex login, a Platform OPENAI_API_KEY set via talk.realtime.providers.openai.apiKey for Control UI Talk, or plugins.entries.voice-call.config.realtime.providers.openai.apiKey for Voice Call, or the OPENAI_API_KEY environment variable.

Memory embeddings

OpenClaw can use OpenAI, or an OpenAI-compatible embedding endpoint, for memory_search indexing and query embeddings:

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

For OpenAI-compatible endpoints that require asymmetric embedding labels, set queryInputType and documentInputType under memorySearch. OpenClaw forwards these as provider-specific input_type request fields: query embeddings use queryInputType; indexed memory chunks and batch indexing use documentInputType. See the Memory configuration reference for the full example.

Getting started

**Best for:** direct API access and usage-based billing.

<Steps>
  <Step title="Get your API key">
    Create or copy an API key from the [OpenAI Platform dashboard](https://platform.openai.com/api-keys).
  </Step>
  <Step title="Run onboarding">
    ```bash
    openclaw onboard --auth-choice openai-api-key
    ```

    Or pass the key directly:

    ```bash
    openclaw onboard --openai-api-key "$OPENAI_API_KEY"
    ```
  </Step>
  <Step title="Verify the model is available">
    ```bash
    openclaw models list --provider openai
    ```
  </Step>
</Steps>

### Route summary

| Model ref              | Runtime config                                       | Route                     | Auth                              |
| ----------------------- | ------------------------------------------------------ | --------------------------- | ------------------------------------ |
| `openai/gpt-5.5`       | unset, or provider/model `agentRuntime.id: "codex"`   | Codex app-server harness   | Ordered API-key auth profile       |
| `openai/gpt-5.4-mini`  | unset, or provider/model `agentRuntime.id: "codex"`   | Codex app-server harness   | Ordered API-key auth profile       |
| `openai/gpt-5.5`       | provider/model `agentRuntime.id: "openclaw"`          | OpenClaw embedded runtime  | Selected `openai` API-key profile  |

<Note>
Agent turns on `openai/*` use the Codex app-server harness by default. For
API-key auth on an agent model, create an `openai` API-key auth profile and
order it with `auth.order.openai`; `OPENAI_API_KEY` remains the direct
fallback for non-agent OpenAI API surfaces. Run `openclaw doctor --fix` to
migrate older legacy Codex auth-order entries.
</Note>

### Config example

```json5
{
  env: { OPENAI_API_KEY: "example-openai-key-not-real" },
  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
}
```

To try ChatGPT's current Instant model from the OpenAI API, set the model
to `openai/chat-latest`:

```json5
{
  env: { OPENAI_API_KEY: "example-openai-key-not-real" },
  agents: { defaults: { model: { primary: "openai/chat-latest" } } },
}
```

`chat-latest` is a moving alias. OpenAI recommends `gpt-5.5` for production
API usage, so keep `openai/gpt-5.5` as the stable default unless you want
that alias behavior. The alias only accepts `medium` text verbosity;
OpenClaw forces any other requested verbosity to `medium` for this model.

<Warning>
OpenClaw does **not** expose `gpt-5.3-codex-spark` on the direct OpenAI
API-key route. It is available only through Codex subscription catalog
entries when your signed-in account exposes it.
</Warning>

**Best for:** using your ChatGPT/Codex subscription with native Codex app-server execution instead of a separate API key. Codex cloud requires ChatGPT sign-in.

<Steps>
  <Step title="Run Codex OAuth">
    ```bash
    openclaw onboard --auth-choice openai
    ```

    Or run OAuth directly:

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

    For headless or callback-hostile setups, add `--device-code` to sign
    in with a ChatGPT device-code flow instead of the localhost browser
    callback:

    ```bash
    openclaw models auth login --provider openai --device-code
    ```
  </Step>
  <Step title="Use the canonical OpenAI model route">
    ```bash
    openclaw config set agents.defaults.model.primary openai/gpt-5.5
    ```

    No runtime config is required for the default path. OpenAI agent
    turns select the native Codex app-server runtime automatically, and
    OpenClaw installs or repairs the bundled Codex plugin when this route
    is chosen.
  </Step>
  <Step title="Verify Codex auth is available">
    ```bash
    openclaw models list --provider openai
    ```

    After the gateway is running, send `/codex status` or `/codex models`
    in chat to verify the native app-server runtime.
  </Step>
</Steps>

### Route summary

| Model ref                | Runtime config                                | Route                                                  | Auth                                            |
| -------------------------- | ------------------------------------------------ | --------------------------------------------------------- | -------------------------------------------------- |
| `openai/gpt-5.5`         | unset, or provider/model `agentRuntime.id: "codex"` | Native Codex app-server harness                        | Codex sign-in, or an ordered `openai` auth profile |
| `openai/gpt-5.5`         | provider/model `agentRuntime.id: "openclaw"`  | OpenClaw embedded runtime, internal Codex-auth transport | Selected `openai` OAuth profile                 |
| Legacy Codex GPT-5.5 ref | repaired by doctor                            | Rewritten to `openai/gpt-5.5`                            | Migrated OpenAI OAuth profile                   |
| `codex-cli/gpt-5.5`      | repaired by doctor                            | Rewritten to `openai/gpt-5.5`                            | Codex app-server auth                           |

<Warning>
Prefer `openai/gpt-5.5` for new subscription-backed agent config. Older
Codex GPT refs are legacy OpenClaw routes, not the native Codex runtime
path; run `openclaw doctor --fix` to migrate them. `gpt-5.3-codex-spark`
stays limited to accounts whose Codex subscription catalog advertises it;
direct OpenAI API-key and Azure refs for it stay suppressed.
</Warning>

<Note>
New config should put OpenAI agent auth order under `auth.order.openai`;
doctor migrates older legacy Codex auth-order entries.
</Note>

### Config example

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

With an API-key backup, keep the model on `openai/gpt-5.5` and put the
auth order under `openai`. OpenClaw tries the subscription first, then the
API key, while staying on the Codex harness:

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

<Note>
Onboarding no longer imports OAuth material from `~/.codex`. Sign in with
browser OAuth (default) or the device-code flow above; OpenClaw manages the
resulting credentials in its own agent auth store.
</Note>

### Check and recover Codex OAuth routing

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

For a specific agent, add `--agent <id>`:

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

If an older config still has legacy Codex GPT refs, or a stale OpenAI
runtime session pin without explicit runtime config, repair it:

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

If `models auth list --provider openai` shows no usable profile, sign in
again:

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

Use `--profile-id` for multiple Codex OAuth logins in the same agent, then
control them via auth ordering or `/model ...@<profileId>`:

```bash
openclaw models auth login --provider openai --profile-id openai:ritsuko
openclaw models auth login --provider openai --profile-id openai:lain
```

Run `openclaw doctor --fix` to migrate older legacy OpenAI Codex prefix
profile ids and order entries before relying on profile ordering.

### Status indicator

Chat `/status` shows which model runtime is active for the current
session. The bundled Codex app-server harness appears as
`Runtime: OpenAI Codex` for `openai/*` agent turns. Stale OpenAI runtime
session pins are repaired to Codex unless config explicitly pins OpenClaw.

### Doctor warning

If legacy Codex model refs or stale OpenAI runtime pins remain in config
or session state, `openclaw doctor --fix` rewrites them to `openai/*` with
the Codex runtime unless OpenClaw is explicitly configured.

### Context window cap

OpenClaw treats model metadata and the runtime context cap as separate
values. For `openai/gpt-5.5` through the Codex OAuth catalog:

- Native `contextWindow`: `400000`
- Default runtime `contextTokens` cap: `272000`

The smaller default cap has better latency and quality characteristics in
practice. Override it with `contextTokens`:

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

<Note>
Use `contextWindow` to declare native model metadata. Use `contextTokens`
to limit the runtime context budget. The direct OpenAI API-key route
reports a larger native `contextWindow` (`1000000`) for `gpt-5.5`; the two
routes are tracked separately because upstream catalogs differ.
</Note>

### Catalog recovery

OpenClaw uses upstream Codex catalog metadata for `gpt-5.5` when it is
present. If live Codex discovery omits the `gpt-5.5` row while the account
is authenticated, OpenClaw synthesizes that OAuth model row so cron,
sub-agent, and configured default-model runs do not fail with
`Unknown model`.

Native Codex app-server auth

The native Codex app-server harness uses openai/* model refs with runtime config unset or provider/model agentRuntime.id: "codex", but its auth is still account-based. OpenClaw selects auth in this order:

1. Ordered OpenAI auth profiles for the agent, preferably under auth.order.openai. Run openclaw doctor --fix to migrate older legacy Codex auth profile ids and auth order.
2. The app-server's existing account, such as a local Codex CLI ChatGPT sign-in.
3. For local stdio app-server launches only, and only when the app-server reports no account: CODEX_API_KEY, then OPENAI_API_KEY.

A local ChatGPT/Codex subscription sign-in is not replaced just because the gateway process also has OPENAI_API_KEY for direct OpenAI models or embeddings. The env API-key fallback applies only to the local stdio no-account path; it is never sent over WebSocket app-server connections. When a subscription-style Codex profile is selected, OpenClaw also keeps CODEX_API_KEY and OPENAI_API_KEY out of the spawned stdio app-server child and sends the selected credentials through the app-server login RPC instead.

When that subscription profile is blocked by a Codex usage limit, OpenClaw marks the profile blocked until Codex's advertised reset time and lets auth ordering rotate to the next openai:* profile, without changing the selected model or dropping out of the Codex harness. Once the reset time passes, the subscription profile is eligible again.

Image generation

The bundled openai plugin registers image generation through the image_generate tool. It supports both OpenAI API-key and Codex OAuth image generation through the same openai/gpt-image-2 model ref.

Capability	OpenAI API key	Codex OAuth
Model ref	openai/gpt-image-2	openai/gpt-image-2
Auth	OPENAI_API_KEY	OpenAI Codex OAuth sign-in
Transport	OpenAI Images API	Codex Responses backend
Max images per request	4	4
Edit mode	Enabled (up to 5 reference images)	Enabled (up to 5 reference images)
Size overrides	Supported, including 2K/4K sizes	Supported, including 2K/4K sizes
Aspect ratio / resolution	Not forwarded to OpenAI Images API	Mapped to a supported size when safe

{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-2" },
    },
  },
}

See [Image Generation](/tools/image-generation) for shared tool parameters, provider selection, and failover behavior.

gpt-image-2 is the default for OpenAI text-to-image generation and image editing. gpt-image-1.5, gpt-image-1, and gpt-image-1-mini remain usable as explicit model overrides. Use openai/gpt-image-1.5 for transparent-background PNG/WebP output; the current gpt-image-2 API rejects background: "transparent".

For a transparent-background request, call image_generate with model: "openai/gpt-image-1.5", outputFormat: "png" or "webp", and background: "transparent"; the older openai.background provider option is still accepted. OpenClaw also protects the public OpenAI and OpenAI Codex OAuth routes by rewriting default openai/gpt-image-2 transparent requests to gpt-image-1.5; Azure and custom OpenAI-compatible endpoints keep their configured deployment/model names.

The same setting is exposed for headless CLI runs:

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

Use the same --output-format and --background flags with openclaw infer image edit when starting from an input file. --openai-background remains available as an OpenAI-specific alias. Use --quality low|medium|high|auto to control OpenAI Images quality and cost. Use --openai-moderation low|auto to pass OpenAI's moderation hint from either image generate or image edit.

For ChatGPT/Codex OAuth installs, keep the same openai/gpt-image-2 ref. When an openai OAuth profile is configured, OpenClaw resolves that stored OAuth access token and sends image requests through the Codex Responses backend; it does not first try OPENAI_API_KEY or silently fall back to an API key. Configure models.providers.openai explicitly with an API key, custom base URL, or Azure endpoint when you want the direct OpenAI Images API route instead. If that custom image endpoint is on a trusted LAN/private address, also set browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw keeps private/internal OpenAI-compatible image endpoints blocked unless this opt-in is present.

Generate:

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

Generate a transparent PNG:

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

Edit:

/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

Video generation

The bundled openai plugin registers video generation through the video_generate tool.

Capability	Value
Default model	openai/sora-2
Modes	Text-to-video, image-to-video, single-video edit
Reference inputs	1 image or 1 video
Size overrides	Supported for text-to-video and image-to-video
Aspect ratio	Converted to the closest supported size, not forwarded raw
Other overrides	resolution, audio, watermark are unsupported and dropped with a tool warning

OpenAI image-to-video requests use POST /v1/videos with an image input_reference. Single-video edits use POST /v1/videos/edits with the uploaded video in the video field.

{
  agents: {
    defaults: {
      videoGenerationModel: { primary: "openai/sora-2" },
    },
  },
}

See [Video Generation](/tools/video-generation) for shared tool parameters, provider selection, and failover behavior.

The OpenAI provider declares supportsSize but not supportsAspectRatio or supportsResolution. OpenClaw's shared normalization layer converts a requested aspectRatio into the closest matching OpenAI size before the request reaches the provider, so aspect-ratio requests generally still work. resolution has no size fallback and is dropped, surfaced to the caller as Ignored unsupported overrides for openai/<model>: resolution=<value>.

GPT-5 prompt contribution

OpenClaw adds a shared GPT-5 prompt contribution for GPT-5-family models on the openai provider (including legacy pre-repair Codex refs that normalize to openai/*). Other providers that also serve GPT-5-family model ids, such as OpenRouter or opencode routes, do not receive this overlay; it is gated on provider id openai, not on model id alone. Older GPT-4.x models never receive it.

The native Codex app-server harness does not receive the persona/tool- discipline behavior contract or the friendly interaction-style overlay through developer instructions; native Codex keeps Codex-owned base, model, and project-doc behavior, and OpenClaw disables Codex's built-in personality for native threads so agent workspace personality files stay authoritative. OpenClaw contributes only runtime context to native Codex threads: channel delivery, OpenClaw dynamic tools, ACP delegation, workspace context, and OpenClaw skills. The heartbeat-guidance text from this same contribution is the one exception: native Codex heartbeat turns do get it, injected as dedicated collaboration instructions rather than through the shared prompt-contribution hook.

The GPT-5 contribution adds a tagged behavior contract for persona persistence, execution safety, tool discipline, output shape, completion checks, and verification on matching OpenClaw-assembled prompts. Channel- specific reply and silent-message behavior stays in the shared OpenClaw system prompt and outbound delivery policy. The friendly interaction-style layer is separate and configurable.

Value	Effect
"friendly" (default)	Enable the friendly interaction-style layer
"on"	Alias for "friendly"
"off"	Disable only the friendly style layer

```json5 { agents: { defaults: { promptOverlays: { gpt5: { personality: "friendly" }, }, }, }, } ``` ```bash openclaw config set agents.defaults.promptOverlays.gpt5.personality off ``` Values are case-insensitive at runtime, so `"Off"` and `"off"` both disable the friendly style layer. Legacy `plugins.entries.openai.config.personality` is still read as a compatibility fallback when the shared `agents.defaults.promptOverlays.gpt5.personality` setting is unset.

Voice and speech

The bundled `openai` plugin registers speech synthesis for the `messages.tts` surface.

| Setting      | Config path                                            | Default                          |
| ------------- | --------------------------------------------------------- | ----------------------------------- |
| Model        | `messages.tts.providers.openai.model`                  | `gpt-4o-mini-tts`                |
| Voice        | `messages.tts.providers.openai.speakerVoice`           | `coral`                          |
| Speed        | `messages.tts.providers.openai.speed`                  | (unset)                          |
| Instructions | `messages.tts.providers.openai.instructions`           | (unset, `gpt-4o-mini-tts` only)  |
| Format       | `messages.tts.providers.openai.responseFormat`         | `opus` for voice notes, `mp3` for files |
| API key      | `messages.tts.providers.openai.apiKey`                 | Falls back to `OPENAI_API_KEY`   |
| Base URL     | `messages.tts.providers.openai.baseUrl`                | `https://api.openai.com/v1`      |
| Extra body   | `messages.tts.providers.openai.extraBody` / `extra_body` | (unset)                        |

Available models: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Available voices:
`alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`,
`marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`.

`extraBody` is merged into `/audio/speech` request JSON after OpenClaw's
generated fields, so use it for OpenAI-compatible endpoints that require
additional keys such as `lang`. Prototype keys are ignored.

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

<Note>
Set `OPENAI_TTS_BASE_URL` to override the TTS base URL without affecting
the chat API endpoint. OpenAI TTS and Realtime voice are both configured
through an OpenAI Platform API key; OAuth-only installs can still use
Codex-backed chat models, but not OpenAI live talk-back.
</Note>

The bundled `openai` plugin registers batch speech-to-text through OpenClaw's media-understanding transcription surface.

- Default model: `gpt-4o-transcribe`
- Endpoint: OpenAI REST `/v1/audio/transcriptions`
- Input path: multipart audio file upload
- Used wherever inbound audio transcription reads `tools.media.audio`,
  including Discord voice-channel segments and channel audio attachments

To force OpenAI for inbound audio transcription:

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

Language and prompt hints are forwarded to OpenAI when supplied by the
shared audio media config or per-call transcription request.

The bundled `openai` plugin registers realtime transcription for the Voice Call plugin.

| Setting          | Config path                                                          | Default |
| ----------------- | ----------------------------------------------------------------------- | --------- |
| Model            | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
| Language         | `...openai.language`                                                 | (unset) |
| Prompt           | `...openai.prompt`                                                   | (unset) |
| Silence duration | `...openai.silenceDurationMs`                                        | `800`   |
| VAD threshold    | `...openai.vadThreshold`                                             | `0.5`   |
| Auth             | `...openai.apiKey`, `OPENAI_API_KEY`, or `openai` OAuth              | API keys connect directly; OAuth mints a Realtime transcription client secret |

<Note>
Uses a WebSocket connection to `wss://api.openai.com/v1/realtime` with
G.711 u-law (`g711_ulaw` / `audio/pcmu`) audio. When only `openai` OAuth is
configured, the Gateway mints an ephemeral Realtime transcription client
secret before opening the WebSocket. This streaming provider is for Voice
Call's realtime transcription path; Discord voice currently records short
segments and uses the batch `tools.media.audio` transcription path
instead.
</Note>

The bundled `openai` plugin registers realtime voice for the Voice Call plugin.

| Setting                               | Config path                                                              | Default             |
| --------------------------------------- | ---------------------------------------------------------------------------- | ---------------------- |
| Model                                  | `plugins.entries.voice-call.config.realtime.providers.openai.model`     | `gpt-realtime-2.1`  |
| Voice                                  | `...openai.voice`                                                       | `alloy`             |
| Temperature (Azure deployment bridge)  | `...openai.temperature`                                                 | `0.8`               |
| VAD threshold                          | `...openai.vadThreshold`                                                | `0.5`                |
| Silence duration                       | `...openai.silenceDurationMs`                                           | `500`                |
| Prefix padding                         | `...openai.prefixPaddingMs`                                             | `300`                |
| Reasoning effort                       | `...openai.reasoningEffort`                                             | (unset)              |
| Auth                                   | `openai` API-key/OAuth profile, external Codex login, `...openai.apiKey`, or `OPENAI_API_KEY` | API-key sources first; Codex OAuth fallback |

Available built-in Realtime voices for `gpt-realtime-2.1`: `alloy`, `ash`,
`ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`, `cedar`.
OpenAI recommends `marin` and `cedar` for the best Realtime quality. This
is a separate set from the Text-to-speech voices above; a TTS-only voice
such as `fable`, `nova`, or `onyx` is not valid for Realtime sessions.
Set the model explicitly to `gpt-realtime-2.1-mini` when you prefer the
smaller, lower-cost Realtime 2.1 variant.

<Note>
Backend OpenAI realtime bridges use the GA Realtime WebSocket session
shape, which does not accept `session.temperature`. Azure OpenAI
deployments remain available via `azureEndpoint` and `azureDeployment` and
keep the deployment-compatible session shape (including `temperature`).
Supports bidirectional tool calling and G.711 u-law audio.
</Note>

<Note>
Realtime voice is selected when the session is created. OpenAI allows most
session fields to change later, but the voice cannot be changed after the
model has emitted audio in that session. OpenClaw currently exposes the
built-in Realtime voice ids as strings.
</Note>

<Note>
Control UI Talk uses OpenAI browser realtime sessions with a Gateway-
minted ephemeral client secret and a direct browser WebRTC SDP exchange
against the OpenAI Realtime API. The Gateway mints that client secret with
the selected `openai` credential. Configured keys, API-key profiles, and
`OPENAI_API_KEY` take precedence; an `openai` OAuth profile or external
Codex login is the fallback. Gateway relay and Voice Call backend realtime
WebSocket bridges use the same credential order for native OpenAI endpoints.
Maintainer live verification is available with
`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`;
the OpenAI legs verify both the backend WebSocket bridge and the browser
WebRTC SDP exchange without logging secrets.
Pass `--openai-only` to run those two legs without Google credentials.
</Note>

Azure OpenAI endpoints

The bundled openai provider can target an Azure OpenAI resource for image generation by overriding the base URL. On the image-generation path, OpenClaw detects Azure hostnames on models.providers.openai.baseUrl and switches to Azure's request shape automatically.

Realtime voice uses a separate configuration path (`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`) and is not affected by `models.providers.openai.baseUrl`. See the **Realtime voice** accordion under [Voice and speech](#voice-and-speech) for its Azure settings.

Use Azure OpenAI when:

• You already have an Azure OpenAI subscription, quota, or enterprise agreement
• You need regional data residency or compliance controls Azure provides
• You want to keep traffic inside an existing Azure tenancy

Configuration

For Azure image generation through the bundled openai provider, point models.providers.openai.baseUrl at your Azure resource and set apiKey to the Azure OpenAI key (not an OpenAI Platform key):

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

OpenClaw recognizes these Azure host suffixes for the Azure image-generation route:

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

For image-generation requests on a recognized Azure host, OpenClaw:

• Sends the api-key header instead of Authorization: Bearer
• Uses deployment-scoped paths (/openai/deployments/{deployment}/...)
• Appends ?api-version=... to each request
• Uses a 600s default request timeout for Azure image-generation calls. Per-call timeoutMs values still override this default.

Other base URLs (public OpenAI, OpenAI-compatible proxies) keep the standard OpenAI image request shape.

Azure routing for the `openai` provider's image-generation path requires OpenClaw 2026.4.22 or later. Earlier versions treat any custom `openai.baseUrl` like the public OpenAI endpoint and fail against Azure image deployments.

API version

Set AZURE_OPENAI_API_VERSION to pin a specific Azure preview or GA version for the Azure image-generation path:

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

The default is 2024-12-01-preview when the variable is unset.

Model names are deployment names

Azure OpenAI binds models to deployments. For Azure image-generation requests routed through the bundled openai provider, the model field in OpenClaw must be the Azure deployment name you configured in the Azure portal, not the public OpenAI model id.

If you create a deployment called gpt-image-2-prod that serves gpt-image-2:

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

The same deployment-name rule applies to any image-generation call routed through the bundled openai provider.

Regional availability

Azure image generation is currently available only in a subset of regions (for example eastus2, swedencentral, polandcentral, westus3, uaenorth). Check Microsoft's current region list before creating a deployment, and confirm the specific model is offered in your region.

Parameter differences

Azure OpenAI and public OpenAI do not always accept the same image parameters. Azure may reject options public OpenAI allows (for example certain background values on gpt-image-2) or expose them only on specific model versions. These differences come from Azure and the underlying model, not OpenClaw. If an Azure request fails with a validation error, check the parameter set supported by your specific deployment and API version in the Azure portal.

Azure OpenAI uses native transport and compat behavior but does not receive OpenClaw's hidden attribution headers - see the **Native vs OpenAI-compatible routes** accordion under [Advanced configuration](#advanced-configuration).

For chat or Responses traffic on Azure (beyond image generation), use the onboarding flow or a dedicated Azure provider config; openai.baseUrl alone does not pick up the Azure API/auth shape. A separate azure-openai-responses/* provider exists; see the Server-side compaction accordion below.

Advanced configuration

OpenClaw uses WebSocket-first with SSE fallback (`"auto"`) for `openai/*`.

In `"auto"` mode, OpenClaw:
- Retries one early WebSocket failure before falling back to SSE
- After a failure, marks WebSocket as degraded for 60 seconds and uses SSE
  during cool-down
- Attaches stable session and turn identity headers for retries and
  reconnects
- Normalizes usage counters (`input_tokens` / `prompt_tokens`) across
  transport variants

| Value                | Behavior                          |
| ---------------------- | ------------------------------------ |
| `"auto"` (default)   | WebSocket first, SSE fallback     |
| `"sse"`              | Force SSE only                    |
| `"websocket"`        | Force WebSocket only              |

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

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

OpenClaw exposes a shared fast-mode toggle for `openai/*`:

- **Chat/UI:** `/fast status|auto|on|off`
- **Config:** `agents.defaults.models["<provider>/<model>"].params.fastMode`

When enabled, OpenClaw maps fast mode to OpenAI priority processing
(`service_tier = "priority"`). Existing `service_tier` values are
preserved, and fast mode does not rewrite `reasoning` or
`text.verbosity`. `fastMode: "auto"` starts new model calls fast until the
auto cutoff, then starts later retry, fallback, tool-result, or
continuation calls without fast mode. The cutoff defaults to 60 seconds;
set `params.fastAutoOnSeconds` on the active model to change it.

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

<Note>
Session overrides win over config. Clearing the session override in the
Sessions UI returns the session to the configured default.
</Note>

OpenAI's API exposes priority processing via `service_tier`. Set it per model in OpenClaw:

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

Supported values: `auto`, `default`, `flex`, `priority`.

<Warning>
`serviceTier` is forwarded only to native OpenAI endpoints
(`api.openai.com`) and native Codex endpoints (`chatgpt.com/backend-api`).
If you route either provider through a proxy, OpenClaw leaves
`service_tier` untouched.
</Warning>

For direct OpenAI Responses models (`openai/*` on `api.openai.com`), the OpenAI plugin's OpenClaw stream wrapper auto-enables server-side compaction:

- Forces `store: true` (unless model compat sets `supportsStore: false`)
- Injects `context_management: [{ type: "compaction", compact_threshold: ... }]`
- Default `compact_threshold`: 70% of `contextWindow` (or `80000` when
  unavailable)

This applies to the built-in OpenClaw runtime path and to OpenAI provider
hooks used by embedded runs. The native Codex app-server harness manages
its own context through Codex and is not affected by this setting.

<Tabs>
  <Tab title="Enable explicitly">
    Useful for compatible endpoints like Azure OpenAI Responses:

    ```json5
    {
      agents: {
        defaults: {
          models: {
            "azure-openai-responses/gpt-5.5": {
              params: { responsesServerCompaction: true },
            },
          },
        },
      },
    }
    ```
  </Tab>
  <Tab title="Custom threshold">
    ```json5
    {
      agents: {
        defaults: {
          models: {
            "openai/gpt-5.5": {
              params: {
                responsesServerCompaction: true,
                responsesCompactThreshold: 120000,
              },
            },
          },
        },
      },
    }
    ```
  </Tab>
  <Tab title="Disable">
    ```json5
    {
      agents: {
        defaults: {
          models: {
            "openai/gpt-5.5": {
              params: { responsesServerCompaction: false },
            },
          },
        },
      },
    }
    ```
  </Tab>
</Tabs>

<Note>
`responsesServerCompaction` only controls `context_management` injection.
Direct OpenAI Responses models still force `store: true` unless compat
sets `supportsStore: false`.
</Note>

For `openai` provider GPT-5-family models run through OpenClaw's embedded runtime, OpenClaw already defaults to a stricter execution contract called `strict-agentic`. It auto-activates whenever the resolved provider is `openai` and the model id matches the GPT-5 family, unless config explicitly opts back out:

```json5
{
  agents: {
    defaults: {
      embeddedAgent: { executionContract: "default" },
    },
  },
}
```

Setting `"strict-agentic"` explicitly is a no-op on a supported lane (it
is already the default) and inert on unsupported provider/model pairs.

With `strict-agentic` active, OpenClaw:
- Auto-enables `update_plan` for substantial work
- Retries structurally empty or reasoning-only turns with a visible-answer
  continuation
- Uses explicit harness plan events when the selected harness provides
  them

OpenClaw does not classify assistant prose to decide whether a turn is a
plan, progress update, or final answer.

<Note>
This contract lives entirely in OpenClaw's embedded agent runner. It does
not apply to the native Codex app-server harness, which manages its own
turn and plan behavior; the harness selection matters more than the
execution-contract setting for native Codex runs.
</Note>

OpenClaw treats direct OpenAI, Codex, and Azure OpenAI endpoints differently from generic OpenAI-compatible `/v1` proxies:

**Native routes** (`openai/*`, Azure OpenAI):
- Keep `reasoning: { effort: "none" }` only for models that support the
  OpenAI `none` effort
- Omit disabled reasoning for models or proxies that reject
  `reasoning.effort: "none"`
- Default tool schemas to strict mode
- Attach hidden attribution headers on verified native hosts only (Azure
  OpenAI does not get these headers, even though it is a native route)
- Keep OpenAI-only request shaping (`service_tier`, `store`,
  reasoning-compat, prompt-cache hints)

**Proxy/compatible routes:**
- Use looser compat behavior
- Strip Completions `store` from non-native `openai-completions` payloads
- Accept advanced `params.extra_body`/`params.extraBody` pass-through JSON
  for OpenAI-compatible Completions proxies
- Accept `params.chat_template_kwargs` for OpenAI-compatible Completions
  proxies such as vLLM
- Do not force strict tool schemas or native-only headers

Related

Choosing providers, model refs, and failover behavior. Shared image tool parameters and provider selection. Shared video tool parameters and provider selection. Auth details and credential reuse rules.