openclaw/docs/providers/openai.md

summary	read_when	title
Use OpenAI via API keys or Codex subscription in OpenClaw	You want to use OpenAI models in OpenClaw You want Codex subscription auth instead of API keys You want Astra async tools, mid-turn steering, or cached reasoning changes You need stricter GPT-5 agent execution behavior	OpenAI

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

Page	Read it when
OpenAI setup	You are connecting an account: the API-key and Codex subscription paths, route summaries, OAuth recovery, and the long-context opt-in.
OpenAI authentication	Choose Codex login, an API key, or SIWC based on model access, plugins, usage tracking, and permissions.
OpenAI models	You are choosing a model ref: the quick-choice table, GPT-6 Astra, Sol, Luna, and the GPT-5.6 tiers.
OpenAI runtimes and Codex auth	You need to know which runtime runs an openai/* turn, and how native Codex resolves its account.
OpenAI coverage and cost	You want the capability matrix, memory embeddings, or how subscription quota and Platform billing are reported.
OpenAI image generation	You are generating or editing images through the bundled openai plugin.
OpenAI voice and speech	You are configuring text-to-speech, transcription, or realtime voice, including per-route auth order.
Azure OpenAI endpoints	You are pointing the bundled openai provider at an Azure OpenAI resource.
OpenAI advanced configuration	You are tuning prompt contribution, transport, Fast mode, compaction, strict-agentic mode, or proxy compat.

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

Choosing providers, model refs, and failover behavior. Shared image tool parameters and provider selection. Shared video tool parameters and provider selection. Auth details and credential reuse rules.