Codex 高频报错排查指南：安装、认证到模型配置全解析

最近老有朋友拿着同一张截屏来问我Codex 明明装好了npm 那一步也没报错怎么一运行就撂挑子要么回一句codex: command not found要么直接给你来一行codex auth token is unavailable。说实话这类问题我自己踩过太多次了。Codex 这种命令行 AI 编程工具最磨人的从来不是对话体验而是安装、认证、配置这一层。今天我把这段时间遇到的高频报错凑成一张清单一共 10 个每个都给你报错原文、产生原因、排查路径和可以直接抄的解决办法。不管你是刚下载安装包的新手还是已经折腾过第三方模型的老手这条排查路线应该都能帮你定位到问题。先上速览表方便你对号入座序号报错关键词 / 现象所属阶段直接处理方向1codex: command not found安装PATH、全局目录、权限2安装包下载失败、进度条卡死安装npm 源、缓存、包管理器3桌面版打不开 / 闪退启动WebView2、日志、配置损坏4codex auth token is unavailable认证登录状态、token、环境变量5登录超时 / 扫码失败 / 二次登录无反应认证登录流程、cookie、auth.json6cc switch local proxy failed while handling codex endpoint /responses网络/配置本地转发进程、环境变量、endpoint7connect ECONNREFUSED/ETIMEDOUT/ENOTFOUND网络连通性、API 地址、超时8The gpt-5.6-sol model is not supported when using codex模型配置model 字段、支持清单9接入 DeepSeek 等第三方模型报错模型配置base_url、key、模型别名10SyntaxError: Unexpected token/ 执行任务时报process is not defined运行环境Node 版本、项目环境## 1. 拿到报错先分门别类别一上来就重装 ### 1.1 报错的三类分法 Codex 的报错再多按生命周期也就三类**安装类**、**认证类**、**运行时类**。 安装类解决的是“工具能不能装上、命令能不能找到”典型症状是 codex: command not found、npm ERR!。这类问题主要在 PATH 和安装源上重装前先检查环境变量。 认证类解决的是“工具知不知道你是谁”典型症状是 auth token is unavailable、401 Unauthorized。这类问题不换机器、不重装登录状态重置一下往往就好。 运行时类解决的是“知道你是谁之后请求能不能正确走通”包括网络问题、模型名问题、配置解析问题。这类最迷惑因为 Codex 本身没坏报错却五花八门。 我习惯给朋友一句话命令找不到查 PATHtoken 报错查登录请求失败查网络模型报错查配置。这个口诀能过滤掉一半的无效操作。 ### 1.2 我的排查顺序 遇到报错别乱试我个人的固定顺序是**日志 → 配置 → 环境变量 → 网络 → 源代码**。 先从日志看起Codex CLI 的错误信息末尾通常是最具体的原因比如 config.toml 的解析错误、端口占用、模型名不合法。再看配置文件~/.codex/ 目录下的 config.toml 和 auth.json 是重灾区。然后检查环境变量特别是 OPENAI_API_KEY、DEEPSEEK_API_KEY 这类 key 是否被意外设置。接着做网络连通性测试最后才考虑升级版本或者重装。 这个顺序看起来没什么技术含量但实际操作中真的能省很多时间。我见过太多人一报错就 npm uninstall -g 重装结果装完还是同一个报错因为问题根本不在安装包上。 ## 2. 安装阶段高频报错命令找不到与下载失败 ### 2.1 codex: command not found 的三种成因 这个报错大概是新手遇到最多的。安装过程没有任何提示结果 codex --version 一执行终端告诉你找不到这个命令。 第一种成因npm 的全局 bin 目录不在 PATH 里。这种情况很常见尤其是用 nvm 管理 Node 的时候。先查一下当前 npm 的全局前缀 bash npm prefix -g把输出目录加到 shell 的 PATH 里比如输出是/Users/你的用户名/.nvm/versions/node/v18.20.0就在.zshrc或.bashrc里加上export PATH$PATH:$(npm prefix -g)/bin然后在当前终端重新加载配置source ~/.zshrc或source ~/.bashrc。第二种成因二进制安装包没有给执行权限。如果你下载的是tar.gz解压后直接用的版本解压完后要确认codex文件有可执行权限chmod x /path/to/codexWindows 用户通常是解压后没有把目录加入系统 PATH去“环境变量 - Path”里加一下即可。第三种成因安装其实没成功。npm install 在下载过程中被中断或者缓存损坏。这种情况不需要升级系统直接清理重装npm cache clean --force npm uninstall -g openai/codex npm install -g openai/codex注意不要在 mac 上用 sudo 强行把 npm 全局包装到系统目录。这会绕开 nvm 的权限管理后面升级 Node 时会非常痛苦。2.2 安装包下载失败或进度条卡死现象很典型npm install 停在sill idealTree buildDeps卡了十几分钟最后给你一个npm ERR! network或ETIMEDOUT。或者二进制的tar.gz下到一半断掉重开又是从头下。最常见的原因是 npm 源到本地的连通性不好或者网络出口波动导致下载长时间停滞。处理方式很简单把 npm 源换到国内镜像npm config set registry https://registry.npmmirror.com换源后建议把缓存清一下再装npm cache clean --force npm install -g openai/codexmacOS 上我更推荐用 Homebrew 安装brew install codexLinux 用户可以直接下载官方 release 的tar.gz解压后放到/usr/local/bin并加上执行权限。装完先验证版本codex --version如果版本号正常说明安装链路没问题。2.3 桌面版打不开 / 闪退这个针对 Windows 桌面版和部分 Linux 桌面用户现象是安装完点图标没反应或者窗口一闪就没了。我第一次遇到时以为软件坏了重装了三遍没解决。后来查日志才发现是系统缺 WebView2 Runtime。Windows 上很多桌面应用依赖这个组件缺失时不会提示直接闪退。排查步骤按顺序来去%USERPROFILE%\.codex\logs看日志文件闪退原因一般写在最后几行。打开事件查看器看对应时间的应用程序错误记录。如果是 Windows确认 WebView2 Runtime 已安装没有就去微软官网下载安装。如果有旧的config.toml或auth.json备份后先挪走用全新配置启动一次。还有一个低级但常见的问题某些公司的安全策略会把 Codex 的缓存目录/tmp或%TEMP%下的临时文件锁住导致应用启动时写文件失败。给 Codex 设置一个可写的临时目录或者临时关一下安全软件再试多半就能起来。3. 登录与认证报错auth token is unavailable的彻底排查3.1 这个报错到底在说什么codex auth token is unavailable的字面意思就是Codex 在本地找不到可用的登录凭据。它读取的位置是~/.codex/auth.json。这个文件里存的登录状态、token 信息如果文件不存在、格式损坏、内容过期或者没权限读取Codex 都会认为“token 不可用”。对这个报错第一反应不该是重装而是检查登录链路ls -la ~/.codex/ cat ~/.codex/auth.json如果auth.json不存在直接登录codex login按终端提示完成浏览器或设备码授权成功后auth.json会自动生成。3.2 token 不可用的六个排查点聊几个我实际踩过的坑按概率排序没登录或登录态过期Codex 的登录态不是永久的过期后第一次请求就会报这个错。重新codex login即可不用删配置。环境变量覆盖掉了本地 token如果你在 shell 里设了OPENAI_API_KEY而且这个值是空的、或者写错了Codex 会优先读环境变量本地auth.json里明明有合法 token 也没用。先执行echo $OPENAI_API_KEY看看有没有意外值。有误导的变量就先unset OPENAI_API_KEY再试一次。auth.json 格式损坏比如手动编辑过、多写了个逗号或者被同步工具部分覆盖。用 Python 快速校验python3 -m json.tool ~/.codex/auth.json报 JSONDecodeError 就说明文件坏了备份后删掉重新codex login。文件权限不对Linux/macOS 上Codex 对auth.json的权限敏感。如果文件被其他用户可读它可能直接拒绝读取。把权限收回来chmod 600 ~/.codex/auth.jsonHOME 路径不一致如果你用 sudo 安装或者用不同用户切换终端~解析到的目录不一样就会出现“这台机器明明登录过换个终端就报 token 不可用”的诡异情况。确认启动 Codex 的终端环境里echo $HOME指向同一个目录。迁移过.codex目录从旧机器拷贝的auth.json往往和机器、设备绑定直接拷过来不一定能用。建议在新机器上重新登录。3.3 登录重试的正确姿势先清理再登录避免旧状态干扰codex logout rm -rf ~/.codex/auth.json codex login完成后可以用codex auth status这类命令确认登录状态。不同版本命令名可能不一样先用codex --help看一下当前版本支持哪些子命令。注意如果你配置了第三方模型服务不要把第三方 key 写到auth.json里。Codex 对这块的读取逻辑按 provider 区分写错地方会一直报另一个奇怪的错——模型名认出来了但 key 找不到。4. 网络与转发配置报错cc switch local proxy failed实战解析4.1 报错出现的真实场景报错原文是cc switch local proxy failed while handling codex endpoint /responses.第一次看到这段报错我是懵的。后来摸清楚规律才发现Codex 在请求模型接口时会在本地起一个转发进程负责把请求统一转发到配置的 endpoint。特别是你设置了第三方模型服务或自定义 base_url 时这个本地转发进程就是请求链路的关键一环。它启动失败或者启动后没法正常工作就会出现上面的报错。常见触发场景包括配置里写了不支持的 endpoint、本地端口被占用、网络相关环境变量指向了一个已经失效的地址。4.2 排查步骤详解按顺序来别跳第一步看日志。打开~/.codex/logs/目录下当天的日志文件找 “local proxy” 或 “endpoint” 关键字。日志里往往会直接把原因写明比如端口冲突、DNS 解析失败。第二步检查端口占用。如果你配置里指定了本地端口先看它是不是被别的进程占了lsof -i :端口号macOS 和 Linux 上这个命令直接能用Windows 可以netstat -ano | findstr 端口号。把占用进程处理掉再重启 Codex。第三步检查网络相关环境变量。Codex 是 Node 实现的 CLIHTTP 客户端会自动读取HTTP_PROXY、HTTPS_PROXY、ALL_PROXY这类环境变量。如果你之前设置过而这些变量指向的地址已经不可用就会出现转发失败。检查一下env | grep -i proxy发现可疑变量就临时清掉再试unset HTTP_PROXY unset HTTPS_PROXY unset ALL_PROXY第四步检查 endpoint 地址。确认base_url没写错协议是不是https有没有多余的斜杠路径是不是到/v1为止。很多人在这儿把https://api.xxx.com/v1/chat/completions整段填进去结果请求路径重复直接报转发错误。第五步如果根本不需要本地转发功能检查是不是误开了某个 provider 配置或模型路由相关的开关。把它关掉用默认配置启动一次验证。4.3 网络连通性测试别让 Codex 背锅还有一类报错不包含 proxy 字样但本质上也是网络问题connect ECONNREFUSED connect ETIMEDOUT getaddrinfo ENOTFOUND这些报错的意思是请求根本没到模型服务端或者中途卡住了。先做连通性测试而不是重装 Codexcurl -I https://api.openai.com/v1/models如果想测第三方模型服务把地址换成你的 endpoint。看返回状态200网络通路正常继续查配置和 key。401网络通了但是 key 无效。超时或无响应本地到目标节点的连通性不好。Codex 对网络环境比较敏感能不能顺畅使用很大程度上取决于你本地到 API 服务节点的实际连通情况。不同时间、不同网络出口测试结果可能差别很大。我的建议是把连通性测试做在前面而不是反复重装找问题。5. 模型与配置类报错model not supported和配置解析失败5.1 模型不支持大概率是拼写和版本的问题报错原文The gpt-5.6-sol model is not supported when using codex.看到 “model is not supported” 时先别怀疑 Codex 坏掉了。它只是想告诉你你配置的模型名Codex 当前不认识。原因基本是这两个配置里的model字段写错了名字或者第三方服务不支持某个特定模型。注意gpt-5.6-sol这类名字看着像官方型号实际上可能是不存在的组合或者需要某个新版本才支持。排查方式codex --help在输出里找当前版本支持的模型列表或者直接看官方文档里对应的模型支持表。然后把config.toml里model gpt-5.6-sol改成官方支持的模型名。5.2 配置文件的正确写法~/.codex/config.toml是核心配置一份最简单的默认配置大概是这个样子model gpt-5-codex [model_provider] name openai base_url https://api.openai.com/v1 env_key OPENAI_API_KEY几个容易出错的地方base_url写到/v1这一层就行不要带/chat/completions或/responses这样的子路径。env_key对应的是环境变量名不是 key 本身的值。如果你的 key 不叫OPENAI_API_KEY需要先调整环境变量名或者在配置里换成对应的变量名。还有一点同一个 key 不要重复出现在多个位置。如果你同时在环境变量里设置了OPENAI_API_KEY又在配置文件里写了一个 keyCodex 会优先使用环境变量这时候配置文件的 key 就会被忽略表现为“配置明明改对了还是 401”。5.3 接入 DeepSeek 等第三方模型时的高频坑很多人把 Codex 接入 DeepSeek目的是用上更灵活的模型组合。做法本身没问题但第三方模型的接入点很多报错也五花八门。最常见的三种第一种401 Unauthorized。key 填错了或者没有 export 到当前终端环境。注意终端里export DEEPSEEK_API_KEYxxx只在当前会话生效换一个终端就没了。建议写到 shell 配置里。第二种model not found / model not supported。第三方服务支持的是deepseek-chat这类模型名和 Codex 默认的模型命名规则不一致。需要在配置里显式指定并且确认服务商是否支持通过 Codex 的请求格式来调用。一份常见第三方接入配置长这样model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY提示上面这段是根据当下常见实践的写法具体模型名和 endpoint 要以服务商最新的接口文档为准。我见过不少人照抄网上的旧配置结果模型名已经换过一轮照搬就报错。第三种请求链路偶发失败。第三方服务的并发限制、超时设置和官方接口不一样容易出现“第一次能跑第二次就失败”。这通常不是配置问题而是调用频次被限制。处理方式是降低并发、增加重试或者检查 Codex 的 timeout 配置。6. 运行时环境报错Node 版本、构建工具、进程崩溃6.1SyntaxError: Unexpected token与 Node 版本运行codex --version或者执行任务时终端突然抛出一堆SyntaxError: Unexpected token ??这类错误根因往往是 Node 版本太低。Codex 这类工具对 Node 版本有最低要求太低的版本解析不了新语法。先查node -v再看 Codex 安装文档里要求的版本。如果版本过低用 nvmLinux/macOS或 nvm-windows 升级 Node不要自己手动覆盖系统目录里的 node容易把环境搞乱。升级后用node -v确认再运行codex --version。这一步做好能消除一大半莫名其妙的语法错误。6.2 Codex 执行项目任务时报process is not defined这个报错不是 Codex 本身的报错而是 Codex 在帮你干活的项目里触发的。我在 Vite Vue3 项目里遇到过ReferenceError: process is not defined原因是浏览器环境没有 Node 的process对象但 Vite 配置文件或某个依赖在浏览器端代码里读取了process.env。Codex 只是执行了命令然后把项目原本的问题暴露出来了。排查思路看报错堆栈里涉及哪个文件优先检查vite.config.ts和项目根目录的构建配置。把process.env.xxx替换成import.meta.env.xxx。也可以直接把这个报错上下文回传给 Codex让它修正代码。Codex 执行类报错的大部分情况都不是 Codex 本身坏了而是它所在的项目环境有历史包袱。排查时先把它当成普通开发环境报错来处理。6.3 长任务导致的进程崩溃用 Codex 处理超大项目时终端里的进程可能突然被杀掉。表面上看像崩溃实际上是内存或会话超时。我的处理经验是拆分子任务让 Codex 一次只处理一个模块而不是一把梭。尤其是在 CI 环境下没有交互式 terminal 时很多交互确认流程会直接失败。先看 Codex 是否支持非交互模式以及对应的参数。长时间任务建议把输出重定向到日志文件方便回溯报错现场。7. 10 个高频报错速查表 黄金排查五步法7.1 高频报错速查表把前面展开的 10 个报错压成一张速查表遇到问题直接查序号报错 / 现象阶段最直接的处理办法1codex: command not found安装检查 PATH 和npm prefix -g2下载失败、ETIMEDOUT安装换 npm 镜像、清缓存、用包管理器3桌面版闪退启动补 WebView2、查日志、重置配置4auth token is unavailable认证codex login检查环境变量覆盖5登录超时 / 二次登录无反应认证清理旧 token重新登录6cc switch local proxy failed...网络/配置查本地转发进程、端口、环境变量7ECONNREFUSED/ENOTFOUND网络curl -I测试 endpoint 连通性8model is not supported模型配置查支持清单改model字段9第三方模型401/model not found模型配置核对 key、base_url、模型名10SyntaxError/process is not defined运行环境升级 Node、修复项目环境7.2 黄金排查五步法不管哪个报错我实际落地用的排查流程永远是这五步第一步复现并记录。确保能在固定操作下复现把完整报错复制下来不要只看最后一行。日志里的前因后果往往比报错本身更值钱。第二步查日志。~/.codex/logs/下的日志文件是最可靠的信息源。注意看时间戳找出第一次出现错误的时间点回忆当时改了什么配置。第三步查配置和环境变量。逐个确认config.toml、auth.json、OPENAI_API_KEY、HTTP_PROXY等环境变量的实际值。这一步能解决五成问题。第四步隔离变量。临时把第三方配置全部去掉用最纯净的默认配置启动。如果能跑说明问题在自定义配置里二分法逐步加回去找到罪魁祸首。第五步升级或重装。codex update或者卸载重装是最后手段不是第一手段。7.3 调试常用命令下面这组命令是我在不同版本 Codex 上用过的命令名可能随版本变化最准的方式是codex --help查看codex --version codex --help codex login codex logout codex auth status codex update日志和配置目录的固定位置也值得记一下ls -la ~/.codex/ tail -f ~/.codex/logs/*.log cat ~/.codex/config.toml cat ~/.codex/auth.json我在实际使用中最大的感触是Codex 的报错配置类问题占六成认证类占三成真正的核心 bug 反而很少。遇到报错先别急着卸载重装把config.toml和auth.json打开看一遍再查一下环境变量多半就找到原因了。另外第一次配好之后记得备份一份~/.codex目录升级前先 diff 一下配置变化这个习惯帮我省了不少时间。希望这套排查思路对你有用有新的报错也欢迎拿来一起研究。