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 / Model xxx is currently unavailable

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 installer downloads Microsoft's own bootstrapper (https://get.microsoft.com/installer/download/9PLM9XGG6VKS) and waits for it, falls back to winget, and only then asks you to install by hand. Every step is bounded and prints progress, so it will not sit there forever.

• Stuck at "Starting package install…": winget handed the install to the Microsoft Store install service and the service never answered. Older versions of the script had no timeout — press Ctrl+C, download and run the bootstrapper above, then re-run the installer; it skips the install and just writes the config.

• The Store will not open / has no Install button: usually InstallService or wuauserv was disabled by a system "optimizer". Check (a normal window is enough):

  Get-Service InstallService, wuauserv | Select-Object Name,Status,StartType

  If StartType is Disabled, restore them from an elevated PowerShell:

  Set-Service InstallService -StartupType Manual; Start-Service InstallService
  Set-Service wuauserv -StartupType Manual; Start-Service wuauserv

• Install fails in an elevated PowerShell: Store apps install per user and an admin window gets refused — re-run the script in a normal window.

• Confirm it landed: Get-AppxPackage -Name OpenAI.Codex (the Store listing is called "ChatGPT", but the package is still OpenAI.Codex — don't look for ChatGPT).

If the desktop app really will not install, 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).