stack/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 want Astra async tools, mid-turn steering, or cached reasoning changes 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. For embedded agent turns with runtime policy unset or auto, OpenAI's route facts decide whether OpenClaw may select the bundled Codex app-server runtime implicitly. The openai/* prefix alone does not select a runtime.

• Agent models - openai/* through the runtime selected by explicit agentRuntime config or OpenAI's implicit route policy. 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 - codex/* and openai-codex/* refs are repaired to openai/* plus model-scoped agentRuntime.id: "codex" 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.6-sol	Fresh subscription setup; sign in with Codex auth.
Direct API-key billing for agent turns	openai/gpt-5.6-sol plus an ordered API-key auth profile	Fresh API-key setup uses the explicit Sol id.
Choose an exact GPT-5.6 tier	openai/gpt-5.6-sol, -terra, or -luna	Check models list for the tiers available to this account.
Account without GPT-5.6 access	openai/gpt-5.5	Explicit recovery choice; OpenClaw does not silently downgrade.
Direct API-key billing, explicit OpenClaw runtime	openai/gpt-5.6 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.

Retired subscription model references

GPT-5.4 and GPT-5.4 Mini are retired from the ChatGPT-account Codex route. Run openclaw doctor --fix to replace persisted subscription references with their documented successors: openai/gpt-5.6-terra and openai/gpt-5.6-luna, respectively. This includes defaults, per-agent model selections, automation overrides, and unlocked session overrides whose selected route is known. The Platform API-key route is unaffected. Doctor retains pinned overrides when their successor is outside the agent's model policy, or when clearing an override would keep the same retired model and account. It reports the model or policy change needed, along with unresolved or conflicting account routes. Review the repair output, restart the Gateway, and re-enable any automation that was disabled after repeated failures.

GPT-6 Astra

Select openai/gpt-6-astra with an OpenAI API-key profile or a ChatGPT/Codex subscription that has access to Astra. Access is rolling out; a successful account catalog remains authoritative, so adding model support does not grant access to an account that has not received it. If ChatGPT/Codex catalog discovery is unavailable, the offline fallback list omits Astra until account discovery succeeds.

openclaw models set openai/gpt-6-astra

Astra uses the Responses API for agent tool calls. It supports text and image input, a 1,050,000-token context window, and up to 128,000 output tokens. OpenClaw retains its ordinary 272,000-token active input budget by default. The supported reasoning efforts are low, medium, high, xhigh, and max. OpenClaw defaults Astra to low on both the OpenClaw and Codex runtimes to limit reasoning cost and subscription-budget consumption on ordinary prompts. The OpenAI provider owns this default, so model selection, Control UI, and Codex turn requests share it. Explicit agent, model, global, and session thinking settings still take precedence; switching models does not clear an existing high override. Use /think default to clear a session override. An existing minimal setting maps to low. Astra cannot disable reasoning; off never sends the unsupported none effort. Temperature and top_p are not sent. These defaults also apply to configured Astra model entries without explicit reasoning or temperature compatibility metadata. Azure Responses deployments continue to use their configured capabilities.

/think ultra is also available on the OpenClaw and Codex runtimes. Ultra enables proactive sub-agent orchestration; it is not a raw Responses API effort. OpenClaw uses max, while native Codex selects Astra's model-defined effort (xhigh).

Standard pricing per million tokens is $10 input, $1 cache reads, $12.50 cache writes, and $50 output. Requests above 272K input tokens have higher rates. See the Astra model reference and migration guide.

Async tools, steering, and reasoning changes

Use an OpenAI Platform API-key profile and the built-in OpenClaw runtime for these Astra capabilities. They require the official https://api.openai.com/v1 Responses endpoint. Configure the existing model settings:

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-6-astra": {
          agentRuntime: { id: "openclaw" },
          params: {
            transport: "auto",
            responsesServerCompaction: false,
          },
        },
      },
    },
  },
}

• Async function calls: Astra can continue reasoning while OpenClaw runs a direct function tool. OpenClaw sends the completed result in the next model request after the active response finishes. This applies to direct tools; code-mode tools retain their existing execution flow.
• Mid-turn steering: Steering messages can reach Astra while it is reasoning, using the active session's cached WebSocket. Use auto or websocket-cached; SSE keeps ordinary queued steering at the next available runtime boundary. Each live batch owns one response; later messages can steer its successor. Context or payload hooks that rewrite the active request's prefix keep ordinary queued delivery.
• Reasoning changes without rebuilding the cached prefix: Change the thinking level, for example with /think high, before the next user turn. OpenClaw preserves the original request-level effort and places a configuration_update at the new turn. This optimization works across matching session history over SSE or cached WebSockets. Automatic steering continuations keep their inherited settings. If steering waits for a tool result or approval, the explicit continuation uses current request settings, including output limits and reasoning settings, without repeating accepted steering. Earlier configuration_update items retain their effect; a changed request-level effort does not replace those controls. When accepted steering waits for a tool result or approval and its history contains effort controls, finish that input with a compatible Astra model and mode before switching.

The example disables automatic server compaction because OpenAI cannot combine it with configuration updates. Cache-preserving effort changes also exclude automatic truncation, pro mode, and API multi-agent mode. The cache state is local to the running process or connection; expiry, restart, or rewritten history starts a fresh request using the selected effort.

The native Codex harness owns its own Responses loop; these built-in-runtime capabilities do not imply native Codex support.

Naming map

Name you see	Layer	Meaning
openai	Provider prefix	Canonical OpenAI model route; route facts determine the implicit 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.

Implicit agent runtime

When provider/model agentRuntime policy is unset or auto, OpenAI's provider-owned route policy chooses the implicit runtime from the effective endpoint and adapter:

Effective route facts	Implicit runtime
Exact official Platform HTTPS endpoint with openai-responses, or exact official ChatGPT HTTPS endpoint with openai-chatgpt-responses; no authored provider request override	Codex may be selected
Authored openai-completions adapter	OpenClaw
Custom endpoint	OpenClaw
Explicit exact official endpoint using HTTP	Rejected
Route with an authored provider/model request override	OpenClaw

Valid model-scoped params.fastMode / params.fast_mode, cutoff, and thinking values are typed agent-runtime controls, not authored provider request params. Affirmative reasoning support and native reasoning-effort metadata also preserve Codex selection. See Runtime selection for the supported capability values and the request overrides that remain protected.

An explicit agentRuntime.id: "openclaw" keeps a Codex-eligible route on OpenClaw. Explicit agentRuntime.id: "codex" requires a registered Codex harness; unsupported routes/auth fail closed, except that authored request overrides may use Codex's declared exact-request OpenClaw fallback before execution. Inspect the completed result's actual harness when a recipe depends on native execution. Runtime selection does not change credential type or billing: Platform API-key auth and ChatGPT/Codex subscription auth remain distinct.

openclaw doctor --fix migrates legacy codex/* and openai-codex/* model refs, legacy Codex auth profile ids, and legacy Codex auth-order entries to the canonical openai route. Migrated model refs receive model-scoped agentRuntime.id: "codex"; use auth.order.openai for new auth-order config.

Fresh OpenAI setup applies a GPT-5.6 primary only when no primary model is configured. Adding or refreshing OpenAI auth preserves an existing explicit selection, including `openai/gpt-5.5`, unless you explicitly use `models auth login --set-default` or `models set`. Use an API-key auth profile only when you want API-key auth for an agent model.

GPT-5.6 limited preview

OpenClaw recognizes the exact openai/gpt-5.6-sol, openai/gpt-5.6-terra, and openai/gpt-5.6-luna model ids. 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 access guide.

OpenAI's GPT-5.6 Sol model page documents the bare openai/gpt-5.6 id as a supported alias for Sol. Fresh API-key and ChatGPT/Codex OAuth setup use the canonical openai/gpt-5.6-sol ref so model pickers do not show both names for the same tier. Run openclaw doctor --fix to rewrite persisted bare OpenAI refs to that canonical identity. The native Codex catalog can show the exact Sol, Terra, and Luna ids depending on workspace access. Check the current account with:

openclaw models list --provider openai

API organization and Codex workspace access can differ. If GPT-5.6 is not available, select GPT-5.5 explicitly:

openclaw models set openai/gpt-5.5

OpenClaw surfaces the upstream access error and does not silently replace a GPT-5.6 selection with GPT-5.5.

Eligible exact official HTTPS routes may select the bundled Codex app-server plugin when runtime policy is unset or `auto`; authored Completions routes, custom endpoints, and request-transport overrides remain on OpenClaw. Plaintext official HTTP endpoints are rejected. Explicit provider/model runtime config remains authoritative. 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	Codex-compatible HTTPS route with runtime unset/auto, or explicit 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	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 (auth order depends on the selected Realtime route; see below)
Embeddings	memory embedding provider	Yes

Released GPT-Live browser and Gateway-relay WebRTC try an OpenClaw ChatGPT OAuth profile first and fall back to Platform API-key auth. Ordinary GA browser Realtime tries Platform auth first and falls back to OAuth only when no Platform credential source is configured. Direct backend sockets and unlisted or private realtime routes require Platform API-key auth.

Platform auth is resolved in this order: configured realtime API key, openai API-key profile, then OPENAI_API_KEY. Voice Call, Discord realtime voice, direct backend sockets, unlisted or private realtime routes, and realtime transcription still require Platform auth.

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, a Platform 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.

In Control UI Video Talk with Platform auth, OpenAI WebRTC receives camera context on demand: when the model calls describe_view, the browser sends one bounded JPEG over the realtime data channel. OpenClaw does not attach a continuous camera track to the OpenAI session.

Memory embeddings

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

{
  memory: {
    search: {
      provider: "openai",
      model: "text-embedding-3-small",
    },
  },
}

For OpenAI-compatible endpoints that require asymmetric embedding labels, set queryInputType and documentInputType under memory.search. 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 policy or route facts                                 | Route                     | Auth                              |
| ---------------- | ------------------------------------------------------------- | ------------------------- | --------------------------------- |
| `openai/gpt-5.6` | unset/`auto`, exact official HTTPS native route, no request override | Codex may be selected     | Ordered API-key auth profile      |
| `openai/gpt-5.6` | provider/model `agentRuntime.id: "openclaw"`                  | OpenClaw embedded runtime | Selected `openai` API-key profile |
| `openai/gpt-5.5` | explicit provider/model `agentRuntime.id`                     | Selected agent runtime    | Selected OpenAI API-key profile   |
| `openai/*`       | authored Completions, custom, or request override | OpenClaw embedded runtime | Credential type remains unchanged |
| `openai/*`       | plaintext official HTTP endpoint                  | Rejected                 | Credential is not sent             |

<Note>
With runtime unset or `auto`, only an eligible exact official HTTPS native
route may select the Codex app-server harness implicitly. 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: { vars: { OPENAI_API_KEY: "example-openai-key-not-real" } },
  agents: { defaults: { model: { primary: "openai/gpt-5.6-sol" } } },
}
```

The bare direct-API `gpt-5.6` alias is also accepted and resolves to the
Sol tier. If this API organization does not expose GPT-5.6, set the primary
to `openai/gpt-5.5` explicitly.

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

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

`chat-latest` is a moving alias. Fresh OpenAI API-key setup instead uses
`openai/gpt-5.6-sol`. The bare direct-API `openai/gpt-5.6` alias remains
supported and resolves to Sol. Existing
explicit primaries, including `openai/gpt-5.5`, remain unchanged. The
`chat-latest` 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.6-sol
    ```

    No runtime config is required for this exact official HTTPS native
    route. It may select the Codex app-server runtime automatically, and
    OpenClaw installs or repairs the bundled Codex plugin when that runtime
    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 policy or route facts                                 | Route                                                    | Auth                                               |
| ------------------------ | ------------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------- |
| `openai/gpt-5.6-sol`     | unset/`auto`, exact official HTTPS native route, no request override | Codex may be selected                                    | Codex sign-in, or an ordered `openai` auth profile |
| `openai/gpt-5.6-terra`   | unset/`auto`, exact official HTTPS native route, no request override | Codex may be selected                                    | Codex sign-in when the catalog exposes Terra       |
| `openai/gpt-5.6-luna`    | unset/`auto`, exact official HTTPS native route, no request override | Codex may be selected                                    | Codex sign-in when the catalog exposes Luna        |
| `openai/gpt-5.6-sol`     | provider/model `agentRuntime.id: "openclaw"`                  | OpenClaw embedded runtime, internal Codex-auth transport | Selected `openai` OAuth profile                    |
| `openai/gpt-5.5`         | explicit provider/model `agentRuntime.id`                     | Selected agent runtime                                   | Selected OpenAI auth profile                       |
| `openai/*`               | authored Completions, custom, or request override | OpenClaw embedded runtime                                | Credential requirement remains route-specific      |
| `openai/*`               | plaintext official HTTP endpoint                  | Rejected                                                 | Credential is not sent                              |
| 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>
Fresh subscription-backed setup uses exact `openai/gpt-5.6-sol`; the
native Codex catalog may also expose exact Terra or Luna refs. If the
account does not expose GPT-5.6, select `openai/gpt-5.5` explicitly. Older
Codex GPT refs are legacy OpenClaw routes, not the native Codex runtime
path; run `openclaw doctor --fix` to migrate them without upgrading an
existing explicit GPT-5.5 selection. `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.6-sol" },
    },
  },
}
```

With an API-key backup, keep the selected model under `openai/*` 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.6-sol" },
    },
  },
  auth: {
    order: {
      openai: [
        "openai:[email protected]",
        "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> -s`:

```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` when an eligible implicit route or explicit
provider/model runtime policy selects it.

### 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 defaults and long-context opt-in

OpenClaw treats native model capacity and the active runtime budget as
separate values:

- `contextWindow` declares the model's native window.
- `contextTokens` caps how much of that window OpenClaw uses for active input.

ChatGPT/Codex OAuth follows the live Codex account catalog. The current
catalog commonly advertises a `272000` token active window for GPT-5.6.
Direct API-key GPT-5.5 and GPT-5.6 models also default to `272000`
`contextTokens`, even though the Platform API exposes a larger native
window. This keeps the normal latency, quality, and cost profile consistent
across auth modes. Override a direct model's active-input budget with
`models.providers.openai.models[].contextTokens` on that exact model entry.

For direct API-key GPT-5.5 and GPT-5.6, OpenAI documents a `1050000`
token provider window and `128000` maximum output tokens. Reserving the
full output allowance gives the shared safe input budget used by both
runtime recipes below:

```text
1050000 total - 128000 maximum output = 922000 safe active input
automatic compaction threshold = 700000 active tokens
```

`922000` is a derived operating budget, not a separate provider-published
input limit. The two runtimes translate that budget differently: embedded
OpenClaw sends Responses compaction controls, while native Codex owns its
catalog window and automatic compaction. See the official
[model comparison](https://developers.openai.com/api/docs/models/compare)
and [GPT-5.5 model page](https://developers.openai.com/api/docs/models/gpt-5.5).

#### Embedded OpenClaw translation

This example pins the exact Sol model to the embedded OpenClaw runtime,
enables OpenAI API Fast mode through the shared runtime control, and asks OpenAI Responses
to compact at `700000` active tokens:

```json5
{
  models: {
    providers: {
      openai: {
        models: [
          {
            id: "gpt-5.6-sol",
            name: "GPT-5.6 Sol",
            contextWindow: 1050000,
            contextTokens: 922000,
            maxTokens: 128000,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.6-sol" },
      models: {
        "openai/gpt-5.6-sol": {
          agentRuntime: { id: "openclaw" },
          params: {
            fastMode: true,
            responsesServerCompaction: true,
            responsesCompactThreshold: 700000,
          },
        },
      },
    },
  },
}
```

OpenAI Responses automatic compaction emits an encrypted `compaction`
output item. A stateless client carries the newest item into the next
request and may drop every earlier input item. OpenClaw persists that item
opaquely, fences reuse by route, session, and auth, replays it, prunes the
replaced prefix, carries it through worker transcript commits, and removes
it from display and diagnostics. Never print, log, or expose the encrypted
content.

A process-owned isolated-Gateway run verified this exact
`openai/gpt-5.6-sol` configuration. Dense turns reached `295098`, `586562`,
and `863664` prompt tokens. Turn three emitted and persisted a first-class
server compaction item; the next request replayed that exact opaque item,
pruned its prefix, and used `9602` prompt tokens. A deterministic long
response produced `5480` output tokens, durable markers survived compaction
and Gateway restart, restart latency was `12081` ms, every call reported
`serviceTier: priority`, and the full suite took `220.03` seconds. These
timings are observations, not service-level guarantees.

#### Native Codex translation

Keep the same OpenClaw model selection, but make Codex the explicit runtime
and do not add Responses compaction params to this model entry:

```json5
{
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.6-sol" },
      models: {
        "openai/gpt-5.6-sol": {
          agentRuntime: { id: "codex" },
          params: { fastMode: true },
        },
      },
    },
  },
}
```

Codex must receive `922000` for both `context_window` and
`max_context_window`, `700000` for `auto_compact_token_limit`, and matching
app-server overrides with `model_auto_compact_token_limit_scope=total`.
Codex then applies its 95% effective-window reserve, yielding `875900`
active tokens. Configure an ordered OpenAI API-key profile and keep the
default isolated agent-scoped Codex home. The complete catalog, app-server,
auth, and restart recipe is in
[Codex harness long context](/plugins/codex-harness/configuration#direct-api-long-context).

These examples are two explicit runtime choices, not one auto-selecting
configuration. The model-scoped `agentRuntime` and runtime-owned compaction
settings must change together. OpenClaw can retain both choices only when
their model refs or agent configurations are distinguishable; otherwise,
switch the model runtime and its matching config as one atomic change. Then
restart the Gateway and native Codex app-server, run `/model default -s`,
and start a fresh chat. Existing native Codex threads retain the provider
and model recorded when they were created.

<Warning>
OpenAI applies higher long-context pricing once a GPT-5.5 or GPT-5.6
request exceeds `272000` input tokens: the whole qualifying request is
billed at 2× input and cache rates and 1.5× output rates. Fast-mode pricing
is model-specific; GPT-5.6 Sol API Fast mode is currently another 2× over
Standard. For that model, combined long-context Fast traffic is therefore
4× short-context Standard input-side pricing and 3× short-context Standard
output pricing. Large prompts are resent or compacted across turns, so an
opt-in session can cost substantially more than the default even when the
visible reply is short. See [Fast mode](https://openai.com/api-priority-processing/)
and [OpenAI API pricing](https://developers.openai.com/api/docs/pricing).
The API remains authoritative for account access, actual limits, and billing.
</Warning>

### 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 when an eligible exact official HTTPS route selects it implicitly, or when provider/model agentRuntime.id: "codex" selects it explicitly. 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. For the default isolated agent home, OpenClaw bridges that native CLI account into the app-server through its login RPC; it does not share the CLI's config, plugins, or thread store.
3. For local stdio app-server launches only, and only when the app-server reports no account: CODEX_API_KEY, then OPENAI_API_KEY.

The default per-agent codex-home/auth.json is not a runtime auth store. If you copied or mounted Codex CLI credentials there, import them into the agent's OpenClaw auth store before starting a native Codex turn. Replace <agent-id> with the configured agent that owns this Codex home:

openclaw migrate plan codex --from <codex-home> --agent <agent-id> --include-secrets --item auth:openai
openclaw migrate apply codex --from <codex-home> --agent <agent-id> --include-secrets --item auth:openai --yes

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)
Moderation	low or auto; generate and edit	low or auto; generate and edit
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: {
      mediaModels: { image: { 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 with both image generate and image edit to pass OpenAI's moderation hint. The direct OpenAI Images API and the ChatGPT/Codex OAuth Responses backend both support moderation for text-to-image generation and reference-image edits.

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: {
      mediaModels: { video: { 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 to matching GPT-5-family OpenClaw-assembled prompts. The OpenAI plugin setting below controls the friendly style on OpenAI-family routes. Older GPT-4.x model ids do not match.

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 { plugins: { entries: { openai: { config: { personality: "friendly" }, }, }, }, } ``` ```bash openclaw config set plugins.entries.openai.config.personality off ``` Values are case-insensitive at runtime, so `"Off"` and `"off"` both disable the friendly style layer. The retired `agents.defaults.promptOverlays` key is no longer read; config validation rejects it, and `openclaw doctor --fix` migrates its personality value into `plugins.entries.openai.config.personality` when that key is unset.

Voice and speech

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

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

Available models: `gpt-4o-mini-tts`, `gpt-4o-mini-tts-2025-12-15`, `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
{
  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 requires an OpenAI Platform API key.
OAuth-only installs can use Codex-backed chat models and GA Realtime browser
Talk over a ChatGPT subscription when the account has access (see the
Realtime accordion).
OpenAI TTS, Voice Call, GA Gateway relay, and Discord realtime voice still
require a Platform API key.
</Note>

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

Batch transcription can use the selected OpenAI API-key or ChatGPT OAuth
profile on the standard transcription endpoint when the account permits it.
Configured models, prompts, and language hints work through the same request
path. Access and quota errors are reported without switching credential
classes; OAuth support does not imply included or unlimited transcription.
Custom endpoints and request overrides require an API-key profile.
See [Audio and voice notes](/nodes/audio#openai-transcription-alongside-chatgpt%2Fcodex-oauth)
for selecting a separate audio API-key profile when desired.

- 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: {
      models: [
        {
          type: "provider",
          provider: "openai",
          model: "gpt-4o-transcribe",
          capabilities: ["audio"],
        },
      ],
      audio: {
        enabled: true,
      },
    },
  },
}
```

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` API-key profile    | Platform API key required |

<Note>
Uses a WebSocket connection to `wss://api.openai.com/v1/realtime` with
G.711 u-law (`g711_ulaw` / `audio/pcmu`) audio. For an `openai` API-key
profile, 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` auth profile, `...openai.apiKey`, or `OPENAI_API_KEY` | Released GPT-Live: OAuth first; ordinary GA browser: Platform first; Platform required for other routes |

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.

#### Gateway-controlled Realtime call cleanup

Closing a Gateway-controlled GA Realtime WebRTC session retires its Gateway
authority and closes the local sideband before asking OpenAI to hang up the
provider call. These are separate events; control closure does not establish
provider acknowledgment or recall already queued media.

If hangup fails, explicit cancellation or cleanup reports the failure. The
broker retries automatically after 1 second, then 5 seconds, with the existing
30-second timeout for each attempt. After all three attempts fail, the log
reports `cleanup INCOMPLETE`. The exact cleanup obligation and its capacity
remain reserved, including across plugin replacement: eight sessions globally
and two per Gateway client. Restore provider connectivity; a later OpenAI
broker/plugin runtime cleanup can retry these retained calls. Repeating End
or `talk.client.close` is not that retry boundary because the Gateway session
may already be retired.

Cleanup obligations are in memory only. Gateway exit, crash, or restart can
lose them; restarting is not proof that the provider call ended. The
adapter's 30-minute active-session lease is not a remote-lifetime guarantee
or a fallback after failed hangup.

#### GA Realtime browser authentication

Ordinary GA browser Talk tries Platform auth first in this order: the
configured realtime key, an `openai` API-key profile, then `OPENAI_API_KEY`.
When a Platform credential is available, the Gateway mints an ephemeral
client secret and the browser performs the SDP exchange directly.

When no Platform credential source is configured, ordinary GA browser Talk
falls back to the OpenClaw ChatGPT OAuth subscription profile. The
single-use Gateway offer broker keeps OAuth server-side, exchanges the
browser's SDP, and returns only the answer SDP. An explicitly configured but
unavailable Platform credential fails instead of falling back to OAuth.

Gateway-controlled GA relay, iOS client-owned WebRTC, Voice Call, direct
backend sockets, and Discord realtime voice require Platform auth.

#### Released GPT-Live browser and Gateway relay authentication

Released GPT-Live browser and Gateway-relay WebRTC try the OpenClaw ChatGPT
OAuth subscription profile first. When OAuth is unavailable, the Gateway
falls back to Platform auth in this order: the configured realtime key, an
`openai` API-key profile, then `OPENAI_API_KEY`. Create the OAuth profile
with `openclaw models auth login --provider openai`.

Both credential types stay in the Gateway. The single-use offer broker
exchanges the browser's SDP and returns only the answer SDP; it does not
send an OAuth token, Platform key, or ephemeral client secret to the browser.

The enabled OpenAI plugin starts the broker automatically, including when
you sign in after the Gateway has started. The broker opens a provider
session only when you start Talk; signing in does not open the microphone or
start a voice session. Returning to the browser after sign-in refreshes the
chat microphone's readiness.

#### Unlisted and private realtime transport paths

Unlisted or private browser Talk uses Platform-key client WebRTC with
Gateway-owned control. Gateway relay and other direct backend consumers use
the Platform-key bidirectional transport. Credentials and provider control
remain on the Gateway.

Use the account-issued realtime model value. Unlisted model values are
accepted as free-form Talk config but are not published through catalogs
or diagnostics. Opt in explicitly with `talk.realtime.model`; the released
model remains the default.

Current Platform-key sessions accept `marin` and `cedar`. OpenClaw defaults
to `marin` and maps unsupported configured voices back to it.

Unlisted or private browser WebRTC prerequisites, in order:

1. A Platform API key configured through `talk.realtime.providers.openai.apiKey`,
   an `openai` API-key profile, or `OPENAI_API_KEY`.
2. `talk.realtime.model` set to the account-issued value — via **Settings →
   Talk** in the Control UI or the config below.
3. The bundled `openai` plugin registered in full mode. A restrictive
   `plugins.allow` list fails with "OpenAI realtime browser session broker
   is unavailable".

```json5
{
  talk: {
    realtime: {
      provider: "openai",
      model: "<account-issued-realtime-model>",
      transport: "webrtc",
    },
  },
}
```

Gateway relay uses the direct bidirectional transport:

```json5
{
  talk: {
    realtime: {
      provider: "openai",
      model: "<account-issued-realtime-model>",
      transport: "gateway-relay",
    },
  },
}
```

Browser Talk uses `transport: "webrtc"`.

| Consumer | Unlisted/private route status |
| --- | --- |
| Browser Talk | Supported with Platform-key client WebRTC and Gateway-owned sideband |
| Gateway-relay Talk | Supported with direct Platform-key transport |
| Discord bidirectional voice | Supported with the Platform-key backend WebSocket |
| Voice Call and telephony | Supported with the Platform-key backend WebSocket |
| iOS client-owned Talk | Implemented; device live verification pending |
| Android realtime Talk | Pending an Android device live-proof flip; Android stays on native Talk |

These rows describe implemented transports, not account entitlement or
complete model capability parity. See the [Discord voice policy limits](/channels/discord#voice-channels)
and [Voice Call tool limits](/plugins/voice-call#realtime-voice-conversations) before
selecting an unlisted or private route for those consumers.

<Warning>
Unlisted or private routes require a Platform API key with access to the
configured account-issued model. OAuth is not a fallback for them. If
session creation is rejected, verify that the key and configured model
belong to the same Platform project.
</Warning>

A `403 Voice session access denied` response is overloaded and does not by
itself prove an account entitlement problem: an invalid voice produces the
same response. First verify the model and voice against the accepted lists
above, then verify the Platform key and configured model against the same
project.

The released Gateway-owned WebRTC route uses OAuth first with Platform
fallback, routes sideband delegations through the configured OpenClaw
agent, and keeps credentials away from relay clients. Unlisted or private
browser WebRTC and the direct backend socket remain Platform-only. The
direct socket enables Discord voice and Voice Call/telephony; OpenClaw
converts G.711 u-law telephony audio to and from the provider's 24 kHz PCM
stream. Android's client-side gate stays closed until the Gateway relay
path has live proof from an Android device.

The WebRTC path creates a provider call and joins its sideband. The direct
backend path opens one bidirectional session, sends a Frameless
`session.update`, then carries PCM audio, transcripts, delegations, and
delegation results over that socket.

Maintainers can exercise the Platform direct path and the separate GA
browser OAuth path with the opt-in live tests. The account-issued realtime
model is read from `talk.realtime.model`; missing credentials or model config
produce sanitized skips, and the tests never print either value:

```bash
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_GPT_LIVE=1 node --import tsx scripts/test-live.mts -- extensions/openai/realtime-quicksilver.live.test.ts
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_GPT_LIVE=1 node --import tsx scripts/test-live.mts -- extensions/openai/realtime-quicksilver-gateway-bridge.live.test.ts
```

<Note>
GA backend OpenAI realtime bridges use the Realtime WebSocket session
shape, which does not accept `session.temperature`; GPT-Live uses the
separate Frameless Bidi shape. 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 browser WebRTC sessions. The released
browser/Gateway-owned route tries ChatGPT OAuth first through the Gateway
offer broker, keeping OAuth server-side. When OAuth is unavailable, it
falls back to Platform credentials in this order: configured realtime key,
API-key profile, then `OPENAI_API_KEY`. Direct backend sockets and unlisted
or private realtime routes require Platform credentials.
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 the backend WebSocket bridge, a synthesized PCM24
speech-to-response audio roundtrip, and the browser WebRTC SDP exchange
without logging secrets. Pass `--openai-only` to run those legs without
Google credentials. Use `--openai-audio-cycles 3` for a short repeated
connect, talkback, and close soak.
</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

The transport and serviceTier examples below are authored embedded-provider request settings, so an otherwise eligible auto route stays on OpenClaw instead of selecting Codex implicitly. Valid fastMode / fast_mode values and valid cutoff keys are typed agent-runtime controls and do not select a runtime. Runtime-specific examples therefore pin agentRuntime.id explicitly. The native Codex app-server harness owns its transport and request settings. Authored embedded-provider settings can therefore select the declared OpenClaw fallback even with explicit agentRuntime.id: "codex"; see Runtime selection.

Direct API-key requests use SSE by default. Set `params.transport` when you want Responses WebSocket mode on an eligible official OpenAI endpoint.

| Value                 | Behavior |
| --------------------- | -------- |
| `"sse"` (default)     | Stream each request over SSE |
| `"auto"`              | Prefer a session-cached WebSocket, with pre-dispatch SSE fallback |
| `"websocket-cached"`  | Explicitly use the session-cached WebSocket path, with the same pre-dispatch SSE fallback |
| `"websocket"`         | Use a transient WebSocket for the request, with pre-dispatch SSE fallback |

Cached modes keep one eligible connection per session. When the prior
request and response still match the current history, OpenClaw sends only
the new input and references the prior response with
`previous_response_id`. Otherwise it sends full history without that
reference.

A setup or handshake failure before request dispatch falls back to SSE; it
is not retried or reconnected first. After dispatch, failures with an
unknown outcome remain replay-unsafe and fail closed. The explicit server
rejections `previous_response_not_found` and
`websocket_connection_limit_reached` are safe exceptions: OpenClaw closes
the failed socket and retries that turn once over SSE with full history and
no rejected `previous_response_id`.

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

Related OpenAI docs:
- [Responses API WebSocket mode](https://developers.openai.com/api/docs/guides/websocket-mode)
- [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`

Valid `params.fastMode` / `params.fast_mode` values and valid cutoff keys
are typed runtime controls. They do not count as authored provider request
params and do not select OpenClaw or Codex. The example below pins embedded
OpenClaw because it describes a direct provider request.

When enabled on the embedded runtime, OpenClaw maps fast mode to OpenAI API
Fast mode (formerly Priority processing) and currently sends
`service_tier = "priority"`. 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": {
          agentRuntime: { id: "openclaw" },
          params: { fastMode: "auto", fastAutoOnSeconds: 30 },
        },
      },
    },
  },
}
```

<Note>
The full precedence is inline message, stored session, per-agent default,
global default, per-model `params.fastMode`, then off. `/fast default`
clears only the session layer. `/status` reports the resolved OpenClaw
policy and runtime, not the upstream service tier actually honored or
returned. See [Thinking levels](/tools/thinking#fast-mode-%2Ffast) and
[Codex harness](/plugins/codex-harness/commands#shared-fast-mode-and-codex-fast-mode).
</Note>

Fast mode is premium-priced and model-specific. GPT-5.6 Sol API Fast mode
currently costs 2× Standard token pricing, with long-context multipliers
stacking as described above. ChatGPT/Codex-credit Fast mode is a separate
billing system: GPT-5.6 and GPT-5.5 currently consume 2.5× Standard credits,
while API-key Codex runs use API token pricing. See
[Fast mode](https://openai.com/api-priority-processing/),
[API pricing](https://developers.openai.com/api/docs/pricing), and
[Codex speed](https://learn.chatgpt.com/docs/agent-configuration/speed).

OpenAI now calls this API product Fast mode; it was formerly Priority processing. OpenClaw currently sends the wire value `service_tier = "priority"`. Set an explicit tier per model on the embedded OpenClaw runtime:

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

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

<Warning>
`params.serviceTier` is an authored embedded-provider setting, not native
Codex app-server configuration. It is forwarded only by the embedded
runtime to native OpenAI endpoints (`api.openai.com`) and native ChatGPT
endpoints (`chatgpt.com/backend-api`). If you route either provider through
a proxy, OpenClaw leaves `service_tier` untouched. Configure the native
harness separately with `plugins.entries.codex.config.appServer.serviceTier`;
the shared Fast-mode run control can supersede that value.
</Warning>

For store-capable direct OpenAI Responses models (`openai/*` resolved to `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)

The same resolved route and effective threshold gate the client preflight,
so OpenClaw does not delay local compaction unless the transport will inject
`context_management`. ChatGPT OAuth, custom proxies, and routes with
`compat.supportsStore: false` are not store-capable and therefore ignore
these server-compaction controls. 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.

OpenAI emits the compacted state as an encrypted `compaction` output item.
Keep that item opaque. For stateless continuation, carry the newest item
forward and drop the earlier input prefix it replaces. OpenClaw does this
automatically: it persists and replays the item only for the matching
route, session, and auth identity, preserves it across worker transcript
commits, and filters it from user-visible history and diagnostics. Never
display or log the encrypted content.

<Tabs>
  <Tab title="Enable explicitly">
    Useful for store-capable endpoints like Azure OpenAI Responses. Setting
    this to `true` does not override endpoint or `supportsStore` capability:

    ```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:
- Makes `progress_card` available for substantial work unless `tools.updatePlan` disables it
- 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

If a usable tool schema is incompatible with requested strict mode, the request uses
`strict: false`. Debug logs report the downgrade under `openai-transport`,
with a bounded sample of incompatible tools. Built-in and managed Responses
requests share duplicate suppression for the same model and schemas.

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.