油葫芦阅金经几个月前，我把Windows主力机重新收拾干净，打算把Codex真正用起来。原以为这就是一个“装个包”的简单活，结果一晚上全耗在“unable to locate the codex cli binary”这条报错上。后来我把环境、路径、执行策略、模型配置这些前置条件完整梳理了一遍，才发现Windows下装Codex的难点并不在Codex本身，而在Windows那一堆环境细节。这篇文章就从我的实际经历出发，把从零开始安装Codex CLI、完成登录、排查Cli binary报错，以及把Codex接到DeepSeek这类第三方模型服务的完整路径都写出来，给准备在Windows上装Codex、又不想到处翻答案的人一个可参照的流程。
Codex是OpenAI推出的编程代理工具，能用自然语言指挥它读代码、改文件、执行命令、跑测试。它在Windows下的形态不止一个：命令行、桌面应用、IDE插件都有。本文以命令行版为主线来讲，因为不管你想用桌面版还是编辑器插件，底层基本都要依赖同一套CLI，先把CLI跑通，后面所有事情都会顺很多。
1. 装之前先搞明白：Codex在Windows上有哪几种形态
1.1 命令行版、桌面版与IDE插件的分工
Codex在Windows上不是一个单一入口，围绕它至少有三层形态，很多人第一次接触时容易混在一起。
| 形态 | 安装方式 | 典型使用场景 | 特点 |
|---|---|---|---|
| 命令行版（Codex CLI） | npm全局安装 | PowerShell、CMD、Windows Terminal里直接跑 | 最适合脚本化、最容易被GUI调用 |
| 桌面应用 | OpenAI官网客户端 | 图形界面里对话式操作本地代码 | 上手快，但排错不如CLI直观 |
| IDE插件 | VS Code等编辑器扩展市场 | 编辑器内直接呼出Codex | 看diff方便，适合日常编码流 |
三者并不互斥，不少人会同时装。但有一个容易被忽略的事实：桌面应用和IDE插件在Windows上操作本地代码时，经常被设计成调用你本机已经装好的Codex CLI，而不是自己内置一套运行时。这就是后面那个“unable to locate the codex cli binary”报错的来源——图形界面找到了，底层CLI却没找到。
1.2 为什么我建议你先装CLI
我的个人建议是：哪怕你主要想用桌面版，也先安装CLI。原因有三个。
第一，CLI是底座。桌面版和IDE插件在Windows上的很多问题，归根结底都是它们找不到CLI。CLI装好、环境变量配好，GUI层面的报错能消掉一大半。
第二，CLI最好排查。命令行里能直接看到完整日志，遇到问题能一步步试错。图形界面报错往往只有一个弹窗，你连日志都看不到。
第三，CLI最适合自动化。团队要统一装环境的时候，一条npm命令就能装完，README里写一行命令比写一堆“去官网下载再点下一步”要省心太多。
所以下面的内容先围绕CLI铺开，把Windows环境准备、安装、登录、配置、排错都过一遍，桌面版和IDE插件的配合方式放到后面章节一并讲。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Windows环境准备：三个容易忽略的细节
2.1 Node.js版本：Codex CLI的运行时基座
Codex CLI目前通过npm分发，所以Node.js是硬前提。建议安装Node.js 18 LTS或更高版本，我自己用的是20 LTS，稳定性挑不出毛病。如果你机器上已经装过Node，可以用node -v先确认版本，太旧的版本建议升级，否则安装依赖时容易出各种莫名其妙的报错。
装完Node之后，我建议顺手确认一下npm源。如果你使用的是国内镜像源，版本同步有时候会有延迟，可能导致装到旧版本，或者在拉取某些依赖时出现缺失。遇到这类情况，切回官方源再执行安装通常就能解决。具体怎么切换，不同镜像源的文档里写得很清楚，按自己网络环境选择就行，这里不展开。
2.2 Git：不是必须，但强烈建议
Codex处理代码任务时会频繁用到git，比如生成改动补丁、对比当前工作区、恢复被修改的文件。Windows上如果不装Git，Codex在涉及仓库操作的任务里会缺胳膊少腿。
装Git的时候有一个细节很多人会忽略：安装向导里有一个“调整PATH环境变量”的选项，一定要选成“Git from the command line and also from 3rd-party software”。如果选了默认的“仅从Git Bash中使用”，那PowerShell里依然找不到git命令，Codex也就调不到git能力。装完之后可以在终端里跑一下git --version确认一下。
2.3 PowerShell执行策略：为啥你执行codex会报“禁止运行脚本”
Windows默认的PowerShell执行策略是Restricted，这会禁止运行.ps1脚本。而npm在Windows上安装的不少全局包都会附带PowerShell启动脚本，Codex CLI的启动脚本也可能以.ps1或.cmd的形式存在。
如果你执行codex相关命令时遇到“无法加载文件...因为在此系统上禁止运行脚本”这类提示，大概率就是执行策略拦住了。解决方式是给当前用户放开受限模式：
powershell复制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
执行完可以用Get-ExecutionPolicy确认输出是RemoteSigned，然后重新打开终端再试。这一步不需要管理员权限，只影响当前用户，安全风险可控。
3. 手把手安装：npm方式装Codex CLI并完成登录
3.1 全局安装命令与版本验证
打开PowerShell或Windows Terminal，直接执行：
powershell复制npm install -g @openai/codex
安装过程会拉取依赖，网络正常情况下一两分钟内就能完成。如果卡住不动，优先检查网络和npm源配置，并不是Codex本身的问题。
装完以后验证一下：
powershell复制codex --version
能输出版本号，说明CLI已经进入PATH。如果提示“无法识别codex”，先不要慌，十有八九是npm全局目录不在系统PATH里。这个问题的排查我会放在第4节详细讲，因为它是全网最常见的报错入口。
3.2 登录认证的两种方式
Codex CLI在使用之前必须完成认证，目前常见方式有两种。
第一种是ChatGPT账号登录。执行：
powershell复制codex login
按提示在浏览器里完成授权，CLI会把凭证保存到本地。这种方式最推荐，因为日常使用时的体验最接近官方设计，账号体系下的额度、对话上下文管理都更完整。
第二种是API Key方式。如果你有OpenAI API Key，可以设置环境变量：
powershell复制setx OPENAI_API_KEY "sk-你的key"
注意setx设置完不会立刻在当前终端生效，需要新开一个窗口才能读到。而且用API Key方式时，一般还要在配置文件里指定对应的模型提供方，这一点到第5节会详细说。
两种方式可以共存，按需选择。
3.3 用一个小任务验证安装
装好、登录完，跑一个最简单的任务来验证整条链路：
powershell复制codex "用Python写一个读取文件前10行的脚本，保存到demo.py"
正常情况下，Codex会先读取当前目录下的文件结构，然后生成对应代码，经过你确认后写入文件。看到这个过程走完，说明从安装到认证的整条链路已经通了。
首次运行可能会提示选择模型、确认使用条款之类的内容，按提示操作就行。如果你不太确定当前使用的模型，等会儿第5节会教你如何检查和切换。
4. 最常踩的坑：codex cli binary定位失败的完整排查
4.1 这个报错到底在表达什么
“unable to locate the codex cli binary. set codex cli path or ensure the executable is installed and available in your system path.”这条报错的热度极高，大多数出现在ChatGPT桌面应用或者某些IDE插件里。
它表达的意思很直白：图形界面程序准备调用Codex，但是系统PATH里找不到对应的可执行文件。这里有一个容易误导人的地方——你在终端里敲codex能正常运行，不代表GUI程序也能找到同一个命令。因为图形界面进程与终端进程的环境变量可能不一样，尤其是通过桌面快捷方式启动的应用，往往继承的是系统级环境变量，而不是你终端里刚改过的用户环境变量。
4.2 排查链路：从PATH到GUI设置
这一节是全文最值得反复看的部分。我按实际排查顺序写，你照着走就能定位问题。
第一步，确认CLI是否真的装了。在终端里执行：
powershell复制codex --version
如果连这条都不识别，说明安装或PATH有问题，先把CLI装好再往下走。
第二步，找到codex可执行文件的具体位置。执行：
powershell复制where.exe codex
正常会输出一个完整路径。Windows上npm全局包的典型位置是C:\Users\<你的用户名>\AppData\Roaming\npm\codex.exe或者codex.cmd。如果你看到的是Git Bash里的路径，说明你可能是通过其他环境安装的，也先记下来。
第三步，确认npm全局目录在PATH里。执行：
powershell复制npm prefix -g
如果输出的路径和上一步where.exe codex结果的目录一致，说明安装位置没问题；如果不一致，或者这个路径根本不在系统PATH里，那就需要手动加进去。
在PowerShell里可以用下面这行命令把npm全局目录追加到当前用户的PATH：
powershell复制$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", $currentPath + ";C:\Users\<你的用户名>\AppData\Roaming\npm", "User")
加完以后重启终端，再跑codex --version验证一遍。
第四步，如果你用的是ChatGPT桌面应用，还需要进应用的设置界面，找到与Codex CLI路径相关的选项，把路径手动指向刚才查到的codex.cmd或codex.exe。这个设置项在不同版本里位置略有差异，但关键词通常是“Codex CLI Path”。设置完成后，必须完全退出应用再重新打开，让进程重新读取环境变量。
我特意提一下“完全退出”这四个字，因为不少用户卡在“明明改对了为什么不生效”，其实就是没重启应用，进程还拿着旧的环境变量。养成改完环境变量就重启进程的习惯，能省掉很多无谓的时间。
4.3 验证修复成功的三个命令
修复之后，我用三个命令来确认：
codex --version：确认CLI本身可用where.exe codex：确认系统能定位到可执行文件- 重新打开GUI应用里的Codex面板：确认报错消失
这三个都通过，就说明CLI binary定位的问题已经解决。如果你是在IDE插件里遇到报错，同样检查该插件对Codex CLI路径的配置项，思路完全一致。
5. 进阶玩法：把Codex CLI接到DeepSeek等模型服务
5.1 Codex的模型提供方机制
Codex默认使用OpenAI自家的模型，但它的配置体系支持通过模型提供方（model provider）机制接入其他服务。这类用法对不少国内用户来说很实际，比如把推理成本更低的DeepSeek模型接到Codex里，用自己的API Key按量计费，用在日常的轻量开发任务上。
Codex的核心配置文件在用户主目录下的~/.codex/config.toml。如果你在某个项目里放了.codex/config.toml，那这个项目配置会覆盖全局配置。理解这一点很重要，因为很多时候你改了全局配置不生效，原因就是当前目录下有一个项目级配置在“抢权”。
5.2 配置DeepSeek provider的完整示例
以接入DeepSeek为例，在~/.codex/config.toml里加入下面的内容：
toml复制model = "deepseek/deepseek-chat"
model_provider = "deepseek"
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"
wire_api = "chat"
保存之后，设置环境变量：
powershell复制setx DEEPSEEK_API_KEY "你的DeepSeek API Key"
然后重开终端，执行codex命令。
这里有几个细节值得注意。
第一，base_url到底要不要拼/v1等路径后缀，取决于模型服务商的实际接口设计。有的服务需要，有的不需要，以服务商文档为准，不是写错了就一定报错，而是会出现请求路径404这类问题，到时候排查起来很绕。
第二，env_key指的是你本机环境变量的名字，不是API Key本身。Codex启动时会读取这个环境变量，对应关系要配对。
第三，wire_api字段用于指定底层协议风格，是走chat completions风格还是responses风格。如果配错，Codex可能会直接报模型不支持，或者请求成功但解析不了返回内容。
配置完以后，可以用codex --help查看当前生效的模型和提供方，确认配置真正被读取到了。
5.3 常见的配置报错与规避办法
接入第三方模型后，最常见的报错是“model not supported”，或者类似“the 'gpt-5.6-sol' model is not supported when using codex with...”这类提示。遇到这种情况，优先检查两处：model字段写的模型名是否真的存在于当前provider支持列表里；wire_api是否与该服务商的实际接口风格一致。
排查方式很简单：先把model字段注释掉，让Codex走默认模型，如果命令能正常跑起来，说明问题出在模型名或provider配置上；然后把模型名逐个换回试试，就能缩小范围。
另外要有一点心理准备：接入第三方模型后，Codex的某些功能可能依赖OpenAI特有接口，如果第三方模型的兼容性不够，会出现功能降级。比如某些工具调用协议、特殊格式的响应不支持等。这不是Bug，是接口能力差异，用之前心里有数就行，别到时候以为是自己环境又配错了。
6. 日常使用建议与升级维护
6.1 中文乱码问题：一个让Windows用户难受的小坑
Windows终端默认代码页可能不是UTF-8，Codex输出中文的时候偶尔会变乱码。这个问题在中文Windows系统上尤其常见，因为默认代码页是GBK。
最简单的临时解决办法是在会话里执行：
powershell复制chcp 65001
把代码页切到UTF-8。更一劳永逸的做法是换用Windows Terminal，并在设置里把默认配置文件的语言区域调成UTF-8。另外，如果你让Codex读写中文文件，记得确认文件本身是UTF-8编码，否则保存出来的文件在别的工具里看就是乱码。
这个坑不大，但第一次碰到时很容易误判成Codex安装有问题。
6.2 和VS Code、Windows Terminal配合
我目前比较顺手的用法是：Windows Terminal里单独开一个PowerShell标签页，专门跑Codex。VS Code的内置终端也能跑，但要注意启动目录。Codex一般会把当前工作目录当成项目根目录，所以一定要在项目根目录里启动，别图省事在C盘根目录或桌面直接跑。不然它可能试图对你的整个文件系统指手画脚，那个场面会很难控制。
如果你平时在VS Code里写代码，建议给Codex一个独立终端，不要和项目运行日志混在同一个终端里，免得输出信息互相干扰。还有一个小技巧：Codex在修改代码前会有确认和diff预览，建议不要直接回车放行，先扫一眼改动，养成这个习惯能避免很多误操作。
6.3 升级与卸载的正确姿势
Codex迭代速度很快，建议定期升级。升级命令很简单：
powershell复制npm update -g @openai/codex
有时候更新后出现配置文件字段不兼容的情况，尤其是第5节提到的config.toml里的provider配置，旧版本字段可能在新版本里已经改名。遇到这种情况，查一下当前版本的官方配置说明，按新字段调整即可。
如果想彻底卸载：
powershell复制npm uninstall -g @openai/codex
这个命令只会移除CLI程序本身，不会动~/.codex配置目录。如果你想连配置一起清掉，可以手动删除这个目录。另外，API Key这类敏感信息如果已经不需要了，记得从环境变量里一并移除，不要留着在系统里吃灰。
最后说点我在实际使用中的体会。Windows上装Codex，遇到的大部分问题都不是Codex本身有多复杂，而是Windows的PATH机制、PowerShell执行策略、UTF-8编码这些老问题。我第一次碰到“unable to locate the codex cli binary”的时候，也以为是装错了包，后来才发现只是npm全局目录没进PATH。先把Windows这套环境细节弄明白，再谈工具本身，能省下大把时间。如果你后续想把Codex接到自己的自动化脚本里，记得先把CLI基础链路跑通，再考虑GUI和IDE插件，基础打牢了，后面怎么接都顺手。