Codex CLI

OpenAI Codex CLI is OpenAI's official agentic command-line tool. This page wires it to PrimeRouter.

The easier route: the one-click install page

Open primerouter.ai/en/install/codex, sign in, and download an installer with your API key already embedded — it does everything on this page.

Where the config lands

The script writes ~/.codex/config.toml (or %USERPROFILE%\.codex\config.toml on Windows) pointing at PrimeRouter, and stores the key in Codex's own credential file ~/.codex/auth.json. Both files are backed up to <name>.bak.<timestamp> first.

Already using Codex? Two things to know

• Signed in with a ChatGPT account: Codex keeps a single credential, so the PrimeRouter key replaces it (your file is backed up — run codex login to switch back any time).
• Coming from another provider: the script reuses the model_provider id this machine already had, so your codex resume history does not disappear. See Session history below.

One-line installer

Windows PowerShell

irm https://primerouter.ai/install/codex.ps1 | iex

macOS / Linux / WSL

curl -fsSL https://primerouter.ai/install/codex.sh | bash

💡 What it does: ① verify Node v22+ ② install @openai/codex globally if missing (asks first) ③ prompt for your API key with read -rs / Read-Host ④ back up and write config.toml, reusing the existing model_provider id ⑤ back up and write auth.json, and clear the PRIMEROUTER_API_KEY variable and LaunchAgent older versions of the script left behind.

Start Codex:

codex

Something broke? See Codex troubleshooting first.

Fallback: manual install

Full step-by-step manual setup

See Coding Tools → Codex CLI for the long-form guide. TL;DR:

1. Install Node.js v22+

2. npm install -g @openai/codex

3. Edit ~/.codex/config.toml (top-level keys MUST come before the [model_providers.*] table — TOML puts anything below a table header inside that table, and Codex then silently falls back to the default OpenAI provider):

   model_provider = "primerouter"
   model = "gpt-5.6-sol"
   model_reasoning_effort = "high"
   disable_response_storage = true
   
   [model_providers]
   [model_providers.primerouter]
   name = "PrimeRouter"
   wire_api = "responses"
   requires_openai_auth = true
   base_url = "https://primerouter.ai/v1"

   Then store the key in Codex's credential file: printf '%s' "sk-your-key" | codex login --with-api-key

   ⚠️ Mutually exclusive with a ChatGPT account login: codex login stores a single credential — signing in with ChatGPT later replaces this key (and vice versa).

   Need both at once? Use the env_key variant under "Alternative" in Coding Tools → Codex CLI — but be aware that a missing variable makes Codex fail the request rather than fall back, so GUI apps, IDE extensions and older terminals will not see it.

4. Run codex

Session history is missing

codex resume only lists sessions whose recorded model_provider id matches your current config (--last filters the same way; --all only widens the directory filter). Switching from another provider changes that id, so older sessions drop out of the list.

No file is lost — they are all still under ~/.codex/sessions/. Re-running the one-click installer fixes it: it reuses the existing id and points it at PrimeRouter. To just take a look without changing anything:

codex resume -c model_provider=your-old-id

Forgot the old id:

grep -ho '"model_provider":"[^"]*"' ~/.codex/sessions/*/*/*/*.jsonl | sort | uniq -c | sort -rn

Prefer a clean id and accept that older sessions no longer appear in the list (the files stay on disk):

curl -fsSL https://primerouter.ai/install/codex.sh | PRIMEROUTER_CODEX_PROVIDER_ID=primerouter bash