Codex 常见问题排查

本页按报错原文组织：把终端里的那一行拿来搜，直接跳到对应小节。每一节都是「为什么会这样」+「一条能复制的修复命令」。

先确认三件事

node -v            # 需要 v22+
codex --version    # 能打出版本号说明 Codex 已装好
cat ~/.codex/config.toml   # Windows PowerShell: type $env:USERPROFILE\.codex\config.toml

config.toml 里 model_provider 应指向一个 base_url = "https://primerouter.ai/v1" 的 provider；key 存在 ~/.codex/auth.json。这两个文件都由一键脚本生成，重跑脚本永远是最省事的修复方式（旧文件会先备份成 <原名>.bak.<时间戳>）。

codex: command not found / 无法将“codex”项识别为 cmdlet

Codex 装好了，但装到的目录不在当前终端的 PATH 里。最常见的原因是脚本因为全局目录没有写权限，把它装进了用户级目录 ~/.npm-global/bin，并把 PATH 写进了 shell 配置文件——新开的终端才会读到。

macOS / Linux：新开一个终端窗口，或在当前终端执行

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

想永久生效又不想重跑脚本，把上面这行追加到 ~/.zshrc（zsh）或 ~/.bash_profile（macOS bash）/ ~/.bashrc（Linux bash）。

Windows：npm 的全局目录默认是 %APPDATA%\npm。先关掉再重开 PowerShell；仍然不行就检查目录是否在 PATH 里：

npm config get prefix      # 打出的路径应出现在下面的列表里
$env:Path -split ';'

npm ERR! EACCES / permission denied

npm install -g 想往系统目录写，但当前用户没权限。不要用 sudo（会让后续 codex 升级也得带 sudo，还会把文件属主改成 root）。

一键脚本会自动改用用户级前缀 ~/.npm-global，所以正常情况下你不会看到这个错。手动安装时照做即可：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"     # 同时追加到 ~/.zshrc 或 ~/.bash_profile
npm install -g @openai/codex

因为在此系统上禁止运行脚本 / running scripts is disabled on this system

Windows PowerShell 的执行策略默认禁止运行 .ps1 文件。两种解法任选：

# 方法一：不落地文件，直接从网络执行（不需要改执行策略）
irm https://primerouter.ai/install/codex.ps1 | iex

# 方法二：已经下载了 codex.ps1，只对本次运行放行
powershell -ExecutionPolicy Bypass -File .\codex.ps1

不建议全局 Set-ExecutionPolicy Unrestricted——只为装一个工具放开整机策略没有必要。

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

Codex CLI 是 npm 包，需要 Node.js 22 或更新。一键脚本检测到版本不够会询问是否代为安装 LTS；手动安装去 https://nodejs.org/ 下 LTS 版即可。装完确认：

node -v      # 应为 v22.x 或更高

Windows 上装完 Node 记得重开 PowerShell，否则新的 PATH 不生效。

401 / Invalid API key / Codex 突然让你登录 ChatGPT

Codex 只保存一份凭证（~/.codex/auth.json）。三种情况会走到这里：

1. 你在 Codex 里执行过 codex login（登录 ChatGPT 账号）——它把 PrimeRouter 的 key 顶掉了。重跑一键脚本即可恢复（脚本会提示发现 ChatGPT 登录并备份）；或者手动写回：

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

2. key 在控制台被删除或禁用——去令牌页确认那把 key 还在且状态为启用，不在就新建一把后重跑脚本。
3. config.toml 没指向 PrimeRouter——Codex 走了官方 provider，自然要求 ChatGPT 登录。见下面「配置写了但 Codex 仍走官方」。

The model 'xxx' does not exist / model_not_found / 无可用渠道

config.toml 里的 model = "…" 在你账户的分组里不可用（每个分组开通的模型不同）。到控制台模型页看你能用的模型名，然后二选一：

# 方法一：指定模型重跑脚本（变量要写在管道右侧的 bash 前面，写在 curl 前面进不了脚本）
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

方法二：直接改 ~/.codex/config.toml 里的 model = "…" 那一行（保持它在 [model_providers] 之上）。

403 / insufficient_user_quota / 用户额度不足 / 预扣费额度失败

• 403 + insufficient_user_quota（文案「用户额度不足, 剩余额度: …」或「预扣费额度失败, 用户剩余额度: …」）：账户额度用完了，到充值页充值后立即恢复，不需要重装。
• 单纯的 429 Too Many Requests：短时间请求过多触发限流，等几秒重试；Codex 自己会重试流式请求。持续出现时到日志页看具体返回。

配置写了但 Codex 仍走官方 / 一启动就要 ChatGPT 登录

九成是 TOML 顺序问题：model_provider、model 这些顶层键被写到了 [model_providers] 表头下面。TOML 会把表头之后的所有键都归进那张表，Codex 读不到顶层的 model_provider，就静默回落到默认的 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"

拿不准就重跑一键脚本，它生成的文件顺序一定是对的。

codex resume 看不到历史会话

codex resume 只列出 model_provider id 与当前配置一致的会话；从别的服务商切过来、id 变了，旧会话就不在列表里，但文件一个都没丢。一键脚本会自动沿用这台机器原有的 id 来避免这个问题——详细说明和临时查看旧会话的命令见 Codex 配置教程 → 历史会话看不到了。

Codex Desktop 下载失败 / DMG 打不开

macOS：一键脚本先从镜像 https://primerouter.ai/codex-app-releases/Codex.dmg 下载，镜像没有时回落到 OpenAI 官方地址。

• 下载中断：重跑脚本即可，它会重新下载。
• hdiutil: attach failed / 提示映像损坏：文件没下完整，删掉重下；确认磁盘剩余空间 > 1 GB。
• 首次打开被系统拦截：在「应用程序」里右键该 app → 打开（当前 OpenAI 的安装包把它命名为 ChatGPT.app，脚本装完会打印实际路径，别按名字找 Codex）。

Windows：桌面版通过 Microsoft Store 分发，脚本只负责写配置。Store 打不开或地区不可用时，先用 Codex CLI 顶上——两者共用同一份 config.toml，之后装上桌面版无需再配。

请求超时 / stream disconnected / 长时间无响应

1. 确认 ~/.codex/config.toml 里 base_url = "https://primerouter.ai/v1"（少了 /v1 会收到一段 HTML 而不是 JSON，Codex 报解析错误；路径写多了会 404 Invalid URL）。
2. 看状态页对应模型是否正常。
3. 推理强度设成 high 时单次响应可能很长，遇到网络抖动更容易断；可以把 model_reasoning_effort 临时改成 medium 试试。
4. 仍然不行，换个网络环境验证一下是不是本地链路问题：

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

   能返回 JSON 说明链路通，问题在客户端；返回不了就是网络。

---

仍未解决？把终端完整输出发到支持渠道，附上 ~/.codex/config.toml（去掉 key）。