Intelligent Model Routing for Codex CLI

How Codex CLI uses a custom model provider

Codex CLI, OpenAI's open-source coding agent for the terminal, can send its requests to providers other than OpenAI. You describe the provider in a [model_providers.<id>] table in ~/.codex/config.toml, with a name, a base_url and the environment variable that holds the key (env_key), then select it with model_provider.

Two details matter for any router:

• Responses API only. Codex's configuration reference says "responses" is the only supported value of wire_api, and current releases don't support a Chat Completions-only endpoint. The router must accept POST /v1/responses and stream its events.
• User-level config. A project's own .codex/config.toml ignores model_provider and model_providers, so the provider belongs in your user-level ~/.codex/config.toml.

Air Router offers the Responses API at https://api.airllm.ai/v1, so Codex can use it as a custom provider.

Why route Codex CLI's requests

A single Codex task is rarely a single model call. Codex reads files, runs commands in its sandbox, looks at the output and edits again, and each turn of that loop is another request carrying your instructions, AGENTS.md, tool results and the conversation so far. Some of those turns are demanding, like working out why a test fails. Many are routine, like listing files or summarising command output.

With one fixed model, every turn is billed at that model's rate, whether it needed it or not. A model router lets the routine turns run on fast, efficient models and saves the stronger models for the turns that need them. It can also fall back to another eligible model when a provider has a problem, so a long session isn't stopped by one failed call. You keep Codex's own loop, approvals and sandbox exactly as they are.

Set up Codex CLI with Air Router

The AirLLM setup script can write this configuration for you. To do it by hand on macOS or Linux:

1. Check Codex is installed

   Run codex --version.

2. Add AirLLM as a provider

   Add the lines below to ~/.codex/config.toml.

3. Set your key

   Export AIRLLM_API_KEY in your shell, and add the same line to ~/.zshrc (or ~/.bashrc) to keep it.

4. Send a test prompt

   Run Codex with a small task and check the result.

model = "airllm-auto"
model_provider = "airllm"

[model_providers.airllm]
name = "AirLLM"
base_url = "https://api.airllm.ai/v1"
env_key = "AIRLLM_API_KEY"
wire_api = "responses"

export AIRLLM_API_KEY="your_airllm_api_key"
codex "Write a simple Java method to validate an email address."

The key lives in its own variable, AIRLLM_API_KEY, so other OpenAI tools in your shell never pick it up. On Windows, the Developer Guide's Codex section has the PowerShell steps and the %USERPROFILE%\.codex\config.toml path; inside WSL, use the steps above.

Choose airllm-auto or airllm-openai

The model line holds an AirLLM routing model. Air Router reads it as a preference and matches each request to a suitable underlying model.

You can change the model for a single run with -m (for example codex -m airllm-openai) or with /model inside a session. The routing models page describes all six names.

Check that it works

Inside a Codex session, /status shows the current session configuration and token usage, so you can confirm the provider is airllm. Then send a short prompt and open your AirLLM dashboard: the request should appear in your usage logs. If it doesn't, Codex is still using another provider, usually because model_provider is missing or the key isn't exported in that terminal.

Everyday use: sessions, scripts and profiles

Because the provider is set in your user-level configuration, it applies whether you work interactively or script Codex with codex exec, which also accepts -m to choose a model. Approvals, sandbox modes, AGENTS.md and MCP servers are Codex features and work as they normally do.

If you also use Codex with your ChatGPT sign-in, a profile keeps the two apart. Since Codex 0.134.0, a profile is its own file, ~/.codex/<name>.config.toml, selected with --profile <name>. Older guides that use [profiles.x] tables inside config.toml are out of date.

What changes when Codex goes through Air Router

Codex keeps its own agent loop, tools and approvals. Air Router handles the model side: it routes each step to a suitable model, starting simple steps on fast models and escalating when checks fail, considers existing prompt caches before switching models, and reduces repeated file content and tool history before a request reaches the model. For the general idea, read what an AI coding agent router is; for Anthropic's agent, see the Claude Code router guide.

Troubleshooting

• 404 Not Found: the base_url must end in /v1: https://api.airllm.ai/v1.
• 401 Unauthorized: AIRLLM_API_KEY isn't set in this terminal, or the key is wrong.
• Provider not used: the provider is in a project's .codex/config.toml, which Codex ignores for provider settings. Move it to ~/.codex/config.toml.
• Wrong wire API: keep wire_api = "responses"; Codex no longer supports "chat".
• Model not found: use one of the six airllm-* names.
• Works in one terminal but not another: the key was exported only in the first window. Add the export line to your shell profile and open a new terminal.

More fixes are in the Developer Guide's troubleshooting section.

Frequently asked questions

Related

Sources

• Codex on GitHub (openai/codex)
• Codex docs — advanced configuration
• Codex docs — configuration reference
• Codex docs — gateway compatibility
• Codex docs — slash commands and CLI options