Codex router: run OpenAI Codex CLI on any model (2026 guide)
By Felix Wunderlich -
Updated August 13, 2026. Commands verified at publish time with Codex CLI 0.147.0.
TL;DR: the mechanism is a nine-line block in ~/.codex/config.toml, a custom provider with wire_api = "responses" pointing at a Responses-compatible gateway, plus features.multi_agent = false for third-party backends. That runs Codex on GPT-family models through Opper, an EU-hosted route included, and switching is a codex -m flag. Most older tutorials are broken because wire_api = "chat" was removed in February 2026. For the full 700+ catalog inside a coding agent today, opper launch opencode is the tested one-command path.
OpenAI's Codex CLI is an open-source agentic coding harness, Apache-2.0 licensed with over 105,000 GitHub stars and a release cadence measured in days, and by default it is wired to OpenAI's own API. That combination is why "Codex router" became its own category of search: developers want the harness with a different engine behind it, a cheaper model for routine work, an EU-hosted deployment for compliance, or simply one key and one bill across providers. This guide covers the mechanism Codex actually supports, the 2026 changes that quietly broke most older tutorials, and the exact configurations we verified with Codex CLI 0.147.0 in August 2026. If your harness is Claude Code rather than Codex, we wrote the same guide for it.
One disambiguation up front, because the terms collide constantly: a Codex router is anything that points Codex's traffic at a different backend, while OpenRouter is one specific hosted backend such a setup can point at. Both appear below.
Which Codex routing path fits?
| Path | What you run | Models | Billing | EU option |
|---|---|---|---|---|
config.toml → Opper | A nine-line config block | 700+ catalog; OpenAI-family models verified through Codex today | One bill at provider rates | GPT-5.5 on Azure's EU data zone, tested |
config.toml → OpenRouter | Nothing extra | OpenRouter's catalog, exact slugs required | OpenRouter's billing | Depends on the provider serving each request |
codex --oss local | Ollama or LM Studio | Local open-weight models | Free, your hardware | Your machine |
opper launch opencode | The Opper CLI plus opencode | Full 700+ catalog over chat completions | One bill at provider rates | EU routes available |
How does Codex CLI talk to a different provider?
Unlike Claude Code, Codex has no generic environment variable that overrides where requests go; the openai_base_url setting only re-points the built-in OpenAI provider. The real mechanism lives in ~/.codex/config.toml (project-scoped .codex/config.toml files work too, in projects you have trusted): a [model_providers.<id>] block with a name, a base_url, an env_key naming the environment variable that holds your API key, and a wire_api, activated by setting top-level model_provider and model, all per OpenAI's config reference. The built-in ids openai, ollama and lmstudio are reserved, so a custom provider needs its own id.
Why do most Codex router tutorials fail in 2026?
Two breaking changes gutted the tutorial ecosystem. First, wire_api = "chat" no longer exists: Codex deprecated the chat completions wire protocol in December 2025 and removed it in February 2026, so every config that sets it now fails hard with instructions to use "responses", the only supported value. The community discussion records the fallout, since much of the ecosystem at the time, Ollama, vLLM and LiteLLM among them, spoke only chat completions. The practical consequence is that a Codex backend must implement the OpenAI Responses API properly, streaming included, and any tutorial that routes Codex over /chat/completions is dead on arrival. Second, profiles changed format: --profile now layers a separate $CODEX_HOME/<name>.config.toml file on top of the base config, so older tutorials built around [profiles.x] tables inside the main config.toml no longer match how current versions document profiles. The reliable pattern in August 2026 is also the simplest one, top-level configuration and no profiles.
Option 1: a nine-line config to a hosted gateway
This is the configuration we verified end to end on Codex CLI 0.137.0 and 0.147.0, real completed turns and all:
# ~/.codex/config.toml
model = "openai/gpt-5.3-codex"
model_provider = "opper"
[features]
multi_agent = false
[model_providers.opper]
name = "Opper"
base_url = "https://api.opper.ai/v3/compat"
env_key = "OPPER_API_KEY"
wire_api = "responses"
Then export your key and start Codex as usual:
export OPPER_API_KEY="your-key" # from your Opper account
codex
What makes this work after February 2026 is that Opper's gateway serves a Responses-compatible endpoint at /v3/compat, alongside its OpenAI and Anthropic chat endpoints, where chat-only gateways can no longer sit behind Codex at all. Switching models is a flag, for example codex -m azure/gpt-5.5, using ids from the model catalog, 700+ models, and billing goes through the gateway at provider rates with no markup on inference.
The multi_agent = false line is load-bearing. Codex's multi-agent feature advertises extra tools to the backend, a tool_search tool among them, and in our tests third-party Responses backends mishandle them, ours included today: the visible symptom is a session that hangs or drops with "stream disconnected before completion". Disabling the feature removes those tools client-side and sessions complete normally. The trade-off is honest: Codex's sub-agent spawning is off for routed sessions, and feature flags are an unstable surface that can change with any release, so treat this as an August 2026 workaround rather than a permanent incantation.
One more honest boundary: Codex ships some of its tools in OpenAI-specific formats, freeform grammar custom tools among them, and in our tests non-OpenAI upstreams rejected those payloads, so the verified scope for Codex through Opper today is OpenAI-family models, openai/* and Azure-served GPT deployments. That verified set includes azure/gpt-5.5, which is served from Azure OpenAI's EU data zone, so the EU-residency claim in the table above is tested, not theoretical. For the rest of the catalog inside a coding agent, see the opencode section below.
Option 2: OpenRouter direct, or fully local
OpenRouter documents Codex CLI officially, which is more than most gateways can say: the same model_providers block with base_url = "https://openrouter.ai/api/v1", wire_api = "responses" and env_key = "OPENROUTER_API_KEY", with the model set to an exact OpenRouter slug, provider prefix included, and the config placed at user level. Their June 2026 tutorial uses top-level configuration, the pattern that still matches current Codex versions. The balance point, stated gently because it applies to everyone building against OpenAI's newest protocol: there are reports of intermittent Responses request failures with codex exec through OpenRouter, closed by the Codex team as not planned, and third-party Responses implementations simply vary in polish, which is exactly what the multi_agent flag in option 1 compensates for on our side.
Fully local needs no router at all, because it is built into Codex itself: codex --oss with --local-provider ollama or --local-provider lmstudio runs against local open-weight models, free apart from your hardware.
What about opencode?
If the goal is any model inside a coding agent rather than Codex specifically, opencode is the harness where the whole catalog works today. It is MIT-licensed, maintained by Anomaly (formerly sst/opencode) with over 196,000 GitHub stars, and it speaks the chat completions format every provider serves, so the tool-format ceiling that limits Codex does not apply, DeepSeek and Claude included. Through the Opper Agent CLI it is a one-command setup, verified working end to end in our tests:
npx @opperai/cli login # one OAuth sign-in
opper launch opencode # opencode, routed through Opper
The launcher grafts an opper provider into your existing opencode config rather than overwriting it, pre-populates the model picker with a curated set, defaults to opper/claude-opus-4-7, and addresses any catalog model as opper/<model-id>, headless runs included via opencode run -m opper/claude-opus-4-7 "…". Every session ends with a summary of duration, models, tokens and cost, plus a link to the full traces.
What changes when you leave api.openai.com?
Billing follows the credential: codex login with ChatGPT sign-in includes usage in your plan, codex login --with-api-key bills at OpenAI's API rates, and a custom provider with an env_key bills through that provider, so a ChatGPT Plus or Pro subscription never applies off OpenAI's own endpoint. On support, the model_providers mechanism itself is documented by OpenAI, while running non-OpenAI models behind it is unendorsed territory, and Codex's tooling is visibly tuned for its GPT-5.x-codex models. And your data path becomes whatever the backend makes it: a gateway's own hosting is not the same thing as where inference runs, so check which deployment actually serves your tokens before pointing an agent full of proprietary source at it, which is why our routes state residency per deployment.
Codex router FAQ
Why does my Codex config with wire_api = "chat" fail?+
The chat completions wire protocol was removed from Codex CLI in February 2026, after a December 2025 deprecation, and "responses" is now the only supported value. Any config or tutorial routing Codex over /chat/completions predates the change and cannot work on current versions; the backend you point at must implement the OpenAI Responses API. The removal and its fallout are documented in the Codex repo discussion.
Can I use my ChatGPT Plus or Pro subscription through a Codex router?+
No. Subscription usage applies only to sessions where Codex talks to OpenAI via ChatGPT sign-in. A custom provider authenticates with its own key through env_key and bills through that provider at its API rates, so routed sessions are never covered by a ChatGPT plan.
Does Codex CLI work with OpenRouter?+
Yes, and OpenRouter documents the setup in a first-party tutorial: a model_providers block with their base URL, wire_api set to "responses", and the model as an exact OpenRouter slug including the provider prefix. There are reports of intermittent Responses request failures with codex exec on record, so expect polish to vary, as it does across all third-party Responses implementations today.
Can Codex CLI run DeepSeek V4?+
Not reliably,. Codex sends its tools in OpenAI-specific formats, freeform grammar custom tools included, and in our tests DeepSeek V4 deployments rejected those payloads regardless of the route. The dependable way to run DeepSeek V4 inside a coding agent today is opencode, which speaks the chat completions format DeepSeek serves everywhere; opper launch opencode sets that up in one command.
What is the difference between a Codex router and OpenRouter?+
A Codex router is any setup that points Codex CLI's Responses-API traffic at a backend other than api.openai.com, using the config.toml model_providers mechanism. OpenRouter is one hosted backend such a setup can point at; Opper's gateway is another, and a local Ollama via codex --oss is a third. The router is the mechanism, OpenRouter is a destination.
Can Codex run fully offline?+
Yes, and it is built in: codex --oss with --local-provider ollama or --local-provider lmstudio runs Codex against local open-weight models with no gateway involved. Capability depends entirely on how strong a model your hardware can serve.
How do I keep Codex inference in the EU?+
Route it to an EU-hosted model deployment, and check the deployment rather than the gateway's address, since where a gateway company runs is not where inference runs. A tested configuration from this guide: codex -m azure/gpt-5.5 through Opper serves GPT-5.5 from Azure OpenAI's EU data zone. How routes and residency work is covered in our compliance overview, and each entry in the model directory shows the region serving it.
What does features.multi_agent = false actually do?+
It turns off Codex's multi-agent feature, which advertises extra tools, tool_search among them, that many third-party Responses backends mishandle, causing sessions to hang or drop with "stream disconnected before completion". With the flag set, those tools are not sent and routed sessions complete normally, at the cost of sub-agent spawning. Feature flags are an unstable surface, so re-test after Codex upgrades.
Pick your lane
If you want Codex on GPT-family models through one gateway, with an EU-hosted route and one bill, the nine-line config above is tested and takes about two minutes. If you would rather go direct, OpenRouter documents its own setup and codex --oss covers fully local. And if the real goal is any of 700+ models inside a coding agent today, install the Opper CLI and you are one opper launch opencode away, or create a free account first and browse the models it unlocks.