在Windows上安装Codex CLI的新手指南
在Windows平台上首次部署Codex CLI，需从本地开发环境入手。本文将系统讲解安装流程，帮助用户顺利完成配置。
引言
初次接触Codex CLI并希望在Windows环境下完成安装的用户，需重点掌握安装流程、环境变量核查及常见问题解决方法。本文将为这类用户提供清晰的指引。
本文内容专注于本地开发环境的配置，不包含外部服务接入、付费功能或推广信息。
适用环境
- 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你的用户名AppDataRoamingnpm
检查Path中是否包含npm目录：
$env:Path -split ';' | Select-String 'npm'
若能显示npm全局目录，说明Path配置基本正常。
若无输出，可手动添加用户环境变量：
Windows 设置 系统 关于 高级系统设置 环境变量 用户变量 Path 编辑 新建
添加以下目录：
C:Users你的用户名AppDataRoamingnpm
保存后，关闭所有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版本。
安装完成后重新打开PowerShell，再次验证：
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
若where.exe codex无返回结果，通常意味着npm全局目录未加入Path。
将以下目录加入用户Path：
C:Users你的用户名AppDataRoamingnpm
随后关闭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