Codex CLI 常见错误排查手册：401、429、Sandbox、网络全套修复

摘要 — Codex CLI 跑不起来通常是认证、网络、沙箱、限流、模型五类问题之一。本文按报错原文直接给修复命令，并附国内通过 ofox 走 https://api.ofox.run/v1 中转的完整 ~/.codex/config.toml，省去翻官方 issue 列表的时间。

先搞清楚是哪一类

Codex CLI 已经从早期的 Node.js 版重写成 Rust，认证支持 ChatGPT Plus/Pro/Team 登录或 API key，沙箱默认拦截外网。报错时先问自己四件事：

1. 能登录吗？ → 认证类
2. 请求能出门吗？ → 网络类
3. 命令能落地吗？ → 沙箱类
4. 模型能响应吗？ → 限流/模型类

把报错原文复制出来，对着下面找。

一、认证类错误

401 Unauthorized / Authentication failed

浏览器反复跳转或启动报 401 时，先检查认证状态和选中的 provider：

codex login status
# 确需切换账户时，再使用 codex logout 和 codex login

如果浏览器登录链路在你的网络环境下根本完不成（国内常见），直接切到 API key 模式：

export OPENAI_API_KEY="sk-..."
codex

API-key 模式不使用同一套 OAuth 回调，但仍需有效密钥、模型权限和可达的 API 路线。

多账号 / 多 key 切换

~/.codex/auth.json 一次只能存一个登录态。需要切账号时，建议用 shell 变量明确指定：

export OPENAI_API_KEY="$KEY_FOR_PROJECT_A"
codex

或者直接走 ~/.codex/config.toml 的 model_providers 段配置多 provider，按项目切换。

二、网络与连接类错误

”Network Access Restricted” / 沙箱阻断网络

Codex CLI 默认沙箱不放行网络，curl、git clone、npm install 全部会被拦下来。如果你信任当前任务，临时放开：

codex -c 'sandbox_workspace_write.network_access=true'

需要完全无沙箱（不推荐长期使用），用 --dangerously-bypass-approvals-and-sandbox 或在 config 里设 sandbox_mode = "danger-full-access"。

国内连不上 api.openai.com

直接报 connect ETIMEDOUT 或 SSL 握手失败时，把 base URL 换成 ofox 中转。一次性测试：

export OPENAI_BASE_URL="https://api.ofox.run/v1"
export OPENAI_API_KEY="$OFOXAI_API_KEY"
codex

要让 Codex CLI 永久走 ofox，在 ~/.codex/config.toml 写入：

model_provider = "ofoxai-codex"

[model_providers.ofoxai-codex]
name = "Ofox AI"
base_url = "https://api.ofox.run/v1"
env_key = "OFOXAI_API_KEY"
wire_api = "responses"

注意 Codex CLI 走的是 OpenAI Responses API 协议（wire_api = "responses" 是当前唯一受支持的值），并非所有模型都支持。配置完后到 ofox 模型广场 看哪些型号标了 Responses 兼容再选。

更完整的 Windows + WSL 安装环节单独成文，见 Codex CLI Windows 安装：WSL/原生/常见报错。

三、Sandbox 与权限错误

approval prompt 反复弹

沙箱模式不等于审批策略。按工作范围配置写入权限，再选择适用的审批策略；组织要求可能限制可用设置：

sandbox_mode = "workspace-write"
approval_policy = "on-request"

approval_policy 的合法值还包括 untrusted（已知安全的只读命令自动放行，可能改状态的需要确认）、never（不请求工具审批，但不扩大沙箱权限）、granular 表配置（按类别配置，具体字段见当前官方参考）。

sandbox-exec ENOENT (macOS)

macOS 上沙箱依赖系统的 sandbox-exec 工具，缺它会直接 ENOENT。先装一次 Xcode 命令行工具：

xcode-select --install

仍然报错就检查当前 working directory 的权限，或者换到 ~/code 之类的目录再试。

WSL 下 VS Code 扩展沙箱不放行

VS Code Codex 扩展在 WSL 下即便设了 danger-full-access 仍可能拒绝网络，这是已知 issue。临时解法是退回到终端直接跑 codex，避免走 VS Code 扩展。

四、限流与模型错误

429 rate_limit_exceeded

先确认是哪种限流。/status 是 Codex 交互式会话里的斜杠命令，不是 shell 子命令——先 codex 进入会话，再在输入框输入：

/status

会显示当前 model、approval 模式、token 用量和限额/reset 信息。ChatGPT Plus/Pro 登录态遇到的是订阅窗口限流，只能等 reset。API key 模式可以立刻换 key 或换 provider 继续跑；走 ofox 中转的话，单一上游被限不影响全局。

context_length_exceeded

把 /model 切换到长上下文型号，例如 GPT-5.4 / Claude Sonnet 4.6 等支持 200k+ 的模型；或者在 prompt 里手动裁剪历史。Codex CLI 不会自动截断，需要主动管理对话长度。

model_not_found

报这个一般是 config 里写了你 provider 没上架的模型名。回到 ofox 模型广场 复制实际可用的 model id，再贴回 config 或 /model 命令。

五、安装与升级错误

command not found: codex

全局安装没生效，确认 npm 全局 bin 在 PATH 里（npm bin -g 在 npm 9 已被移除，改用 npm prefix -g）：

export PATH="$(npm prefix -g)/bin:$PATH"

或者用 npx --yes @openai/codex 临时跑一次确认能跑通，再排查 PATH。NVM / Volta / sudo EACCES / Codex Desktop 非交互 shell 等深一层原因，看 “codex: command not found”：npm install -g 装完 7 个修复套路。

旧版本残留导致行为异常

Node.js 老版和 Rust 新版的 config 字段并不完全兼容。怀疑是历史残留时，把整个 ~/.codex/ 备份后清空再重装：

mv ~/.codex ~/.codex.bak
npm i -g @openai/codex@latest
codex

新版会重新写一份干净的 config 和 auth。

配套阅读

• 工作流上手：Codex CLI 真实编程工作流
• Windows 环境从零开始：Codex CLI Windows 安装：WSL/原生
• 选型时回头看模型对比：Claude Sonnet 4.5 vs 4.6 实战选型

写在最后

先保存完整错误，再按认证、端点、模型与权限逐项核对。当前官方配置参考说明设置作用域；429 排查说明何时重试。更换 URL 不等于修复所有网络或权限错误。