第一次接触 Codex 的时候，我其实不是卡在“怎么安装”，而是卡在一连串很典型的新手问题上：Codex 到底是什么？我在项目目录里执行安装命令，它会不会被装进这个项目？为什么我明明在 Windows 电脑上，到了 WSL 里还能直接进入 D: 盘？以及，既然都能看到同一份代码了，那项目到底该放在 Windows 目录里，还是放在 WSL 自己的 Linux 目录里？这些问题不理顺，后面越装越乱。(OpenAI开发者)
如果你也是 Windows 用户，而且是第一次接触 Codex CLI，那我先把结论放在前面：目前更稳的路线是 Windows + WSL + 在 WSL 里安装 Node.js + 在 WSL 里安装 Codex CLI。OpenAI 的 Windows 文档就是按这条路径写的；Codex CLI 文档本身也说明，CLI 可以通过 npm 安装，第一次运行时会要求登录。(OpenAI开发者)
先把最容易混淆的地方说清楚
很多人第一次安装 CLI，都会默认以为“我在某个项目目录里执行了安装命令，所以工具应该就装进这个项目了”。但 npm 的 -g 不是这个意思。只要你用了全局安装，npm 就会把包安装到它的全局 prefix 目录，而不是你当前所在的项目目录。npm 官方文档写得很清楚：在 Windows 上，这个全局位置默认通常是 %AppData%\npm。所以你站在 D:\files\Project\Python\ai-writer-mvp 里执行 npm i -g @openai/codex，并不代表 Codex 被装进了这个项目文件夹。(npm文档)
另一个特别容易让新手困惑的点是：WSL 明明是 Linux，为什么它能直接进入 Windows 的 D: 盘？其实原因很简单，微软官方一直都是这么设计的。WSL 会自动为本机硬盘创建挂载点，所以你在 Linux 里看到的 /mnt/c、/mnt/d，本质上就是已经挂载好的 Windows 盘符。换句话说，D:\files\Project\Python\ai-writer-mvp 在 WSL 里天然就对应成 /mnt/d/files/Project/Python/ai-writer-mvp。这不是“两个系统神奇互通”，而是 WSL 本来就提供的文件系统互操作能力。(Microsoft Learn)
不过，能访问不代表最适合长期开发。微软官方也专门提醒过：如果你的项目文件直接放在挂载的 Windows 盘里，比如 /mnt/d/...，你当然可以继续工作，但通常把项目直接放在 WSL 自己的 Linux 文件系统里，性能会更好。这个区别在前端依赖安装、测试扫描、文件监听、Git 操作比较多的时候，会更明显。(Microsoft Learn)
为什么我更推荐用 WSL 来装 Codex CLI
如果只是“试试看能不能跑起来”，Windows 原生环境未必不行；但如果你想少踩坑、少碰路径和权限的边界问题，那 WSL 还是更稳妥。OpenAI 的官方 Windows 页面给出的就是“先装 WSL，再在 WSL 里装 Node.js 和 Codex CLI”的流程。这不是某种民间偏方，而是官方推荐路径。(OpenAI开发者)
从体验上讲，这条路线的好处也很直观。你后面无论是跑 git、npm、python，还是让 Codex 读取仓库、编辑代码、执行命令，整个环境都更接近 Linux 工具链的原生语义。这样后续遇到的问题更少，排查思路也更统一。Codex CLI 文档本身也把它描述成一个会在你当前目录里检查仓库、编辑文件、运行命令的终端代理，所以“工作目录”和“运行环境”放对，真的很重要。(OpenAI开发者)
从零开始安装：一条最省心的路线
第一步是准备 WSL。如果你还没有装 WSL，可以在管理员 PowerShell 或 Windows Terminal 里执行 wsl --install。这是 OpenAI Windows 文档里给出的起点。装好以后，再输入 wsl 进入 Linux shell。(OpenAI开发者)
第二步是在 WSL 里安装 Node.js。OpenAI 的 Windows 指南建议通过 nvm 在 WSL 中安装 Node，示例版本是 Node 22。这样做的好处是以后升级 Node、切换版本都会更方便。你可以先装 nvm，然后执行 nvm install 22，最后用 node -v 和 npm -v 确认环境是否已经正常。(OpenAI开发者)
第三步才是正式安装 Codex CLI。命令很简单：
npm i -g @openai/codex
如果后面想升级到最新版，直接改成：
npm i -g @openai/codex@latest
这就是 Codex CLI 官方页面写的安装方式。(OpenAI开发者)
第一次启动时，看到什么才算正常
安装完成后，直接执行 codex。第一次运行时，Codex 会提示你登录。OpenAI 官方认证文档说明，Codex 支持两种登录方式：一种是用 ChatGPT 账号登录，另一种是用 API key。对于普通新手来说，直接走 ChatGPT 账号登录最省事。(OpenAI开发者)
如果终端里弹出一条很长的 auth.openai.com 链接，让你去浏览器完成授权，这也是正常流程。浏览器里完成登录后，CLI 会继续往下走。你后面如果看到类似 “Signed in with your ChatGPT account” 这样的提示，基本就说明认证已经完成了。CLI 参考文档里也有单独的 codex login 和 codex logout 命令，说明它本身就是按这种认证模型设计的。(OpenAI开发者)
进入交互界面后，最先该看哪一行
很多人第一次进到 Codex 界面，注意力会放在模型名上，比如 gpt-5.4。这个当然重要，但对实际使用来说，更关键的其实是 directory 这一行。因为 Codex CLI 会在它当前所在的目录里读取、编辑和运行代码，所以如果你看到的是 directory: ~，那就意味着它当前工作在 Linux 的 home 目录，而不是你的项目目录。(OpenAI开发者)
这时候最稳的做法，不是在 home 目录里硬聊，而是先把目录切对。比如你的项目还在 Windows 的 D 盘里，那就先进入：
cd /mnt/d/files/Project/Python/ai-writer-mvp
codex
或者直接一条命令完成：
codex -C /mnt/d/files/Project/Python/ai-writer-mvp
如果你以后已经把项目迁到 WSL 本地目录，比如 ~/code/ai-writer-mvp，那就直接在那个目录里启动即可。CLI 参考文档里专门列出了 codex login 等子命令，CLI 主文档则明确说明它是在当前工作目录内执行代码相关任务的。(OpenAI开发者)
一个最常见的小坑：Windows 路径语法和 WSL 路径语法不是一回事
这个坑几乎所有新手都会踩一次。你在 Windows CMD 里可以写：
D:\files\Project\Python\ai-writer-mvp
但到了 WSL 的 bash 里，你就必须写成：
/mnt/d/files/Project/Python/ai-writer-mvp
所以像 cd /d D:\files\Project\Python\ai-writer-mvp 这种命令，在 WSL 里一定会报错，因为那是 Windows CMD 的写法，不是 bash 的写法。WSL 文档对 /mnt/<drive letter>/ 的说明非常直接，理解了这个映射关系，后面就不会反复混淆。(Microsoft Learn)
项目放在 /mnt/d 还是 ~/code，到底怎么选
这是个没有必要神化，但也确实值得尽早想清楚的问题。
如果你现在只是想先把 Codex 跑起来、顺手体验一下，那项目继续放在 /mnt/d/files/... 没问题，迁移仓库反而会增加心智负担。微软官方也没有说“不能这样做”，只是说这样做通常不如把项目直接放在 WSL 文件系统里快。(Microsoft Learn)
但如果你后面准备长期在 WSL 里做开发，比如主要在 WSL 里跑 git、npm、pytest、构建命令，甚至让 Codex 长期在这个环境里工作，那么把仓库放在像 ~/code/项目名 这样的 Linux 本地目录里，通常会更顺。这个建议不是为了“看起来更专业”，而是因为底层文件系统路径更自然、I/O 往往更快、工具行为也更一致。(Microsoft Learn)
安装时最常见的几个问题，怎么排查
第一个高频问题是：安装命令一直转圈，看起来像卡住了。比如执行 npm i -g @openai/codex 后，终端长时间没什么输出。这种情况不一定真的是 Codex 安装坏了，很多时候只是 npm 默认日志不够详细。一个很实用的排查方法，是按 Ctrl + C 中断后，重新用更详细的方式执行：
npm i -g @openai/codex --verbose --timing
这样你更容易看出它到底卡在下载、校验还是解包阶段。npm 官方文档本身就强调了全局安装与 prefix 的关系，而更详细日志也是通用排查思路。(npm文档)
第二个高频问题是：怀疑网络或 npm registry 有问题。这时候可以先检查当前源，再做一个简单连通性测试：
npm config get registry
npm ping
如果 npm ping 明显很慢，或者直接失败，那问题更可能出在网络、代理、镜像源，而不是 Codex 本身。npm 这套工具链本来就依赖 registry 和全局 prefix 的正常工作。(npm文档)
第三个高频问题是：装完了，但找不到 codex 命令。这个时候先别急着重装，先看 npm 的全局前缀：
npm config get prefix -g
在 Windows 上，它通常应该指向 %AppData%\npm。如果 prefix 不对，或者 PATH 没配好，那全局命令就可能找不到。npm 官方对这件事的描述非常明确：全局安装进 prefix，不进当前项目目录。(npm文档)
把整套流程压缩成一份最实用的清单
如果你不想每次都重新想一遍，可以把下面这份当成自己的固定开局流程。
先打开 WSL，然后确认 Node 和 npm 正常：
node -v
npm -v
再安装或升级 Codex：
npm i -g @openai/codex@latest
然后进入项目目录。如果项目还在 Windows 盘里：
cd /mnt/d/files/Project/Python/ai-writer-mvp
如果项目已经迁到 WSL 里：
cd ~/code/ai-writer-mvp
最后启动：
codex
或者一步到位：
codex -C /mnt/d/files/Project/Python/ai-writer-mvp
这就是一套很适合新手复用的基本流程：先保证环境在 WSL，确认 Node/npm 正常，再进入正确目录启动 Codex。它不复杂，但能帮你避开绝大多数最容易混淆的问题。(OpenAI开发者)
最后，把今天最关键的三句话留下来
第一，npm i -g 是全局安装，不是装进你当前项目目录；在 Windows 上，全局安装默认通常走 %AppData%\npm。(npm文档)
第二，WSL 能访问你的 D: 盘，不是意外，而是因为 Windows 盘符会自动挂载到 /mnt/<盘符>。(Microsoft Learn)
第三，项目放在 /mnt/d/... 可以用，但如果你以后长期在 WSL 里开发，把仓库放在 WSL 自己的 Linux 文件系统里，通常会更顺。(Microsoft Learn)
