装好 Codex 之后跑不起来很常见因为这套东西不是单一一个二进制文件的事它的完整链路是“客户端 — 配置 — 网络 — 认证 — 模型服务 — 工具链”。报错只告诉你某一环断了并不会告诉你断在哪。所以我这篇不讲什么抽象方法论直接给你十个我在实际环境里反复见过的高频报错按环节拆开每个都带排查思路和解决动作照着走就行。适用的人主要有两类一是刚装好 Codex CLI连登录、认证、API 配置都没完全搞清楚的新手二是想把 Codex 接到第三方模型服务比如 DeepSeek 或本地推理后端的折腾型用户。前者会遇到大量环境和认证类报错后者会遇到大量请求转发和响应格式类报错这两类典型问题我下面都会覆盖到。1. 先搞清 Codex 跑不起来的报错都藏在哪个环节1.1 Codex 的完整调用链路里有哪些环节容易出问题Codex CLI 不是一个“打开即用”的普通软件。看起来你只是在终端敲了一个命令实际上它内部要依次完成好几件事读取本地配置文件比如~/.codex/config.toml和~/.codex/auth.json根据配置找到目标模型服务商并带上认证信息把请求发给模型的 API 端点收到模型返回的文本、工具调用指令在本地执行工具调用比如文件读写、命令执行把执行结果再返回给模型继续会话这六步里每一步都可能成为报错源。大多数“跑不起来”并不是模型能力问题而是第一步到第三步之间出了配置、认证或者网络问题。我见过太多人纠结“是不是 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 解析失败排查方式很直接。先检查文件是否存在权限是啥内容是否合法ls -la ~/.codex/ cat ~/.codex/auth.json如果文件不存在用codex login重新走一遍登录流程。如果是在无浏览器环境里使用可以手动创建 auth.json。最基本的结构是{ tokens: { default: { access_token: 你的token, refresh_token: 可选的refresh_token, expires_at: 2026-01-01T00:00:00Z } } }不同版本字段会有差异最稳的办法是先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 的请求确实发出来了但在本地转发环节断了。遇到这个报错先按顺序排查查看 ccswitch 的进程是否还活着端口是否被占用把 Codex 的 base_url 改成直接指向目标模型服务绕过本地转发层测一次看转发层日志里有没有更具体的错误比如连接超时、服务端返回 5xx确认 ccswitch 的配置文件和 Codex 的 model_provider 之间是否匹配我实际操作中的经验是这种报错大多数不是模型服务的问题而是转发组件自己崩了。重启一下 ccswitch 服务或者升级到新版本往往就能解决。如果问题反复出现尽量别在配置里叠加太多转发层。能直连的模型服务就直连转发层越多排查越难。提示你完全可以直接编辑~/.codex/config.toml通过 model_provider 切换后端不一定非要用 ccswitch。工具只是方便不是必需品。2.3 401 / 403 报错API key 不可用或无权访问Codex 返回 401 或者 403信息本身已经比较明确了认证失败。但这个认证失败背后的原因很值得展开。201key 本身错误copy 的时候多复制了空格202key 对应的服务商不支持你选的那个模型203base_url 指向的是 A 服务商但 key 却是 B 服务商的完全不匹配。很多接入第三方服务的用户会搞混一个点Codex CLI 在较新版本里默认走 Responses API/responses而不少第三方服务只实现了 OpenAI 的 Chat Completions 接口/chat/completions。当 base_url 指向这些服务时请求发过去就像用错误的钥匙开锁返回 401 或者 404 都很正常。这时需要给 Codex 配置兼容参数让它把请求转换到 Chat Completions 格式。手动验证的步骤我建议固定下来curl https://你的模型服务地址/v1/chat/completions \ -H Authorization: Bearer 你的key \ -H Content-Type: application/json \ -d {model:你的模型名,messages:[{role:user,content:hi}],max_tokens:10}如果这个 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路径并做格式转换。配置参考大概长这样model deepseek-chat model_providers [ { name deepseek, base_url https://api.deepseek.com/v1, wire_api chat } ] model_provider deepseekwire_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 相关报错。ECCError Correcting Code是数据中心显卡上的一种内存纠错功能主要出现在 A100、H100、A30 这类卡上。当显卡内存出现可纠正或不可纠正错误时NVIDIA 驱动可能会限制显存使用量或者直接导致推理服务启动失败。你会在启动日志里看到 ECC error 之类的字眼。排查顺序先用nvidia-smi看显卡是否在列表里驱动状态是否正常看dmesg里有没有 GPU 相关的硬件错误如果是 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 编译环境。解决动作很固定安装 Visual Studio Build Tools安装时勾选“使用 C 的桌面开发”工作负载安装完成后重启终端确认link.exe能被找到装完之后再重新执行原来的安装命令大概率就能过。如果还是报类似错误检查一下终端是不是没重启、PATH 里没有把 VS 的工具目录加进去。别手动瞎改 PATHVS 自带的环境激活脚本会在开发者终端里自动配置好。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 从零到跑通的检查顺序如果你现在一脸懵不知道从哪个报错开始查直接按下面的顺序走一遍多数情况半小时内能定位顺序检查项做什么1版本与配置codex --version确认~/.codex/config.toml基础配置存在2认证文件检查~/.codex/auth.json是否存在且权限正常3最小链路用 curl 直接请求目标 API确认 key、模型名、base_url 可用4转发组件如果用了 ccswitch确认进程存活、端口未被占用必要时绕过它直连5模型格式第三方服务确认走 chat 接口还是 responses 接口按需设置 wire_api6本地推理服务如果接本地后端先确认后端服务本身能正常响应7工具链Windows 环境确认 MSVC Build Tools 已安装PATH 正常这套顺序的核心逻辑是从底层往上查。底层指的是“你的 API 通不通”上层指的是“Codex 的配置解析对不对”。底层通了再把注意力集中到上层底层不通先修底层。5.2 最后分享几个我自己的实操习惯先说日志习惯。每次排查告警我不会只盯着终端里最后几行因为很多 Codex 报错会包含两段一段是用户友好提示一段是内部错误详情。内部错误详情里往往才藏着关键信息比如请求的 URL、返回的状态码、是哪个中间层抛出的异常。把这些完整记录下来再动手改配置。再说配置习惯。改config.toml或者.env之前先备份一份原文件。特别是折腾第三方服务时改一个字段可能导致另一个字段失效没有备份就只能凭记忆回滚。备份一下也就是一条 cp 命令成本极低。最后说验证习惯。每改完一个配置用最小的方式跑一次不要一上来就跑复杂的多轮任务。跑通了第一条简单请求再逐步加复杂度。一次只改一个变量这看起来像老生常谈但我在排障时的每一次高效定位靠的都是这个笨办法。
Codex CLI 高频报错排查指南：从认证配置到模型服务全链路修复
装好 Codex 之后跑不起来很常见因为这套东西不是单一一个二进制文件的事它的完整链路是“客户端 — 配置 — 网络 — 认证 — 模型服务 — 工具链”。报错只告诉你某一环断了并不会告诉你断在哪。所以我这篇不讲什么抽象方法论直接给你十个我在实际环境里反复见过的高频报错按环节拆开每个都带排查思路和解决动作照着走就行。适用的人主要有两类一是刚装好 Codex CLI连登录、认证、API 配置都没完全搞清楚的新手二是想把 Codex 接到第三方模型服务比如 DeepSeek 或本地推理后端的折腾型用户。前者会遇到大量环境和认证类报错后者会遇到大量请求转发和响应格式类报错这两类典型问题我下面都会覆盖到。1. 先搞清 Codex 跑不起来的报错都藏在哪个环节1.1 Codex 的完整调用链路里有哪些环节容易出问题Codex CLI 不是一个“打开即用”的普通软件。看起来你只是在终端敲了一个命令实际上它内部要依次完成好几件事读取本地配置文件比如~/.codex/config.toml和~/.codex/auth.json根据配置找到目标模型服务商并带上认证信息把请求发给模型的 API 端点收到模型返回的文本、工具调用指令在本地执行工具调用比如文件读写、命令执行把执行结果再返回给模型继续会话这六步里每一步都可能成为报错源。大多数“跑不起来”并不是模型能力问题而是第一步到第三步之间出了配置、认证或者网络问题。我见过太多人纠结“是不是 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 解析失败排查方式很直接。先检查文件是否存在权限是啥内容是否合法ls -la ~/.codex/ cat ~/.codex/auth.json如果文件不存在用codex login重新走一遍登录流程。如果是在无浏览器环境里使用可以手动创建 auth.json。最基本的结构是{ tokens: { default: { access_token: 你的token, refresh_token: 可选的refresh_token, expires_at: 2026-01-01T00:00:00Z } } }不同版本字段会有差异最稳的办法是先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 的请求确实发出来了但在本地转发环节断了。遇到这个报错先按顺序排查查看 ccswitch 的进程是否还活着端口是否被占用把 Codex 的 base_url 改成直接指向目标模型服务绕过本地转发层测一次看转发层日志里有没有更具体的错误比如连接超时、服务端返回 5xx确认 ccswitch 的配置文件和 Codex 的 model_provider 之间是否匹配我实际操作中的经验是这种报错大多数不是模型服务的问题而是转发组件自己崩了。重启一下 ccswitch 服务或者升级到新版本往往就能解决。如果问题反复出现尽量别在配置里叠加太多转发层。能直连的模型服务就直连转发层越多排查越难。提示你完全可以直接编辑~/.codex/config.toml通过 model_provider 切换后端不一定非要用 ccswitch。工具只是方便不是必需品。2.3 401 / 403 报错API key 不可用或无权访问Codex 返回 401 或者 403信息本身已经比较明确了认证失败。但这个认证失败背后的原因很值得展开。201key 本身错误copy 的时候多复制了空格202key 对应的服务商不支持你选的那个模型203base_url 指向的是 A 服务商但 key 却是 B 服务商的完全不匹配。很多接入第三方服务的用户会搞混一个点Codex CLI 在较新版本里默认走 Responses API/responses而不少第三方服务只实现了 OpenAI 的 Chat Completions 接口/chat/completions。当 base_url 指向这些服务时请求发过去就像用错误的钥匙开锁返回 401 或者 404 都很正常。这时需要给 Codex 配置兼容参数让它把请求转换到 Chat Completions 格式。手动验证的步骤我建议固定下来curl https://你的模型服务地址/v1/chat/completions \ -H Authorization: Bearer 你的key \ -H Content-Type: application/json \ -d {model:你的模型名,messages:[{role:user,content:hi}],max_tokens:10}如果这个 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路径并做格式转换。配置参考大概长这样model deepseek-chat model_providers [ { name deepseek, base_url https://api.deepseek.com/v1, wire_api chat } ] model_provider deepseekwire_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 相关报错。ECCError Correcting Code是数据中心显卡上的一种内存纠错功能主要出现在 A100、H100、A30 这类卡上。当显卡内存出现可纠正或不可纠正错误时NVIDIA 驱动可能会限制显存使用量或者直接导致推理服务启动失败。你会在启动日志里看到 ECC error 之类的字眼。排查顺序先用nvidia-smi看显卡是否在列表里驱动状态是否正常看dmesg里有没有 GPU 相关的硬件错误如果是 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 编译环境。解决动作很固定安装 Visual Studio Build Tools安装时勾选“使用 C 的桌面开发”工作负载安装完成后重启终端确认link.exe能被找到装完之后再重新执行原来的安装命令大概率就能过。如果还是报类似错误检查一下终端是不是没重启、PATH 里没有把 VS 的工具目录加进去。别手动瞎改 PATHVS 自带的环境激活脚本会在开发者终端里自动配置好。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 从零到跑通的检查顺序如果你现在一脸懵不知道从哪个报错开始查直接按下面的顺序走一遍多数情况半小时内能定位顺序检查项做什么1版本与配置codex --version确认~/.codex/config.toml基础配置存在2认证文件检查~/.codex/auth.json是否存在且权限正常3最小链路用 curl 直接请求目标 API确认 key、模型名、base_url 可用4转发组件如果用了 ccswitch确认进程存活、端口未被占用必要时绕过它直连5模型格式第三方服务确认走 chat 接口还是 responses 接口按需设置 wire_api6本地推理服务如果接本地后端先确认后端服务本身能正常响应7工具链Windows 环境确认 MSVC Build Tools 已安装PATH 正常这套顺序的核心逻辑是从底层往上查。底层指的是“你的 API 通不通”上层指的是“Codex 的配置解析对不对”。底层通了再把注意力集中到上层底层不通先修底层。5.2 最后分享几个我自己的实操习惯先说日志习惯。每次排查告警我不会只盯着终端里最后几行因为很多 Codex 报错会包含两段一段是用户友好提示一段是内部错误详情。内部错误详情里往往才藏着关键信息比如请求的 URL、返回的状态码、是哪个中间层抛出的异常。把这些完整记录下来再动手改配置。再说配置习惯。改config.toml或者.env之前先备份一份原文件。特别是折腾第三方服务时改一个字段可能导致另一个字段失效没有备份就只能凭记忆回滚。备份一下也就是一条 cp 命令成本极低。最后说验证习惯。每改完一个配置用最小的方式跑一次不要一上来就跑复杂的多轮任务。跑通了第一条简单请求再逐步加复杂度。一次只改一个变量这看起来像老生常谈但我在排障时的每一次高效定位靠的都是这个笨办法。
