OpenAI Codex configuration for OpenRouter

OpenAI’s coding & work tool Codex is not tied to OpenAI as a first-party model provider. In particular, it allows OpenRouter to be used - a hub to currently 480 models offered by independent inference providers. These inference providers offer models not found in the OpenAI like OpenAI’s own open-weights models gpt-oss-20b or gpt-oss-120b, or third party models including Gemini, Claude, Grok or GLM. (There is a bug that prevents these third party models from actually being used, see below).

Basics

Codex configuration is in ~/.codex/config.toml on Mac. The first thing to change is the OpenAI centric model specifier from:

model = "gpt-5.6-sol"

to perhaps:

model = "openai/gpt-5.6-sol"

and tell Codex to the OpenRouter provider:

model_provider = "openrouter"

with the provider definition further down below, perhaps before the projects sections start:

[model_providers.openrouter]
name = "openrouter"
base_url="https://openrouter.ai/api/v1"

Authentication

Authentication to OpenRouter works by API keys, which OpenRouter describes here. The advice given there to use the API keys as Bearer token does not work with Codex, however. Passing it through the http_headers configuration setting in the provider section like this:

[model_providers.openrouter]
...
http_headers = { "Authorization" = "Bearer sk-or-v1-..." }

would cause this error message in Codex when trying to use the model:

unexpected status 401 Unauthorized: Missing Authentication header, url: https://openrouter.ai/api/v1/responses

This is a documented issue. The fix is to use a dedicated setting:

[model_providers.openrouter]
name = "openrouter"
base_url="https://openrouter.ai/api/v1"
experimental_bearer_token = "sk-or-v1-..."

Another fix could be to use environment variables as documented by OpenAI for Codex and custom providers.

Tool-use bug

When trying to use a model that is not offered by OpenAI as a first party provider (including gpt-oss), Codex will show this error message:

No endpoints found that support the native `namespace` tool type. To learn more about provider routing, visit: https://openrouter.ai/docs/guides/routing/provider-selection

Codex Github issue #32318 tracks this.