Skip to main content
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 - old Codex model refs and profile ids are repaired to openai/* by openclaw doctor --fix.
OpenAI explicitly supports subscription OAuth usage in external tools and workflows like OpenClaw.

​
Usage and cost tracking

OpenClaw keeps subscription quota and Platform API billing distinct:
  • ChatGPT/Codex OAuth shows the subscription plan, quota windows, and credit balance.
  • OPENAI_ADMIN_KEY shows 30 days of provider-reported organization cost and completions usage in Control UI Usage, including daily spend, request/token totals, top models, and cost categories.
  • OPENAI_PROJECT_ID optionally scopes Admin API history to one project.
  • OpenClaw never sends OPENAI_API_KEY or an openai inference profile to organization APIs; those credentials may belong to custom, Azure, or agent-local endpoints.
An explicit Admin key takes precedence over OAuth. Provider-reported history is not merged with OpenClaw’s session-derived estimated cost; it can include API activity from other clients and provider-side billing adjustments. OpenAI’s API Usage Dashboard documentation describes the organization-owner and explicit Usage Dashboard permission requirements for usage data. Provider, model, runtime, and channel are separate layers. If those labels are getting mixed together, read Agent runtimes before changing config.

​
Quick choice

​
Naming map

​
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: An explicit non-default provider/model agentRuntime.id remains authoritative. For example, agentRuntime.id: "openclaw" keeps an otherwise Codex-eligible route on OpenClaw, while agentRuntime.id: "codex" requires Codex and fails closed when the effective route is not declared Codex-compatible. 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 model refs, legacy Codex auth profile ids, and legacy Codex auth-order entries to the canonical openai route. Use auth.order.openai for new auth-order config.
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. With direct OpenAI API-key auth, the bare openai/gpt-5.6 id is an alias for Sol and is the fresh setup default. The native Codex catalog does not apply that direct-API alias client-side; depending on workspace access, it can show the exact Sol, Terra, and Luna ids. Fresh ChatGPT/Codex OAuth setup therefore uses openai/gpt-5.6-sol. Check the current account with:
API organization and Codex workspace access can differ. If GPT-5.6 is not available, select GPT-5.5 explicitly:
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 Realtime voice goes through the public OpenAI Platform Realtime API and requires a Platform API key. Codex OAuth tokens authenticate the ChatGPT Codex backend instead; they are not interchangeable with Platform API keys for the public Realtime endpoints.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.

​
Memory embeddings

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

​
Getting started

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

Get your API key

Create or copy an API key from the OpenAI Platform dashboard.
2

Run onboarding

Or pass the key directly:
3

Verify the model is available

​
Route summary

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.

​
Config example

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

​
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.
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.
See 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:
Use the same --output-format and --background flags with openclaw infer image edit when starting from an input file. --openai-background remains available as an OpenAI-specific alias. Use --quality low|medium|high|auto to control OpenAI Images quality and cost. Use --openai-moderation low|auto to pass OpenAI’s moderation hint from either image generate or image edit. For ChatGPT/Codex OAuth installs, keep the same openai/gpt-image-2 ref. When an openai OAuth profile is configured, OpenClaw resolves that stored OAuth access token and sends image requests through the Codex Responses backend; it does not first try OPENAI_API_KEY or silently fall back to an API key. Configure models.providers.openai explicitly with an API key, custom base URL, or Azure endpoint when you want the direct OpenAI Images API route instead. If that custom image endpoint is on a trusted LAN/private address, also set browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw keeps private/internal OpenAI-compatible image endpoints blocked unless this opt-in is present. Generate:
Generate a transparent PNG:
Edit:

​
Video generation

The bundled openai plugin registers video generation through the video_generate tool. 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.
See Video Generation for shared tool parameters, provider selection, and failover behavior.The OpenAI provider declares supportsSize but not supportsAspectRatio or supportsResolution. OpenClaw’s shared normalization layer converts a requested aspectRatio into the closest matching OpenAI size before the request reaches the provider, so aspect-ratio requests generally still work. resolution has no size fallback and is dropped, surfaced to the caller as Ignored unsupported overrides for openai/<model>: resolution=<value>.

​
GPT-5 prompt contribution

OpenClaw adds a shared GPT-5 prompt contribution for GPT-5-family models on the openai provider (including legacy pre-repair Codex refs that normalize to openai/*). Other providers that also serve GPT-5-family model ids, such as OpenRouter or opencode routes, do not receive this overlay; it is gated on provider id openai, not on model id alone. Older GPT-4.x models never receive it. The native Codex app-server harness does not receive the persona/tool- discipline behavior contract or the friendly interaction-style overlay through developer instructions; native Codex keeps Codex-owned base, model, and project-doc behavior, and OpenClaw disables Codex’s built-in personality for native threads so agent workspace personality files stay authoritative. OpenClaw contributes only runtime context to native Codex threads: channel delivery, OpenClaw dynamic tools, ACP delegation, workspace context, and OpenClaw skills. The heartbeat-guidance text from this same contribution is the one exception: native Codex heartbeat turns do get it, injected as dedicated collaboration instructions rather than through the shared prompt-contribution hook. The GPT-5 contribution adds a tagged behavior contract for persona persistence, execution safety, tool discipline, output shape, completion checks, and verification on matching OpenClaw-assembled prompts. Channel- specific reply and silent-message behavior stays in the shared OpenClaw system prompt and outbound delivery policy. The friendly interaction-style layer is separate and configurable.
Values are case-insensitive at runtime, so "Off" and "off" both disable the friendly style layer.
Legacy plugins.entries.openai.config.personality is still read as a compatibility fallback when the shared agents.defaults.promptOverlays.gpt5.personality setting is unset.

​
Voice and speech

The bundled openai plugin registers speech synthesis for the messages.tts surface.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.
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.
The bundled openai plugin registers batch speech-to-text through OpenClaw’s media-understanding transcription surface.
  • Default model: gpt-4o-transcribe
  • Endpoint: OpenAI REST /v1/audio/transcriptions
  • Input path: multipart audio file upload
  • Used wherever inbound audio transcription reads tools.media.audio, including Discord voice-channel segments and channel audio attachments
To force OpenAI for inbound audio transcription:
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.
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.
The bundled openai plugin registers realtime voice for the Voice Call plugin.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.
GPT-Live (upcoming). OpenAI’s full-duplex gpt-live-1 and gpt-live-1-mini models replaced ChatGPT voice mode in July 2026; the developer API is rolling out to early-access organizations. OpenClaw recognizes the model family but does not run it yet: GPT-Live sessions are WebRTC-only, own their turn-taking (no VAD), and delegate agent work through a handoff event protocol that OpenClaw’s realtime transports do not implement yet. Configuring a gpt-live-* model fails closed with guidance on both the WebSocket bridge and Talk browser sessions instead of silently connecting audio without agent access. API access is also gated per OpenAI organization during early access. Keep gpt-realtime-2.1 (the default) until GPT-Live support lands.
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.
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.
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.

​
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 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):
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:
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:
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.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 per-model params examples below shape OpenClaw’s embedded provider request. Configuring them is authored request behavior, so an otherwise eligible auto route stays on OpenClaw instead of selecting Codex implicitly. The native Codex app-server harness owns its own transport and request settings; explicit agentRuntime.id: "codex" fails closed when the effective route is not declared Codex-compatible.
OpenClaw uses WebSocket-first with SSE fallback ("auto") for openai/*.In "auto" mode, OpenClaw:
  • Retries one early WebSocket failure before falling back to SSE
  • After a failure, marks WebSocket as degraded for 60 seconds and uses SSE during cool-down
  • Attaches stable session and turn identity headers for retries and reconnects
  • Normalizes usage counters (input_tokens / prompt_tokens) across transport variants
Related OpenAI docs:
OpenClaw exposes a shared fast-mode toggle for openai/*:
  • Chat/UI: /fast status|auto|on|off
  • Config: agents.defaults.models["<provider>/<model>"].params.fastMode
When enabled, OpenClaw maps fast mode to OpenAI priority processing (service_tier = "priority"). Existing service_tier values are preserved, and fast mode does not rewrite reasoning or text.verbosity. fastMode: "auto" starts new model calls fast until the auto cutoff, then starts later retry, fallback, tool-result, or continuation calls without fast mode. The cutoff defaults to 60 seconds; set params.fastAutoOnSeconds on the active model to change it.
Session overrides win over config. Clearing the session override in the Sessions UI returns the session to the configured default.
OpenAI’s API exposes priority processing via service_tier. Set it per model in OpenClaw:
Supported values: auto, default, flex, priority.
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.
For direct OpenAI Responses models (openai/* on api.openai.com), the OpenAI plugin’s OpenClaw stream wrapper auto-enables server-side compaction:
  • Forces store: true (unless model compat sets supportsStore: false)
  • Injects context_management: [{ type: "compaction", compact_threshold: ... }]
  • Default compact_threshold: 70% of contextWindow (or 80000 when unavailable)
This applies to the built-in OpenClaw runtime path and to OpenAI provider hooks used by embedded runs. The native Codex app-server harness manages its own context through Codex and is not affected by this setting.
Useful for compatible endpoints like Azure OpenAI Responses:
responsesServerCompaction only controls context_management injection. Direct OpenAI Responses models still force store: true unless compat sets supportsStore: false.
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:
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.
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.
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

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.