1. 先搞清 Codex 跑不起来的报错都藏在哪个环节

1.1 Codex 的完整调用链路里有哪些环节容易出问题

Codex CLI 不是一个“打开即用”的普通软件。看起来你只是在终端敲了一个命令，实际上它内部要依次完成好几件事：

1. 读取本地配置文件（比如 ~/.codex/config.toml 和 ~/.codex/auth.json ）
2. 根据配置找到目标模型服务商，并带上认证信息
3. 把请求发给模型的 API 端点
4. 收到模型返回的文本、工具调用指令
5. 在本地执行工具调用，比如文件读写、命令执行
6. 把执行结果再返回给模型，继续会话

这六步里，每一步都可能成为报错源。大多数“跑不起来”并不是模型能力问题，而是第一步到第三步之间出了配置、认证或者网络问题。我见过太多人纠结“是不是 Codex 这个工具太笨”，结果一看日志，压根是 API 地址配错或者 token 文件读取失败。

所以排查时必须先定位是哪一环断了。如果模型请求根本没发出去，你改再多的模型提示词都没有用。如果请求发出去了但响应格式不对，那就要去检查服务端兼容性。

1.2 第一步不是改配置，是学会怎么看日志

很多人一遇到报错就急着搜错误码，其实先打开日志开关往往更快。Codex CLI 不少版本都支持 DEBUG 级别的日志输出，比如用环境变量或 --verbose 参数启动。日志会告诉你请求最终发到了哪个 URL、用了什么模型、返回了什么状态码，这比猜要准得多。

我的习惯是拿到任何 Codex 报错，先做三件事：

• 把报错原文完整复制下来，不要只看最后一行
• 用 codex --version 确认当前版本，老版本和新版本的报错信息差异很大
• 开 DEBUG 日志或直接用 curl 手动请求目标 API，测试最小链路是否通

最小链路测试是排障的神器。你不需要经过 Codex 那层封装，直接用 curl 模拟一个最简单的请求，如果 curl 能返回正常结果，问题一定出在 Codex 本身的配置或转发层；如果 curl 也报错，那就是认证、网络或服务端问题。后面每一个报错，我都会把这种“最小链路验证”思路嵌进去。

2. 认证、网络与配置类的高频报错

2.1 “codex auth token is unavailable” —— token 文件没读到，先别怪网络

这个报错我见过不下几十次。很多用户第一反应是“是不是我的 key 失效了”，但大多数情况下根本没有网络请求发出去。Codex CLI 会先从本地读取认证信息，如果读不到就直接退出。

我遇到过的具体原因大概有三种：

• 使用了 OPENAI_API_KEY 环境变量，但 Codex 新版改用了 ~/.codex/auth.json 作为认证来源，环境变量没被读取
• token 文件存在，但权限不对。比如你用 root 执行过写入，之后切换到普通用户，普通进程没权限读取
• auth.json 文件里的字段名或值被写错了，比如多余的引号、空格，导致 JSON 解析失败

排查方式很直接。先检查文件是否存在，权限是啥，内容是否合法：

如果文件不存在，用 codex login 重新走一遍登录流程。如果是在无浏览器环境里使用，可以手动创建 auth.json。最基本的结构是：

不同版本字段会有差异，最稳的办法是先 codex login 跑一次，让它自动生成标准格式，你再去改里面的 token 值。

注意：在 Linux、macOS 上，如果 auth.json 的权限是 0644 且归属正确，普通用户也能读。最常见的是用 sudo 安装或运行过，导致文件归属变成 root，普通用户读不了，解决方法是 chown -R 你的用户名 ~/.codex 。

2.2 “cc switch local proxy failed while handling codex endpoint /responses” —— 转发层挂了，和模型没关系

这个报错是典型的“请求在中间层失败”。很多人用 ccswitch 这类工具来管理多套 Codex 后端配置，它会起一个本地转发组件，把 Codex 的请求转发到对应的模型服务。报错里的 /responses 是 OpenAI Responses API 的端点路径，也就是说 Codex 的请求确实发出来了，但在本地转发环节断了。

遇到这个报错，先按顺序排查：

1. 查看 ccswitch 的进程是否还活着，端口是否被占用
2. 把 Codex 的 base_url 改成直接指向目标模型服务，绕过本地转发层测一次
3. 看转发层日志里有没有更具体的错误，比如连接超时、服务端返回 5xx
4. 确认 ccswitch 的配置文件和 Codex 的 model_provider 之间是否匹配

我实际操作中的经验是：这种报错大多数不是模型服务的问题，而是转发组件自己崩了。重启一下 ccswitch 服务，或者升级到新版本，往往就能解决。如果问题反复出现，尽量别在配置里叠加太多转发层。能直连的模型服务就直连，转发层越多，排查越难。

提示：你完全可以直接编辑 ~/.codex/config.toml ，通过 model_provider 切换后端，不一定非要用 ccswitch。工具只是方便，不是必需品。

2.3 401 / 403 报错：API key 不可用或无权访问

Codex 返回 401 或者 403，信息本身已经比较明确了：认证失败。但这个认证失败背后的原因很值得展开。201：key 本身错误，copy 的时候多复制了空格；202：key 对应的服务商不支持你选的那个模型；203：base_url 指向的是 A 服务商，但 key 却是 B 服务商的，完全不匹配。

很多接入第三方服务的用户会搞混一个点：Codex CLI 在较新版本里默认走 Responses API（ /responses ），而不少第三方服务只实现了 OpenAI 的 Chat Completions 接口（ /chat/completions ）。当 base_url 指向这些服务时，请求发过去就像用错误的钥匙开锁，返回 401 或者 404 都很正常。这时需要给 Codex 配置兼容参数，让它把请求转换到 Chat Completions 格式。

手动验证的步骤我建议固定下来：

如果这个 curl 能正常返回，说明 key、网络、模型名三件事都没问题，那问题就在 Codex 的配置层面；如果 curl 也是 401，就老老实实去检查 key 的可用性。

2.4 像“971210”这种自定义错误码，先搜日志再搜网络

像 971210 这类看起来不像标准 HTTP 状态码的错误，很多人一上来就搜“971210报错”，根本搜不到标准答案。这类自定义错误码最靠谱的排查路径是去日志里找它的上下文。

我的建议是这样：先在 Codex 或转发组件的日志里搜这个数字，看它是在哪一层返回的。如果是在网络层返回，多半是连接被断开，比如目标服务不可达或网关超时；如果是在 HTTP 响应体里返回，那就是模型服务商自定义的业务错误，需要去查那个服务商自己的文档。

也可以粗暴一点，用最小链路测试把中间层全部绕开，直接测目标 API。如果绕开中间层之后能通，说明是中间层（转发、网关）的问题；如果绕开之后还是不通，那就是目标服务的问题。这个方法适用于任何“看不懂的错误码”。

3. 模型响应与生成结果环节的报错

3.1 接入 DeepSeek 等第三方兼容服务时报错：不是模型不行，是格式不兼容

现在很流行把 Codex 接到 DeepSeek 这类兼容 OpenAI 接口的服务上，好处是成本低、key 好拿。但这也是报错重灾区。最常见的两类报错：一类是 model not found ，另一类是解析响应时提示 invalid_json 或 missing tool_calls 。

model not found 相对好解决，就是你在 Codex 配置里写的模型名和目标服务商的实际模型名对不上。DeepSeek 的模型名通常是 deepseek-chat 、 deepseek-reasoner ，别想当然写 deepseek-v3 之类的旧名字。最稳的做法是查服务商最新的模型列表文档，或者直接用一个简单的 curl 请求验证。

第二类 missing tool_calls 这类报错比较隐蔽。Codex 官方接口默认是 Responses API，它要求模型返回的结构里有严格的字段约束，包括工具调用结构。不少第三方模型服务虽然名面上“兼容 OpenAI”，但实际上只兼容到了 Chat Completions 那层，没有按 Responses API 的结构返回。Codex 拿到这种响应之后解析不出来，就报格式错误。

解决方向是在 Codex 的 model_provider 配置里，把接口类型设置成 chat，让它走 /chat/completions 路径并做格式转换。配置参考大概长这样：

wire_api = "chat" 这一行是关键。不加这行，Codex 可能默认用 Responses API 去请求，第三方服务直接不知道怎么处理，各种怪报错随之而来。

注意：不同 Codex 版本的 model_providers 配置语法可能有差异，使用前先确认版本兼容性。宁可先跑一个最小请求，也不要一次性配完所有参数。

3.2 Codex 生成的 SQL 一执行就报 MySQL 1064：语法层面的事别急着怪模型

MySQL 1064 是标准语法错误，意思是 MySQL 解析不了你给它的 SQL。很多人让 Codex 帮忙写复杂查询，直接复制到 MySQL 里执行就报 1064，于是觉得“Codex 生成代码不靠谱”。但实际上，Codex 报错的关键原因通常是它没有足够的上下文，不知道你用的 MySQL 版本、表结构、字段名。

1064 的常见触发点有三个：

• SQL 字符串里的引号没有正确转义，导致 MySQL 解析错位
• 代码里使用了版本特有的 SQL 特性，比如某些窗口函数或 JSON 函数，而目标 MySQL 版本过低
• 表名或字段名拼写与数据库不一致，MySQL 误判为语法错误

我自己用 Codex 辅助写 SQL 时，一定会把关键表结构贴给它。不是简单地告诉它“表名是什么”，而是把 CREATE TABLE 语句或者 SHOW CREATE TABLE 的结果完整贴进去。给它 10 分钟猜表结构，不如喂它 10 行建表语句。它知道字段名之后，生成的 SQL 执行成功率会明显上升。

排查 1064 的实操路径：先找到报错 SQL 里第一个报错位置，MySQL 经常会指出具体坐标；然后手动检查该位置附近的引号、逗号、括号是否闭合；最后单独执行这一条 SQL 的最小版本，一步步加复杂度，定位问题。

3.3 429、超时和限流报错：第三方服务不是说好不限制就不限制

Codex 跑得多了之后，遇到 429 和超时几乎是必然的。OpenAI 官方接口有限流策略，第三方兼容服务也会有限流。这个问题看起来不复杂，但实际排查时往往有一个误区：只看返回码，不看日志细节。

429 有时还会伴有 Retry-After 响应头，提示你多久之后重试。但第三方兼容服务不一定都会按标准格式返回这个头，所以不能盲目依赖客户端的自动重试机制。

我的处理经验是分两路走：

• 如果频繁触发 429，减少并发会话数，一个账号同时跑太多会话很容易撞限
• 如果是第三方服务间歇性超时，先确认它的服务状态页或者直接 curl 测延迟，别急着在 Codex 侧开重试

另外，Codex 某些版本会同时发起多个子请求（比如工具调用并行），这会在短时间内把额度耗尽。可以把并行度调低，保证单个会话稳定优先。

4. 本地环境、GPU 与工具链的报错

4.1 NVIDIA 屏蔽 ECC 报错：本地推理服务起不来，Codex 自然连不上

如果你的 Codex 后端用的是本地推理服务，比如 vLLM、ollama、llama.cpp 或者自建推理框架，那 GPU 环境问题就会直接表现为 Codex 请求失败。比较典型的一种是 NVIDIA ECC 相关报错。

ECC（Error Correcting Code）是数据中心显卡上的一种内存纠错功能，主要出现在 A100、H100、A30 这类卡上。当显卡内存出现可纠正或不可纠正错误时，NVIDIA 驱动可能会限制显存使用量，或者直接导致推理服务启动失败。你会在启动日志里看到 ECC error 之类的字眼。

排查顺序：

1. 先用 nvidia-smi 看显卡是否在列表里，驱动状态是否正常
2. 看 dmesg 里有没有 GPU 相关的硬件错误
3. 如果是 ECC 导致显存被禁用，且确认是软件层面问题，可以尝试关闭 ECC（大多数游戏卡其实没有这个选项）

关闭 ECC 的命令不复杂，但这属于数据中心显卡才有的操作，普通消费级显卡不需要处理，也别看到报错就乱改 BIOS 设置。大多数情况下，问题出在驱动版本和 CUDA 版本不匹配，而不是硬件损坏。建议先在 CPU 后端上跑一次推理，排除 Codex 配置问题，再回到 GPU 环境逐层排查。

提示：本地推理服务先用最简单的方式验证，比如直接用 curl 或测试脚本请求一次模型完成一个最短回答。本地服务能通，再去接 Codex，能把“服务端问题”和“Codex 配置问题”彻底切开。

4.2 gloo 连接类报错：本地分布式推理框架初始化失败的隐藏坑

gloo 是 PyTorch 里常用的进程组通信库，常用于多机多卡训练和推理。如果你本地用的推理框架依赖 PyTorch 分布式，启动时有可能出现 gloo 初始化失败、TCPStore 连接失败之类的报错。

这类报错和 Codex 本身没有任何关系，但因为你的 Codex 要连的“后端服务”起不来，表现出来就是 Codex 调用失败。我看到过有人折腾了半天 Codex 配置，最后发现是团队的推理服务在分布式初始化阶段压根没起来。

排查思路通常这么走：

• 看主进程日志里报的是监听地址错误还是连接拒绝
• 检查机器之间防火墙是否放行了通信端口
• 如果是多网卡环境，可能选错了网卡，设置 GLOO_SOCKET_IFNAME 指向正确的网卡名
• 把通信地址方式改成 env:// 或手动指定，避免主机名解析失败

如果你是单机在跑，可以考虑不用分布式启动参数，直接把推理服务改成单进程模式。很多本地场景根本不需要分布式，简单模式更稳，少一层通信就少一类报错。

4.3 Windows 工具链缺失：link.exe not found这类编译报错别硬解

在 Windows 上跑 Codex 或配套工具时，我经常见到 link.exe not found 、 cl.exe 找不到这类编译工具链报错。这个问题的根源非常简单：你的机器上没装 MSVC 编译工具链，或者安装了没加到当前环境的 PATH 里。

这些报错通常不是 Codex 本身的问题，而是你安装在用 pip、npm 或 Rust 源码安装某个依赖时，需要本地编译原生模块，而系统里没有 C/C++ 编译环境。

解决动作很固定：

1. 安装 Visual Studio Build Tools
2. 安装时勾选“使用 C++ 的桌面开发”工作负载
3. 安装完成后重启终端，确认 link.exe 能被找到

装完之后再重新执行原来的安装命令，大概率就能过。如果还是报类似错误，检查一下终端是不是没重启、PATH 里没有把 VS 的工具目录加进去。别手动瞎改 PATH，VS 自带的环境激活脚本会在开发者终端里自动配置好。

4.4 安装 Ubuntu 时报 IO error：磁盘、挂载和 WSL 文件系统的坑

有些人在 WSL 或虚拟机里折腾 Codex 环境时，安装 Ubuntu 阶段就报 IO error ，根本走不到配置那一步。这个报错看起来很底层，但其实原因往往不复杂：

• 磁盘空间不够，安装镜像写不进去
• 文件系统只读，挂载参数有问题
• 磁盘坏块或虚拟磁盘损坏
• WSL 迁移时目标目录权限不对

我自己在 WSL 里安装和运行 Codex 的经验是：把工作目录放在 Linux 原生文件系统（比如 /home/用户名/codex ），不要放在 /mnt/c/ 下面。 /mnt/c 是跨文件系统访问，IO 性能和权限处理都比较特殊，装依赖时容易触发各种诡异读写错误。

如果 IO error 是在虚拟机安装镜像阶段出现，优先检查镜像文件完整性。ISO 文件下载损坏是常见原因，重新校验校验值之后再做安装，能省很多时间。

5. 附一份排障顺序速查表，还有我的几个实操习惯

5.1 从零到跑通的检查顺序

如果你现在一脸懵，不知道从哪个报错开始查，直接按下面的顺序走一遍，多数情况半小时内能定位：

这套顺序的核心逻辑是从底层往上查。底层指的是“你的 API 通不通”，上层指的是“Codex 的配置解析对不对”。底层通了，再把注意力集中到上层；底层不通，先修底层。

5.2 最后分享几个我自己的实操习惯

先说日志习惯。每次排查告警，我不会只盯着终端里最后几行，因为很多 Codex 报错会包含两段：一段是用户友好提示，一段是内部错误详情。内部错误详情里往往才藏着关键信息，比如请求的 URL、返回的状态码、是哪个中间层抛出的异常。把这些完整记录下来，再动手改配置。

再说配置习惯。改 config.toml 或者 .env 之前，先备份一份原文件。特别是折腾第三方服务时，改一个字段可能导致另一个字段失效，没有备份就只能凭记忆回滚。备份一下也就是一条 cp 命令，成本极低。

最后说验证习惯。每改完一个配置，用最小的方式跑一次，不要一上来就跑复杂的多轮任务。跑通了第一条简单请求，再逐步加复杂度。一次只改一个变量，这看起来像老生常谈，但我在排障时的每一次高效定位，靠的都是这个笨办法。