新手在Windows上安装Codex CLI的教程

引言

本文面向第一次在 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你的用户名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、函数、脚本文件或可运行程序的名称

处理方式：

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 的本地安装已经基本完成。

十一、写在最后

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

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

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

遇到问题时，优先运行：

codex doctor

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