OpenAI Provider Setup and Usage in OpenClaw

OpenClaw assigns a single provider identifier, openai, to cover both direct API-key authentication and ChatGPT/Codex subscription sign-in. The canonical route for models is openai/*. When an embedded agent turn runs with no runtime policy, or with auto set, the route facts from OpenAI determine whether OpenClaw can silently pick the bundled Codex app-server runtime. Merely having the openai/* prefix does not by itself trigger any runtime.

• Agent models - openai/* via the runtime that explicit agentRuntime configuration chooses, or that OpenAI's implicit route policy picks. Use Codex auth to sign in for ChatGPT/Codex subscriptions, or set up an API-key auth profile if you prefer key-based billing.
• Non-agent OpenAI APIs - direct access to the OpenAI Platform with pay-per-use billing, through OPENAI_API_KEY or an openai API-key auth profile.
• Legacy config - references to codex/* and openai-codex/* get fixed up to openai/* along with model-scoped agentRuntime.id: "codex" by openclaw doctor --fix.

OpenAI explicitly allows subscription OAuth in external tools and workflows, including OpenClaw.

Usage and cost tracking

OpenClaw treats subscription quota and Platform API billing as separate things:

• ChatGPT/Codex OAuth surfaces the subscription plan, quota windows, and credit balance.
• OPENAI_ADMIN_KEY displays 30 days of provider-reported organization cost and completions usage in the Control UI Usage view, covering daily spend, request/token totals, top models, and cost categories.
• OPENAI_PROJECT_ID can optionally limit Admin API history to a single project.
• OpenClaw never forwards OPENAI_API_KEY or an openai inference profile to organization APIs; those credentials might belong to custom, Azure, or agent-local endpoints.

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

The API Usage Dashboard documentation from OpenAI 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:

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 converts older codex/* and openai-codex/* model references, legacy Codex auth profile identifiers, and outdated Codex auth-order entries into the standard openai path. Converted model references get model-level agentRuntime.id: "codex"; for new auth-order configuration, use auth.order.openai.

Note

A clean OpenAI installation assigns a GPT-5.6 primary model only if no primary model already exists. When you add or refresh OpenAI auth, an existing explicit choice is kept, including openai/gpt-5.5, unless you explicitly pass models auth login --set-default or models set. Reserve an API-key auth profile for cases where API-key auth is the intended mechanism for an agent model.

GPT-5.6 limited preview

OpenClaw recognizes the precise openai/gpt-5.6-sol, openai/gpt-5.6-terra, and openai/gpt-5.6-luna model identifiers. Each of the three exposes xhigh and max reasoning in the current catalog. OpenAI positions Sol as the top-tier offering, Terra as the mid-range option, and Luna as the quick, budget-friendly choice. Check the GPT-5.6 launch announcement and access guide.

The GPT-5.6 Sol model page on OpenAI's site lists the plain openai/gpt-5.6 id as a recognized alias for Sol. Fresh API-key and ChatGPT/Codex OAuth setups adopt the canonical openai/gpt-5.6-sol reference so model selectors avoid displaying duplicate names for the same tier. Execute openclaw doctor --fix to rewrite persisted bare OpenAI references to that canonical identity. Depending on workspace access, the native Codex catalog may show the exact Sol, Terra, and Luna ids. Verify the current account with:

openclaw models list --provider openai

API organization and Codex workspace access are not always aligned. When GPT-5.6 is unavailable, explicitly pick GPT-5.5:

openclaw models set openai/gpt-5.5

OpenClaw surfaces the upstream access error and never quietly substitutes a GPT-5.6 selection with GPT-5.5.

Note

When runtime policy is unset or auto, eligible exact official HTTPS routes may select the bundled Codex app-server plugin; authored Completions routes, custom endpoints, and request-transport overrides stay on OpenClaw. Plaintext official HTTP endpoints are rejected. Explicit provider/model runtime config remains authoritative. Run openclaw doctor --fix to fix stale legacy Codex model refs, codex-cli/* refs, or old runtime session pins that were not set by explicit runtime config.

OpenClaw feature coverage

Note

GA OpenAI Realtime backend voice bridges demand a Platform API key. GA browser Talk may alternatively use an OpenClaw ChatGPT OAuth profile when no Platform credential exists. Browser and Gateway-relay GPT-Live favor a ChatGPT OAuth profile and initiate calls through the Codex backend. Under Platform API-key auth, they rely on api.openai.com/v1/live, which requires API access. Other GPT-Live backend voice bridges depend on the Frameless Bidi WebSocket and require Platform API-key auth.

Platform auth resolution follows this sequence: configured realtime API key, openai API-key profile, then OPENAI_API_KEY. Voice Call, Discord realtime voice, GA Gateway relay, and realtime transcription still mandate Platform auth.

When API-key auth flags missing billing, add Platform credits at platform.openai.com/account/billing for the organization tied to your realtime credentials under API-key auth. Realtime voice accepts the openai API-key auth profile generated by openclaw onboard --auth-choice openai-api-key, a Platform API key configured 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 invokes 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 supports 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, configure queryInputType and documentInputType within memory.search. OpenClaw passes these along as provider-specific input_type request fields: query embeddings rely on queryInputType, while indexed memory chunks and batch indexing use documentInputType. The complete example appears in the Memory configuration reference.

Getting started

API key (OpenAI Platform)

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

Get your API key

Grab or generate an API key from the OpenAI Platform dashboard.

Run onboarding

openclaw onboard --auth-choice openai-api-key

Alternatively, supply the key directly:

openclaw onboard --openai-api-key "$OPENAI_API_KEY"

Verify the model is available

openclaw models list --provider openai

Route summary

Note

When runtime is unset or set to auto, only an eligible exact official HTTPS native route can implicitly pick the Codex app-server harness. For API-key auth on an agent model, set up an openai API-key auth profile and place it in order with auth.order.openai; OPENAI_API_KEY stays as the direct fallback for non-agent OpenAI API surfaces. Running openclaw doctor --fix migrates older legacy Codex auth-order entries.

Config example

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

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

Codex subscription

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.

Run Codex OAuth

openclaw onboard --auth-choice openai

Or run OAuth directly:

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:

openclaw models auth login --provider openai --device-code

Use the canonical OpenAI model route

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.

Verify Codex auth is available

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.

Route summary

Warning

A fresh subscription-based setup relies on the exact openai/gpt-5.6-sol; the native Codex catalog can also surface exact Terra or Luna refs. When the account lacks GPT-5.6, pick openai/gpt-5.5 explicitly. Older Codex GPT refs map to legacy OpenClaw routes, not the native Codex runtime path; run openclaw doctor --fix to migrate them without touching an existing explicit GPT-5.5 selection. gpt-5.3-codex-spark remains restricted to accounts whose Codex subscription catalog lists it; direct OpenAI API-key and Azure refs for it stay hidden.

Note

Fresh config should place OpenAI agent auth order under auth.order.openai; doctor converts older legacy Codex auth-order entries.

Config example

{
  plugins: { entries: { codex: { enabled: true } } },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.6-sol" },
    },
  },
}

With an API-key fallback, keep the chosen model under openai/* and set the auth order under openai. OpenClaw attempts the subscription first, then the API key, while remaining on the Codex harness:

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

Note

Onboarding no longer pulls OAuth material from ~/.codex. Authenticate via browser OAuth (default) or the device-code flow above; OpenClaw stores the resulting credentials in its own agent auth store.

Check and recover Codex OAuth routing

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 particular agent, add --agent <id>:

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

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

openclaw doctor --fix
openclaw config validate

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

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 manage them via auth ordering or /model ...@<profileId> -s:

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:

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 and GPT-5.5 model page.

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:

{
  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,
          },
        },
      },
    },
  },
}

When OpenAI Responses performs automatic compaction, it produces an encrypted compaction output item. A stateless client forwards only the most recent item to the following request, and all earlier input items may be discarded. OpenClaw stores that item without interpreting it, limits reuse by route, session, and auth, sends it back on replay, removes the replaced prefix, carries it through worker transcript commits, and keeps it out of display and diagnostics. The encrypted content must never be printed, logged, or otherwise exposed.

This exact openai/gpt-5.6-sol setup was verified with a process-owned isolated-Gateway run. Dense turns consumed 295098, 586562, and 863664 prompt tokens. On turn three, a first-class server compaction item was emitted and persisted; the next request replayed that identical opaque item, stripped its prefix, and ran with 9602 prompt tokens. A deterministic long response generated 5480 output tokens, durable markers held up through compaction and Gateway restart, restart latency measured 12081 ms, every call returned serviceTier: priority, and the complete suite finished in 220.03 seconds. These numbers are observations only, not service-level promises.

Native Codex translation

Retain the existing OpenClaw model selection, but designate Codex as the explicit runtime and leave Responses compaction parameters off this model entry:

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

Codex needs 922000 for both context_window and max_context_window, 700000 for auto_compact_token_limit, and corresponding app-server overrides with model_auto_compact_token_limit_scope=total. Codex then applies its 95% effective-window reserve, leaving 875900 active tokens. Set up an ordered OpenAI API-key profile and stick with the default isolated agent-scoped Codex home. The full catalog, app-server, auth, and restart procedure appears in Codex harness long context.

These two examples represent explicit runtime choices, not a single auto-selecting configuration. The model-scoped agentRuntime and runtime-owned compaction settings must be updated together. OpenClaw can preserve 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. After that, restart the Gateway and native Codex app-server, run /model default -s, and open a fresh chat. Existing native Codex threads keep the provider and model they were created with.

Warning

Once a GPT-5.5 or GPT-5.6 request goes past 272000 input tokens, OpenAI charges long-context pricing at a higher rate: the entire qualifying request is billed at 2× input and cache rates and 1.5× output rates. Fast-mode pricing varies by model; GPT-5.6 Sol API Fast mode currently adds another 2× over Standard. For that model, combined long-context Fast traffic thus comes to 4× short-context Standard input-side pricing and 3× short-context Standard output pricing. Because large prompts are resent or compacted across turns, an opt-in session can run well above the default cost even when the visible reply is short. Refer to Fast mode and OpenAI API pricing. Account access, actual limits, and billing are ultimately governed by the API.

Catalog recovery

OpenClaw pulls upstream Codex catalog metadata for gpt-5.5 whenever it is available. If live Codex discovery is missing the gpt-5.5 row while the account is authenticated, OpenClaw fabricates that OAuth model row so cron, sub-agent, and configured default-model runs avoid failing with Unknown model.

Native Codex app-server auth

The native Codex app-server harness adopts openai/* model refs when an eligible exact official HTTPS route picks it implicitly, or when provider/model agentRuntime.id: "codex" selects it explicitly. Its auth remains account-based. OpenClaw chooses auth in this sequence:

1. Ordered OpenAI auth profiles for the agent, ideally 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, for example a local Codex CLI ChatGPT sign-in. For the default isolated agent home, OpenClaw bridges that native CLI account into the app-server via its login RPC; the CLI's config, plugins, or thread store are not shared.
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 Codex CLI credentials were copied or mounted 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 overridden merely because the gateway process also holds OPENAI_API_KEY for direct OpenAI models or embeddings. The env API-key fallback is limited to the local stdio no-account path; it is never transmitted 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.

If that subscription profile hits a Codex usage limit, OpenClaw flags the profile as blocked until Codex's advertised reset time and lets auth ordering rotate to the next openai:* profile, without altering the selected model or leaving the Codex harness. Once the reset time arrives, the subscription profile becomes eligible again.

Image generation

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

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

Note

Shared tool parameters, provider selection, and failover behavior are covered in Image Generation.

gpt-image-2 serves as the default for OpenAI text-to-image generation and image editing tasks. Explicit model overrides remain possible with gpt-image-1.5, gpt-image-1, and gpt-image-1-mini. For transparent-background PNG/WebP output, use openai/gpt-image-1.5; the current gpt-image-2 API rejects background: "transparent".

When requesting a transparent background, invoke image_generate with model: "openai/gpt-image-1.5", outputFormat: "png", or "webp", along with background: "transparent"; the legacy openai.background provider option is still recognized. OpenClaw also safeguards the public OpenAI and OpenAI Codex OAuth routes by converting default openai/gpt-image-2 transparent requests to gpt-image-1.5; Azure and custom OpenAI-compatible endpoints retain their configured deployment/model names.

The same setting applies to headless CLI executions:

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

When starting from an input file, use the identical --output-format and --background flags with openclaw infer image edit. The OpenAI-specific alias --openai-background remains available. Control OpenAI Images quality and cost with --quality low|medium|high|auto. To pass OpenAI's moderation hint, combine --openai-moderation low|auto with both image generate and image edit. Moderation for text-to-image generation and reference-image edits is supported on both the direct OpenAI Images API and the ChatGPT/Codex OAuth Responses backend.

For ChatGPT/Codex OAuth installations, maintain the same openai/gpt-image-2 reference. When an openai OAuth profile is set up, OpenClaw resolves the stored OAuth access token and routes image requests through the Codex Responses backend; it does not attempt OPENAI_API_KEY first or silently switch to an API key. If you prefer the direct OpenAI Images API route, configure models.providers.openai explicitly with an API key, custom base URL, or Azure endpoint. Should that custom image endpoint reside on a trusted LAN/private address, also set browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw blocks private/internal OpenAI-compatible image endpoints unless this opt-in is provided.

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 via the video_generate tool.

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

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

Note

Refer to Video Generation for shared tool parameters, provider selection, and failover behavior.

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

GPT-5 prompt contribution

OpenClaw appends a shared GPT-5 prompt contribution to matching GPT-5-family OpenClaw-assembled prompts. The OpenAI plugin setting below governs 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 preserves 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 sole exception: native Codex heartbeat turns do receive 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 remains in the shared OpenClaw system prompt and outbound delivery policy. The friendly interaction-style layer is separate and configurable.

Config

{
  plugins: {
    entries: {
      openai: {
        config: { personality: "friendly" },
      },
    },
  },
}

CLI

openclaw config set plugins.entries.openai.config.personality off

Tip

At runtime, casing is ignored, so both "Off" and "off" turn off the friendly style layer.

Note

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

Speech synthesis (TTS)

Speech synthesis for the tts surface is registered by the bundled openai plugin.

The available models are gpt-4o-mini-tts, gpt-4o-mini-tts-2025-12-15, tts-1, tts-1-hd. The available voices are alloy, ash, ballad, cedar, coral, echo, fable, juniper, marin, onyx, nova, sage, shimmer, verse.

After OpenClaw's generated fields, extraBody gets merged into the /audio/speech request JSON, so it works for OpenAI-compatible endpoints that need extra keys like lang. Prototype keys are ignored.

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

Note

To change only the TTS base URL without touching the chat API endpoint, set OPENAI_TTS_BASE_URL. An OpenAI Platform API key is required for OpenAI TTS. OAuth-only installs can use Codex-backed chat models, GPT-Live browser and Gateway-relay Talk, 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.

Speech-to-text

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:

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

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

Realtime transcription

Realtime transcription for the Voice Call plugin is registered by the bundled openai plugin.

Note

A WebSocket link to wss://api.openai.com/v1/realtime carries G.711 u-law (g711_ulaw / audio/pcmu) audio. For an openai API-key profile, the Gateway generates a temporary Realtime transcription client secret prior to opening the WebSocket. This streaming provider serves Voice Call's realtime transcription path; Discord voice captures short segments and relies on the batch tools.media.audio transcription path instead.

Realtime voice

Realtime voice for the Voice Call plugin is registered by the bundled openai plugin.

For gpt-realtime-2.1, the built-in Realtime voices are alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar. OpenAI suggests marin and cedar for optimal Realtime quality. These differ from the Text-to-speech voices listed earlier; a TTS-only voice like fable, nova, or onyx cannot be used in Realtime sessions. If you want the smaller, cheaper Realtime 2.1 variant, explicitly set the model to gpt-realtime-2.1-mini.

GA Realtime browser Talk over ChatGPT OAuth

Browser Talk works with gpt-realtime-2.1, gpt-realtime-2.1-mini, or gpt-realtime-2 using either Platform API-key auth or an OpenClaw ChatGPT OAuth subscription profile. Platform auth is checked in this order: the configured realtime key, an openai API-key profile, then OPENAI_API_KEY. If none is set, the Gateway falls back to the ChatGPT OAuth profile established by openclaw models auth login --provider openai.

The enabled OpenAI plugin starts its browser session broker automatically, including when you sign in after the Gateway has started. This browser path needs no separate Talk provider configuration or Platform API key. The broker opens a provider session only when you start Talk; signing in does not activate the microphone or begin a voice session. After signing in, returning to the browser refreshes the chat microphone's readiness.

The two browser routes share the same Talk session contract, though each keeps credentials on a different side of the trust boundary. With Platform auth, an ephemeral client secret is minted and the browser exchanges SDP directly with OpenAI. OAuth auth remains on the Gateway: the existing single-use offer broker forwards multipart sdp plus the canonical browser session policy to /v1/realtime/calls, and only the answer SDP comes back. The OAuth token never touches the browser. A configured Platform credential that fails resolution still closes down safely; that source must be repaired or removed before OAuth fallback becomes available.

This GA OAuth fallback applies only to browsers. iOS client-owned WebRTC, Voice Call, Gateway relay, provider WebSocket transports, Discord realtime voice, and other backend GA Realtime bridges stay restricted to Platform keys.

GPT-Live transport paths

GPT-Live works for browser Talk and Gateway-owned gateway-relay Talk with ChatGPT OAuth or an enrolled Platform API key. ChatGPT OAuth initiates the call through the Codex backend using JSON sdp and session; Platform API keys rely on multipart call creation at /v1/live. Both attach the Gateway-owned sideband at wss://api.openai.com/v1/live/<call-id>. Media, credentials, and sideband control all stay on the Gateway with the relay. Discord and Voice Call use the Frameless Bidi wss://api.openai.com/v1/live?model=... endpoint, authenticated with a Platform API key.

Go with gpt-live-1-codex (the recommended option) or gpt-live-1-boulder-alpha. On this route, gpt-live-1 and gpt-live-1-mini are not accepted. Opt in explicitly using talk.realtime.model; gpt-realtime-2.1 stays the GA default.

GPT-Live adheres to the Codex V3 voice contract: arbor, breeze, cove, ember, juniper, maple, sol, spruce, and vale. OpenClaw defaults to cove and remaps unsupported configured voices back to it. These differ from GA Realtime voices; marin and cedar are GA options. Current speech-roundtrip verification covers ChatGPT OAuth with spruce; Platform GPT-Live follows the same Codex V3 voice contract, but live verification there demands an account with API access.

Browser WebRTC prerequisites, in order:

1. A ChatGPT OAuth auth profile: openclaw models auth login --provider openai. An existing Codex CLI (~/.codex) sign-in is not picked up; the profile has to be present in OpenClaw. A Platform API key with /v1/live access works as an alternative, though that access is gated behind a waitlist.
2. talk.realtime.model assigned a gpt-live-* value, either through Settings → Talk in the Control UI or the config shown below.
3. The bundled openai plugin registered in full mode. A restrictive plugins.allow list produces "OpenAI GPT-Live browser session broker is unavailable".

GPT-Live favors the ChatGPT OAuth profile even when a Platform key is present. Without an OAuth profile, an unresolved configured Platform key must be fixed or removed before another credential can take over.

{
  talk: {
    realtime: {
      provider: "openai",
      model: "gpt-live-1-codex",
      transport: "webrtc",
    },
  },
}

For the Gateway-owned WebRTC path, choose Gateway relay. It prefers the OpenClaw ChatGPT OAuth profile and falls back to an enrolled Platform key from talk.realtime.providers.openai.apiKey, an openai API-key profile, or OPENAI_API_KEY:

{
  talk: {
    realtime: {
      provider: "openai",
      model: "gpt-live-1-codex",
      transport: "gateway-relay",
    },
  },
}

Browser Talk uses transport: "webrtc".

These rows cover implemented transports, not account entitlement or full model capability parity. Review the Discord voice policy limits and Voice Call tool limits before picking GPT-Live for those consumers.

Warning

Platform API-key access to /v1/live is waitlist-gated and frequently returns 400 model_not_found without enrollment. Use a ChatGPT OAuth profile, or apply for Platform access via the GPT-Live API access form.

A 403 Voice session access denied response is overloaded and does not by itself indicate an account entitlement problem: an invalid voice yields the same response. Check the model and voice against the accepted lists above first, then confirm that the chosen ChatGPT OAuth profile and chatgpt-account-id belong to the same account.

The Gateway-owned WebRTC route sends sideband delegations through the configured OpenClaw agent and keeps OAuth or Platform credentials away from relay clients. The direct WebSocket bridge supports Discord voice and Voice Call/telephony with Platform auth; OpenClaw converts G.711 u-law telephony audio to and from GPT-Live's 24 kHz PCM stream. Android's client-side gate remains closed until the Gateway relay path has live proof from an Android device.

The WebRTC path places a call on api.openai.com/v1/live and joins its sideband there. The backend path opens /v1/live?model=..., sends a Frameless session.update, then carries PCM audio, transcripts, delegations, and delegation results over that single socket. The legacy chatgpt.com backend route returns 403 and is unused.

Maintainers can run OpenClaw's full OAuth path with the opt-in live test. It skips when no ChatGPT OAuth credential is available and never outputs token material:

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 rejects session.temperature; GPT-Live uses the separate Frameless Bidi shape. Azure OpenAI deployments remain reachable via azureEndpoint and azureDeployment and keep the deployment-compatible session shape (including temperature). Supports bidirectional tool calling and G.711 u-law audio.

Note

Realtime voice is chosen at session creation. OpenAI permits most session fields to change later, but the voice cannot be altered after the model has produced audio in that session. OpenClaw currently exposes the built-in Realtime voice ids as strings.

Note

Control UI Talk depends on OpenAI browser WebRTC sessions. When Platform credentials are present, GA gpt-realtime-* models rely on a Gateway-issued ephemeral client secret plus a direct browser SDP exchange. Configured realtime keys, API-key profiles, and OPENAI_API_KEY follow that route in that sequence. If no Platform credential exists, GA browser Talk uses the same Gateway offer broker as GPT-Live, keeping ChatGPT OAuth server-side. GPT-Live opts for ChatGPT OAuth when both auth modes are set up, and switches to Platform API-key access when the account has waitlist-gated /v1/live access. The GA Gateway relay and Voice Call backend realtime WebSocket bridges demand Platform credentials. GPT-Live Gateway relay, by contrast, uses Gateway-owned WebRTC, choosing ChatGPT OAuth first and then waitlist-enabled Platform access; Voice Call GPT-Live employs the Platform-key backend WebSocket. Maintainer live verification runs via OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts; the OpenAI legs check 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 execute those legs without Google credentials. For a brief repeated connect, talkback, and close soak, use --openai-audio-cycles 3.

Azure OpenAI endpoints

The bundled openai provider can generate images against an Azure OpenAI resource by overriding the base URL. On the image-generation path, OpenClaw spots Azure hostnames in models.providers.openai.baseUrl and automatically adopts Azure's request format.

Note

Realtime voice follows a distinct configuration path (plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint) and stays unaffected by models.providers.openai.baseUrl. Its Azure settings live in the Realtime voice accordion under Voice and speech.

Choose Azure OpenAI when:

• An Azure OpenAI subscription, quota, or enterprise agreement is already in place
• Regional data residency or compliance controls from Azure are needed
• Keeping traffic inside an existing Azure tenancy is preferred

Configuration

For Azure image generation through the bundled openai provider, set models.providers.openai.baseUrl to your Azure resource and assign apiKey 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

On a recognized Azure host, image-generation requests trigger OpenClaw to:

• Send the api-key header in place of Authorization: Bearer
• Adopt deployment-scoped paths (/openai/deployments/{deployment}/...)
• Attach ?api-version=... to every request
• Apply a 600s default timeout for Azure image-generation calls, though per-call timeoutMs values still take precedence.

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

Note

Azure routing for the openai provider's image-generation path needs OpenClaw 2026.4.22 or newer. Older releases treat any custom openai.baseUrl as the public OpenAI endpoint and fail against Azure image deployments.

API version

To lock in a specific Azure preview or GA version for the Azure image-generation path, set AZURE_OPENAI_API_VERSION:

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

When the variable is unset, the default is 2024-12-01-preview.

Model names are deployment names

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

If a deployment named gpt-image-2-prod serves gpt-image-2:

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

That deployment-name rule also holds for any image-generation call routed through the bundled openai provider.

Regional availability

Azure image generation works only in a limited set of regions (for instance eastus2, swedencentral, polandcentral, westus3, uaenorth). Verify Microsoft's current region list before setting up a deployment, and ensure the specific model is available in your region.

Parameter differences

Azure OpenAI and public OpenAI do not always accept identical image parameters. Azure might reject options public OpenAI permits (such as certain background values on gpt-image-2) or expose them only on particular model versions. These variations stem from Azure and the underlying model, not OpenClaw. If an Azure request returns a validation error, inspect the parameter set supported by your deployment and API version in the Azure portal.

Note

Azure OpenAI uses native transport and compat behavior but does not get 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 adopt 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 remains on OpenClaw instead of implicitly selecting Codex. Valid fastMode / fast_mode values and valid cutoff keys are typed agent-runtime controls and do not choose 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 thus pick the declared OpenClaw fallback even with explicit agentRuntime.id: "codex", see Runtime selection.

Transport (WebSocket vs SSE)

Direct API-key calls default to SSE streaming. To switch an eligible official OpenAI endpoint into Responses WebSocket mode, set params.transport.

Cached modes hold one eligible connection per session. When the current history still matches the prior request and response, OpenClaw transmits only the new input and points to the earlier response via previous_response_id. If not, the full history goes out without that reference.

If setup or handshake fails before request dispatch, the call drops back to SSE; no retry or reconnect happens first. After dispatch, failures with an indeterminate outcome stay replay-unsafe and fail closed. The explicit server rejections previous_response_not_found and websocket_connection_limit_reached are safe exceptions: OpenClaw shuts down the failed socket and retries that turn once over SSE, sending full history and omitting the rejected previous_response_id.

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

Related OpenAI docs:

• Responses API WebSocket mode
• Streaming API responses (SSE)

Fast mode

A shared fast-mode toggle is exposed by OpenClaw 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 are not counted 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.

{
  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 and Codex harness.

Fast mode carries a premium price and is 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, API pricing, and Codex speed.

OpenAI API Fast mode with service_tier

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:

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

Server-side compaction (Responses API)

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.

Enable explicitly

Useful for store-capable endpoints like Azure OpenAI Responses. Setting this to true does not override endpoint or supportsStore capability:

{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.5": {
          params: { responsesServerCompaction: true },
        },
      },
    },
  },
}

Custom threshold

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: {
            responsesServerCompaction: true,
            responsesCompactThreshold: 120000,
          },
        },
      },
    },
  },
}

Disable

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { responsesServerCompaction: false },
        },
      },
    },
  },
}

Note

responsesServerCompaction affects only context_management injection. Direct OpenAI Responses models still enforce store: true unless compat sets supportsStore: false.

Strict-agentic GPT mode

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

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

Native vs OpenAI-compatible routes

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

Native routes (openai/*, Azure OpenAI):

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

Proxy/compatible routes:

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

Related

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