---
source_url: https://opper.ai/blog/codex-router
title: "Codex router: run OpenAI Codex CLI on any model (2026 guide)"
description: "How to route OpenAI Codex CLI to other models in 2026: the config.toml mechanism, why old wire_api tutorials broke, plus tested gateway and local setups."
author: "Felix Wunderlich"
published: 2026-08-13
---

# Codex router: run OpenAI Codex CLI on any model (2026 guide)

By Felix Wunderlich, 13 Aug 2026

*Updated September 29, 2026. Commands verified at publish time with Codex CLI 0.147.0 and retested with Codex CLI 0.159.0 on September 29.*

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](https://github.com/openai/codex) 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](https://opper.ai/blog/claude-code-router).

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](https://opper.ai/models); GPT and DeepSeek V4 tested September 29, non-OpenAI models with web search off | 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 codex` | The Opper CLI plus Codex | Any catalog model via `--model`; GPT-5.5, Claude Sonnet 5, Gemini 3.1 Pro, DeepSeek V4 and Kimi K2.6 tested September 29 | One bill at provider rates | EU routes available |
| `opper launch opencode` | The Opper CLI plus opencode | Full [700+ catalog](https://opper.ai/models) 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](https://developers.openai.com/codex/config-reference). The built-in ids `openai`, `ollama` and `lmstudio` are reserved, so a custom provider needs its own id.

```mermaid
flowchart LR
  CX["Codex CLI"] -->|"model_provider in config.toml"| R{"Which provider block?"}
  R -->|"default"| OA["api.openai.com<br/>ChatGPT sign-in or API key"]
  R -->|"custom: opper"| OP["Opper /v3/compat<br/>Responses endpoint, one key"]
  R -->|"custom: openrouter"| ORT["OpenRouter /api/v1<br/>their slugs, their billing"]
  R -->|"--oss"| L["Ollama or LM Studio<br/>local models"]
```

## 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](https://github.com/openai/codex/discussions/7782) 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:

```toml
# ~/.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:

```bash
export OPPER_API_KEY="your-key"  # from your Opper account
codex
```

What makes this work after February 2026 is that [Opper's gateway](https://opper.ai/llm-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](https://opper.ai/models), 700+ models, and billing goes through the gateway at provider rates with [no markup on inference](https://opper.ai/pricing).

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, dated: in our August tests (Codex 0.137.0 and 0.147.0), non-OpenAI upstreams rejected some of the OpenAI-specific tool payloads Codex sends, so the scope we verified then 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. We retested on September 29 with Codex 0.159.0. Through `opper launch codex` (Opper CLI 0.1.37), GPT-5.5, Claude Sonnet 5, Gemini 3.1 Pro, Gemini 3.5 Flash, DeepSeek V4 Pro, DeepSeek V4 Flash and Kimi K2.6 each completed a turn that wrote a file and ran a shell command. The launcher starts on Claude Opus 5 unless you pass `--model`, and it turns off Codex's built-in web search tool, which non-OpenAI upstreams reject (DeepSeek returned "Extra inputs are not permitted", Gemini a 502 naming the unsupported tool). With the config block above and a non-OpenAI model, add `web_search = "disabled"` for the same effect: DeepSeek V4 Flash failed without it and completed with it. Two caveats remain: Codex warns that it has no metadata for non-OpenAI model ids and falls back to defaults, and DeepSeek wrote its file through the shell rather than Codex's patch tool. 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](https://openrouter.ai/blog/tutorials/codex-cli-openrouter/), 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](https://github.com/openai/codex/issues/12114) 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](https://opencode.ai/docs/) 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](https://opper.ai/agent-cli) it is a one-command setup, verified working end to end in our tests:

```bash
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](https://opper.ai/ai-compliance).

---

## 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](https://github.com/openai/codex/discussions/7782).

**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](https://openrouter.ai/blog/tutorials/codex-cli-openrouter/): 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?**

Yes, on current Codex. In our September 29 retest with Codex 0.159.0, `opper launch codex --model deepinfra/deepseek-v4-pro` (and `deepinfra/deepseek-v4-flash`) completed turns that wrote a file and ran a shell command. With a hand-written config, add `web_search = "disabled"`, since DeepSeek rejects Codex's built-in web search tool. In our August tests on Codex 0.137.0 and 0.147.0 it was not reliable. The other route for DeepSeek V4 inside a coding agent is opencode, which speaks the chat completions format DeepSeek serves everywhere; [opper launch opencode](https://opper.ai/agent-cli) 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](https://opper.ai/ai-compliance), and each entry in the [model directory](https://opper.ai/models) 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](https://opper.ai/agent-cli) and you are one `opper launch opencode` away, or [create a free account](https://opper.ai/sign-up/free) first and browse the [models](https://opper.ai/models) it unlocks.
