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

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

先搞清楚是哪一类

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

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

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

一、认证类错误

401 Unauthorized / Authentication failed

最常见的死循环：浏览器登录反复跳转，或 codex 启动后立刻报 401。处理方法是清掉缓存的 auth 文件再重登：

rm -f ~/.codex/auth.json
codex login

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

export OPENAI_API_KEY="sk-..."
codex

key 模式不需要 OAuth 回调，连不通 auth.openai.com 也能跑。

多账号 / 多 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.ai/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.ai/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 反复弹

只读沙箱（默认）下每条 shell 命令都要确认。日常开发建议改成允许工作区写入 + 越界时再问：

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

approval_policy 的合法值还包括 untrusted（已知安全的只读命令自动放行，可能改状态的需要确认）、never（全自动，CI 场景常用）、granular（按 sandbox、规则、MCP、权限、skill 等类别分别配置）。

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。

旧版本残留导致行为异常

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 实战选型

写在最后

报错原文先复制，对照五类直接抄命令。国内场景下，一行 OPENAI_BASE_URL=https://api.ofox.ai/v1 能干掉一半的网络问题；剩下那半，多半是 sandbox 策略改一行 config 的事。