OpenAI Codex CLI

OpenAI's 2025 open-source agentic CLI (@openai/codex).

Two different "Codex"

• This page's Codex CLI = OpenAI's official agentic CLI
• Not the same as PrimeRouter's internal ChannelTypeCodex (a low-level channel type)

Get an API key first — see Common setup.

Install

# All platforms (needs Node 20+)
npm install -g @openai/codex
codex --version

Config file location

OS	Path
macOS	~/.codex/config.toml
Linux	~/.codex/config.toml
Windows	%USERPROFILE%\.codex\config.toml (i.e. C:\Users\<you>\.codex\config.toml)

Edit config

macOS / Linux

mkdir -p ~/.codex
vim ~/.codex/config.toml

Windows PowerShell

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex" | Out-Null
notepad "$env:USERPROFILE\.codex\config.toml"

Write (⚠️ top-level keys MUST come before the [model_providers.*] table — TOML puts everything below a table header inside that table, and Codex then silently falls back to the default OpenAI provider):

Recommended · key stored in Codex's own credentials (auth.json)

The key lives in Codex's credential file, so no environment variable is involved — terminal, GUI double-click and IDE extensions all read it:

# Default provider + model (must come first)
model_provider = "primerouter"
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
disable_response_storage = true

# Custom provider pointing to PrimeRouter
[model_providers]
[model_providers.primerouter]
name = "PrimeRouter"
wire_api = "responses"
requires_openai_auth = true
base_url = "https://primerouter.ai/v1"

macOS / Linux

printf '%s' "sk-your-primerouter-key" | codex login --with-api-key
codex

Windows PowerShell

"sk-your-primerouter-key" | codex login --with-api-key
codex

⚠️ Mutually exclusive with a ChatGPT account login: codex login stores a single credential — signing in with ChatGPT later replaces this key (and vice versa). The one-click installer backs the previous auth.json up to auth.json.bak.<timestamp> first; run codex login to sign back in whenever you want to switch.

Alternative · key in an environment variable (env_key)

Only worth it when you need a ChatGPT account login and PrimeRouter to coexist and want to switch between them via model_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"
env_key = "PRIMEROUTER_API_KEY"
base_url = "https://primerouter.ai/v1"

macOS / Linux

export PRIMEROUTER_API_KEY="sk-your-primerouter-key"
codex

macOS GUI launch (one extra step)

# GUI apps never read shell profiles; inject into the launchd user session
launchctl setenv PRIMEROUTER_API_KEY "sk-your-primerouter-key"

Windows PowerShell

$env:PRIMEROUTER_API_KEY = "sk-your-primerouter-key"
codex

Windows user env (permanent, visible to GUI)

setx PRIMEROUTER_API_KEY "sk-your-primerouter-key"
:: Reopen the terminal to take effect

⚠️ env_key is not a "fall back if unset" mechanism: when the variable is missing, Codex fails the request outright with Missing environment variable: PRIMEROUTER_API_KEY. Every launch context that does not inherit your shell profile hits this — GUI app, IDE extension, a terminal opened before the variable was written. It also cannot be combined with requires_openai_auth: env_key is checked first and fails first.

Migrating from another provider: codex resume shows no history

Codex's resume list only shows sessions whose recorded model_provider id matches your current config (codex resume --last filters the same way; --all only widens the directory filter). Changing model_provider from another vendor's id (say foo-relay) to primerouter therefore drops every older session out of the list.

No session file is lost — they are all still under ~/.codex/sessions/, just filtered out. Three ways to deal with it:

1. Re-run the one-click installer (recommended). It reuses the provider id this machine already had and points it at PrimeRouter, so the history stays visible:

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

2. Look without changing the config:

   codex resume -c model_provider=your-old-id

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

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

Forgot the old id? Check model_provider in a ~/.codex/config.toml.bak.* backup, or read it straight out of the session files:

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

Tool-use compatibility

• Codex CLI uses the OpenAI Responses API (/v1/responses) for its agent loop
• PrimeRouter translates Responses to a compatible form, so Claude tool calls work end-to-end
• wire_api = "chat" (chat completions) was removed in codex-cli 0.14x — configs still carrying it fail to load; use "responses"