在Windows上部署Codex CLI时，最容易误判的信号是“版本号能打印出来”。这只证明本地可执行文件已经被找到并启动，不能证明登录凭证可用，更不能证明一次模型请求和文件修改已经完成。
本文把验证拆成五层：运行时与命令解析、CLI安装、认证来源、真实请求、文件操作。这样遇到npm.ps1、Missing environment variable或HTTP 403时，可以直接回到出错的层次排查，而不是重复安装整个环境。
本文命令在Windows PowerShell中执行。示例采用npm安装路径，已使用其他安装方式的读者可跳过安装步骤，直接从命令解析开始检查。
1. 先确认Node.js和npm是否可执行
node --version
npm.cmd --version
两条命令都应返回版本号。如果node无法识别，先确认是否安装了适合当前架构的Node.js Windows安装包，并重新打开终端，使更新后的PATH生效。安装包应来自Node.js官方渠道；不要把下载页上的Docker命令当作Windows本机安装命令。
图1：命令尚未进入Codex阶段，先检查Node.js安装和终端环境。
这里刻意使用npm.cmd。PowerShell可能将npm解析到同名的.ps1脚本；当脚本执行策略禁止运行时，报错发生在Shell启动脚本阶段，并不代表npm包损坏。可用下面的命令确认解析结果：
Get-Command npm* -All
若npm.cmd --version能正常输出，通常可以继续使用.cmd入口，不必为安装CLI修改整台机器的执行策略。
图2：版本号与本文环境不同没有关系；npm仍需单独验证。
2. 安装CLI，并区分“装好”与“可用”
npm.cmd install -g @openai/codex@latest
codex.cmd --version
codex.cmd --help
-g表示安装为npm全局工具，不等于必须使用管理员权限。安装完成后，codex.cmd --version应返回CLI版本；--help能进一步确认命令入口可启动。npm WARN不一定意味着失败，应结合最终退出状态和版本检查判断。
如果安装命令完成，但PowerShell仍找不到codex.cmd，依次检查：
Get-Command codex.cmd -ErrorAction SilentlyContinue
npm.cmd config get prefix
第二条会给出npm全局安装目录。检查该目录下是否存在codex.cmd，以及目录本身是否在当前用户的PATH里。若刚修改过PATH，重新打开终端再测；不要删除原有环境变量内容。
到这一步只能认定本地安装入口可运行。 账号权限、API配额和网络请求尚未经过验证。
3. 固定工作目录，再判断认证来源
先在一个独立的测试目录中操作，避免首次启动时将整个用户目录作为工作范围：
$testDir = Join-Path $env:USERPROFILE 'CodexProjects\cli-smoke-test'
New-Item -ItemType Directory -Path $testDir -Force | Out-Null
Set-Location -LiteralPath $testDir
Get-Location
Codex CLI常见的认证路径是ChatGPT登录或OpenAI API Key。两者不是同一套凭证；自定义模型服务还可能要求单独的provider配置。先确认当前机器实际准备使用哪一条路径，再处理认证错误。
交互式登录可从以下命令开始：
codex.cmd login
codex.cmd login status
login status有结果，只能说明存在相应的登录状态；它不能证明当前选中的provider一定会使用这份凭证。如果配置要求读取某个环境变量，应检查当前PowerShell进程里该变量是否存在，同时避免打印密钥明文：
[bool]$env:OPENAI_API_KEY
True不代表Key有效，False则说明当前窗口里没有这个变量。进程级环境变量不会自动同步到其他已打开的终端。
如果需要检查用户级配置文件，默认位置是$env:USERPROFILE.codex\config.toml；设置了CODEX_HOME时，应以该变量指定的目录为准。排查时先确认provider、模型名和凭证变量名，再决定是否编辑配置。不要把真实Key写进文章、截图或故障反馈。
首次交互启动时可能出现工作目录信任或Windows沙箱选项。确认界面显示的是前面创建的测试目录，并按当前任务需要授予权限；这与凭证能否通过服务端验证是两回事。
图3：此图用于识别沙箱界面；界面上的版本、模型标签和路径不是本文的调用成功证明。
4. 用最小真实请求验证链路
版本号、帮助页和登录状态都不能代替一次真实模型请求。进入前面的空目录后，可以用非交互命令做一次只读检查：
codex.cmd exec --skip-git-repo-check --sandbox read-only '请只回复“连接测试”。不要读取或修改文件，也不要执行命令。'
--skip-git-repo-check用于这个专门创建的非Git测试目录；--sandbox read-only限制本次任务的写入能力。这个测试的目标不是评估模型质量，而是确认CLI能取得所需凭证、发出请求并收到模型回复。若失败，应保留完整错误类型和响应来源，再按下表定位。
| 现象 | 已验证的部分 | 下一步检查 |
|---|---|---|
codex.cmd --version失败 | 还未验证本地入口 | npm安装结果、全局目录和PATH |
Missing environment variable | CLI已启动，凭证读取失败 | 当前provider要求的变量名及当前进程环境 |
| HTTP 401 | 已发出请求，认证未通过 | 凭证来源、服务地址、是否过期或无权限 |
| HTTP 403 | 已发出请求，被服务端拒绝 | 返回正文中的地区、组织或访问策略信息 |
| HTTP 404或模型不存在 | 请求路径或模型解析失败 | 实际服务地址和模型标识 |
| HTTP 429 | 服务端限制了请求 | 速率、额度及返回正文 |
这里的“响应来源”很关键：同一个403可能来自登录流程、官方API或自定义provider，不能仅凭状态码断言是config.toml没有生效，也不能把更换服务写成通用修复步骤。
5. 本机检查记录：失败也要按层次呈现
2026年9月29日，在一台已有安装环境的Windows机器上检查到Node.js v24.21.0、npm 11.19.0和Codex CLI 0.158.0。这组版本仅是测试环境记录，不是本文的最低版本要求，也不代表在全新系统上重新完成了安装。
使用Crazyrouter作为自定义provider的既有配置发起只读任务，CLI返回Missing environment variable: OPENAI_API_KEY。本文写作时又执行了一次上文的非Git目录只读命令，仍得到相同错误。这证明本地CLI已进入凭证读取阶段，但没有得到模型回复；不能据此宣称该provider已跑通。另一次使用独立的官方路径对照测试，先出现地区限制相关的403，随后HTTPS回退返回无效API Key的401。这些测试都未完成模型回复或文件创建。
这组结果说明：版本检查通过、存在登录状态、真实请求成功是三个不同的结论。 缺环境变量时重复安装Node.js没有针对性；403也需要结合返回正文和请求实际去向判断。
6. 请求成功后，再验收文件操作
只有上面的只读请求得到正常回复，才继续做写入测试。建议在同一个测试目录里下达范围明确的任务，例如：
仅在当前目录创建 index.html。
页面显示“Codex CLI 文件写入测试”，并提供一个按钮；点击按钮后显示“交互正常”。
HTML、CSS和JavaScript都写在这个文件内，不安装依赖，也不读取或修改其他文件。
完成后说明修改了哪些文件；若无法写入，请明确说明失败原因。
退出交互界面并返回PowerShell后，验证文件，而不是只看CLI的完成描述：
Test-Path -LiteralPath .\index.html
Start-Process .\index.html
Test-Path返回True只能证明文件存在；还需要在浏览器里确认页面显示内容和按钮行为。测试结束时，检查目录内是否出现了任务范围之外的文件。模型能回复、文件实际存在、页面可打开、交互符合要求，四项都通过，才算完成这次端到端验收。
排查顺序
碰到问题时，可以按下面的顺序缩小范围：
Shell能找到命令
-> CLI能启动
-> 当前配置能取得凭证
-> 服务端接受请求并返回模型结果
-> 工具按预期写入文件
-> 产物通过人工验收
每一步只证明当前层，不替下一层背书。记录CLI版本、执行命令、请求去向、脱敏后的完整错误以及当前工作目录，通常就足以让一次“装好了但不能用”的问题变成可定位、可复现的故障。