Windows 安装 Codex CLI 教程：npm 安装、首次登录与常见报错排查【无图精华版】

Windows 安装 Codex CLI 教程：npm 安装、首次登录与常见报错排查

在 Windows 上安装 Codex CLI 时，常见的卡点是：找不到 node、PowerShell 禁止运行 npm.ps1，或者安装完成后仍然无法识别 codex。本文按"检查环境 → 安装 → 验证 → 登录 → 运行第一个任务"的顺序说明操作方法。

适用范围：Windows 原生 PowerShell，使用 npm 安装 Codex CLI。 OpenAI 官方也提供独立安装器；本文只展开 npm 路线，因此需要先安装 Node.js。WSL 用户应在自己的 Linux 环境中按照对应文档操作，不要直接混用本文的 Windows 路径和 .cmd 命令。

全文使用可复制的命令和排错表，按正文即可完成操作。登录界面和版本号可能变化，以当前安装版本为准。

已安装 Node.js？先看这组命令

逐条运行下面的命令，前一步成功后再执行下一步：

powershell 复制代码

node --version
npm.cmd --version
npm.cmd install -g @openai/codex@latest
codex.cmd --version

如果第一条命令就报错，从下一节开始检查。安装通过后，跳到第六节，在项目目录中启动并登录。

本文统一使用 npm.cmd 和 codex.cmd。它们是 npm 在 Windows 上提供的命令入口，可以避免 PowerShell 优先选中同名 .ps1 文件时触发脚本执行策略报错。

一、安装前检查

打开 PowerShell，分别运行：

powershell 复制代码

node --version
npm.cmd --version

如果两条命令都能输出版本号，可以直接进入"安装 Codex CLI"部分。

如果提示无法识别 node 或 npm，通常是以下两种情况：

电脑尚未安装 Node.js；
Node.js 已安装，但当前终端还没有加载新的环境变量。

典型提示包括"无法将 node 项识别为 cmdlet、函数、脚本文件或可运行程序的名称"。如果只有 npm.ps1 报错，而 node 能输出版本号，直接参考第三节。

二、安装 Node.js

前往 Node.js 官网下载 Windows 安装包。

下载 Windows 对应的 LTS 版本并按向导安装。一般情况下，保持默认选项即可。

安装向导提示完成后，点击 Finish 退出。

安装完成后，关闭原来的 PowerShell，再打开一个新窗口，然后重新检查：

powershell 复制代码

node --version
npm.cmd --version

能够看到版本号，说明 Node.js 和 npm 已经可用。

如果使用 VS Code 内置终端，必要时关闭并重新打开整个 VS Code，让它重新读取环境变量。版本号不必与其他教程的示例完全一致。

三、解决 npm.ps1 被禁止运行的问题

部分 Windows 电脑在 PowerShell 中执行 npm 时，会看到类似提示：

text 复制代码

无法加载文件 npm.ps1，因为在此系统上禁止运行脚本

这通常不是 npm 安装损坏，而是 PowerShell 的脚本执行策略阻止了 npm.ps1。

不修改执行策略时，可以直接调用 npm 的 Windows 命令文件：

powershell 复制代码

npm.cmd --version

如果这条命令能输出版本号，后续安装 Codex CLI 时也可以使用 npm.cmd。

通常使用 npm.cmd 就足够，无需修改系统设置。 如果希望继续使用不带后缀的 npm，可以先查看执行策略：

powershell 复制代码

Get-ExecutionPolicy -List

在自己管理的个人电脑上，确认需要调整策略后，可以只为当前用户设置 RemoteSigned：

powershell 复制代码

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

如果出现确认提示，确认作用域为 CurrentUser 后再选择继续。修改后重新打开 PowerShell。公司或学校管理的电脑可能受组织策略限制，此时应联系管理员处理。

四、安装 Codex CLI

在 PowerShell 中运行：

powershell 复制代码

npm.cmd install -g @openai/codex@latest

安装完成后检查版本：

powershell 复制代码

codex.cmd --version

如果能够看到 codex-cli 和版本号，说明命令行工具已经安装成功。使用 codex.cmd 可以避免 PowerShell 将同名的 codex.ps1 作为脚本拦截。

这里验证的是 CLI 已安装且命令可执行。是否能够完成登录和模型请求，还需要继续验证。

以后需要更新时，可以再次运行：

powershell 复制代码

npm.cmd install -g @openai/codex@latest
codex.cmd --version

五、安装成功后找不到 codex 命令

如果安装过程没有报错，但系统提示无法识别 codex，先关闭当前 PowerShell，再打开一个新窗口。

然后运行：

powershell 复制代码

Get-Command codex.cmd -ErrorAction SilentlyContinue
npm.cmd config get prefix

第一条命令用于检查系统能否找到 Codex，第二条命令用于查看 npm 的全局安装位置。

如果 Get-Command 没有返回结果，继续检查全局安装目录中是否存在命令文件：

powershell 复制代码

$npmPrefix = (npm.cmd config get prefix).Trim()
Test-Path (Join-Path $npmPrefix 'codex.cmd')

根据输出分两种情况处理：

检查结果	说明	下一步
`True`，但 `Get-Command` 找不到命令	安装目录中有文件，当前 `Path` 可能未包含该目录	把 `npm.cmd config get prefix` 的实际输出加入用户 `Path`，然后重新打开终端
`False`	当前 npm 全局目录中没有 `codex.cmd`	查看安装日志，并确认安装时与现在使用的是同一套 Node.js / npm

可以通过完整路径进一步验证：

powershell 复制代码

& (Join-Path $npmPrefix 'codex.cmd') --version

若完整路径能运行，问题通常在命令查找路径。Windows 中可通过"编辑账户的环境变量 → 用户变量 → Path → 编辑 → 新建"添加实际目录；保留原有条目。

六、在项目目录中启动 Codex

建议先创建一个独立的练习目录，不要直接在整个用户目录或包含大量私人文件的目录中启动编码工具。

powershell 复制代码

New-Item -ItemType Directory -Path "$env:USERPROFILE\CodexProjects\demo" -Force
Set-Location "$env:USERPROFILE\CodexProjects\demo"
codex.cmd

首次启动时，按照终端显示的登录方式完成认证。登录选项可能随版本和账号状态变化，应以当前界面及官方说明为准。

官方入门文档提供"Sign in with ChatGPT"或其他可用登录方式。选择适合自己账号的入口，完成浏览器中的步骤，再回到终端查看结果。认证选项见 OpenAI 官方登录说明。

如果登录页面无法完成，不要反复修改未知配置，也不要使用来源不明的脚本。可以按下面的顺序检查：

确认系统时间和时区正确；
确认浏览器可以正常打开登录页面；
关闭旧终端后重新运行 codex.cmd；
检查账号状态以及服务支持范围；
查看 Codex 官方文档中的最新登录说明。

登录完成后，可以在 Codex 的输入框中发送一个范围明确的任务：

text 复制代码

查看当前目录，说明有哪些文件。如果目录为空，告诉我即可，先不要修改文件。

如果能收到正常回答，说明首次任务流程已经走通。codex.cmd --version 成功但任务失败时，应继续排查认证、网络或账号权限，而不是直接重装 Node.js。

七、需要手动修改 config.toml 吗？

按照官方入门流程进行基础安装和登录，不需要先照抄一份第三方 config.toml。建议先用默认配置完成第一个任务，再根据需要配置模型、工具或其他选项。

确实需要调整时，参考 OpenAI 官方配置文档，先备份已有配置，只使用当前版本支持的配置项。

八、目录信任和沙箱怎么选

Codex 可能会要求确认是否信任当前目录。只有当目录中的文件可以交给工具读取和修改时，才继续操作。

使用时建议遵守以下原则：

在独立项目目录中运行；
执行命令前确认命令内容和目标路径；
修改重要文件前使用版本控制或做好备份；
不在提示词、代码或截图中公开密码、令牌和其他凭证；
不为了省事关闭全部安全保护。

如果只是阅读和分析代码，可以优先使用限制更严格的权限。需要写文件或运行命令时，再根据实际任务授权。

九、常见问题

1. `node` 命令无法识别

确认已经安装 Node.js，并在安装后重新打开 PowerShell。如果仍然无效，检查 Node.js 安装目录是否在 Path 环境变量中。

2. `npm.ps1` 无法运行

可以使用 npm.cmd 代替 npm。只有在确认设备归自己管理、脚本来源可信时，才调整当前用户的 PowerShell 执行策略。

3. 安装时出现权限错误

如果看到 EPERM 或 EACCES，先检查 npm 全局安装目录是否属于当前用户、是否有相关进程占用文件，以及安装日志中具体失败的路径。不要把所有权限错误都当成同一个问题。

4. `codex.cmd --version` 正常，但启动后无法登录

这说明 CLI 本体通常已经安装完成，问题更可能出在认证、浏览器、账号状态、网络环境或服务可用范围。应根据终端中的原始错误信息逐项排查。

5. 如何确认当前使用的是哪个 Codex

运行：

powershell 复制代码

Get-Command codex.cmd | Format-List Name,Source,Version
codex.cmd --version

这两条命令可以帮助确认命令路径和当前版本。

6. 安装时超时或无法连接 npm 仓库

先查看当前 registry，再测试连接：

powershell 复制代码

npm.cmd config get registry
npm.cmd ping

npm.cmd ping 成功只说明当前 registry 可访问，不代表 Codex 登录服务一定可用。如果 ping 失败，按日志检查网络、代理和 registry 设置；公司内部 registry 应遵循组织配置。

7. 报错太多，先检查哪一步？

现象	优先检查
`node` 无法识别	Node.js 是否安装、终端是否重启、安装路径是否在 `Path` 中
`npm.ps1` 或 `codex.ps1` 被禁止运行	改用 `npm.cmd` 或 `codex.cmd`
安装命令失败	npm 原始日志、registry 连通性、目录权限
安装成功，但找不到 `codex.cmd`	npm 全局目录、命令文件是否存在、用户 `Path`
版本检查正常，登录失败	浏览器认证、账号状态、系统时间、网络环境
已登录，但任务请求失败	终端原始错误、服务访问情况、账号权限或额度

十、安装检查清单

node --version 能正常输出；
npm.cmd --version 能正常输出；
codex.cmd --version 能正常输出；
已重新打开 PowerShell，使环境变量生效；
Codex 在独立项目目录中启动；
登录过程使用当前版本提供的官方入口；
没有公开密码、令牌或包含敏感参数的链接；
重要文件已经备份或纳入版本控制。

按照"Node.js、npm、Codex CLI、登录、项目目录"的顺序逐项检查，通常比一次修改多项配置更容易定位问题。工具版本和登录界面可能更新，具体选项应以 Codex 当前界面及官方文档为准。

Windows 安装 Codex CLI 教程：npm 安装、首次登录与常见报错排查【无图精华版】