Windows 版 ChatGPT 客户端更新后,一打开就弹出 ChatGPT failed to start,下面跟着一句 Unable to locate the Codex CLI binary。网上常见的解法是「设一个 CODEX_CLI_PATH 环境变量」,但不少人照做后还是同一个弹窗。这篇把报错逐句拆开,按「先修复、再定位、后设变量」的顺序走,并把设完变量仍然报错的几种原因、找不到 codex.exe 的情况和一键脚本都补齐。
微信扫码咨询 ChatGPT failed to start、Codex 客户端报错处理与 ChatGPT Plus/Pro 国内升级
先看结论:这条报错的意思是客户端找不到自带的
codex.exe。先用 Windows 的「修复」功能处理一次,没好再找到真实存在的codex.exe,让用户变量CODEX_CLI_PATH指向它,最后完全退出客户端再打开。已经设过变量还没修好,直接跳到 改完 CODEX_CLI_PATH 仍然报错怎么排查。
客户端修好后继续用 Codex,支付宝和微信即可开通 Plus/Pro
本次报错的时间线如下,方便判断你遇到的是不是同一个问题:
| 时间 | 情况 |
|---|---|
| 2026-08-26 | Windows 版 ChatGPT 客户端推送更新,部分用户更新后启动即弹出 ChatGPT failed to start |
| 更新之后 | 客户端内 codex.exe 所在的版本目录会随更新变化,手动写死的路径可能再次失效 |
| 适用范围 | Windows 版 ChatGPT 客户端;Mac 和 WSL 的差异见下文单独分支 |
ChatGPT failed to start 报错原文逐句解释
ChatGPT failed to start 启动报错弹窗
弹窗里的英文一共四句,每一句都对应一个你可以做的动作:
| 报错原文 | 意思 | 你要做的动作 |
|---|---|---|
| ChatGPT failed to start. | 客户端本身启动失败,还没走到登录和联网那一步 | 不用换网络、不用退出账号 |
| Unable to locate the Codex CLI binary. | 客户端找不到 Codex CLI 的执行文件 codex.exe | 去电脑里找 codex.exe 在哪 |
| Set CODEX_CLI_PATH | 可以用环境变量手动告诉客户端 codex.exe 的位置 | 新建用户变量 CODEX_CLI_PATH,值填 codex.exe 完整路径 |
| or ensure the Electron resources include bin/codex. | 或者让安装包里本该自带的 resources\bin\codex 文件回来 | 先用 Windows「修复」或重装客户端,把缺的文件补回来 |
所以处理顺序是倒过来的:先试最后一句(修复安装包),不行再做第三句(设变量)。
ChatGPT 客户端检查更新显示已经是最新版本
客户端检查更新显示「已经是最新版本」也照样会报错,所以单纯重启、检查更新不一定能修好路径问题。这篇只处理「找不到 Codex CLI binary」这一条;登录失败(比如被要求验证手机号)、网络异常或账号提示属于别的问题,可以对照 ChatGPT 14 种常见报错的解决方法 处理,不要照搬下面的步骤。
先用 Windows 应用「修复」处理 ChatGPT 客户端
改环境变量之前,先让 Windows 修复一次客户端。修复会重新校验安装文件,缺失的 bin\codex 有可能直接被补回来。
- 打开 Windows 的「设置」。
- 进入「应用」,点击「安装的应用」。
- 找到 ChatGPT,点击右侧的三个点,选择「高级选项」。
- 在「重置」区域点击「修复」。
打开 Windows 设置
进入应用中的安装的应用页面
打开 ChatGPT 高级选项
点击 ChatGPT 修复按钮
修复结束后重新打开 ChatGPT。能正常启动,到这里就结束了,后面的步骤都不用做;还是同一条报错,再继续往下。
**注意:**只点「修复」,不要点下面的「重置」。Windows 页面已经注明,重置会删除这个应用的数据。
定位 codex.exe 的真实路径
打开开始菜单,搜索并启动 Windows PowerShell(普通打开即可,不需要管理员)。
在开始菜单中搜索 Windows PowerShell
把下面的命令复制进去,按回车:
Get-ChildItem "$env:LOCALAPPDATA\OpenAI\Codex" -Recurse -Filter codex.exe -File -ErrorAction SilentlyContinue | Select-Object -ExpandProperty FullName
在 PowerShell 中输入 codex.exe 查找命令
等命令跑完。找到文件时,PowerShell 会输出一条完整路径:
PowerShell 输出 codex.exe 完整路径
常见格式如下:
C:\Users\你的用户名\AppData\Local\OpenAI\Codex\bin\版本目录\codex.exe
复制你自己电脑上实际输出的那一行。用户名和版本目录每台电脑都不一样,不要照抄示例。
拿到路径后先验证一下文件确实存在,结果必须是 True:
Test-Path "把上面输出的完整路径粘贴到这里"
这条命令没有任何输出,说明默认目录里没有 codex.exe,直接看 找不到 codex.exe 的四种情况。输出了不止一行,先看 搜到多个 codex.exe 该选哪个。
新建 CODEX_CLI_PATH 用户环境变量
- 在 Windows 搜索栏输入「编辑系统环境变量」,打开对应的控制面板选项。
- 在「系统属性」窗口点击「环境变量」。
- 在**上方的「用户变量」**区域点击「新建」(不是下方的系统变量)。
- 变量名填
CODEX_CLI_PATH。 - 变量值填上一步确认存在的
codex.exe完整路径。
搜索并打开编辑系统环境变量
在系统属性中打开环境变量
新建 CODEX_CLI_PATH 用户环境变量
变量值只粘贴路径本身,不要加引号,不要带说明文字,也不要把下面这条示例原样填进去:
C:\Users\xxx\AppData\Local\OpenAI\Codex\bin\xxx\codex.exe
确认无误后点「确定」,回到环境变量窗口再点一次「确定」,最后关闭系统属性窗口。
确认环境变量并关闭系统属性窗口
关键一步:环境变量不会进入已经在运行的客户端进程。必须完全退出 ChatGPT(包括托盘里的图标)再重新打开,新变量才会生效。
改完 CODEX_CLI_PATH 仍然报错怎么排查
这一节是给「设过变量还是报错」的读者准备的,按出现频率从高到低排列。
先验证变量值是否生效
新开一个 PowerShell 窗口(旧窗口读不到新变量),依次执行:
[Environment]::GetEnvironmentVariable('CODEX_CLI_PATH', 'User')
Test-Path ([Environment]::GetEnvironmentVariable('CODEX_CLI_PATH', 'User'))
& ([Environment]::GetEnvironmentVariable('CODEX_CLI_PATH', 'User')) --version
- 第一行输出为空:变量没建在「用户变量」里,或者变量名拼错了(常见的是写成
CODEX_CLI_PAHT、多了空格)。 - 第二行是
False:路径填错了,或者值里带了引号、说明文字。 - 第三行没打印出版本号:这个
codex.exe本身跑不起来,换一个候选文件(见下文多个codex.exe的选法)。
另外检查一下「系统变量」里有没有一个旧的、错误的 CODEX_CLI_PATH,有的话删掉,只保留用户变量那一条,避免两处值不一致时搞不清哪个在起作用。
ChatGPT 进程没有完全退出
点窗口右上角的叉,ChatGPT 往往只是缩到托盘,后台进程还在,它读到的还是旧环境。打开任务管理器结束所有 ChatGPT 进程,或者在 PowerShell 里执行:
Get-Process -Name ChatGPT -ErrorAction SilentlyContinue | Stop-Process -Force
然后从开始菜单重新打开。还不行就注销一次 Windows 账户再登录,让资源管理器也重新加载环境变量。
路径含中文或空格
路径里的空格本身没问题,但变量值不要手动加引号,加了引号反而会被当成路径的一部分。
用户名是中文(例如 C:\Users\张三\...)时,个别情况下客户端调起 codex.exe 会失败。可以先换成 8.3 短路径试试:
(New-Object -ComObject Scripting.FileSystemObject).GetFile("你的 codex.exe 完整路径").ShortPath
把输出的短路径(类似 C:\Users\9F2A~1\AppData\...\codex.exe)填进 CODEX_CLI_PATH。如果短路径也不行,就把 codex.exe 所在的整个文件夹复制到纯英文目录,比如 C:\Tools\codex\,再把变量指向新位置。
搜到多个 codex.exe 该选哪个
按下面的优先级选:
%LOCALAPPDATA%\OpenAI\Codex\bin\下的文件,这是客户端自己的那份。有多个版本目录时,选修改时间最新的。- npm 全局目录下的文件(路径里带
node_modules\@openai\codex),这是你用npm i -g @openai/codex装的命令行版。 - 其他软件目录里的同名文件(比如编辑器插件自带的
codex.exe)不要选,插件一更新就会被删掉,变量又会失效。
想看每个文件的修改时间,可以用这条命令:
Get-ChildItem "$env:LOCALAPPDATA\OpenAI\Codex" -Recurse -Filter codex.exe -File -ErrorAction SilentlyContinue | Sort-Object LastWriteTime -Descending | Select-Object FullName, LastWriteTime
npm 全局目录没有写入权限
执行 npm i -g @openai/codex 时出现 EPERM 或 EACCES,通常是 npm 全局目录被设到了 C:\Program Files\nodejs 这类需要管理员权限的位置,或者以前用管理员装过一次导致文件归属不对。不要为此改用管理员运行,而是把全局目录改回当前用户下:
npm config get prefix
npm config set prefix "$env:APPDATA\npm"
npm i -g @openai/codex
装好后用 npm root -g 下的路径重新查找 codex.exe(命令见下一节)。
公司电脑禁止修改环境变量
「编辑系统环境变量」需要管理员权限,公司电脑经常点不开。用户变量本身不需要管理员,可以换两个入口:
rundll32 sysdm.cpl,EditEnvironmentVariables
这条命令会直接打开当前用户的环境变量窗口。或者用命令行写入:
setx CODEX_CLI_PATH "你的 codex.exe 完整路径"
这两种方式都被组策略拦截时,说明公司限制了注册表写入,只能联系 IT 帮你设置,或者请他们把 ChatGPT 客户端重新部署一次。
找不到 codex.exe 的四种情况
客户端目录里本来就没有 codex.exe
更新包没有把 codex.exe 带下来时,%LOCALAPPDATA%\OpenAI\Codex 里就是空的。先回到上面再「修复」一次;还没有,就卸载 ChatGPT 后重新安装,再搜一遍。国内网络下载安装包不顺利,可以参考 Codex 接入 DeepSeek 教程里的国内镜像下载方法。
只装过 npm 版 Codex CLI 但搜错了位置
npm 全局安装的文件通常在 %APPDATA% 下的 npm 目录,不会出现在前面搜索的 %LOCALAPPDATA% 里。没装过就先装:
npm --version
npm i -g @openai/codex
通过 npm 全局安装 Codex CLI
提示找不到 npm 命令时,先安装 Node.js,装完重新打开 PowerShell:
winget install --id OpenJS.NodeJS.LTS
装好后用这条命令找真正的 codex.exe:
Get-ChildItem (npm root -g) -Recurse -Filter codex.exe -File -ErrorAction SilentlyContinue | Select-Object -ExpandProperty FullName
**注意:**变量必须指向真正的
codex.exe。不要填 npm 目录,也不要填codex.ps1或codex.cmd,where.exe codex查到的通常就是这两个包装脚本。
codex.exe 被杀毒软件隔离
文件刚出现又消失,或者搜得到但运行时报「拒绝访问」,多半是被 Windows 安全中心或第三方杀毒软件拦了。打开「Windows 安全中心 → 病毒和威胁防护 → 保护历史记录」,找到 codex.exe 相关条目选择「还原」,再把它所在目录加入排除项。
codex.exe 装在其他盘或其他账户下
自定义过 npm 目录、把程序装到 D 盘,或者之前用另一个 Windows 账户安装过,默认目录都搜不到。直接按盘符搜:
Get-ChildItem -Path D:\ -Recurse -Filter codex.exe -File -ErrorAction SilentlyContinue | Select-Object -ExpandProperty FullName
把 D:\ 换成你要搜的盘。整盘搜索比较慢,耐心等它跑完。搜到其他账户目录下的文件时,最好用当前账户重新安装一份,而不是跨账户引用。
Mac、WSL 与非默认盘安装的处理方法
Mac 客户端出现同样报错
Mac 上同样提示找不到 Codex CLI binary 时,先确认应用包里的文件还在:
find /Applications -path '*Resources/bin/codex' 2>/dev/null
没有输出,先把应用拖进废纸篓,重新下载安装。重装还不行,可以用 npm 装一份命令行版并找到它的真实二进制:
npm i -g @openai/codex
find "$(npm root -g)/@openai/codex" -type f -name codex -perm +111
Mac 上图形界面应用不读 ~/.zshrc 里的变量,需要用 launchctl 设置,然后 Command + Q 彻底退出客户端再打开:
launchctl setenv CODEX_CLI_PATH "/上面找到的/codex"
launchctl setenv 重启电脑后会失效,重启后还报错就再执行一次。
在 WSL 里装了 Codex CLI
WSL 里用 npm 装的 codex 是 Linux 程序,Windows 客户端调不起来。不要把 CODEX_CLI_PATH 指向 \\wsl$\... 这类 WSL 路径,而是在 Windows 这一侧(PowerShell 里)再装一份,按上文步骤取 codex.exe 的路径。WSL 环境本身的搭建可以参考 Windows 用 PowerShell 和 WSL2 安装 OpenClaw 的教程。
客户端或 npm 装在非默认盘
把 npm 全局目录设到了 D 盘,或者用 Windows「移动」功能把应用挪到了其他盘,搜索时把目录换掉即可,例如:
Get-ChildItem "D:\nodejs\node_global" -Recurse -Filter codex.exe -File -ErrorAction SilentlyContinue | Select-Object -ExpandProperty FullName
不确定 npm 目录在哪,执行 npm root -g 看一下。路径里有空格(比如 D:\Program Files\...)照常填写,变量值同样不加引号。
一键修复脚本:自动设置 CODEX_CLI_PATH
不想一步步手动操作,可以用下面这个 PowerShell 脚本。它会依次做三件事:在客户端目录和 npm 全局目录里搜索 codex.exe,把找到的路径写进用户变量 CODEX_CLI_PATH,然后结束 ChatGPT 进程并重新打开。
**必须以普通用户身份运行:**不要右键「以管理员身份运行」。
CODEX_CLI_PATH是当前用户的变量,用管理员身份(尤其是另一个管理员账户)运行,变量可能写到别的账户下,你自己的客户端还是读不到。脚本检测到管理员权限会直接退出。
保存脚本
打开记事本,粘贴下面的全部内容,「另存为」时保存类型选「所有文件」,文件名填 fix-codex-cli-path.ps1,保存到桌面。
# fix-codex-cli-path.ps1
# Run from a normal (non-administrator) PowerShell window.
param(
[string]$Path,
[string[]]$ExtraRoot = @()
)
$principal = New-Object Security.Principal.WindowsPrincipal([Security.Principal.WindowsIdentity]::GetCurrent())
if ($principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
Write-Host 'Do not run as administrator. Close this window and use a normal PowerShell.' -ForegroundColor Red
exit 1
}
if ($Path) {
$candidates = @(Get-Item -LiteralPath $Path -ErrorAction Stop)
} else {
$roots = @("$env:LOCALAPPDATA\OpenAI\Codex", "$env:APPDATA\npm")
if (Get-Command npm -ErrorAction SilentlyContinue) {
$roots += (npm root -g)
}
$roots += $ExtraRoot
$candidates = $roots |
Where-Object { $_ -and (Test-Path -LiteralPath $_) } |
Select-Object -Unique |
ForEach-Object { Get-ChildItem -LiteralPath $_ -Recurse -Filter codex.exe -File -ErrorAction SilentlyContinue } |
Sort-Object FullName -Unique |
Sort-Object LastWriteTime -Descending
}
if (-not $candidates) {
Write-Host 'codex.exe not found. Run "npm i -g @openai/codex" first, or use -Path / -ExtraRoot.' -ForegroundColor Red
exit 1
}
Write-Host 'Found codex.exe:'
$candidates | ForEach-Object { Write-Host " $($_.FullName) [$($_.LastWriteTime)]" }
$clientDir = "$env:LOCALAPPDATA\OpenAI\Codex\"
$preferred = $candidates | Where-Object { $_.FullName.StartsWith($clientDir, [StringComparison]::OrdinalIgnoreCase) } | Select-Object -First 1
$exe = if ($preferred) { $preferred.FullName } else { ($candidates | Select-Object -First 1).FullName }
Write-Host "Using: $exe" -ForegroundColor Green
$version = & $exe --version 2>&1
if ($LASTEXITCODE -ne 0) {
Write-Host "Warning: '$exe --version' failed: $version" -ForegroundColor Yellow
} else {
Write-Host "codex --version: $version"
}
[Environment]::SetEnvironmentVariable('CODEX_CLI_PATH', $exe, 'User')
$env:CODEX_CLI_PATH = $exe
Write-Host "CODEX_CLI_PATH (User) = $([Environment]::GetEnvironmentVariable('CODEX_CLI_PATH', 'User'))"
$running = Get-Process -Name ChatGPT -ErrorAction SilentlyContinue
if ($running) {
Write-Host 'Closing ChatGPT...'
$running | Stop-Process -Force
Start-Sleep -Seconds 2
}
$app = Get-StartApps | Where-Object { $_.Name -eq 'ChatGPT' } | Select-Object -First 1
if ($app) {
Start-Process "shell:AppsFolder\$($app.AppID)"
Write-Host 'ChatGPT restarted.' -ForegroundColor Green
} else {
Write-Host 'Done. Please open ChatGPT from the Start menu.' -ForegroundColor Yellow
}
脚本里的提示文字用的是英文,是为了避开 Windows PowerShell 读取中文脚本时的编码乱码问题,不影响功能。
运行脚本
打开普通的 Windows PowerShell,执行:
cd ([Environment]::GetFolderPath('Desktop'))
powershell -ExecutionPolicy Bypass -File .\fix-codex-cli-path.ps1
-ExecutionPolicy Bypass 只对这一次运行生效,不会改系统的脚本执行策略,也不需要管理员。看到 Using: 后面是你认可的路径、最后出现 ChatGPT restarted.,客户端就会自动重新打开。
指定路径或额外搜索目录
脚本选错了文件,或者 codex.exe 在其他盘,可以手动指定:
powershell -ExecutionPolicy Bypass -File .\fix-codex-cli-path.ps1 -Path "D:\Tools\codex\codex.exe"
powershell -ExecutionPolicy Bypass -File .\fix-codex-cli-path.ps1 -ExtraRoot "D:\nodejs"
-Path 直接使用你给的文件;-ExtraRoot 会在默认目录之外再多搜一个目录。
ChatGPT failed to start 常见问题
设置 CODEX_CLI_PATH 后仍然报错怎么办?
先确认三件事:变量值没有引号和多余文字、Test-Path 结果是 True、ChatGPT 进程已经全部结束后再打开。这三项都没问题,按上文「改完 CODEX_CLI_PATH 仍然报错怎么排查」逐条往下看。
以后更新客户端又出现同一条报错怎么办?
更新后 codex.exe 的版本目录可能变了,变量里写死的还是旧目录。重新运行查找命令(或者重新跑一遍一键脚本),拿到新路径后编辑 CODEX_CLI_PATH 即可。
修复好了还需要保留 CODEX_CLI_PATH 吗?
如果是靠 Windows「修复」解决的,没有设过变量,就不用管。如果是靠变量解决的,等后续客户端更新正常后,可以把这个用户变量删掉,让客户端用自带的文件,避免旧路径失效后再次报错。
「修复」和「重置」有什么区别?
「修复」只重新校验和补齐安装文件,不动你的数据;「重置」会清空这个应用的本地数据,相当于重新安装。处理这条报错只需要「修复」。
电脑上有 Claude Code 或 Codex CLI,能让它帮我改吗?
可以。把报错截图交给能正常使用的本地智能体,发送下面这段要求:
请帮我在 Windows 中查找真实存在的 codex.exe,并把用户环境变量 CODEX_CLI_PATH 指向这个文件。修改前先告诉我准备使用的完整路径。
它给出路径后,仍然要自己用 Test-Path 确认文件确实存在。不要让它把教程里的 xxx 示例路径直接写进变量。
这个报错和 Codex 一直「正在重新连接」是一回事吗?
不是。ChatGPT failed to start 是客户端启动阶段找不到 codex.exe,窗口都打不开;「正在重新连接」是已经打开后与服务端的连接问题,处理方法见 Codex reconnecting 强制 HTTP 修复教程。
**小结:**这条报错的重点只有一个,让客户端找到一个真实存在、能运行的 codex.exe。先「修复」,再定位文件、设用户变量,最后完全退出重开;设了还不行,就按排查清单逐项检查进程、路径、权限和公司策略。
延伸阅读:
- Codex Windows 发布!Codex Windows 最新使用教程 — 客户端修好后,继续了解 Windows 版沙盒、终端兼容和完整开发流程
- Codex App 上手指南:从安装到使用 Skills 教程 — 从安装到 Skills、Automations 的入门路线
- Codex App 配置怎么设置?8 个实用选项与使用优化教程 — 客户端能打开后,把权限、记忆等常用设置调顺手