Codex CLI Windows 新手安装教程：从 Node.js 到首次运行
这篇教程是写给那些第一次在 Windows 上折腾 Codex CLI 的朋友看的。目标很简单：把从零开始的安装流程、环境变量怎么检查、以及那些常见的“坑”都掰扯清楚。
注意，这里只聊本地开发环境的配置，不涉及任何外部接入、付费服务或者别的什么。
适用环境
- Windows 10 或 Windows 11
- PowerShell 或 Windows Terminal
- Node.js LTS
- npm
如果你电脑上已经有 Node.js 了，也别跳过，最好还是跟着下面的检查命令走一遍，确认环境没问题。
安装前需要知道什么
简单来说，Codex CLI 就是个命令行工具，得靠 Node.js 和 npm 才能活。所以，安装顺序基本是固定的：先装 Node.js，检查 node 和 npm 命令是否正常，接着安装 Codex CLI，再检查 codex 命令，最后登录或按提示认证，跑一个基础检查。
新手碰到的麻烦，十有八九不是 Codex 本身的问题，而是这几个地方没搞对：
- Node.js 没装成功
- npm 全局目录没加到系统 Path 里
- 装完之后忘了重启终端，环境变量没刷新
- 网络问题导致 npm 包下不下来
- 明明装了
codex，但系统就是找不到它
照着下面的步骤一步步来就好。
一、安装 Node.js
先打开 Node.js 官网：https://nodejs.org/
下载 LTS 版本的安装包就行。安装的时候，保持默认选项通常没问题。装完之后，关键一步：关掉当前的 PowerShell 或 Windows Terminal，然后重新打开一个新窗口。
为什么非得这样？因为 Windows 的环境变量，通常只在新开的终端窗口里才会生效。
二、检查 Node.js 和 npm
在 PowerShell 里敲下：node -v
如果安装成功，你会看到类似 v20.x.x 这样的输出。接着检查 npm：npm -v，正常会输出 10.x.x。
只要这两条命令都能返回版本号，就说明 Node.js 和 npm 的基础环境已经就绪了。
如果提示“无法识别 node 或 npm”，那八成是 Node.js 没装好，或者装完没重启终端。先试试重启 PowerShell；如果还不行，就重新安装一遍 Node.js LTS。
三、检查 npm 全局安装目录
Codex CLI 是通过 npm 全局安装的。这样一来，Windows 必须能在系统 Path 里找到它的命令才行。
用这个命令查看 npm 全局目录：npm config get prefix
常见的输出大概是这样的：C:\Users\你的用户名\AppData\Roaming\npm
接下来检查 Path 里有没有这个目录：$env:Path -split ';' | Select-String 'npm'
如果能看到 npm 全局目录，说明 Path 基本没问题。如果没有输出，就得手动添加一下用户环境变量：去 Windows 设置 -> 系统 -> 关于 -> 高级系统设置 -> 环境变量 -> 用户变量 -> Path -> 编辑 -> 新建，然后把上面那个目录加进去。保存后，关掉所有 PowerShell 窗口，再重新打开。
四、配置 npm 镜像
如果你在用 npm 安装东西时感觉慢得像蜗牛，或者经常下载失败，可以看看当前 npm 源是什么：npm config get registry
默认通常是 https://registry.npmjs.org/。如果官方源不稳定，可以切换到镜像源：npm config set registry https://registry.npmmirror.com
再确认一下：npm config get registry
以后想切回官方源也很简单：npm config set registry https://registry.npmjs.org/
当然，这一步不是必须的。如果你的网络能正常访问 npm 官方源，保持默认就行。
五、安装 Codex CLI
执行全局安装命令：npm install -g @openai/codex
装完之后，检查版本：codex --version
正常情况下会输出 Codex CLI 的版本号。再看看帮助信息：codex --help
如果能显示命令帮助，恭喜，Codex CLI 已经安装成功了。
六、首次运行
直接敲 codex 试试。如果终端提示要登录或认证，按提示操作就行。也可以显式执行登录命令：codex login
登录完成后，再次运行 codex。如果能顺利进入交互界面，就说明基础安装流程已经走通了。
七、运行本地诊断
Codex CLI 自带一个诊断命令，可以用来检查本地安装、配置和认证状态：codex doctor
以后要是遇到什么异常，先跑这个命令看看终端给出的提示，往往比自己瞎折腾管用。
八、常用命令速查
看版本：codex --version
看帮助：codex --help
启动交互模式：codex
登录：codex login
退出登录：codex logout
检查本地环境：codex doctor
更新 Codex CLI：codex update
在指定目录启动：codex -C "D:\your-project"
九、常见问题
1. node 命令找不到
现象是系统提示“无法将‘node’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。处理方法：先关掉并重新打开 PowerShell，再试 node -v。如果还不行，重新安装 Node.js LTS，并检查 Node.js 安装目录有没有加到 Path 里。
2. npm 命令找不到
Node.js 正常安装时会自带 npm。如果 node -v 正常，但 npm -v 报错，建议直接重新安装 Node.js LTS。装完后再开新终端检查：node -v 和 npm -v。
3. npm install -g 下载失败
先检查 npm 源：npm config get registry。如果下载失败，可以试试切换镜像源：npm config set registry https://registry.npmmirror.com。然后清理缓存重试：npm cache clean --force，再 npm install -g @openai/codex。
如果是在公司网络、校园网或开了袋里的环境下，那得根据自己的网络情况来处理。
4. codex 命令找不到
现象是提示“无法将‘codex’项识别为 cmdlet...”。先检查 Codex 有没有装到 npm 全局目录：npm config get prefix，然后用 where.exe codex 找一下。如果找不到，那多半是 npm 全局目录没加到 Path。把 C:\Users\你的用户名\AppData\Roaming\npm 这个目录加到用户 Path 里，关掉 PowerShell 再重开，然后试试 codex --version。
5. 安装后版本没有变化
先看看命令从哪里来的：where.exe codex。如果系统里有多个 codex 命令，可能会优先执行旧路径下的版本。可以重新安装：npm install -g @openai/codex，或者直接执行更新命令：codex update。
6. PowerShell 重启后配置才生效
这是 Windows 环境变量的一个“特性”。如果刚刚安装了 Node.js、修改了 Path 或者安装了全局命令，最好的做法是关掉所有 PowerShell 窗口，再重新打开。别在旧窗口里反复试，不然可能一直读到旧的缓存环境变量。
十、建议的新手检查清单
安装完成之后，建议按顺序走一遍下面这几条命令：
node -v
npm -v
npm config get prefix
codex --version
codex --help
codex doctor
如果这些都能正常执行，那 Codex CLI 的本地安装就基本算大功告成了。
十一、写在最后
对新手来说，安装 Codex CLI 时最忌讳的就是一上来就想着改什么复杂配置。先得把最基础的链路跑通：确保 Node.js 能用，npm 能用，Codex CLI 本身能运行，并且能正常登录或完成认证。
等基础环境稳定了，再根据自己的习惯去配置工作目录、模型参数或者其他高级选项。遇到问题时，优先跑 codex doctor，根据它的提示来处理，往往比反复卸载重装有效得多。
