OpenAI

OpenClaw uses one provider id, openai, for both direct API-key auth and ChatGPT/Codex subscription auth. openai/* is the standard model route. For embedded agent turns with runtime policy unset or auto, OpenAI's route facts decide whether OpenClaw may select the bundled Codex app-server runtime implicitly. The openai/* prefix alone does not select a runtime.

• Agent models - openai/* through the runtime selected by explicit agentRuntime config or OpenAI's implicit route policy. Sign in with Codex auth for ChatGPT/Codex subscription use, or configure an API-key auth profile when you want key-based billing.
• Non-agent OpenAI APIs - direct OpenAI Platform access, billed per use, through OPENAI_API_KEY or an openai API-key auth profile.
• Legacy config - codex/* and openai-codex/* refs are repaired to openai/* plus model-scoped agentRuntime.id: "codex" by openclaw doctor --fix.

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

This page is an index. OpenAI is documented on nine pages, one per reader job. Open the page that matches your task.

Where each section moved

Every anchor the single-page version published still resolves here, so an existing link such as /providers/openai#implicit-agent-runtime keeps working. Each entry points at the page that now holds the content.

OpenAI setup

• Getting started
• Route summary
• Config example
• Route summary
• Config example
• Check and recover Codex OAuth routing
• Status indicator
• Doctor warning
• Context window defaults and long-context opt-in
• Embedded OpenClaw translation
• Native Codex translation
• Catalog recovery
• API key (OpenAI Platform)
• Get your API key
• Run onboarding
• Verify the model is available
• Codex subscription
• Run Codex OAuth
• Use the standard OpenAI model route
• Verify Codex auth is available

OpenAI models

• Quick choice
• Retired subscription model references
• GPT-6 Astra
• Async tools, steering, and reasoning changes
• GPT-5.6 limited preview

OpenAI runtimes and Codex auth

• Naming map
• Implicit agent runtime
• Native Codex app-server auth

OpenAI coverage and cost

• Usage and cost tracking
• OpenClaw feature coverage
• Memory embeddings

OpenAI image generation

• Image generation
• Supported video providers

OpenAI voice and speech

• Voice and speech
• Gateway-controlled Realtime call cleanup
• GA Realtime browser authentication
• Released GPT-Live browser and Gateway relay authentication
• Unlisted and private realtime transport paths
• Speech synthesis (TTS)
• Speech-to-text
• Realtime transcription
• Realtime voice

Azure OpenAI endpoints

• Azure OpenAI endpoints
• Configuration
• API version
• Model names are deployment names
• Regional availability
• Parameter differences

OpenAI advanced configuration

• GPT-5 prompt contribution
• Advanced configuration
• Config
• CLI
• Transport (WebSocket vs SSE)
• Fast mode
• OpenAI API Fast mode with service_tier
• Server-side compaction (Responses API)
• Enable explicitly
• Custom threshold
• Disable
• Strict-agentic GPT mode
• Native vs OpenAI-compatible routes

Related

For hosted execution, file handling, and connected tools in chat, see the Agents API guide.

Decision models

The bundled openai plugin supports the beta OpenAI Decisions API through OpenClaw's Decision model role. Configure OPENAI_API_KEY or an openai API-key auth profile, then select openai/gpt-6-luna in the Decision picker or set:

{  agents: { defaults: { decisionModel: "openai/gpt-6-luna" } },}

The account and selected model must have Decisions API access. OpenClaw requires a Platform API key for Decisions. It excludes ChatGPT/Codex subscription profiles and Sign in with ChatGPT token-sharing grants before credential resolution. The provider selects the Decisions route before credential resolution. A model-level baseUrl takes precedence over the provider URL, then OPENAI_BASE_URL, then the Platform default. A custom Platform-compatible endpoint must implement the native POST /decisions question and image contract; route metadata does not validate a custom endpoint's implementation. Declare the supported model under models.providers.openai.models when using a custom provider URL; implicit native model discovery does not advertise models for arbitrary endpoints. ChatGPT backend URLs are rejected. Prepared provider, model and request headers retain their normal precedence. An explicit @profile selection remains locked; an incompatible subscription profile does not fall through to a different account.

Boolean questions map to predicates; choices retain their string labels; score levels use zero-based rubric positions. A V2 batch supports up to 400 questions, with up to 255 alternatives per choice question. Larger requests return unsupported-input before credential resolution or an API call. Split independent questions into separate batches, or reduce the alternatives. Legacy V1 callers retain the host's 256-question limit; use contractVersion: 2 for larger batches.

The prepared V2 adapter accepts tagged text, JSON, or one inline PNG, JPEG, or WebP image up to 4 MiB, with optional text. It does not fetch remote image URLs. Explicit JSON scalars and strings remain JSON-encoded; text remains literal. Omitted reasoning and reasoning: "auto" preserve the endpoint default; explicit on and off controls are unsupported. Boolean, Choice, and Score questions work with image evidence. OpenClaw's image envelope is an integration limit, not a claim about the vendor's maximum.

A per-question refusal becomes an error answer with providerCode: "refusal"; successful siblings remain available. Malformed or incomplete answers return invalid-response. Probabilities, fractional scores, confidence, and input/output token usage are preserved. Decision cost stays unknown unless reported; chat token prices do not price this endpoint. V1 text/JSON callers still use the lossless bridge, so a refusal batch cannot be narrowed to V1.

Selecting a Decision model does not replace the primary chat model or enable automatic Decision assistance. Explicit evaluations send the supplied evidence to OpenAI and use Platform billing.

Harness and authentication

Both the OpenClaw and Codex harnesses expose the shared decision_evaluate tool when a Decision model is configured, subject to normal tool policy. The OpenAI plugin sends its requests to POST /v1/decisions. Codex's native model loop still uses Responses.

With automatic OAuth-only discovery, an evaluation returns credentials-unavailable without an API request. An explicitly incompatible provider credential binding remains terminal; OpenClaw does not substitute another account. Configure the Decision API key through OpenClaw's existing OpenAI auth setup, without changing the primary model or Codex login.