Codex 常见问题

大约 4 分钟

Codex CLI 常见问题

Codex CLI 的最大坑就一个：Base URL 必须带 /v1。别的报错基本都能照这页解决。

Codex 和 Claude Code 最大的差异

Codex：https://www.yuzhixiaolongxia.com/v1 ← 带 /v1
Claude Code：https://www.yuzhixiaolongxia.com ← 不带 /v1

复制 Claude 的写法到 Codex 配置里，会直接 404。

1. `codex` 命令装不上 / 装完用不了

怎么动手：

先看 Node 版本：node -v，要求 18 或以上。

网络问题就换镜像：

npm config set registry https://registry.npmmirror.com
npm install -g @openai/codex

装完跑 codex --version 没反应？说明 npm 全局 bin 没在 PATH 里：
- macOS / Linux：echo "export PATH=$(npm config get prefix)/bin:\$PATH" >> ~/.zshrc && source ~/.zshrc
- Windows：npm config get prefix 拿到路径，加到系统环境变量 Path，重开终端。
死活装不上？用一键安装包绕开 npm。

2. Base URL 必须带 `/v1`

这是 Codex 用户最常踩的坑

配置文件 ~/.codex/config.toml：

model = "gpt-5.5"
model_provider = "yuzhi"

[model_providers.yuzhi]
name = "yuzhi"
base_url = "https://www.yuzhixiaolongxia.com/v1"
wire_api = "responses"

环境变量：

export OPENAI_BASE_URL="https://www.yuzhixiaolongxia.com/v1"
export OPENAI_API_KEY="你的令牌"

末尾的 /v1 不能省，省了就是 404。

3. 配置文件 `~/.codex/config.toml` 找不到

情况：第一次装完，找不到这个文件。

怎么动手：

正常路径：第一次跑 codex 命令时会自动创建这个目录和文件。如果没自动建，往下看。

手动建（macOS / Linux）：

mkdir -p ~/.codex
touch ~/.codex/config.toml
# 然后用任意编辑器把上面第 2 题的配置贴进去

手动建（Windows）：在 PowerShell 跑

mkdir $HOME\.codex -Force
New-Item $HOME\.codex\config.toml -ItemType File
notepad $HOME\.codex\config.toml

多账号 / 多 Provider

config.toml 里可以配多组 [model_providers.xxx]，然后通过 model_provider = "..." 切换。开发和生产用不同令牌时很方便。

4. 401 Unauthorized

3 个原因（按顺序排查）：

令牌没填 / 填错：去 /console/token 重新复制，前后不要有空格、换行。
环境变量名：Codex CLI 读 OPENAI_API_KEY。如果你只设了 ANTHROPIC_AUTH_TOKEN（Claude 那套），它看不到。
没生效：改完 ~/.zshrc 之后忘了 source，或者忘了重开终端。

最小验证：

curl -s https://www.yuzhixiaolongxia.com/v1/models \
  -H "Authorization: Bearer 你的令牌" | head

能列出模型 = 令牌和 Base URL 都没问题；报 401 = 令牌的事；报 404 = Base URL 漏了 /v1。

5. 403 余额不足 / 分组不对

怎么动手：

看余额：/console/personal，确认大于 0。
看令牌分组：/console/token，Codex 用的令牌分组必须是 Codex 家族。
分组错了，最快的修法是新建一个 Codex 家族令牌替换，比改老令牌靠谱。

6. 模型 ID 错误 / `model not found`

怎么动手：

去 /pricing 复制最新 ID，不要凭记忆敲。
当前常用：
- gpt-5.5（推荐）
- gpt-5.4
改完 ~/.codex/config.toml 的 model = "..." 字段，重开终端。
模型 ID 是对的还报错？看令牌分组是不是 Codex 家族（回看第 5 题）。

7. 回复慢 / 长时间无响应

怎么动手：

先短请求验通：用上面第 4 题的 curl /v1/models 看连通性。
拆任务：单次提示词别塞太长，输出 token 别设太大。
换小模型试：先 gpt-5.4 或更小的型号，看是不是模型本身慢。
换网络：本地代理不稳定时偶发 5xx 或超时，切手机热点验证一下。
错峰：上游负载高时稍等几分钟。

8. 流式输出怎么开

怎么动手：

CLI 默认就是流式：直接 codex 进入交互界面就是流式输出，正常无需特别配置。
走 API 调用时：请求体里加 "stream": true，并按 SSE 处理响应。
流式断了：常见原因是网络抖动或代理超时。重发即可；如果你是脚本调用，记得对 5xx / connection reset 做指数退避重试。

Codex CLI 配置文件参考

model = "gpt-5.5"
model_provider = "yuzhi"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.yuzhi]
name = "yuzhi"
base_url = "https://www.yuzhixiaolongxia.com/v1"
wire_api = "responses"

9. 并发被限速（429）

症状：批量请求时大量 429 Too Many Requests。

怎么动手：

降并发：单令牌不要起太多并发，改成队列式提交。
退避重试：失败用指数退避（1s → 2s → 4s …）。
拆令牌：测试和生产用不同令牌，避免互相干扰。
错峰：大批量任务放夜里跑。

还没解决？

看监控状态页是否有平台公告
留意主站首页公告位
反馈时贴出：错误日志 + 你的 Base URL + 令牌分组 + 模型 ID

更多 Codex 配置见 Codex CLI 教程。