从真实安装入口出发，定位 Codex CLI 在 Windows 上的命令找不到、版本不更新、登录失败、PATH 冲突和 WSL 混用问题。附只读诊断脚本、错误对照表、配置示例与支持报告模板。
先确认当前终端究竟执行哪一份 Codex，再决定安装、更新或重装。Windows 上很多“安装失败”和“更新没生效”，本质是官方安装器、npm、Desktop 或 WSL 里的不同命令同时存在。只盯着安装提示，很容易修错对象。
先给结论：把问题分成五层
| 问题层 | 常见表现 | 第一条证据 |
|---|---|---|
| 安装 | 脚本无法执行、下载中断、安装器报错 | 终端类型、执行策略、官方域名是否可达 |
| 命令解析 | codex 找不到，或启动的是旧版本 | where.exe codex 与 Get-Command codex -All |
| 身份验证 | 浏览器回调失败、未登录、API Key 无效 | codex login status |
| 运行与配置 | doctor 报依赖、配置文件语法或沙箱问题 | codex doctor --summary |
| 环境混用 | WSL 调用了 Windows 的 codex、node 或 npm | which codex node npm |
这五层必须按顺序排。命令都没有解析成功时，登录和模型配置没有排查价值；PATH 指向旧文件时，反复执行 npm 更新也不会改变当前运行版本。本文命令基于 2026 年 7 月的 OpenAI Codex 官方仓库、Codex CLI 文档和本机实测整理。
30 秒确认：当前执行的是哪一份 Codex
先在你平时运行 Codex 的 Windows PowerShell 中执行：
where.exe codex Get-Command codex -All codex --version npm config get prefix npm list -g @openai/codex --depth=0
where.exe 给出 PATH 中能找到的可执行文件；Get-Command -All 还会显示 PowerShell 实际解析到的命令类型和顺序。第一条通常就是你输入 codex 时真正运行的文件。记录路径和版本，不要先删除任何目录。
一个容易误判的场景是：codex --version 正常，但 npm list -g @openai/codex 显示为空。这并不矛盾。我们的 Windows 实测环境中，PATH 命中的是 OpenAI Codex 应用目录里的独立 codex.exe，npm 全局列表自然没有该包。npm 全局目录只说明 npm 安装面，不能代表整台电脑的所有 Codex 安装。
选择安装方式：官方 Windows 安装器优先
OpenAI 官方仓库当前为 Windows 提供 PowerShell 安装器。新安装、没有既有 Node 工具链或不想管理 npm 全局目录时，优先使用它：
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
执行前确认域名是 chatgpt.com，并从官方 README重新核对命令。这里的 -ExecutionPolicy ByPass 只作用于新启动的这次 PowerShell 进程，不等于永久修改整台机器的策略。Microsoft 的执行策略说明也强调策略存在不同作用域，先用 Get-ExecutionPolicy -List 看清楚再处理。
已经稳定使用 Node/npm 的用户可以选择：
npm install -g @openai/codex codex --version
GitHub Releases还提供各平台构建，但手动下载后仍要自己管理放置目录和更新。无论选择哪一种，安装完成后重新打开终端，再做路径核验；不要同时安装三种然后期待系统自动选最新版本。
install.ps1 无法运行：先分策略、网络和终端
- 提示脚本被策略阻止：运行
Get-ExecutionPolicy -List，看限制来自 Process、CurrentUser、LocalMachine 还是组织策略。使用官方单次命令，不要为了安装永久把系统策略改成 Unrestricted。 irm不存在：你可能不在 PowerShell，或者处于被裁剪的 Shell。确认提示符，再从 PowerShell 执行。- 返回 HTML、超时或证书错误：这是网络、代理、TLS 检查或企业 CA 分支，不是 PATH。不要关闭 TLS 验证，也不要从陌生镜像下载同名脚本。
- 安装提示成功但命令找不到：关闭终端并重新打开，再进入下一节检查 PATH。
企业电脑若受组策略管理，应让管理员确认脚本域名、代理和签名策略。管理员权限不能自动解决错误代理或错误 PATH，盲目“以管理员运行”反而可能把文件装到另一个用户上下文。
codex 命令找不到：定位 PATH，而不是反复安装
where.exe codex
Get-Command codex -All
$env:Path -split ';' | Where-Object { $_ -match 'OpenAI|Codex|npm' }
如果前两条都没有结果，说明当前进程的 PATH 没有可用入口。先确认安装器实际完成，再检查安装目录是否存在。若文件存在但 PATH 没更新，重新登录 Windows 或重新打开终端通常比在旧窗口里反复安装更可靠。
如果返回多个路径，按顺序记录“路径、来源、版本”。常见来源包括 OpenAI/Codex 应用目录、用户 npm 全局目录、系统 npm 目录和 WSL。只处理你能确认来源的一项；不要直接删除 WindowsApps、Program Files 或用户配置目录。Git for Windows若缺失，也应独立安装和验证，不能靠修改 Codex PATH 代替。
更新后还是旧版本：先更新 PATH 命中的安装面
先运行：
codex update codex --version Get-Command codex -All
codex update 是当前 CLI 暴露的更新入口。执行后版本不变，不要马上换十种安装命令；先看当前路径属于哪种安装。如果命中的是 npm 全局目录，再用 npm install -g @openai/codex；如果命中独立安装版，npm 更新只会更新另一份文件。
还要区分“版本号没变”和“更新失败”。官方最新版本页若与本机版本一致，重复更新没有意义。本文核验时的版本是 codex-cli 0.144.4，这只是 2026-07-16 的快照，不应被写成永久最新版本。
登录失败：先查状态，再选浏览器或设备码
codex login codex login status codex login --device-auth
常规流程由 codex login 打开浏览器；完成后用 codex login status 确认当前状态。浏览器打不开、远程终端无法回调或回调被代理拦截时，可尝试设备码方式。登录方式、账号范围和凭据位置以 OpenAI 的身份验证文档为准。
需要 API Key 时，CLI 支持从标准输入接收，而不是把密钥硬编码进文章或脚本。PowerShell 可以让环境变量通过管道进入 codex login --with-api-key，但不要在共享电脑留下明文历史，也不要上传 %USERPROFILE%\.codex\auth.json。排障时最多报告“文件是否存在”和“登录状态”，绝不贴内容。
用 doctor 把“能启动”和“环境健康”分开
codex doctor --summary codex doctor --json codex --help
--summary 适合人工阅读，--json 适合保存结构化证据或交给脚本比较。先看 Codex 版本、Git、Shell、配置和沙箱相关检查，再处理明确失败项。完整命令以CLI 命令参考为准。
诊断工具包里的脚本会运行版本、doctor 摘要和登录状态，并只显示代理变量“是否配置”。它不会读取 Key、Token、auth.json 或配置正文。即便如此，输出仍可能含用户名路径，发到公开 Issue 前要脱敏。
配置文件报错：从最小配置恢复
Codex 用户配置通常位于 %USERPROFILE%\.codex\config.toml。先备份当前文件，再只回退最近一处改动。不要把网上整份配置直接覆盖到自己的机器，因为模型名、审批策略、沙箱模式和 MCP 服务都可能不同。OpenAI 的基础配置文档给出了当前字段语义。
model = "gpt-5-codex" approval_policy = "on-request" sandbox_mode = "workspace-write"
这只是最小示例，不是推荐所有人照抄。若启动错误发生在新增 MCP 或自定义 shell 配置之后，先临时移除那一小段并运行 codex doctor --summary。一次只改一处，才能知道恢复来自哪项修正。
Windows 沙箱报错：先换普通工作目录复现
沙箱和权限问题经常被误当成安装失败。先把一个无敏感数据的小项目放到普通用户可写目录，使用最小配置复现，再对照 OpenAI 的Windows 沙箱说明。网络盘、受保护系统目录、企业安全软件和继承异常的 ACL 都可能让结果不同。
不要为了通过检查长期以管理员权限运行，也不要关闭系统安全软件。管理员模式可能改变 HOME、配置读取和文件所有者，短期看似可用，却把环境差异扩大。先证明普通目录是否正常，再定位具体目录或安全策略。
Windows 原生还是 WSL：选一套主环境
在 Windows PowerShell 中检查：
wsl --status wsl -l -v where.exe codex
在 WSL 发行版内部检查：
which codex which node which npm codex --version codex doctor --summary
若路径以 /mnt/c/ 开头，WSL 正在调用 Windows 工具。需要 Linux 工具链和隔离环境时，应在 WSL 内维护 Linux 侧 Codex、Node 和 npm；项目主要依赖 Windows 应用、盘符和工具时，就用 Windows 原生。OpenAI 的WSL 指南和 Microsoft 的WSL 安装文档分别说明了 Codex 使用边界与 WSL 2 安装方式。
最容易出问题的不是选错平台，而是两边同时修改 PATH、npm 前缀和配置。先选主环境，另一个环境只在确有需要时独立维护；不要让 Windows npm 更新 WSL 的 Codex，也不要把 WSL 路径写入 Windows 用户 PATH。
一张表对照常见报错
| 现象 | 先检查 | 避免 |
|---|---|---|
codex 找不到 | where.exe、Get-Command -All | 连续重复安装 |
| npm 显示未安装但命令可用 | 实际命令路径是否来自独立安装器 | 把 npm 列表当全机清单 |
| 更新后仍是旧版本 | PATH 第一项和官方最新版本 | 更新另一份未被执行的安装 |
| 脚本被禁止 | Get-ExecutionPolicy -List | 永久放宽全机策略 |
| 登录回调失败 | login status、设备码方式 | 公开 Token 或 auth 文件 |
| doctor 报 Git 缺失 | git --version | 靠改 Codex PATH 代替安装 Git |
| 配置后无法启动 | 最近一处 TOML 改动 | 覆盖整份配置 |
WSL 路径在 /mnt/c | which codex node npm | Windows/WSL 混装 |
资源包包含什么
- 只读诊断脚本：检查系统、PowerShell、Codex 路径、版本、doctor、登录状态、Node/npm/Git/WSL 和代理变量是否配置，不读取密钥值。
- 安装与 PATH 清单：区分官方安装器、npm、更新和登录入口。
- 错误对照 CSV：把 12 类常见现象映射到证据和安全处理。
- 支持报告模板：整理最小复现，并列出必须脱敏的字段。
- 最小配置示例：用于比对字段，不覆盖现有
config.toml。 - WSL 清单：识别
/mnt/c混用和主环境边界。
下载说明：正文无需登录即可阅读；ZIP 需要免费注册后下载，登录后会返回原资源。诊断脚本不会修改系统，但输出可能包含个人路径，公开分享前仍需脱敏。
参考资料与版本边界
本文于 2026-07-16 按 OpenAI Codex 官方仓库、官方 CLI/认证/配置/Windows 文档，以及 Microsoft PowerShell 与 WSL 文档核对；命令另在 Windows 环境用 codex-cli 0.144.4 实测。Codex 更新频繁，版本号、安装脚本和登录参数可能变化，执行前请以官方最新页面为准。
- OpenAI Codex 官方 GitHub 仓库
- OpenAI Codex 最新版本
- Codex CLI 官方文档
- Codex 身份验证
- Codex CLI 命令参考
- Codex 基础配置
- Codex Windows 沙箱说明
- Codex 在 WSL 中运行
- Microsoft PowerShell 执行策略
- Microsoft WSL 安装
- npm 全局安装目录说明
- Git for Windows 官方下载
评论0