OpenAI Provider: API Keys and Codex Auth

OpenClaw relies on a single provider id, openai, for two things: authenticating directly with an API key, and authenticating through a ChatGPT/Codex subscription. The standard model route is openai/*. When an embedded agent turn runs with runtime policy unset or set to auto, OpenAI's route facts determine whether OpenClaw is allowed to pick the bundled Codex app-server runtime on its own. A openai/* prefix by itself does not choose a runtime.

Agent models - openai/* runs through whichever runtime is chosen either by an explicit agentRuntime config or by OpenAI's implicit route policy. For ChatGPT/Codex subscription use, sign in with Codex auth; if you prefer billing by key, set up an API-key auth profile.
Non-agent OpenAI APIs - direct OpenAI Platform access, charged per use, via OPENAI_API_KEY or an openai API-key auth profile.
Legacy config - codex/* and openai-codex/* refs get repaired into openai/* plus a model-scoped agentRuntime.id: "codex" by openclaw doctor --fix.

OpenAI states outright that subscription OAuth usage is supported in external tools and workflows such as OpenClaw.

What follows is an index. Nine pages cover OpenAI, each aimed at one reader job. Pick the page that fits what you are doing.

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

All anchors that the single-page version published still resolve on this page, so links already in the wild, like /providers/openai#implicit-agent-runtime, continue to work. Every entry sends you to the page where that content now lives.

OpenAI setup

OpenAI models

OpenAI runtimes and Codex auth

OpenAI coverage and cost

OpenAI image generation

OpenAI voice and speech

Azure OpenAI endpoints

OpenAI advanced configuration

When you need hosted execution, file handling, or connected tools inside chat, consult the Agents API guide.

Model selection, How providers, model refs, and failover behavior are chosen.
Image generation, Parameters shared by the image tool, plus how a provider is picked.
Video generation, Parameters shared by the video tool, plus how a provider is picked.
OAuth and auth, Details on authentication and the rules for reusing credentials.

Decision models

Beta access to the OpenAI Decisions API is available through the bundled openai plugin, which reaches it via OpenClaw's Decision model role. Set up an OPENAI_API_KEY profile or an openai API-key auth profile, then pick openai/gpt-6-luna in the Decision picker, or set:

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

Both the account and the chosen model need Decisions API access. A Platform API key is mandatory for Decisions in OpenClaw. ChatGPT/Codex subscription profiles, along with Sign in with ChatGPT token-sharing grants, are filtered out before credential resolution. The Decisions route is selected by the provider ahead of credential resolution. A model-level baseUrl outranks the provider URL, which in turn outranks OPENAI_BASE_URL, and the Platform default comes last. Any custom Platform-compatible endpoint has to implement the native POST /decisions question and image contract; route metadata alone does not check whether a custom endpoint's implementation is correct. When a custom provider URL is in use, declare the supported model under models.providers.openai.models; models for arbitrary endpoints are not advertised through implicit native model discovery. ChatGPT backend URLs are refused. Prepared provider, model and request headers keep their usual precedence. Once an explicit @profile selection is made it stays locked; an incompatible subscription profile will not fall through to another account.

Predicates are what boolean questions map to; choice labels stay as their strings; score levels are indexed by zero-based rubric positions. A single V2 batch can carry up to 400 questions, and each choice question allows up to 255 alternatives. Requests beyond that return unsupported-input before credential resolution or any API call. Either split independent questions across separate batches or cut down the alternatives. Callers still on legacy V1 keep the host's 256-question limit; larger batches require contractVersion: 2.

The V2 adapter that ships ready to use accepts tagged text, JSON, or a single inline PNG, JPEG, or WebP image of up to 4 MiB, optionally accompanied by text. Remote image URLs are not fetched. Strings and explicit JSON scalars stay JSON-encoded, while text stays literal. Leaving reasoning and reasoning: "auto" out keeps the endpoint default; the explicit on and off controls are not supported.

Boolean, Choice, and Score questions can be answered using image evidence. The image envelope OpenClaw applies is a limit of the integration, not a statement about the vendor's maximum.

When a single question is refused, it turns into an error answer carrying providerCode: "refusal", and its successful siblings stay available. Answers that are malformed or incomplete return invalid-response. Probabilities, fractional scores, confidence, and input/output token usage are all kept. Decision cost remains unknown unless it is reported; chat token prices do not apply to this endpoint. Callers on V1 text/JSON still go through the lossless bridge, which means a batch containing a refusal cannot be narrowed down to V1.

Picking a Decision model neither swaps out the primary chat model nor turns on automatic Decision assistance. An explicit evaluation sends the evidence you supply to OpenAI and is billed through Platform.

Harness and authentication

When a Decision model is configured, the shared decision_evaluate tool is exposed by both the OpenClaw and Codex harnesses, subject to the usual tool policy. Requests from the OpenAI plugin go to POST /v1/decisions. Codex's native model loop continues to use Responses.

Primary-model harness	Primary-model auth	Decision auth and behavior
OpenClaw	Platform API key	A compatible OpenAI API key is resolved by the shared tool.
OpenClaw	ChatGPT OAuth	The shared tool needs its own OpenAI API-key profile or `OPENAI_API_KEY`.
Codex	Platform API key	The shared tool resolves an OpenClaw OpenAI API key on its own, separate from Codex's native credentials.
Codex	ChatGPT OAuth	Chat can still use the native Codex login. The shared tool needs an OpenClaw OpenAI API-key profile or `OPENAI_API_KEY`.

Under automatic OAuth-only discovery, an evaluation comes back with credentials-unavailable and no API request is made. A provider credential binding that is explicitly incompatible stays terminal; OpenClaw will not swap in a different account. Set up the Decision API key through OpenClaw's existing OpenAI auth configuration, leaving the primary model and the Codex login untouched.