MonoRouter
All guides

Set Up Codex CLI with MonoRouter

Route OpenAI Codex CLI through the ChatGPT subscription connected to MonoRouter. One MonoRouter key, every Codex model, all usage on your dashboard alongside Claude Code.

What you need

One-command setup

The installer checks your key against the API before writing anything, then asks how you want it installed.

curl -sSL https://api.monorouter.com/setup/codex.sh | bash

You can pass the key directly to skip the prompt:

curl -sSL https://api.monorouter.com/setup/codex.sh | bash -s -- mrk_yourkey

Two install modes

  • •codex-mono (recommended) — installs a separate codex-mono command with its own CODEX_HOME. Your existing codex keeps talking to OpenAI directly, so you can use both. Undo by deleting two files.
  • •codex — rewires your existing command. Your current config is backed up to ~/.codex/config.toml.bak-<timestamp> first.
The codex-mono mode exists because overwriting a working Codex setup is a real cost. If you are not sure, take it — nothing about your current Codex install changes.

Non-interactive install

For scripted or CI setups, skip every prompt:

MONOROUTER_INSTALL_MODE=mono \
CODEX_MODEL=gpt-5.6-sol \
bash <(curl -sSL https://api.monorouter.com/setup/codex.sh) mrk_yourkey

MONOROUTER_INSTALL_MODE takes mono or replace.

Manual setup

If you would rather not run a script, add this to your ~/.codex/config.toml:

model = "gpt-5.6-sol"
model_provider = "monorouter"

[model_providers.monorouter]
name = "monorouter"
base_url = "https://api.monorouter.com/v1"
wire_api = "responses"
env_key = "MONOROUTER_API_KEY"

Then export your key so Codex can read it:

export MONOROUTER_API_KEY=mrk_yourkey

Models

Any Codex model your subscription allows. Set it with model = "…" in the config, or per run with -m.

  • •gpt-6-astra — newest and most capable, and the most expensive
  • •gpt-5.6-sol — flagship
  • •gpt-5.6-terra — balanced
  • •gpt-5.6-luna — fast
Codex CLI may warn that model metadata for a very new model is unknown. That is Codex's own local table, not MonoRouter — the request still routes correctly.

How it works

Codex speaks the OpenAI Responses API, and MonoRouter serves it at /v1/responses. Unlike the Anthropic path there is no format translation: your request is forwarded as-is and only the credential is substituted — your mrk_ key for the ChatGPT token on your account. That is why every Codex model works rather than a curated subset.

Usage and cost land on your dashboard next to Claude Code, broken down per API key and per provider token.

Troubleshooting

  • •401 from the installer — the key is wrong or revoked. Check /keys.
  • •503 no_tokens_available — no ChatGPT subscription is connected. Connect one at /tokens.
  • •429 with a retry-after — that model hit its rate limit. Only that model is paused; others still work, and the wait is shown in the response.
  • •codex-mono: command not found — ~/.local/bin is not on your PATH. The installer prints the line to add.

FAQ

Does this replace my existing codex command?

Only if you choose it to. The installer offers two modes: codex-mono installs a separate command with its own CODEX_HOME and leaves your existing codex untouched, and codex rewires the existing command after backing up your current ~/.codex/config.toml to a timestamped .bak file.

Which models can I use?

Any Codex model your ChatGPT subscription allows, including gpt-6-astra, gpt-5.6-sol, gpt-5.6-terra and gpt-5.6-luna. MonoRouter forwards the model name unchanged, so there is no curated list to keep in sync.

Do I need an OpenAI API key?

No. Codex authenticates to MonoRouter with your mrk_ key, and MonoRouter substitutes the ChatGPT subscription token connected on your account. You never hold a platform API key.

Where is my MonoRouter key stored?

In a monorouter.env file next to the Codex config, with owner-only (600) permissions. It is never written into config.toml, which references it by environment variable name instead.

Can I set it up without the script?

Yes. Add a [model_providers.monorouter] block to ~/.codex/config.toml with base_url set to your MonoRouter /v1 URL, wire_api = "responses", and env_key = "MONOROUTER_API_KEY", then export that variable in your shell.

What happens if one model hits its rate limit?

Only that model pauses on that provider token. Other Codex models keep working, and the response carries a retry-after so you know how long the wait is.

Ready to get started?

Sign up in 30 seconds — no credit card required. 1,500 free API calls included.

Sign up freeLearn more
guide: set up Codex CLI with MonoRouter · monorouter