Use this file to discover all available pages before exploring further.

OpenAI

OpenAI provides developer APIs for GPT models, and Codex is also available as a ChatGPT-plan coding agent through OpenAI's Codex clients. OpenClaw keeps those surfaces separate so config stays predictable.

OpenClaw supports three OpenAI-family routes. The model prefix selects the provider/auth route; a separate runtime setting selects who executes the embedded agent loop:

API key — direct OpenAI Platform access with usage-based billing (
text
openai/*
models)
Codex subscription through PI — ChatGPT/Codex sign-in with subscription access (
text
openai-codex/*
models)
Codex app-server harness — native Codex app-server execution (
text
openai/*
models plus
text
agents.defaults.agentRuntime.id: "codex"
)

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

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
Direct API-key billing	text `openai/gpt-5.5`	Set text `OPENAI_API_KEY` or run OpenAI API-key onboarding.
GPT-5.5 with ChatGPT/Codex subscription auth	text `openai-codex/gpt-5.5`	Default PI route for Codex OAuth. Best first choice for subscription setups.
GPT-5.5 with native Codex app-server behavior	text `openai/gpt-5.5` plus text `agentRuntime.id: "codex"`	Forces the Codex app-server harness for that model ref.
Image generation or editing	text `openai/gpt-image-2`	Works with either text `OPENAI_API_KEY` or OpenAI Codex OAuth.
Transparent-background images	text `openai/gpt-image-1.5`	Use text `outputFormat=png` or text `webp` and text `openai.background=transparent` .

Naming map

The names are similar but not interchangeable:

Name you see	Layer	Meaning
text `openai`	Provider prefix	Direct OpenAI Platform API route.
text `openai-codex`	Provider prefix	OpenAI Codex OAuth/subscription route through the normal OpenClaw PI runner.
text `codex` plugin	Plugin	Bundled OpenClaw plugin that provides native Codex app-server runtime and text `/codex` chat controls.
text `agentRuntime.id: codex`	Agent runtime	Force the native Codex app-server harness for embedded turns.
text `/codex ...`	Chat command set	Bind/control Codex app-server threads from a conversation.
text `runtime: "acp", agentId: "codex"`	ACP session route	Explicit fallback path that runs Codex through ACP/acpx.

This means a config can intentionally contain both

text

openai-codex/*

and the

text

codex

plugin. That is valid when you want Codex OAuth through PI and also want native

text

/codex

chat controls available.

text

openclaw doctor

warns about that combination so you can confirm it is intentional; it does not rewrite it.

note

GPT-5.5 is available through both direct OpenAI Platform API-key access and subscription/OAuth routes. Use `openai/gpt-5.5` for direct `OPENAI_API_KEY` traffic, `openai-codex/gpt-5.5` for Codex OAuth through PI, or `openai/gpt-5.5` with `agentRuntime.id: "codex"` for the native Codex app-server harness.

note

Enabling the OpenAI plugin, or selecting an `openai-codex/*` model, does not enable the bundled Codex app-server plugin. OpenClaw enables that plugin only when you explicitly select the native Codex harness with `agentRuntime.id: "codex"` or use a legacy `codex/*` model ref. If the bundled `codex` plugin is enabled but `openai-codex/*` still resolves through PI, `openclaw doctor` warns and leaves the route unchanged.

OpenClaw feature coverage

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

Memory embeddings

OpenClaw can use OpenAI, or an OpenAI-compatible embedding endpoint, for

text

memory_search

indexing and query embeddings:


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

For OpenAI-compatible endpoints that require asymmetric embedding labels, set

text

queryInputType

and

text

documentInputType

under

text

memorySearch

. OpenClaw forwards those as provider-specific

text

input_type

request fields: query embeddings use

text

queryInputType

; indexed memory chunks and batch indexing use

text

documentInputType

. See the Memory configuration reference for the full example.

Getting started

Choose your preferred auth method and follow the setup steps.

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


text
<Steps>
  <Step title="Get your API key">
    Create or copy an API key from the [OpenAI Platform dashboard](https://platform.openai.com/api-keys).
  </Step>

  <Step title="Run onboarding">
    ```bash}
    openclaw onboard --auth-choice openai-api-key
    ```

    Or pass the key directly:

    ```bash}
    openclaw onboard --openai-api-key "$OPENAI_API_KEY"
    ```
  </Step>

  <Step title="Verify the model is available">
    ```bash}
    openclaw models list --provider openai
    ```
  </Step>
</Steps>

### Route summary

| Model ref             | Runtime config                    | Route                      | Auth             |
| --------------------- | --------------------------------- | -------------------------- | ---------------- |
| `openai/gpt-5.5`      | omitted / `agentRuntime.id: "pi"` | Direct OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.4-mini` | omitted / `agentRuntime.id: "pi"` | Direct OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.5`      | `agentRuntime.id: "codex"`        | Codex app-server harness   | Codex app-server |

<Note>
  `openai/*` is the direct OpenAI API-key route unless you explicitly force
  the Codex app-server harness. Use `openai-codex/*` for Codex OAuth through
  the default PI runner, or use `openai/gpt-5.5` with
  `agentRuntime.id: "codex"` for native Codex app-server execution.
</Note>

### Config example

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

<Warning>
  OpenClaw does **not** expose `openai/gpt-5.3-codex-spark`. Live OpenAI API requests reject that model, and the current Codex catalog does not expose it either.
</Warning>

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


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

    Or run OAuth directly:

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

    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-codex --device-code
    ```
  </Step>

  <Step title="Set the default model">
    ```bash}
    openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5
    ```
  </Step>

  <Step title="Verify the model is available">
    ```bash}
    openclaw models list --provider openai-codex
    ```
  </Step>
</Steps>

### Route summary

| Model ref                   | Runtime config             | Route                                                     | Auth                  |
| --------------------------- | -------------------------- | --------------------------------------------------------- | --------------------- |
| `openai-codex/gpt-5.5`      | omitted / `runtime: "pi"`  | ChatGPT/Codex OAuth through PI                            | Codex sign-in         |
| `openai-codex/gpt-5.4-mini` | omitted / `runtime: "pi"`  | ChatGPT/Codex OAuth through PI                            | Codex sign-in         |
| `openai-codex/gpt-5.5`      | `runtime: "auto"`          | Still PI unless a plugin explicitly claims `openai-codex` | Codex sign-in         |
| `openai/gpt-5.5`            | `agentRuntime.id: "codex"` | Codex app-server harness                                  | Codex app-server auth |

<Note>
  Keep using the `openai-codex` provider id for auth/profile commands. The
  `openai-codex/*` model prefix is also the explicit PI route for Codex OAuth.
  It does not select or auto-enable the bundled Codex app-server harness.
</Note>

### Config example

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

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

### Status indicator

Chat `/status` shows which model runtime is active for the current session.
The default PI harness appears as `Runtime: OpenClaw Pi Default`. When the
bundled Codex app-server harness is selected, `/status` shows
`Runtime: OpenAI Codex`. Existing sessions keep their recorded harness id, so use
`/new` or `/reset` after changing `agentRuntime` if you want `/status` to
reflect a new PI/Codex choice.

### Doctor warning

If the bundled `codex` plugin is enabled while this tab's
`openai-codex/*` route is selected, `openclaw doctor` warns that the model
still resolves through PI. Keep the config unchanged when that is the
intended subscription-auth route. Switch to `openai/<model>` plus
`agentRuntime.id: "codex"` only when you want native Codex
app-server execution.

### Context window cap

OpenClaw treats model metadata and the runtime context cap as separate values.

For `openai-codex/gpt-5.5` through Codex OAuth:

* Native `contextWindow`: `1000000`
* 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-codex": {
        models: [{ id: "gpt-5.5", contextTokens: 160000 }],
      },
    },
  },
}
```

<Note>
  Use `contextWindow` to declare native model metadata. Use `contextTokens` to limit the runtime context budget.
</Note>

### Catalog recovery

OpenClaw uses upstream Codex catalog metadata for `gpt-5.5` when it is
present. If live Codex discovery omits the `openai-codex/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

text

openai/*

model refs plus

text

agentRuntime.id: "codex"

, but its auth is still account-based. OpenClaw selects auth in this order:

An explicit OpenClaw
text
openai-codex
auth profile bound to the agent.
The app-server's existing account, such as a local Codex CLI ChatGPT sign-in.
For local stdio app-server launches only,
text
CODEX_API_KEY
, then
text
OPENAI_API_KEY
, when the app-server reports no account and still requires OpenAI auth.

That means a local ChatGPT/Codex subscription sign-in is not replaced just because the gateway process also has

text

OPENAI_API_KEY

for direct OpenAI models or embeddings. Env API-key fallback is only the local stdio no-account path; it is not sent to WebSocket app-server connections. When a subscription-style Codex profile is selected, OpenClaw also keeps

text

CODEX_API_KEY

and

text

OPENAI_API_KEY

out of the spawned stdio app-server child and sends the selected credentials through the app-server login RPC.

Image generation

The bundled

text

openai

plugin registers image generation through the

text

image_generate

tool. It supports both OpenAI API-key image generation and Codex OAuth image generation through the same

text

openai/gpt-image-2

model ref.

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


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

note

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

text

gpt-image-2

is the default for both OpenAI text-to-image generation and image editing.

text

gpt-image-1.5

text

gpt-image-1

, and

text

gpt-image-1-mini

remain usable as explicit model overrides. Use

text

openai/gpt-image-1.5

for transparent-background PNG/WebP output; the current

text

gpt-image-2

API rejects

text

background: "transparent"

For a transparent-background request, agents should call

text

image_generate

with

text

model: "openai/gpt-image-1.5"

text

outputFormat: "png"

text

"webp"

, and

text

background: "transparent"

; the older

text

openai.background

provider option is still accepted. OpenClaw also protects the public OpenAI and OpenAI Codex OAuth routes by rewriting default

text

openai/gpt-image-2

transparent requests to

text

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:


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

Use the same

text

--output-format

and

text

--background

flags with

text

openclaw infer image edit

when starting from an input file.

text

--openai-background

remains available as an OpenAI-specific alias.

For Codex OAuth installs, keep the same

text

openai/gpt-image-2

ref. When an

text

openai-codex

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

text

OPENAI_API_KEY

or silently fall back to an API key for that request. Configure

text

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

text

browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true

; OpenClaw keeps private/internal OpenAI-compatible image endpoints blocked unless this opt-in is present.

Generate:


text
/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:


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

Edit:


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

text

openai

plugin registers video generation through the

text

video_generate

tool.

Capability	Value
Default model	text `openai/sora-2`
Modes	Text-to-video, image-to-video, single-video edit
Reference inputs	1 image or 1 video
Size overrides	Supported
Other overrides	text `aspectRatio` , text `resolution` , text `audio` , text `watermark` are ignored with a tool warning


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

note

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

GPT-5 prompt contribution

OpenClaw adds a shared GPT-5 prompt contribution for GPT-5-family runs across providers. It applies by model id, so

text

openai-codex/gpt-5.5

text

openai/gpt-5.5

text

openrouter/openai/gpt-5.5

text

opencode/gpt-5.5

, and other compatible GPT-5 refs receive the same overlay. Older GPT-4.x models do not.

The bundled native Codex harness uses the same GPT-5 behavior and heartbeat overlay through Codex app-server developer instructions, so

text

openai/gpt-5.x

sessions forced through

text

agentRuntime.id: "codex"

keep the same follow-through and proactive heartbeat guidance even though Codex owns the rest of the harness prompt.

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

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

```json5} { agents: { defaults: { promptOverlays: { gpt5: { personality: "friendly" }, }, }, }, } ``` ```bash} openclaw config set agents.defaults.promptOverlays.gpt5.personality off ```

tip

Values are case-insensitive at runtime, so `"Off"` and `"off"` both disable the friendly style layer.

note

Legacy `plugins.entries.openai.config.personality` is still read as a compatibility fallback when the shared `agents.defaults.promptOverlays.gpt5.personality` setting is not set.

Voice and speech

Azure OpenAI endpoints

The bundled

text

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

text

models.providers.openai.baseUrl

and switches to Azure's request shape automatically.

note

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

text

openai

provider, point

text

models.providers.openai.baseUrl

at your Azure resource and set

text

apiKey

to the Azure OpenAI key (not an OpenAI Platform key):


json5
{
  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:

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

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

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

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

note

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 will fail against Azure image deployments.

API version

Set

text

AZURE_OPENAI_API_VERSION

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


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

The default is

text

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

text

openai

provider, the

text

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

text

gpt-image-2-prod

that serves

text

gpt-image-2


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

The same deployment-name rule applies to image-generation calls routed through the bundled

text

openai

provider.

Regional availability

Azure image generation is currently available only in a subset of regions (for example

text

eastus2

text

swedencentral

text

polandcentral

text

westus3

text

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 that public OpenAI allows (for example certain

text

background

values on

text

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.

note

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 —

text

openai.baseUrl

alone does not pick up the Azure API/auth shape. A separate

text

azure-openai-responses/*

provider exists; see the Server-side compaction accordion below.

Advanced configuration

Model selection

Choosing providers, model refs, and failover behavior.

Image generation

Shared image tool parameters and provider selection.

Video generation

Shared video tool parameters and provider selection.

OAuth and auth

Auth details and credential reuse rules.

OpenClaw Docs

OpenAI

Quick choice

Naming map

note

note

OpenClaw feature coverage

Memory embeddings

Getting started

Native Codex app-server auth

Image generation

note

Video generation

note

GPT-5 prompt contribution

tip

note

Voice and speech

Azure OpenAI endpoints

note

Configuration

note

API version

Model names are deployment names

Regional availability

Parameter differences

note

Advanced configuration

Related

Model selection

Image generation

Video generation

OAuth and auth