装好了 Codex 还是跑不起来这个场景我见过太多次了。命令行敲下去没等到要的结果先等来一屏红色报错。Node 装好了、npm 也没报错偏偏运行的时候各种诡异问题。作为一个被 Codex 报错毒打过的老用户今天我把过去半年踩过的高频坑整理成一份可直接对号入座的排查清单覆盖安装、认证、配置、运行时四个层面一共 10 个高频报错每个都给出原因和实测过的解决方案希望能帮你少走点弯路。如果你刚接触 Codex建议先把第一节的运行链条读一遍再对照具体报错如果你已经能跑但时好时坏可以直接跳到后面的速查表。整篇文章不是教科书式讲解而是我实际排查时用的思路和命令。不同系统偶尔有差异但底层逻辑一致。命令行世界里的报错往往是表面现象真正的问题藏在它背后的运行链路上所以这篇文章的核心是帮你建立一套排查思路而不是背命令。1. 先搞清楚 Codex 的运行链条1.1 一次正常的启动要经过哪些环节Codex CLI 本质上是一个 Node.js 包入口命令 codex 启动后会依次做四件事加载本地配置文件、检查认证状态、把自然语言请求发送到模型服务、把返回结果解析并执行。看起来简单但每一步都可能报错。就像开车出门车况再好也得有钥匙、有导航、有可走的路。很多人以为“装好了”就等于“能跑了”结果卡在最不起眼的认证或模型名上。安装阶段对应“车况”npm 把包装好可执行文件放在 bin 目录并且这个目录必须在你的 PATH 环境变量里。认证阶段对应“钥匙”ChatGPT 登录态或 API Key 必须有效Codex 才能拿到模型服务的准入资格。配置阶段对应“导航”模型名、服务地址、参数配置都要正确否则请求发出去也会被对方拒签。运行时阶段则对应“路况”网络通不通、Node 版本够不够、依赖是否完整这些都会直接影响最终结果。另一件容易忽略的事是Codex 会在当前目录和用户主目录同时读取配置。如果你的项目根目录里存在.codex目录它可能与全局配置发生冲突造成model is not supported或auth token is unavailable这类误导性报错。我见过有人明明全局配置没问题却因为项目里一个写错的模型名跑来跑去怀疑 API Key。所以排查时不要只看错误信息本身要从运行链条的起点一层一层往后查。1.2 排查报错前的两条准备工作准备工作一确认安装本身没问题。执行codex --version能输出版本号至少说明命令入口通了如果提示 command not found说明 PATH 没配好或安装没成功。接着执行node -v看 Node 版本是否符合要求。很多诡异问题都源于 Node 版本过低后面我会专门讲。这两条命令成本很低但能筛掉一半基础问题不要跳过。准备工作二打开调试日志。许多 Codex 版本支持通过环境变量调整日志级别例如CODEX_LOG_LEVELdebug或codex --verbose。日志会告诉你它到底在连哪里、请求头里带了什么认证信息、服务端返回了什么状态码。比起盯着终端里那几行红色提示看日志能节省一半时间。如果日志都没开遇到auth token is unavailable这类信息你根本不知道是 token 没找到还是验证失败只能瞎猜。准备工作三准备一个干净目录。我建议专门建一个~/codex-test不要放在已有项目里。然后在这个干净目录里先跑codex --help看看配置文件解析是否正常。这个小习惯能帮你把“项目自身问题”和“Codex 环境问题”隔离开排查速度翻倍。很多人喜欢直接在复杂项目里排查报错结果被一堆不相关环境变量干扰最后浪费一上午。2. 安装阶段的报错装是装上了但跑不起来2.1 报错1codex: command not found命令找不到现象是安装时 npm 没有报任何错误但执行 codex 却提示 command not found。原因几乎都出在 PATH 环境变量上npm 把可执行文件放到了某个目录而当前 shell 没有把这个目录加进 PATH。比如 npm 可能会把全局 bin 放到/usr/local/bin或/Users/你的用户名/.npm-global/bin如果系统默认没有扫描这里codex 命令自然找不到。解决思路是先看 npm 把自己的 bin 目录放到了哪里输入npm prefix -g然后确认这个目录下是否有 codex 文件npm prefix -g # 常见输出/usr/local 或 /Users/you/nvm/versions/node/v20.x.x ls $(npm prefix -g)/bin | grep codex如果 codex 文件确实存在就把这个目录加进 PATH。macOS 或 Linux 下在~/.zshrc或~/.bashrc里加一行export PATH$(npm prefix -g)/bin:$PATH然后执行source ~/.zshrc。Windows 用户需要检查 PowerShell 的$env:PATH改完后重启终端即可。这里有个很容易踩的坑如果你用 nvm 管理 Node全局 bin 目录会和当前 Node 版本绑定。当你切换了 Node 版本之前全局安装的 Codex 会“消失”于是再次出现 command not found。解决办法是切回默认版本后重新安装或者干脆把默认 Node 版本固定成你常用的那一个。我遇到过不止一个同事折腾半天 PATH最后发现是 nvm 版本切换导致安装包不在当前可用链路上。2.2 报错2EACCES: permission denied权限不足现象是全局安装时报EACCES: permission denied甚至 npm 提示需要用 sudo 才能继续。根因是系统级/usr/local/lib/node_modules目录对普通用户不可写尤其是 macOS 使用系统自带 Node 时非常常见。很多新手第一反应是加 sudo这虽然能立刻装成功但后续升级、卸载都会碰到权限问题属于治标不治本。我的建议是优先用 nvm 重装 Node而不是 sudo。因为 nvm 会把 Node 和全局包都安装在用户目录下天然绕开系统目录权限问题后续切换版本也方便。如果你暂时不想动 Node也可以把 npm 全局目录改到用户目录npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.zshrc source ~/.zshrc执行完再重新运行npm install -g openai/codex权限问题就会消失。这里多说一句为什么我一直强调不要 sudo。因为 sudo 安装出来的文件属主是 root等你以后用普通用户执行 codex 相关命令时可能会遇到读写配置目录失败的情况。而且如果你同时使用多个 Node 版本sudo 安装的包有时会落到错误的版本目录里出现你装了包但当前版本找不到的尴尬。用 nvm 从源头解决比事后清理权限干净得多。2.3 报错3npm 依赖安装报错、卡住、出现大量 WARN现象包括安装 Codex 时网络连接超时、ETIMEDOUT、依赖树不完整或最后提示npm error。这类问题多数是网络不稳定或镜像源响应慢。npm 默认注册表在国外偶尔会因为线路问题下载很慢甚至会中途断掉。升级时也会偶发缓存损坏导致安装包残缺。解决步骤一般是这样先清理 npm 缓存再换一个公共镜像源然后卸载重装。常用命令如下npm cache clean --force npm config set registry https://registry.npmmirror.com npm uninstall -g openai/codex npm install -g openai/codex如果你不想永久改掉全局 registry也可以临时指定镜像npm install -g openai/codex --registryhttps://registry.npmmirror.com。这样只对这一次安装生效不会影响其他私有包。注意换个镜像源并不是万能药。如果你在公司内网有些私有 npm 包必须走公司自己的 registry全局换成公网镜像后反而会让私有包安装失败。所以用完镜像后最好把 registry 改回来或者用作用域配置单独指定。另外npm 的 WARN 不一定代表失败但如果你看到npm error code EBADENGINE基本就是 Node 版本问题可以直接跳到后面的报错 10。3. 认证与配置阶段Codex 不认你的身份3.1 报错4codex auth token is unavailable找不到认证令牌这个报错应该是我见过频率最高的一个。现象是执行任何 Codex 命令都提示auth token is unavailable有时还会补充一句 “Run codex login to authenticate”。看起来很简单但根因可以分成好几种从来没有登录过、登录态过期、认证信息没有写入预期路径、环境变量没有正确传入。不同原因对应的解决方式完全不同。最简单的方式是运行codex login按提示完成浏览器或设备码登录。如果你是使用 API Key先检查环境变量是否真的存在echo ${OPENAI_API_KEY:?not set}如果提示 not set说明环境变量没配好。在 shell 配置文件中加入export OPENAI_API_KEY你的key然后执行source ~/.zshrc。这里要特别注意Codex 读取认证信息有优先级临时环境变量通常高于配置文件。如果环境变量和配置文件里同时存在两套 key可能会产生冲突导致认证据说“不可用”。所以我建议只保留一种认证来源要么用登录态要么用 API Key不要混着来。另外auth token is unavailable并不一定代表你的 key 没了也可能是 key 过期了。特别是使用 ChatGPT 账号登录时登录态有时会静默失效但本地 token 文件还留着Codex 读出来才发现已经无法使用。这时候重新执行一次codex login是最快的办法。升级 Codex 版本后也容易触发类似问题因为新版可能换了 token 存储格式旧 token 不再被识别。3.2 报错5认证失败invalid api key / 401 Unauthorized现象是已经设置了 API Key但一请求就被拒返回 401错误信息里带Incorrect API key或Invalid authentication。这个报错比上一种更进一步说明本地确实有 key但服务端不认。根因大多是 key 本身写错了、有隐藏空格、账户权限不足或者是使用了一个没有对应模型访问权限的 key。排查时先确认 key 有没有前后空格最简单的办法是echo |$OPENAI_API_KEY|如果输出里出现| sk-xxx |这种带空格的内容说明变量里可能混入了空白字符。另外检查.env文件时要注意export OPENAI_API_KEYsk-xxx的引号不会带入变量值但如果是从网页复制时少复制一位那就只有重新生成 key 了。检查完 key 之后还要确认账户状态有些账户没有绑定结算方式或者余额不足同样会返回 401 或 403。这种情况换多少个 key 都没用。还有一个容易忽略的点401 和 429 的排查方向完全不同。如果错误码是 429说明是流量或配额超限不是 key 错如果错误码是 401才是认证问题。我见过有人在 429 的时候反复换 key白白浪费时间。所以排查时先看状态码再决定接下来的动作。3.3 报错6模型不支持the xxx model is not supported现象是配置里指定了一个模型名比如model gpt-5.6-sol请求发过去服务端直接拒绝并提示model is not supported。这经常发生在刚升级完 Codex 或者复制别人的配置时。因为 Codex 不同版本支持的模型标识会变老配置里的模型名可能已经下线了或者还没有出现在你用的接口版本中。解决思路很直接先把配置里显式指定的 model 删掉用默认模型跑一遍。如果默认模型能跑说明问题就出在模型名上。接下来去查官方文档确认当前部署环境支持的模型标识。如果你接的是第三方兼容接口就要按对方提供的模型名写注意大小写和连字符比如某些服务把模型命名为gpt-35你写成gpt-3.5就会报不支持。经验之谈是模型名报错时不要只检查用户主目录下的配置项目目录下的.codex/config.toml优先级可能更高。全局配置是对的项目配置错也会报错。快速排查可以用grep -r model ~/.codex/config.toml看看到底哪个文件写了模型名然后在报错信息里找它实际读取的配置文件路径。很多时候错误信息本身已经点名了文件路径只是一眼扫过去忽略了。4. 运行时环境报错连接、解析和 Node 环境4.1 报错7Could not connect to codex endpoint / 请求连接失败这个报错的表现形式很多可能是Could not connect to codex endpoint、ECONNREFUSED、ENOTFOUND也可能是fetch failed。核心意思是 Codex 在发起请求时没能连上它配置的模型服务地址。你可以先把它当成普通的网络问题处理如果只是偶尔一次可能服务端过载稍后重试即可如果每次都失败就要按链路排查。先确认地址本身是否能访问。如果你是使用官方服务可以简单测一下curl -I https://api.openai.com如果 curl 正常但 Codex 连不上重点检查环境里有没有自定义的 base_url。很多人之前为了接其他服务在 shell 配置或环境变量里设置过OPENAI_BASE_URL后来不用了也没删导致 Codex 一直往旧地址发请求。排查时用env | grep -i openai把所有相关环境变量先拉出来看一眼。如果 curl 也不通那就检查 DNS 解析和防火墙出站规则。nslookup api.openai.com可以确认域名解析是否正常防火墙则需要看是否放行了对外 443 端口。这个环节最容易出问题的是公司办公网络通常需要联系网络管理员处理。不要自己乱改系统网络设置很容易把别的服务弄坏。4.2 报错8JSON parse error in config配置文件解析失败现象是运行 codex 时提示配置文件解析失败常见关键词是JSON parse error、TOML parse error后面会跟一个文件路径和行号。原因基本都是手改配置时丢了引号、多了逗号或者用了错误的注释符号。Codex 的配置文件支持 TOML 格式和 JSON 的语法习惯不一样用讲 JSON 的思维写 TOML 很容易出错。如果报错指向 JSON 文件可以用 Node 快速校验node -e JSON.parse(require(fs).readFileSync(process.argv[2],utf8)) ~/.codex/config.json如果报错指向 TOML 文件可以用 Python 3.11 自带的 tomllib 校验python3 -c import tomllib,sys; tomllib.load(open(sys.argv[1],rb)) ~/.codex/config.toml这两条命令会把解析错误精确到行比自己肉眼找快得多。定位到问题后注意 TOML 的注释要用#不要用//字符串统一用双引号数组的最后一个元素后面也不能有逗号。改完后再跑一次codex --help确认配置能正常加载再继续。这里有个 Windows 用户特别容易踩的坑用记事本编辑配置文件后文件可能被存成带 BOM 头或 CRLF 换行的格式TOML 解析器会在第一行前看到一个不可见字符直接报解析失败。建议用 VS Code 等编辑器保存成 UTF-8 无 BOM、LF 换行。看似很小的事卡住你一小时完全没问题。4.3 报错9process is not defined前端项目里碰到这个报错其实不是 Codex CLI 本身报的而是你让 Codex 生成或修改一个前端项目后运行npm run dev或npm run build时才出现process is not defined。原因是在浏览器环境中代码直接引用了process.env但浏览器没有 Node 的全局 process 对象。很多模板代码会在配置文件里读取环境变量但忘了这是要跑在浏览器里的。解决方式取决于你用的构建工具。如果是 Vite 项目打开vite.config.js加上 define 配置import { defineConfig } from vite export default defineConfig({ define: { process.env: {} } })更精确的做法是只注入你需要的变量避免把所有环境变量都暴露给前端define: { process.env.VITE_API_BASE: JSON.stringify(process.env.VITE_API_BASE || ) }这个报错的常见诱因是Codex 在生成代码时把某个环境变量硬编码成了process.env.XXX但实际运行环境没有预留 polyfill。你可以先用grep在整个项目里搜一下process.env找到引用位置再决定是注入还是改写。不要盲目在代码里加 polyfill因为浏览器端不该接触服务端全部环境变量。4.4 报错10Node.js 版本过低导致启动崩溃现象是安装时没报错但一运行就出现ERR_UNKNOWN_FILE_EXTENSION、ERR_REQUIRE_ESM、SyntaxError或者进程一闪而过。这类问题在旧版 Node 上非常常见。Codex 使用了大量较新的 JavaScript 语法和 APINode 18 以下的版本常常无法支持。解决方式很简单先确认当前版本node -v如果低于官方要求的版本建议直接升级到 Node 20 LTS。用 nvm 的话nvm install 20 nvm alias default 20 node -v重新打开终端确认当前 shell 使用的是新的 Node。如果项目里带有.nvmrc文件可以写一个20然后运行nvm use让项目自动切到指定版本。升级后最好把 Codex 重新安装一次避免旧依赖缓存干扰。唯一要注意的是有时候你敲node -v已经显示 20但 npm 全局目录还挂在旧 Node 上。这是 PATH 顺序问题在 nvm 场景下尤其容易发生。最稳妥的方式是重新启动终端再执行which node看路径是否指向 nvm 的版本目录。如果指向了系统自带 node说明 shell 配置里的 PATH 顺序有问题优先调整到 nvm 的路径。5. 一次完整的排查实操从报错到跑通5.1 记录一次真实的 auth token 排查过程假设你执行codex 输出 hello出现了codex auth token is unavailable。这时候我不会急着换 key而是按运行链条顺序排查。第一步看命令本身是否正常codex --version。如果这个命令都提示 command not found那先回去处理 PATH 问题。只有命令入口通了后面才有意义。第二步开日志看细节CODEX_LOG_LEVELdebug codex 输出 hello。日志里会写明找不到 token还是 token 过期或者读取了哪个配置文件。比如它可能会输出using config file /Users/you/.codex/config.toml这能帮你确认是否真的读了预期配置。第三步检查认证方式。如果之前用的是 API Key执行echo ${OPENAI_API_KEY}看看变量是否为空。为空就补齐环境变量不为空但依然报错可能是 key 失效可以执行codex login切换成登录态或者直接重新生成一个 key。如果在 CI 环境里还要确认密钥是否安全传入了环境变量而不是写在代码里。第四步验证连接。curl -I https://api.openai.com能通说明基础网络没问题。如果连不通检查 base_url 配置和防火墙。很多人到这里会发现环境变量里残留了旧的OPENAI_BASE_URL清掉之后立刻恢复。这个步骤特别重要因为网络问题会伪装成认证问题。第五步再跑一次codex 输出 hello。如果还是报错把 debug 日志里服务端返回的状态码找出来。401 是认证失败403 多半是权限不足404 可能是接口路径不对。根据状态码再决定下一步而不是继续盲试。整个流程走下来不到十分钟却能把大多数认证类问题定位清楚。5.2 把这些步骤固化成一份检查清单我习惯把排查逻辑变成一个固定清单每次遇到新环境直接照着做。这个清单的顺序就是 Codex 运行链条的顺序按顺序排除基本不会漏。命令能在 PATH 里找到吗Node 版本够新吗日志开了吗配置文件有没有解析错误认证信息存在吗有效吗网络目标地址能通吗有没有多余的环境变量在干扰这个清单看起来很简单但很管用。很多人喜欢在认证和配置之间反复横跳浪费大量时间最后发现只是 Node 版本切换后命令路径没刷新。把清单从头到尾跑一遍比漫无目的搜索报错信息高效得多。我在新机器上第一次用 Codex 时通常会先跑一遍npm prefix -g、node -v、codex --version和echo $OPENAI_API_KEY四行命令就能把大部分基础问题排除掉。6. 高频报错速查表与避坑经验6.1 10 个报错速查表下面这张表汇总了前面提到的 10 个高频报错。它的价值在于帮你快速建立“现象到根因到处理动作”的映射但注意不要只背答案。真正动手排查时还需要结合具体报错信息、运行环境和你自己的配置。比如同样提示 model is not supported在官方 API 和兼容接口里处理方式可能完全不一样同样提示 auth token is unavailable新装环境和升级环境的原因也可能不同。所以遇到问题别只查表建议回读对应小节里的原理和命令换一台机器也能照样排查。报错关键词常见根因快速处理command not foundPATH 缺失或安装不完整检查npm prefix -g并添加 PATHEACCES permission denied全局目录无写权限用 nvm 或修改 npm prefixnpm WARN / EBADENGINE依赖安装异常Node 版本不匹配清理缓存、换源、升级 Nodeauth token is unavailable未登录或 token 失效执行codex login或设置 API Keyinvalid api key / 401key 错误、空格、权限不足检查环境变量和账户配额model is not supported模型名不存在或配置错误删除或写正确的模型名Could not connect / ENOTFOUND连接不上服务地址curl 排查 DNS、base_url、防火墙JSON/TOML parse error配置文件手误用 node/python 校验配置语法process is not defined前端代码引用了 Node 全局对象Vite define 注入或替换引用Node 版本相关崩溃Node 版本过低升级到 Node 20 LTS 并重装6.2 我的几条实战避坑心得第一条永远不要让配置一开始就复杂化。我第一次用 Codex 时照着网上的配置写满了 model、temperature、system prompt结果模型名写错排查了一个小时。后来我学乖了新环境先用最小配置跑通再逐步加参数。最小配置通常只有一两个字段不会出现“不知道是哪个参数导致报错”的问题这对新手尤其友好。第二条升级 Codex 后如果突然报认证错误优先重新登录。Codex 迭代很快认证方式、配置格式都会变旧 token 字段可能不再兼容。与其怀疑环境变量不如直接执行codex login或者去官方变更说明里看看是不是认证机制改了。我遇到过几次这样的情况重新登录后问题迎刃而解。第三条文件权限和换行符是个隐形坑。Windows 下用记事本编辑 config.toml 可能会引入 BOM 头TOML 解析器会直接不认macOS 或 Linux 下如果配置文件属主不对也会导致读取失败。建议统一用 VS Code 修改配置保存为 UTF-8 无 BOM、LF 换行。我在团队分享时提过这个细节第二天就有人反馈解决了困扰许久的问题。第四条善用日志但别被日志淹没。打开 debug 日志后你会看到大量请求细节关键信息是配置文件路径、认证来源、目标地址和状态码。别盯着每一行看只抓这几类关键词效率会高很多。这也是我整个排查流程里最实用的一招。这些坑我基本都踩过一遍特别是 auth token 和模型名不支持这两个几乎每个新环境都会遇到一次。后来我给自己定了个习惯拿到新机器先跑一轮检查清单再开日志再改配置。如果你现在正被某个报错卡住不用急从运行链条的第一环开始查别在错误信息本身死磕。希望这份清单能让你少折腾半小时多写几行真正的代码。