ChatGPT / Codex 桌面版报“Unable to locate the Codex CLI binary”怎么办？Windows 原因与修复教程

如果 ChatGPT / Codex 桌面版提示 Unable to locate the Codex CLI binary，核心原因是桌面应用在启动 Codex Agent 时没有找到可以执行的 Codex CLI。

Windows 下可以优先按照下面的顺序排查：

使用 codex --version 确认 Codex CLI 本身能够运行；
使用 Get-Command codex 和 npm root -g 找到 Codex 的真实安装位置；
将 CODEX_CLI_PATH 指向真正的 codex.exe，不要误指向 codex.cmd 或 codex.ps1；
完全退出 ChatGPT / Codex 桌面应用后重新启动；
仍然失败时，可以检查 %LOCALAPPDATA%\OpenAI\Codex\bin\ 是否缺少 codex.exe；
如果开启过 WSL Agent Environment，应额外排查 WSL 模式，因为 2026 年 Windows 版已经出现多起 WSL 下无法定位 bundled CLI 的问题；
如果更新桌面版后突然出现该错误，也有可能是当前客户端版本 Bug，而不是你的 Codex CLI 安装错误。

最重要的一点是：

CODEX_CLI_PATH 应该指向真正可以直接执行的 Codex 二进制文件，而不是 npm 创建的 .cmd、.ps1 或其他启动包装脚本。

一、报错是什么？

在 Windows 版 ChatGPT / Codex 桌面应用中，有时会遇到：

Unable to locate the Codex CLI binary.
Set CODEX_CLI_PATH or ensure the Electron resources include bin/codex.

翻译一下就是：

无法找到 Codex CLI 二进制文件。请设置 CODEX_CLI_PATH，或者确保 Electron 应用资源目录中包含 bin/codex。

这个报错已经把排查方向说得比较清楚了。

Codex 桌面应用虽然提供图形界面，但底层部分本地 Agent 功能仍然需要能够启动 Codex CLI。

OpenAI 当前也把 Codex 作为一个可以同时运行在：

ChatGPT 桌面版；
Codex CLI；
IDE；
Web；

等环境中的 Coding Agent。

因此出现这个错误时，重点不是检查“ChatGPT 能不能聊天”，而是检查：

桌面客户端能不能找到并执行 Codex CLI。

二、为什么会出现 Unable to locate the Codex CLI binary？

实际排查下来，大致有下面几种情况。

原因	常见表现	处理方式
Codex CLI 根本没安装	`codex --version` 报错	安装 Codex CLI
CLI 已安装但桌面版找不到	PowerShell 能运行，桌面版报错	设置 `CODEX_CLI_PATH`
指到了 npm 包装脚本	路径是 `.cmd` / `.ps1`	改成真实 `codex.exe`
桌面版 bundled CLI 丢失	`bin` 目录为空	修复/重装或补充二进制
WindowsApps 权限异常	bundled `codex.exe` 存在但无法执行	修复客户端/检查权限
WSL Agent 模式异常	开启 WSL 后开始报错	检查 WSL CLI 和 Agent Environment
桌面版更新 Bug	更新前正常，更新后突然报错	更新/回退/等待官方修复

这里要特别说明：

现在不能看到这个错误就直接判断“你没有安装 Codex”。

截至 2026 年 8 月，OpenAI 官方 Codex GitHub 仓库已经出现多起 Windows 桌面版相关报告。

部分用户甚至能确认应用安装包中存在 codex.exe，但仍然因为 WindowsApps 权限、WSL、二进制搬移失败或桌面客户端路径解析问题触发同一个错误。

所以正确排查方式应该是：

CLI 是否正常 → 路径是否正确 → 桌面应用能否执行 → WSL/客户端版本是否存在异常。

三、第一步：确认 Codex CLI 有没有安装

打开 PowerShell：

codex --version

如果正常，一般会返回类似：

codex-cli x.x.x

具体版本号会随着 Codex 更新变化。

如果提示：

codex : The term 'codex' is not recognized...

说明当前环境还没有正确安装 Codex CLI，或者 npm 全局目录没有加入 PATH。

OpenAI 当前官方提供的 npm 安装方式是：

npm install -g @openai/codex

也可以写成：

npm i -g @openai/codex

安装完成后重新执行：

codex --version

只要能够正常显示版本号，说明 CLI 本身至少可以启动。

如果刚开始使用 Codex，也可以先看看本站整理的 Codex 能力说明：

Codex 能做什么、不能做什么？2026 能力边界、使用条件与结果验证指南

查看这篇 Codex 教程

四、第二步：找到 Codex 的真实路径

接下来执行：

Get-Command codex

但是这里有一个坑。

Get-Command codex 返回的路径不一定是真正的：

codex.exe

它有可能返回：

C:\Users\你的用户名\AppData\Roaming\npm\codex.ps1

或者：

C:\Users\你的用户名\AppData\Roaming\npm\codex.cmd

这是 npm 创建的命令包装器。

平时在 PowerShell 中输入：

codex

它们没有问题。

但是对于需要直接 spawn 二进制文件的 Electron / Node 桌面应用来说，.cmd、.ps1 与真正的 codex.exe 并不完全是一回事。

2026 年 8 月 26 日 OpenAI Codex 官方 GitHub 甚至还有 Windows 新版本报告：

桌面客户端更新后，在解析 .cmd wrapper 时出现 spawn EINVAL，同时伴随：

Unable to locate the Codex CLI binary

因此这里建议继续找真正的 codex.exe。

五、怎么找到真正的 codex.exe？

先执行：

npm root -g

一般会返回类似：

C:\Users\你的用户名\AppData\Roaming\npm\node_modules

然后执行：

$npmRoot = npm root -g
Get-ChildItem $npmRoot -Recurse -Filter codex.exe -ErrorAction SilentlyContinue |
    Select-Object -ExpandProperty FullName

如果正常，可能找到类似：

C:\Users\你的用户名\AppData\Roaming\npm\node_modules\@openai\codex-win32-x64\vendor\x86_64-pc-windows-msvc\bin\codex.exe

具体目录会随着：

Codex 版本；
npm 包结构；
CPU 架构；

发生变化。

不要照抄网上某个人的绝对路径。

以你自己电脑实际查询出来的结果为准。

六、第三步：验证真正的 codex.exe 能否执行

找到以后不要立刻配置。

先运行：

& "C:\你的真实路径\codex.exe" --version

例如：

& "C:\Users\example\AppData\Roaming\npm\node_modules\@openai\codex-win32-x64\vendor\x86_64-pc-windows-msvc\bin\codex.exe" --version

如果这里能够正常显示版本号，说明：

这个文件才是适合拿来配置 CODEX_CLI_PATH 的候选路径。

如果连这个文件都不能正常执行，那么问题还在 CLI 安装本身。

可以考虑先重新安装：

npm uninstall -g @openai/codex
npm install -g @openai/codex

然后重新验证。

七、方法一：设置 CODEX_CLI_PATH

找到真正的 codex.exe 后，可以设置用户级环境变量。

PowerShell：

[Environment]::SetEnvironmentVariable(
    'CODEX_CLI_PATH',
    'C:\完整路径\codex.exe',
    'User'
)

例如：

[Environment]::SetEnvironmentVariable(
    'CODEX_CLI_PATH',
    'C:\Users\example\AppData\Roaming\npm\node_modules\@openai\codex-win32-x64\vendor\x86_64-pc-windows-msvc\bin\codex.exe',
    'User'
)

注意环境变量名称应该写成：

CODEX_CLI_PATH

建议保持这个大小写形式，和报错信息一致。

八、怎么检查 CODEX_CLI_PATH 设置成功？

重新打开一个 PowerShell：

$env:CODEX_CLI_PATH

正常应该显示刚才配置的完整路径。

然后测试：

& $env:CODEX_CLI_PATH --version

如果能够正常输出 Codex CLI 版本，至少说明：

环境变量指向的是一个可以运行的二进制。

九、为什么设置完环境变量还是不生效？

这是 Windows 下非常常见的问题。

已经打开的 ChatGPT / Codex 桌面程序不会自动重新读取你刚设置的环境变量。

因此修改后不能只是：

关闭窗口 → 再点回来。

建议：

关闭 ChatGPT / Codex；
查看右下角系统托盘；
如果仍有 ChatGPT / Codex 进程，彻底退出；
必要时打开任务管理器确认相关进程已经结束；
再重新启动桌面应用。

如果仍然无法读取新环境变量，可以尝试：

注销 Windows 用户重新登录。

或者重启电脑后再次测试。

十、不要把 CODEX_CLI_PATH 指向 codex.cmd

这一点非常值得单独讲。

例如：

Get-Command codex

C:\Users\example\AppData\Roaming\npm\codex.cmd

不要直接写：

CODEX_CLI_PATH=C:\Users\example\AppData\Roaming\npm\codex.cmd

更稳妥的是找到实际：

codex.exe

然后指向它。

原因是 Electron / Node 在 Windows 环境直接启动 .cmd wrapper 时，和 PowerShell 运行命令的行为不完全相同。

这也是为什么可能出现：

PowerShell 中 codex --version 完全正常，但桌面版仍然报找不到 Codex CLI。

十一、方法二：检查 Codex 本地 bin 目录

如果 CODEX_CLI_PATH 没有解决，还可以检查：

%LOCALAPPDATA%\OpenAI\Codex\bin\

PowerShell：

Get-ChildItem "$env:LOCALAPPDATA\OpenAI\Codex\bin" -ErrorAction SilentlyContinue

部分 Windows 版本的 Codex 桌面应用会把可执行文件放到类似：

C:\Users\用户名\AppData\Local\OpenAI\Codex\bin\

官方 GitHub 的 Windows Bug 报告中也能看到桌面应用尝试将 bundled Codex CLI 放到：

%LOCALAPPDATA%\OpenAI\Codex\bin\codex.exe

如果目录存在，但是里面完全没有：

codex.exe

那就比较符合这个报错的特征。

十二、可以手动复制 codex.exe 吗？

可以作为故障排查或临时 workaround，但不建议把它理解成 OpenAI 官方标准安装步骤。

例如你已经确认：

C:\xxx\codex.exe

可以正常运行。

那么可以：

New-Item -ItemType Directory `
    -Path "$env:LOCALAPPDATA\OpenAI\Codex\bin" `
    -Force

然后：

Copy-Item `
    -Path "C:\完整路径\codex.exe" `
    -Destination "$env:LOCALAPPDATA\OpenAI\Codex\bin\codex.exe" `
    -Force

完成后检查：

& "$env:LOCALAPPDATA\OpenAI\Codex\bin\codex.exe" --version

确认正常后彻底退出桌面应用，再重新打开。

十三、为什么我更推荐 CODEX_CLI_PATH 优先？

手动复制有一个明显问题：

副本不会自动跟随 npm 全局 Codex CLI 更新。

例如：

原来的 npm Codex：

0.1xx.x

后来执行：

npm install -g @openai/codex@latest

npm 目录中的 Codex 已经更新。

但：

%LOCALAPPDATA%\OpenAI\Codex\bin\codex.exe

里面手动复制的旧文件可能还是旧版本。

所以如果采用复制方案，每次升级 Codex CLI 后最好重新同步一次。

而 CODEX_CLI_PATH 如果指向当前 npm 包里的实际二进制，在路径不发生变化的情况下维护成本更低。

不过 npm 升级后包结构本身也可能变化，因此升级后如果再次出现错误，第一件事仍然应该重新确认：

$env:CODEX_CLI_PATH

指向的文件还存不存在。

十四、如果开启了 WSL，这个问题要单独排查

如果你之前在 ChatGPT / Codex 桌面版设置中过：

Agent Environment → WSL

然后重启应用以后出现：

Unable to locate the Codex CLI binary

那么问题不一定是 Windows 原生 Codex CLI。

2026 年 OpenAI Codex 官方 GitHub 已经出现多起类似报告：

Windows 原生模式正常，但切换 WSL Agent Environment 后，Codex Desktop 无法正确找到或搬移 Linux Codex CLI。

这种情况下需要分别检查：

Windows PowerShell

codex --version

以及 WSL：

wsl

进入 Linux 后：

which codex

然后：

codex --version

如果 Windows 能运行，但 WSL 中：

command not found

就说明两套环境并不一致。

十五、WSL 模式不要直接拿 Windows codex.exe 硬套

这也是容易踩坑的地方。

例如：

Windows 中：

C:\xxx\codex.exe

可以正常执行。

但 WSL 运行环境真正期望的可能是 Linux 版本：

codex

两边的二进制平台并不一样。

如果桌面客户端处于 WSL Agent Environment，却把：

CODEX_CLI_PATH

强制指向 Windows codex.exe，某些版本反而可能出现新的：

Permission denied

或：

spawn

错误。

OpenAI 官方 Codex GitHub 在 2026 年已经有专门针对 Windows + WSL + CODEX_CLI_PATH 的相关 Bug 报告。

因此如果问题明确发生在：

开启 WSL 以后才出现

优先判断它是不是 WSL 集成问题，不要一味复制 Windows 二进制。

十六、如果应用安装目录本来就有 codex.exe 呢？

还有一种更麻烦的情况。

有些 Windows 用户检查：

C:\Program Files\WindowsApps\OpenAI.Codex_...\app\resources\

发现里面实际上已经存在：

codex.exe

但桌面应用仍然提示：

Unable to locate the Codex CLI binary

这种情况就已经不能简单归类为：

Codex CLI 没安装。

OpenAI 官方 GitHub 中已有 Windows 用户报告：

bundled codex.exe 明明存在；
但是受到 WindowsApps 权限影响；
直接执行出现 Access denied；
客户端仍然无法完成 CLI 初始化。

这种情况下更应该尝试：

更新 ChatGPT / Codex 桌面应用；
Windows 设置中修复应用；
重置应用；
重新安装官方桌面客户端；
暂时关闭 WSL Agent Environment 进行对比；
查看 OpenAI Codex GitHub 是否存在当前版本已知 Bug。

不建议随意修改：

C:\Program Files\WindowsApps

目录权限。

这个目录由 Windows 管理，强行夺取权限可能引发更多应用更新问题。

十七、如果是更新 ChatGPT / Codex 后突然出现怎么办？

这点非常重要。

如果你的情况是：

昨天一切正常
↓
今天桌面应用自动更新
↓
突然开始报 Unable to locate the Codex CLI binary

不要第一时间怀疑自己把 Node.js 或 npm 配坏了。

截至 2026 年 8 月 26 日，OpenAI Codex 官方 GitHub 仍有新的 Windows 桌面版相关 Bug 报告。

其中有用户在更新桌面应用版本后同时遇到：

Unable to locate the Codex CLI binary

以及 Windows .cmd wrapper 的：

spawn EINVAL

问题。

这种情况应该先确认：

codex --version

以及：

& $env:CODEX_CLI_PATH --version

如果两个都正常，而桌面版仍然无法启动 Codex：

问题就很可能已经从“CLI 安装问题”转变成“桌面客户端路径解析或版本问题”。

十八、一套比较稳妥的 Windows 排查流程

如果以后再次碰到这个错误，可以直接按照下面顺序执行。

1. 检查 Codex

codex --version

失败：

→ 重新安装 Codex CLI。

成功：

→ 继续。

2. 看当前命令路径

Get-Command codex

如果返回 .cmd 或 .ps1：

→ 继续寻找真实 codex.exe。

3. 搜索真实 exe

$npmRoot = npm root -g

Get-ChildItem $npmRoot -Recurse -Filter codex.exe -ErrorAction SilentlyContinue |
    Select-Object -ExpandProperty FullName

4. 直接验证 exe

& "完整路径\codex.exe" --version

5. 设置环境变量

[Environment]::SetEnvironmentVariable(
    'CODEX_CLI_PATH',
    '完整路径\codex.exe',
    'User'
)

6. 完全退出桌面应用

不是关闭窗口。

而是完全结束进程后重新启动。

7. 检查本地 bin

Get-ChildItem "$env:LOCALAPPDATA\OpenAI\Codex\bin"

8. 检查 WSL

如果使用 WSL：

wsl

然后：

which codex
codex --version

9. 判断是否是客户端版本问题

如果：

CLI 正常；
codex.exe 正常；
CODEX_CLI_PATH 正常；
只有桌面版失败；

就应该进一步检查当前 ChatGPT / Codex Desktop 版本，而不是反复重装 npm。

十九、修复以后怎么验证？

至少做三层验证。

第一层：普通命令

codex --version

正常。

第二层：实际二进制

& $env:CODEX_CLI_PATH --version

正常。

第三层：桌面版

重新打开 ChatGPT，进入：

Codex

选择一个本地项目，启动一个简单任务。

例如：

读取当前项目的 README，并概括项目结构，不要修改任何文件。

如果 Agent 能正常读取项目并开始工作，说明桌面版和 Codex CLI 之间的调用链已经基本恢复。

二十、几个常见坑

只看 `Get-Command codex` 就结束

不够。

因为它可能只给你：

codex.ps1

或者：

codex.cmd

最好继续找到真正的 codex.exe。

设置环境变量后不重启应用

不行。

旧进程不会自动继承新的用户环境变量。

为了解决问题乱改 WindowsApps 权限

不推荐。

如果问题出在 Microsoft Store 打包、EFS 或 WindowsApps 权限，优先修复客户端。

开着 WSL，却只检查 Windows CLI

容易误判。

Windows CLI 和 WSL CLI 属于两个运行环境。

npm 升级后继续使用旧副本

如果手动复制过：

%LOCALAPPDATA%\OpenAI\Codex\bin\codex.exe

升级后记得重新确认版本。

CLI 正常就认定一定是自己配置错了

也不对。

2026 年 Windows Codex Desktop 确实出现过多起 bundled CLI、WSL 和路径解析相关 Bug。

所以：

CLI 正常 + 桌面版失败

本身就是一个很重要的判断信号。

二十一、常见问题 FAQ

Unable to locate the Codex CLI binary 是什么意思？

意思是 ChatGPT / Codex 桌面应用无法找到或执行它需要的 Codex CLI 二进制文件。

可能是没有安装，也可能是路径、权限、WSL 或桌面客户端自身的问题。

Codex CLI 官方怎么安装？

OpenAI 当前提供的 npm 安装命令是：

npm install -g @openai/codex

安装完成后使用：

codex --version

验证。

CODEX_CLI_PATH 应该填什么？

应该填写真正 Codex CLI 可执行文件的完整路径。

Windows 下一般应该最终指向：

codex.exe

而不是优先指向：

codex.cmd

或：

codex.ps1

为什么 PowerShell 能运行 Codex，ChatGPT 桌面版却找不到？

因为 PowerShell 可以通过 npm 创建的 .ps1 或 .cmd 包装脚本找到 Codex。

而 Electron 桌面应用启动子进程时的路径解析方式可能不同。

此外还可能是：

bundled CLI 缺失；
WindowsApps 权限；
WSL；
桌面客户端 Bug。

`%LOCALAPPDATA%\OpenAI\Codex\bin` 为空正常吗？

具体目录结构会随着版本变化。

但如果当前桌面客户端明确尝试从本地 Codex bin 目录加载 CLI，而这个目录为空，就值得进一步检查。

OpenAI Codex 官方 GitHub 的 Windows Bug 报告中可以看到客户端使用类似目录保存本地 CLI。

可以直接复制 codex.exe 进去吗？

可以作为排查或临时解决办法。

但它不是首选的官方安装方式，而且以后升级 npm Codex 后，这个副本不会自动同步。

开启 WSL 后出现这个错误怎么办？

分别验证 Windows 和 WSL：

Windows：

codex --version

WSL：

which codex
codex --version

如果只在 WSL Agent Environment 出问题，还要考虑当前 Windows Codex Desktop 的 WSL 集成 Bug。

Codex 修好后怎么看剩余额度？

如果 CLI 本身已经恢复，但接下来碰到 Codex 使用量或 Credits 问题，可以继续查看：

2026 年 Codex 额度用完怎么办？Credits 额外购买、自动充值与用量查询教程

Codex Credits 与额度查询教程

如果想了解不同套餐的 Codex 使用额度差异，可以查看：

2026 年 Codex 额度怎么算？Plus、Pro 5x、Pro 20x 限额与使用量完整对比

查看 Codex 套餐额度对比

总结

如果 ChatGPT / Codex 桌面版出现：

Unable to locate the Codex CLI binary.
Set CODEX_CLI_PATH or ensure the Electron resources include bin/codex.

最有效的判断思路不是直接重装所有软件，而是先确认“到底是哪一层找不到 Codex”。

依次检查：

codex --version
↓
npm 实际安装目录
↓
真正的 codex.exe
↓
CODEX_CLI_PATH
↓
%LOCALAPPDATA%\OpenAI\Codex\bin
↓
WSL Agent Environment
↓
ChatGPT / Codex Desktop 当前版本

如果：

codex --version

可以运行，而且真正的：

codex.exe

也可以直接运行，设置：

CODEX_CLI_PATH

以后仍然只有桌面应用报错，就不要一直重复安装 npm。

这时更应该考虑 Windows 桌面客户端本身、WSL 集成、WindowsApps 权限或当前版本 Bug。

这也是排查这个问题时最容易被忽略的一点。

参考资料

OpenAI — Codex
OpenAI 官方 Codex 产品页面，说明 Codex 可以在 ChatGPT、IDE 和终端中使用，并给出 Codex CLI 的 npm 安装方式。
OpenAI Help Center — Using Codex with your ChatGPT plan
OpenAI 官方 Codex 使用说明，涵盖 ChatGPT Desktop Codex mode、Codex CLI、IDE Extension 和 Web 等入口。
OpenAI Help Center — Moving to the new ChatGPT desktop app
OpenAI 官方说明显示，新版 ChatGPT Desktop 已整合 Chat、Work 与 Codex，并支持 Windows 和 macOS。
OpenAI / Codex GitHub — Unable to locate the Codex CLI binary
OpenAI 官方 Codex 仓库中的 Windows / WSL 问题记录，报错信息与本文完全一致，并涉及 CODEX_CLI_PATH、bundled CLI 和 WSL 环境。
OpenAI / Codex GitHub — Windows bundled codex.exe / WindowsApps permission issue
Windows 用户报告 bundled codex.exe 实际存在，但受到 WindowsApps 权限等问题影响，说明该错误并不一定代表 CLI 没有安装。
OpenAI / Codex GitHub — Windows Desktop v26.820.60940 CLI startup regression
2026 年 8 月 26 日提交的 Windows 桌面版问题报告，涉及更新后无法定位 Codex CLI 以及 .cmd wrapper 的 spawn EINVAL 问题。

资料核对时间：2026 年 8 月 26 日。

Codex CLI 和 ChatGPT / Codex Desktop 仍处于快速更新阶段，Windows、WSL、客户端目录结构以及 CLI 加载方式未来可能发生变化。出现同类问题时，应优先以当前客户端版本、OpenAI 官方文档及 OpenAI Codex 官方 GitHub 的最新状态为准。