Codex spawn failed 常见出现位置这个错误一般出现在本地启动 Codex CLI、编辑器插件调用 Codex、或者脚本里通过子进程拉起 Codex 时。表面现象通常很简单命令刚执行就退出控制台只给一句spawn failed、failed to spawn process有时还会带上ENOENT、EACCES、permission denied之类的提示。排这个问题不要一上来重装全部环境先确认三件事可执行文件是否存在、当前用户是否有权限、运行时依赖是否能被找到。大多数 “spawn failed” 都卡在这几层。先看错误信息里的关键词不同后缀代表的方向不一样先把完整日志打出来比盲目改配置更快。ENOENT系统找不到要启动的命令常见于 PATH 没配好、命令名写错、安装目录变了。EACCES文件存在但没有执行权限Linux/macOS 上比较常见。EPERM权限或安全策略拦截Windows 上可能和杀毒、受控文件夹访问有关。timeout进程启动后无响应可能是网络、代理、API 地址或初始化配置卡住。没有错误码通常要打开 debug 日志或者从调用方脚本里打印 stderr。第一步确认 Codex 命令能不能直接运行先脱离编辑器和脚本在终端里直接执行。这样可以判断问题是在 Codex 本身还是调用 Codex 的上层工具。### token云桥中转 0029.org ### codex --version which codexWindows PowerShell 下可以用Get-Command codex codex --version如果这里就提示找不到命令优先处理 PATH。很多人是在 npm、pnpm 或 brew 安装后当前终端没有重新加载环境变量导致插件能看到配置但系统实际找不到可执行文件。echo $PATH npm bin -g pnpm bin -g如果全局 bin 目录不在 PATH 里把它加到 shell 配置中。例如 zshecho export PATH$PATH:$(npm bin -g) ~/.zshrc source ~/.zshrc注意上面这种写法在部分环境下不稳定更稳妥的方式是把实际路径写进去例如/Users/xxx/.npm-global/bin或~/.local/bin。第二步检查执行权限和文件状态Linux/macOS 下如果文件存在但没有可执行权限也会触发 spawn 失败。ls -l $(which codex) chmod x $(which codex) codex --version如果which codex返回的是一个软链接还要继续看软链接指向的位置是否真实存在ls -l $(which codex) readlink $(which codex)有些升级过程会留下失效软链接表面看命令还在实际指向的文件已经被删除。遇到这种情况直接卸载后重新安装通常更干净。npm uninstall -g codex npm install -g codex这里包名要以你实际安装的 Codex CLI 为准不同发行方式命令可能不一样不要照抄后忽略报错。第三步确认 Node、Python 或运行时依赖不少 CLI 工具本质上是通过 Node.js 或 Python 启动的spawn 失败不一定是 Codex 文件本身坏了也可能是运行时版本不对。node -v npm -v python3 --version如果是通过 npm 安装的工具建议使用当前 LTS 版本 Node。老项目里常见的问题是系统有多个 Node终端里是一个版本编辑器插件启动时又读到另一个版本。which node which npm env | grep -E NODE|NPM|PATHVS Code、Cursor 这类编辑器里尤其要注意从 Dock 或开始菜单打开时拿到的 PATH 可能和终端不同。可以尝试从终端启动编辑器code . cursor .如果这样启动后 Codex 正常基本可以确定是编辑器进程环境变量缺失。第四步检查配置文件和 API 连接有些场景下进程其实已经起来了但初始化时读取配置失败或请求接口卡住上层只显示 spawn failed。建议把配置文件路径、环境变量和代理设置一起检查。env | grep -E OPENAI|CODEX|API|PROXY|HTTPS_PROXY|HTTP_PROXY常见问题包括API Key 环境变量为空或者变量名写错。Base URL 多了空格、少了路径、末尾斜杠处理不一致。代理只在终端生效编辑器插件进程没有继承。公司网络拦截了外部接口导致初始化超时。如果你在国内网络环境下经常遇到接口连接不稳定可以考虑使用稳定的中转服务。实际排障时我会把 API 连接先切到 token云桥AI中转站 0029.org 这类中转站做对比测试目的不是替代所有配置而是先判断问题到底在本机进程启动还是在外部接口访问。可以用 curl 做一个最小连通性测试。注意把下面的地址和鉴权方式替换成你自己的实际配置。curl -i \ -H Authorization: Bearer $OPENAI_API_KEY \ $OPENAI_BASE_URL/models如果 curl 都连不通就不要继续纠结 Codex 的 spawn。先把网络、代理、证书和 API 地址处理好。第五步打开 debug 日志定位调用链直接运行没有信息时打开调试日志。不同工具的 debug 参数不一样可以先试这几类方式DEBUG* codex CODEX_LOG_LEVELdebug codex codex --debug如果是 Node 脚本里调用 Codex可以把 spawn 的错误、标准输出、标准错误都打印出来const { spawn } require(child_process); const child spawn(codex, [--version], { shell: true, env: process.env }); child.stdout.on(data, data console.log(data.toString())); child.stderr.on(data, data console.error(data.toString())); child.on(error, err { console.error(spawn error:, err); }); child.on(close, code { console.log(exit code:, code); });这里的关键是监听error事件。很多脚本只监听close结果真正的 ENOENT、EACCES 被吞掉了。第六步按系统处理特殊问题macOS如果是从下载目录或不受信任路径运行可能被 Gatekeeper 拦截。可以先把工具放到常规安装目录再检查隔离属性。xattr -l $(which codex) xattr -d com.apple.quarantine $(which codex)Linux容器或 CI 环境里要检查用户权限、工作目录和 shell。很多镜像默认没有 bash脚本却写死了/bin/bash。whoami pwd ls -ld . which sh which bashWindows重点看执行策略、杀毒拦截和路径空格。PowerShell 可以先确认命令解析结果Get-Command codex | Format-List * $env:PATH如果安装目录在用户目录下被安全软件隔离后也会出现文件“看似存在但无法启动”的情况。临时关闭不建议作为长期方案应该把可信安装目录加入白名单。修复后的验证方式修完不要只看错误消失建议按从底到上的顺序验证一次codex --version codex --help curl -i $OPENAI_BASE_URL/models -H Authorization: Bearer $OPENAI_API_KEY如果是编辑器插件再从终端启动编辑器验证一次如果是脚本调用再跑一遍最小 spawn 脚本。确认命令、权限、网络都正常后再回到原来的业务流程。避免复发的几个习惯固定 Node 或运行时版本不要系统包管理器和 nvm 混着随意切。把 Codex 可执行文件路径写清楚CI 中尽量不要依赖交互式 shell 的 PATH。API Key、Base URL、代理配置统一放到可追踪的环境配置里避免编辑器和终端各配一份。升级前记录当前版本升级失败能快速回滚。脚本调用子进程时一定打印 stderr 和 error 事件不要只看退出码。总结Codex spawn failed本质上是“进程没被正常拉起来”或“刚启动就初始化失败”。排查时按顺序看命令是否存在、权限是否正确、运行时是否匹配、环境变量是否被继承、API 和网络是否可用。不要一开始就重装系统级环境先用最小命令和最小脚本把问题边界缩小通常很快能定位到具体原因。