Codex spawn failed 进程启动失败排查

原创于 2026-06-29 15:01:39 发布 · 2 阅读

0 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#Codex #OpenAI #AI

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 codex

Windows PowerShell 下可以用：

Get-Command codex
codex --version

如果这里就提示找不到命令，优先处理 PATH。很多人是在 npm、pnpm 或 brew 安装后，当前终端没有重新加载环境变量，导致插件能看到配置，但系统实际找不到可执行文件。

echo $PATH
npm bin -g
pnpm bin -g

如果全局 bin 目录不在 PATH 里，把它加到 shell 配置中。例如 zsh：

echo '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|PATH'

VS 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_LEVEL=debug 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 bash

Windows

重点看执行策略、杀毒拦截和路径空格。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 和网络是否可用。不要一开始就重装系统级环境，先用最小命令和最小脚本把问题边界缩小，通常很快能定位到具体原因。