Codex troubleshooting

This page is organized by the exact error text: search for the line your terminal printed and jump to that section. Each section is "why it happens" plus one command you can paste.

Check three things first

node -v            # needs v22+
codex --version    # prints a version → Codex is installed
cat ~/.codex/config.toml   # Windows PowerShell: type $env:USERPROFILE\.codex\config.toml

model_provider in config.toml must point at a provider whose base_url = "https://primerouter.ai/v1"; the key lives in ~/.codex/auth.json. Both files are written by the one-line installer — re-running it is always the cheapest fix (existing files are backed up to <name>.bak.<timestamp> first).

codex: command not found / 'codex' is not recognized as the name of a cmdlet

Codex is installed, but the directory it landed in is not on this terminal's PATH. The usual cause: the global npm directory was not writable, so the script installed into the per-user prefix ~/.npm-global/bin and appended the PATH line to your shell profile — only new terminals read it.

macOS / Linux: open a new terminal window, or run in the current one:

export PATH="$HOME/.npm-global/bin:$PATH"

To make it permanent without re-running the script, append that line to ~/.zshrc (zsh) or ~/.bash_profile (bash on macOS) / ~/.bashrc (bash on Linux).

Windows: npm's global directory defaults to %APPDATA%\npm. Close and reopen PowerShell first; if it still fails, check that the directory is on PATH:

npm config get prefix      # this path should appear in the list below
$env:Path -split ';'

npm ERR! EACCES / permission denied

npm install -g tried to write into a system directory your user cannot write to. Do not reach for sudo — every future codex upgrade would need it too, and the files end up owned by root.

The one-line installer switches to the per-user prefix ~/.npm-global automatically, so you normally never see this. For a manual install, do the same:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"     # also append to ~/.zshrc or ~/.bash_profile
npm install -g @openai/codex

running scripts is disabled on this system

Windows PowerShell's execution policy blocks .ps1 files by default. Either option works:

# Option 1: run straight from the network, no file on disk (no policy change needed)
irm https://primerouter.ai/install/codex.ps1 | iex

# Option 2: you already downloaded codex.ps1 — allow just this run
powershell -ExecutionPolicy Bypass -File .\codex.ps1

Avoid a machine-wide Set-ExecutionPolicy Unrestricted; installing one tool does not justify it.

Node.js v22+ is required / node: command not found

Codex CLI is an npm package and needs Node.js 22 or newer. The installer offers to install the LTS release when the version is too old; to do it by hand, grab the LTS build from https://nodejs.org/. Verify:

node -v      # v22.x or newer

On Windows, reopen PowerShell after installing Node so the new PATH takes effect.

401 / Invalid API key / Codex suddenly asks you to sign in to ChatGPT

Codex keeps a single credential (~/.codex/auth.json). Three things lead here:

1. You ran codex login (ChatGPT account) — it replaced the PrimeRouter key. Re-run the installer (it detects the ChatGPT login and backs it up), or write the key back by hand:

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

2. The key was deleted or disabled in the console — open the API keys page, confirm the key exists and is enabled; otherwise create a new one and re-run the installer.
3. config.toml does not point at PrimeRouter — Codex fell back to the official provider, which requires a ChatGPT login. See "Config is written but Codex still talks to OpenAI" below.

The model 'xxx' does not exist / model_not_found / No available channel for model

The model = "…" in config.toml is not available in your account's group (each group enables a different model list). Check the models you can use on the console models page, then either:

# Option 1: re-run the installer with an explicit model (the variable must precede bash on the
# right side of the pipe; in front of curl it never reaches the script)
curl -fsSL https://primerouter.ai/install/codex.sh | PRIMEROUTER_MODEL=gpt-5.6-sol bash

$env:PRIMEROUTER_MODEL = "gpt-5.6-sol"; irm https://primerouter.ai/install/codex.ps1 | iex

Option 2: edit the model = "…" line in ~/.codex/config.toml directly (keep it above [model_providers]).

403 / insufficient_user_quota / 429

• 403 + insufficient_user_quota (message 用户额度不足, 剩余额度: … — i.e. insufficient user quota; the message itself is only emitted in Chinese): the account balance is used up. Top up on the billing page and requests resume immediately — no reinstall needed.
• A plain 429 Too Many Requests: too many requests in a short burst; wait a few seconds and retry (Codex retries streamed requests itself). If it persists, check the exact response on the logs page.

Config is written but Codex still talks to OpenAI / asks for a ChatGPT login on start

Nine times out of ten this is TOML ordering: the top-level keys model_provider, model, … ended up below the [model_providers] table header. TOML scopes every key after a header into that table, Codex cannot see a top-level model_provider, and silently falls back to the default OpenAI provider.

The correct minimal config (top-level keys first, tables after):

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"

When in doubt, re-run the one-line installer — the file it writes is always in the right order.

codex resume shows no history

codex resume only lists sessions whose recorded model_provider id matches the current config; switching from another provider changes the id, so older sessions drop out of the list — but no file is lost. The installer reuses the id already on this machine to avoid exactly this; details and the command to peek at old sessions are in Codex CLI → Session history is missing.

Codex Desktop download fails / the DMG will not open

macOS: the installer downloads from the mirror https://primerouter.ai/codex-app-releases/Codex.dmg first and falls back to OpenAI's CDN when the mirror does not carry it.

• Interrupted download: re-run the script; it downloads again.
• hdiutil: attach failed / "image is corrupt": the file is incomplete — delete and re-download; make sure there is more than 1 GB free.
• Blocked on first launch: in Applications, right-click the app → Open (OpenAI currently ships it as ChatGPT.app; the script prints the actual path when it finishes, so don't look for an icon named Codex).

Windows: the desktop app ships through the Microsoft Store; the script only writes the config. If the Store is unavailable, start with Codex CLI — both share the same config.toml, so nothing needs reconfiguring once the desktop app is installed.

request timed out / stream disconnected / no response for a long time

1. Confirm base_url = "https://primerouter.ai/v1" in ~/.codex/config.toml (missing /v1 → you get an HTML page instead of JSON and Codex reports a parse error; an extra path segment → 404 Invalid URL).
2. Check the status page for the model you are using.
3. With model_reasoning_effort = "high" a single response can run long and is more exposed to network hiccups; try medium temporarily.
4. Still failing — verify from another network whether the local link is the problem:

   curl -sS https://primerouter.ai/v1/models -H "Authorization: Bearer sk-your-key" | head -c 300

   JSON back means the link is fine and the issue is client-side; nothing back means the network.

---

Still stuck? Send the full terminal output to support, together with ~/.codex/config.toml (remove the key).