Codex CLI Windows 安装使用教程：Node.js配置到首次运行

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，根据它的提示来处理，往往比反复卸载重装有效得多。