适用环境

• Windows 10 或 Windows 11
• PowerShell 或 Windows Terminal
• Node.js LTS
• npm

如果你已经安装过 Node.js，也建议先按本文的检查命令确认环境是否正常。

安装前需要知道什么

Codex CLI 是一个命令行工具。它依赖 Node.js 和 npm 安装，所以安装顺序是：

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

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

下面按步骤处理。

一、安装 Node.js

打开 Node.js 官网：

下载 LTS 版本安装包。

安装时建议保持默认选项。安装完成后，关闭当前 PowerShell 或 Windows Terminal，再重新打开一个新窗口。

重新打开终端是必要的，因为 Windows 环境变量通常需要新终端窗口才会生效。

二、检查 Node.js 和 npm

在 PowerShell 中执行：

如果安装成功，会输出类似：

继续检查 npm：

正常会输出类似：

只要这两个命令都能输出版本号，说明 Node.js 和 npm 的基础环境已经可用。

如果提示无法识别 node 或 npm，通常是 Node.js 没有安装成功，或者安装后没有重新打开终端。可以先重启 PowerShell；如果仍然无效，重新安装 Node.js LTS。

三、检查 npm 全局安装目录

Codex CLI 是通过 npm 全局安装的。全局安装后，Windows 需要能在 Path 中找到对应命令。

查看 npm 全局目录：

常见输出：

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

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

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

添加下面目录：

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

四、配置 npm 镜像

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

默认通常是：

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

再确认一次：

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

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

五、安装 Codex CLI

执行全局安装命令：

安装完成后，检查版本：

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

继续查看帮助：

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

六、首次运行

执行：

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

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

登录完成后，再次运行：

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

七、运行本地诊断

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

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

八、常用命令速查

查看版本：

查看帮助：

启动交互模式：

登录：

退出登录：

检查本地环境：

更新 Codex CLI：

在指定目录启动：

九、常见问题

1. node 命令找不到

现象：

处理方式：

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，再检查：

3. npm install -g 下载失败

先检查当前 npm 源：

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

清理缓存后重试：

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

4. codex 命令找不到

现象：

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

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

把下面目录加入用户 Path：

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

5. 安装后版本没有变化

先查看当前命令位置：

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

可以尝试重新安装：

也可以执行更新命令：

6. PowerShell 重启后配置才生效

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

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

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

十、建议的新手检查清单

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

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

十一、写在最后

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

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

遇到问题时，优先运行：

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