OpenAI

openclaw models list --provider openai

openclaw models set openai/gpt-5.5

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

<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.6`      | unset, or provider/model `agentRuntime.id: "codex"` | Codex app-server harness | 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`      | either runtime                                      | Selected agent runtime   | Selected OpenAI API-key profile  |
| `openai/gpt-5.4-mini` | unset, or provider/model `agentRuntime.id: "codex"` | Codex app-server harness | Ordered API-key auth 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.6" } } },
}
```

The bare direct-API `gpt-5.6` id 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: { 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`, whose bare direct-API id 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>

<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 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.6-sol`      | unset, or provider/model `agentRuntime.id: "codex"` | Native Codex app-server harness                        | Codex sign-in, or an ordered `openai` auth profile |
| `openai/gpt-5.6-terra`    | unset, or provider/model `agentRuntime.id: "codex"` | Native Codex app-server harness                        | Codex sign-in when the catalog exposes Terra       |
| `openai/gpt-5.6-luna`     | unset, or provider/model `agentRuntime.id: "codex"` | Native Codex app-server harness                        | 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`          | either runtime                                      | Selected agent runtime                                 | Selected OpenAI auth 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>
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>`:

```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`.

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

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

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

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

/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536

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

| 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>

- 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.

| 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>

| 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>

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

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

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

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)

- **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>

```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>

- 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>

```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>

**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