Set up Codex with Router

Codex lets you define your own model provider in its config.toml, which is all Router needs. This page shows how to add Router by hand. We also offer automated setup using the Router installer↗, which makes the same changes and lets you refresh Codex's model list with a single command.

Requirements: The Codex CLI or desktop app, and a Router API key from the API keys↗ page. Router supports Codex through the OpenAI Responses API.

Open API keys↗, create a key, and copy it. The secret is shown only once. Add it to your shell profile (for example ~/.zshrc) so Codex can read it:

export RAMP_ROUTER_API_KEY="your-router-key"

Codex reads ~/.codex/config.toml, or config.toml inside the directory named by CODEX_HOME if you have set it. Add the following. Keep the two root keys (model and model_provider) above any [table] headers in the file, because TOML requires root keys to come first.

model = "gpt-5.6-sol"
model_provider = "ramp-router"
 
[model_providers.ramp-router]
name = "Ramp Router"
base_url = "https://api.router.com/v1"
env_key = "RAMP_ROUTER_API_KEY"
wire_api = "responses"
supports_websockets = false

Replace gpt-5.6-sol with any model from GET /v1/models for your key:

curl https://api.router.com/v1/models \
  -H "Authorization: Bearer $RAMP_ROUTER_API_KEY"

Here is what the provider settings do:

Restart your Codex sessions to use Router. To try a different model for one session, pass it with codex --model <model-id>.

The Codex desktop app, and any Codex you launch from a launcher rather than a terminal, generally doesn't see variables exported in your shell profile. Instead, store the key in a file only you can read and have Codex run a command to print it:

mkdir -p ~/.codex
printf '%s' 'your-router-key' > ~/.codex/ramp-router-key
chmod 600 ~/.codex/ramp-router-key

Then replace the env_key line in the provider with an auth table. Codex runs the command whenever it needs the key, so rotating the key means rewriting the file and nothing else:

[model_providers.ramp-router]
name = "Ramp Router"
base_url = "https://api.router.com/v1"
wire_api = "responses"
supports_websockets = false
 
[model_providers.ramp-router.auth]
command = "/bin/cat"
args = ["/Users/you/.codex/ramp-router-key"]
timeout_ms = 5000

Use the absolute path to your own home directory. On Windows, use command = "cmd" and args = ["/c", "type", "C:\\Users\\you\\.codex\\ramp-router-key"].

With the setup above, you choose models by setting model in config.toml or passing --model. To have Codex discover the models your key can use, tell Router you're using Codex and give Codex its own system prompt to go with Router's model list. This needs the key-file setup above, because Codex only asks a provider for its model list when it authenticates with a command.

First, save Codex's own system prompt. Codex ships prompts only for OpenAI models, built into the program, so this step needs the ID of an OpenAI model. Any other ID gives you an empty file. These commands use jq↗, but any tool that reads JSON works. To see which IDs your version of Codex includes:

codex -c 'model_provider="openai"' debug models --bundled | jq -r '.models[].slug'

Then save the prompt for one of them, replacing gpt-5.6-sol with your choice:

codex -c 'model_provider="openai"' debug models --bundled \
  | jq -r '.models[] | select(.slug == "gpt-5.6-sol") | .base_instructions' \
  > ~/.codex/ramp-router-instructions.md

Codex uses this single prompt for every model you run through Router, including models that aren't from OpenAI, so choose the OpenAI model closest to the one you use most.

Then add the instructions file to the root of config.toml, and a header to the provider:

model_instructions_file = "/Users/you/.codex/ramp-router-instructions.md"
 
[model_providers.ramp-router]
# ...the settings from above...
http_headers = { "X-Gateway-Client" = "codex" }

Always set both: the header asks Router for a model list shaped for Codex, and that list doesn't include Codex's own instructions. If you add the header without model_instructions_file, Codex runs without its usual system prompt, which makes it much less effective.

Codex's desktop app keeps one model cache shared by every provider, so OpenAI's model list can replace Router's in its picker. If that happens, set model in config.toml directly, or use ramp router configure codex, which keeps a snapshot of Router's list for the app.

Codex doesn't pick up new Router models on its own with this setup. When Router adds a model, change model to its ID. If you use the picker setup, re-run the instructions command above after upgrading Codex so the file matches your version.

If you install the Ramp CLI, a single command does this for you: ramp router refresh updates Codex's model list to match what Router currently offers.

Remove the model, model_provider, and model_instructions_file lines and the [model_providers.ramp-router] tables from config.toml, and delete the key and instructions files. Codex then goes back to your usual provider.

If a failure persists, report it to the Router team with the x-request-id from the response. See Support and feedback↗.