装好了 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_LEVEL=debug或codex --verbose。日志会告诉你它到底在连哪里、请求头里带了什么认证信息、服务端返回了什么状态码。比起盯着终端里那几行红色提示，看日志能节省一半时间。如果日志都没开，遇到auth token is unavailable这类信息，你根本不知道是 token 没找到还是验证失败，只能瞎猜。
准备工作三：准备一个干净目录。我建议专门建一个~/codex-test，不要放在已有项目里。然后在这个干净目录里先跑codex --help，看看配置文件解析是否正常。这个小习惯能帮你把“项目自身问题”和“Codex 环境问题”隔离开，排查速度翻倍。很多人喜欢直接在复杂项目里排查报错，结果被一堆不相关环境变量干扰，最后浪费一上午。
2. 安装阶段的报错：装是装上了，但跑不起来
2.1 报错1：codex: 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 报错2：EACCES: 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 报错3：npm 依赖安装报错、卡住、出现大量 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 --registry=https://registry.npmmirror.com。这样只对这一次安装生效，不会影响其他私有包。
注意：换个镜像源并不是万能药。如果你在公司内网，有些私有 npm 包必须走公司自己的 registry，全局换成公网镜像后反而会让私有包安装失败。所以用完镜像后，最好把 registry 改回来，或者用作用域配置单独指定。另外，npm 的 WARN 不一定代表失败，但如果你看到npm error code EBADENGINE，基本就是 Node 版本问题，可以直接跳到后面的报错 10。
3. 认证与配置阶段：Codex 不认你的身份
3.1 报错4：codex 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_KEY="sk-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 报错7：Could 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 报错8：JSON 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 报错9：process 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 报错10：Node.js 版本过低导致启动崩溃
现象是安装时没报错，但一运行就出现ERR_UNKNOWN_FILE_EXTENSION、ERR_REQUIRE_ESM、SyntaxError，或者进程一闪而过。这类问题在旧版 Node 上非常常见。Codex 使用了大量较新的 JavaScript 语法和 API，Node 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_LEVEL=debug 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 found | PATH 缺失或安装不完整 | 检查npm prefix -g并添加 PATH |
| EACCES permission denied | 全局目录无写权限 | 用 nvm 或修改 npm prefix |
| npm WARN / EBADENGINE | 依赖安装异常，Node 版本不匹配 | 清理缓存、换源、升级 Node |
| auth token is unavailable | 未登录或 token 失效 | 执行codex login或设置 API Key |
| invalid api key / 401 | key 错误、空格、权限不足 | 检查环境变量和账户配额 |
| 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 和模型名不支持这两个，几乎每个新环境都会遇到一次。后来我给自己定了个习惯：拿到新机器，先跑一轮检查清单，再开日志，再改配置。如果你现在正被某个报错卡住，不用急，从运行链条的第一环开始查，别在错误信息本身死磕。希望这份清单能让你少折腾半小时，多写几行真正的代码。
