装 Codex 这种官方 CLI 工具最气人的往往不是功能不会用而是千辛万苦装好了敲下第一条命令就被一堆莫名其妙的报错糊脸。我身边好几个同事都卡在这一步网上搜一圈答案七零八落有的甚至互相矛盾。这篇文章把我自己折腾 Codex 期间遇到的 10 个高频报错、以及对应的排查思路整理出来从认证、网络、模型名到运行环境都有覆盖。适合刚装好 Codex 却跑不起来的新手也适合被某个怪报错反复折磨、想系统排查一遍的开发者。1. 认证与登录一半的报错都发生在这1.1 报错一Codex auth token is unavailable——最典型的新手拦路虎这个报错我见过太多次了几乎每个新装 Codex 的人都会撞一次。字面意思是“拿不到认证 token”但背后的原因至少有三种。第一种是根本没执行登录。很多人以为装好包、配好环境变量就能直接用但实际上npm install -g openai/codex装出来的只是一个 CLI 壳子它需要一份有效凭据才能向服务端发起请求。正确做法是执行codex login它会拉起浏览器让你授权一次之后把凭据写到本地。这个步骤不能省。第二种是执行了登录但凭据文件没有落在正确的位置。Codex 在 macOS/Linux 上把登录信息存在~/.codex/auth.jsonWindows 上是C:\Users\你的用户名\.codex\auth.json。如果你的 HOME 环境变量被改过或者你用管理员权限跑了终端文件可能写到了别的地方程序自然找不到。排查时先看这个文件是否存在ls -la ~/.codex/auth.json cat ~/.codex/auth.json文件里正常应该是一个OPENAI_API_KEY字段加上登录设备相关的内容。如果文件不存在或者内容是空的直接重来一次codex login。第三种是权限问题。auth.json 的权限太宽松也会被 Codex 拒绝这个细节我在 macOS 上遇到过。因为 Codex 会校验文件不能被其他用户读取如果之前用sudo执行过相关命令导致文件 owner 变成 root普通用户跑起来就会报 token unavailable。修复命令chmod 600 ~/.codex/auth.json chown $USER ~/.codex/auth.json1.2 报错二登录成功却一直 401——问题可能不在 Codex另一种更让人上火的情况是明明浏览器里授权成功了codex login也提示完成但一运行就报 401 Unauthorized或者 Redirect URI mismatch 之类的东西。我把这类问题的排查顺序固定为先看账号再看时间最后看本地文件。先说账号。Codex 这个工具比较特殊它不是“登录就能用”账号还需要具备相应的服务权限。如果你用的是没有绑定支付方式、或者根本没有 API 访问权限的账号登录流程虽然走完了真正发请求时照样会被拒。我的建议是直接去官网或 API 平台确认账号状态别在本地瞎折腾。其次是系统时间。这算一个冷门原因但确实坑过人。token 有签发和过期时间本机时间如果比标准时间快了或慢了几分钟授权服务就会判定 token 无效。我遇到过一台主板电池没电的老机器登录后必现 401最后发现是时间快了两小时。排查命令是date对不上就先打开自动同步时间。最后才是本地文件坏了。auth.json 被某些同步工具覆盖、半截写入、甚至被编辑过都可能导致 401。处理方式最省事把~/.codex/目录备份后直接删掉重新登录mv ~/.codex ~/.codex.bak codex login1.3 报错三远程开发机上没有浏览器登录卡住不动还有一种场景经常遇到在远程开发机或容器里装好 Codex跑codex login时终端提示你去浏览器打开某个链接但机器上根本没有浏览器。大部分人的第一反应是卡在那里不知道干嘛。我的做法是看终端里那条提示它通常会给出一个授权链接和回调信息。在本地浏览器打开链接、完成授权后终端会提示输入一个 code把页面上显示的 code 粘回来就行。如果你的 Codex 版本比较新可以直接用 headless 模式跑codex login --headless这个模式会直接输出完整 URL你在本地浏览器打开授权拿到 code 后回到终端粘贴即可。注意别在多个终端窗口同时跑登录授权码是一次性的先把其他 session 关掉再操作。提示远程终端里弹出的 URL 如果被自动转成超链接复制的时候可能多带]或)字符把地址先复制到纯文本编辑器里检查一眼再打开。2. 请求刚发出去就失败网络与端点类报错2.1 报错四cc switch local proxy failed——配置切换器自己翻了车cc switch local proxy failed while handling codex endpoint /responses是评论区里出现频率最高的一条报错。我先把结论放这里这个报错的根因通常不在 Codex 本体而在于 cc-switch 这个配置切换工具。cc-switch 这类工具做的事情简单说就是帮你维护多套 Codex 配置切换的时候把~/.codex/config.toml里的 base_url、model、token 改成对应那套然后拉起一个本地转发服务。Codex 的请求先到本地转发服务再由它转发到真实端点。报错信息里的local proxy failed说明这个转发服务没有正常监听或者监听了但转发失败。排查我建议按三步走。第一步打开 cc-switch 的日志看转发服务是起不来了还是起来后被杀掉。第二步确认端口没有被占用比如它默认用的几个本地端口用lsof -i :端口号或 Windows 上的netstat -ano | findstr 端口号查一下。第三步检查~/.codex/config.toml里的 base_url 是不是被改成http://127.0.0.1:xx了如果这个值指向的本地转发服务并没有启动那 Codex 一发请求就报 local proxy failed。还有一种情况是路径写错。比如 base_url 写成了http://127.0.0.1:3456/v1Codex 在请求时还会自动拼/responses结果变成/v1/responses这边的转发服务路径对不上一样会失败。最稳妥的做法是把 base_url 写成转发服务要求的裸地址具体路径由它来处理。2.2 报错五connect ETIMEDOUT 与 socket hang up——先查这三处Codex 跑的时候突然给你一个connect ETIMEDOUT或者socket hang up不用急这类网络报错其实最好定位因为它的含义非常直接TCP 握手失败或者连接建立后对端把连接断开了。我一般按三个地方查。第一查 DNS 和连通性。先确认你配置的端点本身可达curl -I https://api.openai.com如果这条命令本身超时说明网络链路有问题Codex 怎么配置都没用。如果通再看是不是端口或者协议被拦了。第二查本机系统级转发设置。Codex 底层走的是 HTTP 客户端库多数情况下会读取系统配置。如果你本机挂着一个全局转发服务它可能把流量也拦了一遍这个服务一崩或者规则配错Codex 这边就表现为connect ETIMEDOUT或ECONNREFUSED。排查方法是临时把系统转发设置关掉再跑一次。如果这样通了再去调转发服务的规则而不是反复重装 Codex。第三查端点地址是否写多了后缀。Codex 的请求路径比较特殊它默认会往 base_url 后面拼/responses。如果你习惯性地在 base_url 里写了https://api.openai.com/v1最终请求就变成/v1/responses这在某些兼容端点下会直接 404 或连接被重置。正确做法是先看你对接的服务文档它要求 base_url 填裸域名还是带/v1。2.3 报错六The model is not supported——模型名不是你想写就能写的The gpt-5.6-sol model is not supported when using Codex这条报错我最近看到特别多。一句话解释你写的模型名不在 Codex 支持的列表里。Codex 会对模型名做一层校验目的是防止把请求发到一个根本不存在的模型上。出现这个报错最常见的原因是你在网上抄了一份配置但配置里的模型名要么已经过期要么被写错。我建议先看本机支持哪些模型名codex models如果你用的是第三方兼容端点比如 DeepSeek 这类服务那模型名必须以服务商提供的为准。Codex 的模型校验逻辑对官方端点和第三方端点不太一样官方端点要求标准模型名第三方端点一般只是透传但仍可能有一层简单校验。我见过有人把官方模型名写进 DeepSeek 的配置结果 DeepSeek 压根没有这个模型自然跑不起来。正确做法是去服务商文档里查模型名然后改到 config.tomlmodel deepseek-chat改完重启 Codex 进程必要时把 cc-switch 也重新切换一次让配置真正落盘。3. 安装与运行环境那些“不是 Codex 的错”的 Codex 报错3.1 报错七codex: command not found 与 PATH 问题装完之后打开新终端输入codex却提示command not found这个问题看起来简单但实战里真的排名靠前。原因几乎都出在 PATH 上少数出现在安装失败上。先说 PATH。通过 npm 全局安装时命令脚本会被放进 npm 的全局 bin 目录在 macOS/Linux 上通常是/usr/local/bin或~/.npm-global/binWindows 上通常是%APPDATA%\npm。如果你的 PATH 里没有这些目录shell 自然找不到codex命令。检查方法npm bin -g然后把输出目录加入 PATH。Windows 用户装完 Node 后如果没勾选自动配置 PATH这里最容易出问题。还有一种情况是你明明安装了但安装到了某个 Node 版本管理工具对应的目录下换了一个 Node 版本后命令就消失了。我的习惯是全局装到固定版本的 Node 下或者直接用 npx 方式规避npx openai/codexnpx 会临时下载并执行不会污染 PATH适合只想试试看的场景。不过正式使用我还是建议全局安装因为 npx 每次启动都可能做检查慢很多。3.2 报错八桌面版打不开——macOS 隔离属性与 Windows SmartScreenCodex 有桌面版之后安装包打不开的报错也多了起来。macOS 上最常见的是提示“无法打开”“已损坏”或“移到废纸篓”这其实是 Gatekeeper 的隔离属性在起作用。修复方式是一行命令sudo xattr -d com.apple.quarantine /Applications/Codex.appWindows 上最常见的是 SmartScreen 拦截通常显示“已保护你的电脑”。处理方式是在安装包上右键选择属性底部“解除锁定”打勾然后再运行。这么做的前提是你确认安装包来源可信官方的包一般不会有这种提示出现拦截往往是因为签名信息还没有被本机信任属于正常现象。这两类都不是 Codex 本身的 bug但很多用户会误以为是安装文件坏了。我的建议是官网下载的包比对一下哈希值没问题就放心处理千万别从第三方站点下载所谓“修改版”。3.3 报错九process is not defined——分清是 CLI 崩了还是代码跑错环境process is not defined这条报错如果出现在你跑 Codex 生成的代码时那大概率不是 Codex 安装的问题而是代码运行环境的问题。最常见的情况是代码里用了process.env.NODE_ENV但你把它放在了浏览器环境里跑浏览器没有 Node 的process全局对象。如果报错出现在 Vite 项目里解决思路有两个。一个是把代码改成用import.meta.env这种浏览器也能识别的环境变量读取方式// 替换前 const env process.env.NODE_ENV; // 替换后 const env import.meta.env.MODE;另一个是在 Vite 配置里做兼容定义export default defineConfig({ define: { process.env: {} } })但这里要提醒一句这种兼容写法只是让报错消失如果你代码里真用到了必须在 Node 里才能跑的process能力它依然不会工作。要分清“报错消失”和“功能正常”是两回事。如果process is not defined是 CLI 本身在启动时直接抛出来的那就优先怀疑 Node 版本问题把 Node 升到官方要求的最低版本之上再重装一次 Codex。4. 配置写了等于没写config.toml 的生效规则4.1 配置文件到底放哪、长什么样Codex 的配置文件是~/.codex/config.tomlmacOS 和 Linux 下都是这个位置Windows 下在C:\Users\用户名\.codex\config.toml。很多人的配置“不生效”第一步就错在文件放错位置比如在项目目录里放了一个.codex文件夹以为它会被读取。实际上大部分版本的 Codex CLI 只读取用户目录下的那份。一份最基础的配置文件不要一上来就写死模型名。很多人喜欢从网上抄一段带具体模型名的配置但 Codex 更新快配置示例里的模型名很可能已经不在支持列表里了。比如model gpt-5.6-sol这种写法看起来像模像样实际一跑就会报 model not supported。我建议先跑一下codex models看它认识谁再用输出里的模型名填进去。配置文件本身是 TOML 格式写过的人都知道它不允许 tab 缩进字符串要用双引号key 不能重复。如果你手写配置时把全角冒号、多余引号写了进去解析会直接失败但不一定立刻报错有些要到发请求时才暴露。建议改完配置后用编辑器自带的 TOML 语法高亮检查一下别盲目自信。4.2 报错十改完 base_url 还是走默认端点——环境变量覆盖与配置路径改完 base_url 之后Codex 还是一直请求默认端点这个问题很有代表性。答案往往是环境变量优先级压过了配置文件。Codex 配置读取规则大致是默认配置config.toml然后环境变量可以覆盖其中一部分。如果你在 shell 里设了OPENAI_BASE_URL或者OPENAI_API_KEY这些环境变量会覆盖配置文件里的 base_url。所以每次改完配置文件测试前先执行env | grep -i codex env | grep -i openai把残留的环境变量清掉再跑。还有就是改完配置后必须重启 Codex 进程它不会热加载配置。如果用了 cc-switch 切换配置记得查看它生成的文件确实写到了~/.codex/config.toml而不是别的自定义路径。这里有一个我自己踩过的坑我同时在~/.zshrc里 export 了一个OPENAI_API_KEY又在 config.toml 里填了另一个 key结果 Codex 一直用环境变量那个我在配置文件里反复改都没用。后来排查到原因时整个人都不好了。现在我的习惯是环境变量和配置文件只选一条路避免两套配置互相打架。4.3 第三方端点怎么配以 DeepSeek 为例很多开发者不想把 Codex 默认接到官方账号而是希望通过兼容端点跑其他模型DeepSeek 是其中被问得挺多的一个。配第三方端点时需要至少确认三件事base_url、model、API key。以 DeepSeek 为例它的 base_url 通常要求填到/v1这个级别model 填deepseek-chatAPI key 到平台申请。对应的 config.toml 大致是model deepseek-chat base_url https://api.deepseek.com/v1 api_key sk-你的key注意这里面有两个常见陷阱。第一base_url 有些服务商要求带/v1有些要求不带写错了要么 404 要么 model not supported。第二api_key字段直接写在 config.toml 里如果这台机器有其他人用注意文件权限要设成 600。更安全的做法是不写在配置文件里而是在环境变量里设置 OPENAI_API_KEY让 Codex 自动读取。我在本地试过第三方端点的坑往往出在“模型名校验”和“路径拼接”上。建议先模拟请求验证端点是否可用再去折腾 Codexcurl https://api.deepseek.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的key \ -d {model: deepseek-chat, messages: [{role: user, content: ping}]}如果这个请求能返回内容再回到 Codex 配置里排查如果不能问题在服务商那边别在 Codex 上浪费时间。5. 通用的报错排查方法论从日志到最小复现5.1 Codex 的日志在哪里看很多人遇到报错只会盯着终端那几行输出但终端信息往往被截断或只显示友好提示真正的错误细节在日志里。Codex 的日志目录在~/.codex/log/下路径大致是ls -la ~/.codex/log tail -f ~/.codex/log/codex-*.log日志会记录每个请求的 URL、状态码、响应体的关键信息。比如某个 500 错误日志里会告诉你到底是网关错误还是模型参数问题某个 401 错误日志里会显示是 token 过期还是权限不足。我每次排查报错的第一步都是打开日志按时间倒序看最后 100 行比在网上搜报错文案快得多。Windows 上日志路径类似在C:\Users\用户名\.codex\log。如果这一层没有日志检查一下是不是装了多个版本的 Codex日志可能写到旧版本的目录下。还有个小技巧加--debug或-v参数重新执行刚才报错的命令通常能得到完整堆栈。5.2 一份可以照抄的五步排查清单我踩过不少坑之后整理了一套固定的排查流程现在遇到 Codex 报错就按这个顺序来效率很高先确认版本和安装方式。执行codex --version记录版本号如果是 npx 拉起确认实际用的是哪个版本。看日志。~/.codex/log下最新的日志文件末尾定位具体错误码和请求 URL。检查配置落盘。任何配置切换工具改完配置后都去读一遍~/.codex/config.toml确认 base_url、model、api_key 是不是你想要的。最小复现。不要一上来就在完整项目里跑先用极简命令验证比如codex exec hello或者codex --help把问题收窄到“是发送请求挂了”还是“本地环境挂了”。隔离环境变量。跑之前清掉所有 OPENAI_/CODEX_ 开头的环境变量排除覆盖问题。这套流程下来80% 的报错都能自己定位。剩下 20% 涉及账号权限或服务端状态就去对应平台查状态页别在本地反复删缓存大概率没用。下面这张表是我压箱底的速查表遇到对应报错直接查报错关键词可能原因首选排查动作auth token is unavailable未登录、auth.json 缺失、权限不对codex login检查~/.codex/auth.json401 Unauthorized账号权限不足、系统时间偏差核对账号状态校准时间重新登录local proxy failedcc-switch 没拉起转发服务、端口被占查 cc-switch 日志和端口占用connect ETIMEDOUTDNS、防火墙、端点地址错误curl -I测连通性检查 base_urlmodel is not supported模型名不在支持列表codex models查看支持列表command not foundPATH 缺少 npm 全局目录npm bin -g检查 PATH桌面版打不开macOS 隔离属性、Windows SmartScreen解除隔离锁定比对哈希process is not defined浏览器环境用了 Node 专属对象改用import.meta.env或 Vite define配置不生效环境变量覆盖了配置文件env第三方端点跑不通base_url 缺/v1、模型名不匹配先用 curl 模拟请求验证端点5.3 最后几条保命建议最后分享几条我在实际运维中总结出来的经验。第一不要同时装多个封装版、切换工具配置错乱是 Codex 报错的最大来源。我之前同时装了官方 CLI、第三方封装、桌面版三个工具的配置文件互相打架最后排查半天发现是配置文件被另一个工具覆盖了。现在我的做法是只保留一条主路径其它全部卸载或者临时改名。第二遇到看不懂的报错先看英文原文。网上很多中文回答是错的甚至有人把别的工具的报错混进来照着改只会更乱。拿英文关键词去官方文档和官方讨论区里搜准确率高得多。第三Codex 更新频率高报错解决办法可能过两个版本就变了。如果你的版本很老很多看起来奇怪的报错其实在升级后就消失了。先npm install -g openai/codexlatest或从官网重新下载桌面版再开始排查往往能省掉大量时间。还有一点如果你改了配置之后 Codex 行为走向另一个极端比如一直失败或者请求根本不发可以先看看是不是 auth.json 里存了多套 key。cc-switch 这类工具切换配置时会把 key 也切换了而你终端里还挂着一个共同的环境变量 key两边不一致的时候 Codex 优先读环境变量就会跟配置里填的模型不匹配。这种问题看日志很容易定位别在那边盲目重装。我个人的体会是Codex 的报错看着多其实归类下来就那么几类认证、网络、配置、环境。90% 的情况都不需要重装系统或者重新申请账号耐下心按日志一层层剥基本都能解决。希望这篇整理能帮你少走一点弯路。