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 安装，所以安装顺序是：

objectivec 复制代码

安装 Node.js
检查 node 命令
检查 npm 命令
安装 Codex CLI
检查 codex 命令
登录或按终端提示完成认证
运行一次基础检查

新手遇到最多的问题通常不是 Codex 本身，而是：

Node.js 没有安装成功
npm 全局目录没有加入 Path
终端没有重新打开，环境变量未刷新
网络环境导致 npm 包下载失败
codex 命令安装了但系统找不到

下面按步骤处理。

一、安装 Node.js

打开 Node.js 官网：

arduino 复制代码

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 全局目录：

arduino 复制代码

npm config get prefix

常见输出：

makefile 复制代码

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

检查 Path 中是否包含 npm 目录：

shell 复制代码

$env:Path -split ';' | Select-String 'npm'

如果能看到 npm 全局目录，说明 Path 基本正常。

如果没有输出，可以手动添加用户环境变量：

复制代码

Windows 设置
系统
关于
高级系统设置
环境变量
用户变量
Path
编辑
新建

添加下面目录：

makefile 复制代码

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

保存后，关闭所有 PowerShell 窗口，再重新打开。

四、配置 npm 镜像

如果你执行 npm 安装时速度很慢，或者经常下载失败，可以先查看当前 npm 源：

arduino 复制代码

npm config get registry

默认通常是：

arduino 复制代码

https://registry.npmjs.org/

如果访问官方源不稳定，可以切换到镜像源：

arduino 复制代码

npm config set registry https://registry.npmmirror.com

再确认一次：

arduino 复制代码

npm config get registry

如果后续需要切回官方源：

arduino 复制代码

npm config set registry https://registry.npmjs.org/

这一步不是必须的。如果你的网络可以正常访问 npm 官方源，可以保持默认配置。

五、安装 Codex CLI

执行全局安装命令：

bash 复制代码

npm install -g @openai/codex

安装完成后，检查版本：

css 复制代码

codex --version

正常情况下会输出 Codex CLI 的版本号。

继续查看帮助：

bash 复制代码

codex --help

如果能看到命令帮助，说明 Codex CLI 已经安装成功。

六、首次运行

执行：

复制代码

codex

如果终端提示登录或认证，按提示操作即可。

也可以显式执行登录命令：

复制代码

codex login

登录完成后，再次运行：

复制代码

codex

如果能进入交互界面，说明基础安装流程已经完成。

七、运行本地诊断

Codex CLI 提供了诊断命令，可以用来检查本地安装、配置和认证状态：

复制代码

codex doctor

如果后续使用中遇到异常，可以优先运行这个命令，看终端给出的提示。

八、常用命令速查

查看版本：

css 复制代码

codex --version

查看帮助：

bash 复制代码

codex --help

启动交互模式：

复制代码

codex

复制代码

codex login

退出登录：

bash 复制代码

codex logout

检查本地环境：

复制代码

codex doctor

更新 Codex CLI：

sql 复制代码

codex update

在指定目录启动：

arduino 复制代码

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 源：

arduino 复制代码

npm config get registry

如果下载失败，可以切换镜像源：

arduino 复制代码

npm config set registry https://registry.npmmirror.com

清理缓存后重试：

css 复制代码

npm cache clean --force
npm install -g @openai/codex

如果公司网络、校园网或代理环境有限制，需要根据自己的网络环境处理。

4. codex 命令找不到

现象：

复制代码

无法将"codex"项识别为 cmdlet、函数、脚本文件或可运行程序的名称

先检查 Codex 是否安装到了 npm 全局目录：

swift 复制代码

npm config get prefix
where.exe codex

如果 where.exe codex 没有结果，通常是 npm 全局目录没有加入 Path。

把下面目录加入用户 Path：

makefile 复制代码

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

然后关闭 PowerShell，重新打开，再执行：

css 复制代码

codex --version

5. 安装后版本没有变化

先查看当前命令位置：

csharp 复制代码

where.exe codex

如果系统里存在多个 codex 命令，可能会优先执行旧路径下的版本。

可以尝试重新安装：

bash 复制代码

npm install -g @openai/codex

也可以执行更新命令：

sql 复制代码

codex update

6. PowerShell 重启后配置才生效

这是 Windows 环境变量的常见行为。

如果刚刚安装 Node.js、修改 Path、安装全局命令，建议关闭所有 PowerShell 窗口，再重新打开。

不要在旧窗口里反复测试，否则可能一直读到旧环境变量。

十、建议的新手检查清单

安装完成后，按顺序执行：

lua 复制代码

node -v
npm -v
npm config get prefix
codex --version
codex --help
codex doctor

如果这些命令都能正常执行，说明 Codex CLI 的本地安装已经基本完成。

十一、写在最后

新手安装 Codex CLI 时，不建议一上来就修改复杂配置。先把最基础的链路跑通：

objectivec 复制代码

Node.js 可用
npm 可用
Codex CLI 可用
可以正常登录或通过终端提示完成认证

基础环境稳定后，再根据自己的开发习惯配置工作目录、模型参数或其他高级选项。

遇到问题时，优先运行：

复制代码

codex doctor

再根据提示处理，比反复卸载重装更有效。