很多人第一次听到 Codex，会以为它只是“ChatGPT 会写代码”那么简单。实际上，Codex 已经不是一个单纯的聊天窗口，而是一套真正能进入你的项目目录、读代码、改代码、跑命令、做代码审查的 AI 编码代理。

如果你最近刚刷到别人用 Codex 改 Bug、补测试、跑自动化，八成也有同一个问题：

这玩意到底怎么装？Windows 能不能直接用？是装 App，还是装 CLI？要不要 API Key？

这篇文章我直接按新手最需要的路径来写，目标不是讲概念，而是让你看完就能装、装完就能跑、跑完就能开始写代码。

截至 2026 年 5 月 8 日，我核对的是 OpenAI 官方 Codex 文档当前版本，下面的步骤以 Windows 用户 为主，兼顾 CLI、桌面端和 WSL2 场景。

---

一、先说结论：Codex 现在有 4 种主流用法

OpenAI 现在把 Codex 分成了几条常见入口：

1. Codex App
   适合想图形化使用的人，下载后直接选项目、聊天、执行任务。
2. Codex CLI
   适合开发者，直接在终端里跑，效率最高。
3. IDE Extension
   适合 VS Code、Cursor、Windsurf 用户，直接在编辑器里调 Codex。
4. Codex Web / Cloud
   适合把任务丢到云端后台跑。

如果你问我，最值得先装哪个？

答案非常直接：

• 想最快上手：先装 Codex App
• 想真正进入开发工作流：直接装 Codex CLI

---

二、安装前你需要准备什么

在正式安装前，先把这几个前提条件看清楚，不然后面十有八九会卡。

1. 账号准备

Codex 现在支持两种登录方式：

• ChatGPT 账号登录
• OpenAI API Key 登录

区别非常重要：

• 用 ChatGPT 登录，走的是订阅权限，CLI 默认也优先走这个方式。
• 用 API Key 登录，走的是 API 按量计费，更适合自动化脚本、CI/CD 这类程序化场景。

如果你只是个人开发者，优先建议用 ChatGPT 登录，因为更省心。

2. Windows 版本建议

OpenAI 官方对 Windows 的建议也很明确：

• Windows 11：推荐
• 较新的 Windows 10：可用，但属于 best effort
• 过老的 Windows 10：不推荐

如果你是 Windows 10 用户，也不是完全不能用，但遇到沙箱、权限、终端兼容问题的概率会高一些。

3. CLI 用户需要 Node.js 和 npm

如果你打算装 CLI，需要先有 Node.js 和 npm 环境。

Codex CLI 官方安装命令是：

npm i -g @openai/codex

所以你本机至少要先能正常执行 npm -v。

---

三、最省事的方案：先装 Codex App

如果你不想一上来就折腾命令行，那先装 App 是最稳的。

第 1 步：下载 Windows 版 Codex

OpenAI 官方 Quickstart 页面已经给出了 Windows 下载入口，直接从官方地址下载安装即可。

第 2 步：打开后登录

安装完成后，打开 Codex，登录方式有两个：

• ChatGPT 账号
• OpenAI API Key

如果你只是正常个人使用，还是那句话：优先用 ChatGPT 登录。

第 3 步：选择项目目录

登录后，Codex 会让你选择一个项目文件夹。这个步骤很关键，因为它决定了 Codex 之后能读写哪个目录。

第 4 步：发第一条消息

选中项目后，确认当前是本地模式，然后直接给它一条任务：

帮我分析这个项目的结构

或者：

帮我找出这个仓库里最容易出 bug 的地方

你会非常直观地感受到，Codex 和普通 AI 对话最大的区别，就是它真的会进目录、读文件、执行动作。

---

四、开发者最常用的方案：安装 Codex CLI

如果你平时就是写代码的，我更建议你直接装 CLI。原因很简单：

真正高频开发时，终端里的 Codex，比网页和纯聊天式 AI 更像一个可协作的工程助手。

第 1 步：安装 Codex CLI

在 PowerShell、Windows Terminal 或其他终端里执行：

npm i -g @openai/codex

这是 OpenAI 官方文档当前给出的 CLI 安装命令。

第 2 步：启动 Codex

安装完成后直接运行：

codex

第一次运行时，Codex 会提示你登录。

第 3 步：完成登录

首次登录时，你可以选择：

• 用 ChatGPT 账号登录
• 用 API Key 登录

CLI 默认在没有有效会话时，会优先引导你走 ChatGPT 登录。

第 4 步：升级 Codex CLI

Codex CLI 更新比较快，官方也给了升级命令：

npm i -g @openai/codex@latest

如果你发现网上某篇教程里的界面、命令、选项和你本机不一样，第一件事不是怀疑自己，而是先执行一次升级。

---

五、Windows 用户最关心的问题：原生跑，还是 WSL2 跑？

这个问题非常关键，因为很多教程一上来就告诉你“直接 WSL2”，但 OpenAI 官方文档的建议其实更细。

方案 A：原生 Windows 运行

OpenAI 官方现在支持 Codex 在 Windows 原生环境下运行，而且有两种沙箱模式：

• elevated：更强，优先推荐
• unelevated：弱一些，但可作为回退方案

官方建议是：

如果原生 Windows 沙箱可用，优先用原生。

原因很现实：

• 性能更好
• 路径更直接
• 不用跨 Windows / Linux 文件系统来回折腾

方案 B：WSL2 运行

什么情况下更适合用 WSL2？

• 你本来就在 Linux 工具链里开发
• 你的项目依赖 Linux 环境
• 原生 Windows 沙箱在你的机器上跑不稳

官方给出的 WSL2 安装思路也很直接。

先在管理员 PowerShell 里执行：

wsl --install

进入 WSL 后，再在 Linux shell 里安装 Node.js，然后安装 Codex：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash nvm install 22 npm i -g @openai/codex codex

还有一个官方建议特别值得记住：

如果你在 WSL2 里开发，仓库尽量放在 Linux home 目录，比如 ~/code/my-app，不要长期放在 /mnt/c/... 下。

原因就是 I/O、权限、软链接兼容性都会更好。

---

六、为什么有人装上了还是登录失败？

这也是新手最容易踩的坑。

1. 邮箱密码登录用户必须注意 MFA

OpenAI 官方文档明确写了：

• 如果你是 邮箱 + 密码 登录 ChatGPT
• 那么在访问 Codex 相关能力前，必须开启 MFA

如果你是：

• Google 登录
• Microsoft 登录
• Apple 登录

官方没有强制你在 ChatGPT 账户侧单独开 MFA，但仍然建议你在对应登录提供方里开好双重验证。

很多人以为是“Codex 登不上”，实际上是账号安全条件没满足。

2. 浏览器回调失败怎么办

如果你是在远程环境、无头环境，或者本机网络拦截了本地浏览器回调，官方建议可以这样登录：

codex login --device-auth

这会走设备码登录流程，更适合服务器、远程终端或浏览器回调异常的场景。

3. 登录信息缓存在哪里

OpenAI 官方文档写得很清楚，Codex 会把登录信息缓存在：

~/.codex/auth.json

或者系统凭据存储中。

这句话你一定要记住：

auth.json 本质上就是敏感凭据，千万不要上传到 GitHub，也不要发给别人。

---

七、CLI 安装后最常见的 5 个报错，我帮你提前避坑

1. codex 不是内部或外部命令

原因通常只有两个：

• npm 全局安装目录没进 PATH
• 终端没重开

最常规的解决方法：

1. 先确认 npm -v 正常
2. 重新打开 PowerShell 或 Windows Terminal
3. 再执行 codex

2. Windows 沙箱初始化失败

OpenAI 官方文档指出，原生 Windows 的 elevated 沙箱失败，常见原因包括：

• 你没通过管理员授权弹窗
• 企业电脑策略禁止本地用户/组创建
• 企业策略禁止防火墙规则修改
• 沙箱用户所需的登录权限被组策略拦掉

这时候别死磕，先做两件事：

1. 重试一次 elevated
2. 还不行就临时切到 unelevated，或者直接改走 WSL2

3. 出现 Windows 错误 1385

这个错误不是 Codex“坏了”，而是 Windows 策略不允许沙箱用户按需要的登录类型启动命令。

如果你在公司电脑上遇到这个错误，十有八九不是你个人能彻底解决的，需要 IT 策略放行。

4. WSL2 里速度很慢

大概率是你把项目放在了：

/mnt/c/...

正确姿势是：

mkdir -p ~/code cd ~/code git clone <your-repo> cd <your-repo>

5. API Key 登录后发现功能不全

这个不是 Bug，是官方设计如此。

按照官方文档当前说明：

• API Key 更适合程序化、自动化场景
• 一些依赖 ChatGPT 额度或云端能力的功能，并不一定可用

如果你是个人高频开发，还是优先用 ChatGPT 登录 更省心。

---

八、进阶建议：装完 Codex，顺手把 OpenAI 官方文档 MCP 也接上

这一步不是必需，但我个人非常推荐。

原因很简单：

你以后在 Codex 里问 OpenAI API、Responses API、模型参数、Codex 配置时，能直接拉官方文档，不容易被过时博客误导。

官方给出的接入命令是：

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp codex mcp list

如果你平时就喜欢在终端里一边查文档一边写代码，这一步非常值。

---

九、给新手的最优安装路线，我直接帮你定了

如果你不想纠结，照这个顺序来：

路线 1：普通开发者

1. 先装 Codex App
2. 用 ChatGPT 账号登录
3. 选一个小项目试跑
4. 再装 Codex CLI
5. 把 Codex 融入你的终端工作流

路线 2：纯终端党

1. 先装 Node.js
2. 执行 npm i -g @openai/codex
3. 执行 codex
4. 选 ChatGPT 登录
5. 先在一个测试目录里玩熟

路线 3：Linux 工具链重度用户

1. 直接启用 WSL2
2. 在 WSL2 里安装 Node.js
3. 安装 Codex CLI
4. 仓库放 ~/code 下

---

十、最后总结：Codex 真正难的不是安装，而是你用不用它进入工作流

说白了，今天装 Codex 已经没有前两年那么折腾了。

官方路径其实非常清晰：

• 想快：装 App
• 想强：装 CLI
• 想稳：Windows 原生优先，不行再 WSL2
• 想少踩坑：优先 ChatGPT 登录，邮箱密码用户记得先开 MFA

真正拉开差距的，从来不是“你有没有装上 Codex”，而是：

你有没有把它真正变成日常开发流程的一部分。

当你开始习惯把“读代码、补测试、修小 Bug、查文档、跑重复命令”这类任务交给 Codex 后，你会发现它不是一个聊天工具，而是一个能落地干活的开发搭子。

如果你准备开始上手，我建议第一条命令不要太复杂，直接从这句开始：

帮我分析当前项目结构，并告诉我最值得优先优化的 3 个地方

这通常就是你和 Codex 真正进入协作状态的开始。