Codex 常见报错解决方案：401、429、网络连接失败

大家好，我是 Codex 中文网的站长宇哥。

先别急着重装

很多人遇到 Codex 报错的第一反应是卸载重装。重装当然能解决一部分安装路径问题，但解决不了账号认证、API key、额度限制、网络代理、项目权限和 MCP Server 启动失败。

排查 Codex 报错，最重要的是先判断错误发生在哪一层：

• 安装层：命令不存在、版本太旧、运行时缺失。
• 登录层：ChatGPT 登录失败、API key 无效、401 Unauthorized。
• 请求层：429 Too Many Requests、模型不可用、额度不足。
• 网络层：DNS、代理、公司网络、TLS、目标服务不可达。
• 项目层：沙箱限制、权限不足、工作区不可信、命令执行失败。
• 扩展层：MCP Server 启动失败、工具认证失败、外部服务超时。

你把层级判断清楚，后面基本就是按清单逐项排除。

第一步：收集最小信息

不要只截图最后一行报错。建议先记录这些信息：

• 你用的是 Codex App、IDE 扩展还是 CLI。
• 当前系统是 macOS、Windows、Linux 还是 WSL2。
• 执行的命令是什么。
• 报错发生在启动、登录、生成、执行命令、调用 MCP，还是构建项目时。
• 同一条命令重试是否稳定复现。
• 当前仓库是否有未提交改动。

CLI 用户可以先运行：

codex --version
codex --help

如果本机支持诊断命令，也可以运行：

codex doctor

诊断命令通常能帮你快速发现安装、认证、配置和运行时问题。即使最终还要人工排查，它也能减少猜测。

401 Unauthorized 怎么排查

401 的含义通常是认证失败。它不等于“Codex 坏了”，也不一定是网络问题。

优先检查这些点：

• 你是否已经完成 ChatGPT 登录或 API key 配置。
• 当前终端里的 API key 是否为空。
• API key 是否复制错、过期、被撤销。
• shell 配置里是否有旧 key 覆盖了新 key。
• 你使用的 provider 和 key 是否匹配。
• 公司代理或中转服务是否改写了认证头。

如果你使用环境变量，可以先确认变量存在：

printenv OPENAI_API_KEY

不建议把完整 key 直接贴到聊天窗口或公开截图里。更安全的检查方式是只看长度：

printf "%s" "$OPENAI_API_KEY" | wc -c

如果你使用的是 Codex 的 ChatGPT 登录流程，优先重新执行登录命令或在 App 中重新登录，而不是盲目改 API key。ChatGPT 登录和 API key 是两条不同路径，排错时不要混在一起。

429 Too Many Requests 怎么排查

429 通常和频率限制、额度、并发或服务端限流有关。它不一定说明你的代码写错了。

常见原因有这些：

• 短时间内发起太多请求。
• 多个自动化任务同时运行。
• 当前账号或项目额度不足。
• 使用的模型或服务有单独速率限制。
• 中转服务本身做了更严格的限流。

处理顺序建议是：

• 先暂停自动化脚本，确认是否有循环请求。
• 降低并发，不要同时开很多 Codex 任务。
• 等待一段时间再重试，观察是否恢复。
• 检查账号、项目或服务商控制台里的额度和限制。
• 在脚本里加入重试和指数退避，不要失败后立刻无限重试。

如果你是在 GitHub Actions、定时任务或自动发文脚本里遇到 429，重点看是不是多个 workflow 同时触发。自动化场景的 429 经常不是单次请求导致的，而是多次任务叠加造成的。

网络连接失败怎么排查

网络错误要分层看，不要只盯着 Codex 命令本身。

先检查基础网络：

ping developers.openai.com

有些网络环境禁用 ping，所以 ping 不通不一定代表 HTTPS 不通。可以再用 curl 测试：

curl -I https://developers.openai.com

如果你使用代理，继续检查环境变量：

printenv HTTP_PROXY
printenv HTTPS_PROXY
printenv ALL_PROXY

常见坑包括：

• 代理只在浏览器里配置了，终端没有配置。
• 终端配置了旧代理地址。
• 公司网络拦截了某些域名或 TLS 连接。
• DNS 污染或解析到不可用地址。
• 中转服务的 Base URL 写错，导致请求发到了不存在的路径。

如果浏览器能访问，但 CLI 不能访问，重点查终端代理、证书和 shell 环境。如果 CLI 能访问官方文档，但 Codex 请求失败，再回到认证、provider、base URL 和模型配置。

codex: command not found 怎么办

命令不存在通常是安装路径或 PATH 问题。

先确认 shell 能不能找到命令：

command -v codex

如果没有输出，说明当前 shell 的 PATH 里没有 Codex。根据安装方式分别处理：

• 安装脚本方式：重新打开终端，确认安装目录是否写入 PATH。
• npm 全局安装：检查 npm 全局 bin 目录是否在 PATH 中。
• Homebrew 安装：确认 Homebrew 的 bin 目录是否在 PATH 中。
• Windows PowerShell：重新打开 PowerShell，或检查安装脚本写入的路径。
• WSL2：确认你是在 WSL 里安装，还是在 Windows 里安装，两个环境不共享同一个 PATH。

npm 用户可以检查：

npm bin -g

如果输出目录不在 PATH 里，就把它加入 shell 配置文件，例如 .zshrc、.bashrc 或对应的 Windows 环境变量。

配置不生效怎么排查

Codex 配置可能来自多个层级。官方配置文档里强调，CLI flags 和 --config 覆盖优先级最高，其次才是项目配置、profile、用户配置和默认值。

排查时可以按这个顺序看：

• 当前命令有没有 -c key=value 或 --config 覆盖。
• 当前是否启用了某个 profile。
• 项目里是否有 .codex/config.toml。
• 当前项目是否被信任，项目配置是否会加载。
• 用户级 ~/.codex/config.toml 是否存在。
• 是否有系统级或公司管理策略覆盖。

临时测试时可以直接用 -c 覆盖一个简单字段，确认配置层是否能被读取。例如：

codex -c model=\"gpt-5\" \"只回复一句配置测试成功\"

如果临时覆盖生效，但写进文件不生效，问题多半在配置文件位置、TOML 语法或项目信任状态。

MCP 相关错误怎么排查

MCP 出问题时，不要把它和 Codex 主流程混在一起。先单独查 MCP：

codex mcp list
codex mcp get <name>

如果是 stdio Server，把启动命令单独复制出来运行，确认它本身能启动。如果是 HTTP Server，用 curl 检查服务是否可达。

常见问题包括：

• 启动命令写错。
• Node.js 或 Python 版本不符合要求。
• 环境变量没有传给 Server。
• token 权限不足。
• HTTP URL 写错路径。
• Server 启动太慢导致超时。
• 项目级配置没有被加载。

MCP 排错建议先做只读测试。比如读取一个公开资源、查询一个测试 issue、打开一个本地页面。不要在没确认稳定前让 MCP 工具执行写操作。

项目命令执行失败怎么办

有时错误看起来像 Codex 报错，其实是项目自己的命令失败，比如 pnpm build、npm test、pytest、go test 没过。

这类问题要把 Codex 和项目命令分开：

pnpm build

如果你自己在终端运行也失败，那就不是 Codex 独有问题，而是项目依赖、类型、测试或环境变量问题。让 Codex 修复时，最好把失败命令和关键错误贴给它，而不是只说“Codex 出错了”。

如果你自己能运行成功，但 Codex 运行失败，再检查沙箱权限、工作目录、环境变量继承和审批策略。

一个推荐的排查模板

以后遇到报错，可以照这个模板问 Codex 或发到社群：

我在使用 Codex CLI 时遇到问题。
系统：macOS / Windows / Linux
入口：CLI / App / IDE 扩展
命令：这里贴命令
阶段：启动 / 登录 / 生成 / 执行命令 / MCP
错误：这里贴关键错误，不贴完整密钥
我已经检查过：版本、登录、网络、配置文件、项目命令
希望你按安装层、认证层、网络层、项目层帮我排查。

信息越完整，排查越快。尤其是 401、429、网络失败这类问题，单看错误码不够，必须结合入口、配置和环境判断。

参考官方文档

遇到问题时，建议优先看官方文档对应页面：

• Codex Quickstart
• Codex CLI 文档
• Codex 配置基础
• Codex 配置参考
• Codex MCP 文档

常见问题 FAQ

401 和 429 可以靠重装解决吗？

通常不行。401 多半是认证或 key 问题，429 多半是频率或额度问题。重装只会影响本地程序和路径，不能恢复账号权限或提高额度。

浏览器能打开网页，为什么 Codex CLI 还是网络失败？

浏览器和终端可能使用不同代理。浏览器代理正常，不代表 shell 里的 HTTP_PROXY、HTTPS_PROXY 也正确。CLI 问题优先检查终端网络环境。

自动发文脚本失败，要先看哪里？

先看 GitHub Actions 或本地脚本日志，确认失败阶段。生成失败、质量检查失败、提交失败、部署失败是四类不同问题，不要混在一起处理。

是否需要把所有错误日志发给别人？

不需要，也不应该。发关键错误、命令、阶段和环境即可。API key、token、cookie、内网地址、用户目录隐私信息都要打码。

总结

Codex 报错排查的核心是分层：安装层看命令和版本，认证层看登录和 key，请求层看 401、429 和模型，网络层看代理和可达性，项目层看构建命令，扩展层看 MCP Server。

不要把所有问题都归结为“Codex 不行”，也不要一上来就重装。按层级排查，通常十分钟内就能把问题缩到一个很小的范围。