引言

如果你是第一次在 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 的输出，说明 node 已经可用了。继续检查 npm：

npm -v

正常会返回 10.x.x 这样的版本号。两个都能跑出版本，说明基础环境已经就绪。

如果提示无法识别 node 或 npm——大概率是安装后没重启终端，或者安装过程出了问题。先重启 PowerShell 试试，不行就重新装一次 Node.js LTS。

三、检查 npm 全局安装目录

Codex CLI 是通过 npm 全局安装的，而 Windows 需要在 Path 里找到对应的命令才能执行。想知道 npm 的全局目录在哪里？执行：

npm config get prefix

常见的输出长这样：

C:Users你的用户名AppDataRoamingnpm

接下来检查这个目录有没有被加到 Path 里：

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

如果能看见那个路径，说明配置正常；如果没有任何输出——那就需要手动添加了。

具体操作路径：Windows 设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → 用户变量 → Path → 编辑 → 新建，然后输入：

C:Users你的用户名AppDataRoamingnpm

保存后，关闭所有 PowerShell 窗口，再重新打开。这一步很重要，不要嫌麻烦。

四、配置 npm 镜像

有时候 npm 安装速度让人着急，或者直接下载失败——问题大多出在镜像源上。先看看当前用的是哪个源：

npm config get registry

默认通常是：

https://registry.npmjs.org/

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

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

再确认一次：

npm config get registry

想切回去也一样简单。注意，这一步不是必须的，如果你的网络访问官方源没问题，保持默认就好。

五、安装 Codex CLI

准备工作都到位了，接下来就是核心步骤。执行：

npm install -g @openai/codex

等安装完成后，检查版本：

codex --version

正常会输出版本号。再跑一下帮助命令：

codex --help

如果能看到帮助信息，说明 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、函数、脚本文件或可运行程序的名称”。

处理方式：

0. 关掉并重新打开 PowerShell。
1. 再次执行 node -v。
2. 如果还不行，重新安装 Node.js LTS。
3. 检查 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 的本地安装已经基本完成。

十一、写在最后

给新手一个建议：别急着上来就搞复杂配置。先把最基础的链路跑通——Node.js 可用，npm 可用，Codex CLI 可用，能正常登录。基础环境稳了，再根据开发习惯配置工作目录、模型参数这些高级选项。

遇到问题，优先跑 codex doctor，根据提示处理，比反复卸载重装实在得多。