Codex 实战篇：如何安装、创建第一个项目，并完成第一次运行
![]()
一、开始之前，你需要准备什么？
先说结论：第一次使用 Codex，不建议一上来就打开复杂项目。
你只需要准备这几样东西：
| 准备项 | 说明 |
|---|---|
| OpenAI / ChatGPT 账号 | Codex 支持 ChatGPT 登录，也支持 API Key 登录；Cloud 相关能力通常需要 ChatGPT 登录 |
| 一台电脑 | Codex App 支持 macOS 和 Windows；CLI 可用于 macOS、Windows、Linux |
| 一个空文件夹 | 第一次建议用空目录练习，避免误改真实项目 |
| Git | 强烈建议安装，用来查看改动和回滚 |
| 浏览器 | 用来登录、预览生成的网页 |
注意：Codex 的套餐、额度、可用模型和功能会变化，具体以 OpenAI 官方页面和你账号实际显示为准。本文重点讲“第一次怎么跑通”，不把精力放在套餐对比上。
二、先选对入口：App、CLI、IDE、Web 到底用哪个？
很多新手卡住的第一步，不是安装失败，而是不知道自己该用哪个入口。
我的建议很简单：
| 入口 | 适合谁 | 第一次是否推荐 |
|---|---|---|
| Codex App | 零基础、新手、想看界面和文件改动的人 | 推荐 |
| Codex CLI | 熟悉终端、想在项目目录里直接工作的人 | 推荐给开发者 |
| Codex IDE Extension | VS Code、Cursor、Windsurf 等编辑器用户 | 适合日常开发 |
| Codex Web / Cloud | 想连接 GitHub、跑远程任务、生成 PR 的人 | 第二阶段再学 |
如果你是第一次用，我建议走这条路线：
Codex App → 选择一个空目录 → Local 模式 → 让它生成一个静态网页 Demo
原因是：桌面 App 能看到项目、线程、终端、文件改动和 Diff，对新手最直观。
三、安装 Codex：按你的系统选择方式
Codex 的安装入口可能会随版本更新，所以最稳的方式是先看官方 Quickstart：
OpenAI Codex Quickstart
下面给你一个实用版路线。
1. macOS：优先安装 Codex App
如果你是 macOS 用户，建议先安装 Codex App。
安装后打开 App，按提示登录。登录方式通常有两种：
- 使用 ChatGPT 账号登录
- 使用 OpenAI API Key 登录
如果你只是个人学习，优先用 ChatGPT 账号登录会更直观。API Key 更适合自动化、CI/CD 或脚本化场景。
如果你已经装好了 CLI，也可以在项目目录运行：
codex app .
这个命令会尝试打开 Codex 桌面端，并把当前目录作为工作目录。
2. Windows：可以用安装包，也可以用 winget
Windows 用户可以从官方文档提供的 Windows App 链接安装，也可以使用命令行方式：
winget install Codex -s msstore
安装完成后，打开 Codex App，登录账号，然后选择项目目录。
Windows 上还有一个容易混淆的点：你可以选择原生 PowerShell 工作流，也可以在 WSL2 里使用 Linux 环境。第一次建议先用默认方式，等你确认自己的项目依赖需要 Linux 工具链时，再考虑 WSL2。
3. CLI：适合熟悉终端的人
如果你想用命令行方式，官方手册中提供了脚本化安装示例。
macOS / Linux：
curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh
Windows PowerShell：
$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex
这里要注意：CODEX_NON_INTERACTIVE=1 是跳过安装提示的脚本化方式，更适合自动化安装。第一次安装时，如果官方 Quickstart 页面给了交互式入口，优先按官方页面来。
安装完成后，验证命令：
codex --version
如果提示 command not found: codex，大概率是安装目录没有加入 PATH。这时不要急着重装，先重新打开终端，或者检查安装输出里提示的路径。
4. IDE 插件：适合已经在编辑器里写代码的人
如果你习惯 VS Code、Cursor、Windsurf 这类编辑器，可以安装 Codex IDE Extension。
装好后，Codex 会出现在编辑器侧边栏。它的优势是可以直接读取你打开的文件和选中的代码，适合做局部修改、解释文件、写测试。
第一次学习时，我仍然建议先用 App 或 CLI 跑通完整流程，再把 IDE 插件作为日常开发入口。
四、登录：ChatGPT 和 API Key 怎么选？
Codex 支持两种常见登录方式：
| 登录方式 | 适合场景 |
|---|---|
| ChatGPT 登录 | 个人使用、桌面 App、IDE、Cloud 任务 |
| API Key 登录 | CLI 自动化、脚本、CI/CD、按 API 用量计费 |
官方文档里也明确提到：Codex Cloud 需要使用 ChatGPT 登录；CLI 和 IDE Extension 支持 ChatGPT 登录和 API Key 登录。
新手建议：
第一次：ChatGPT 登录 进阶自动化：API Key 团队/企业环境：按管理员策略来
API Key 不要写进 Prompt，也不要发给别人。它应该放在受控环境变量、密钥管理工具或 Codex 登录流程里。
如果登录时浏览器打不开，或者你在远程服务器/无图形界面环境里，可以尝试：
codex login --device-auth
这会走设备码登录流程：终端给你一个链接和一次性 code，你在浏览器里完成登录。
五、创建第一个项目：不要从真实项目开始
第一次练习，建议创建一个空目录。
mkdir first-codex-demo cd first-codex-demo git init
为什么要 git init？
因为你需要知道 Codex 到底改了什么。哪怕只是生成一个网页，也建议用 Git 来看文件变化。
接下来有两种方式。
方式一：用 Codex App 打开目录
如果你安装的是桌面 App：
- 打开 Codex App。
- 选择或添加项目目录 first-codex-demo。
- 新建一个 thread。
- 模式选择 Local。
- 输入第一条任务。
第一次建议选择 Local，因为它直接在当前目录工作，最容易理解结果。
Worktree 更适合你已经有 Git 项目，并且希望把改动隔离到单独工作区时使用。新手第一轮不必急着上 Worktree。
方式二：用 CLI 进入目录
如果你用 CLI：
cd first-codex-demo codex
进入交互界面后，直接输入任务即可。
如果你想从终端打开桌面 App：
codex app .
六、第一次运行：直接复制这个 Prompt
第一次任务不要做复杂系统，不要让它接入数据库，不要让它改真实业务项目。
我们只做一个静态网页 Demo。
你可以复制下面这段：
请在当前目录创建一个静态网页 Demo。 主题：零基础入门 Codex 要求： 1. 只使用 HTML、CSS、JavaScript。 2. 页面包含标题、介绍、3 个步骤、注意事项。 3. 样式简洁，适合技术博客截图展示。 4. 不要引入复杂框架或外部依赖。 5. 完成后告诉我生成了哪些文件，以及如何打开预览。 执行方式： 先给出计划，再创建文件，最后检查页面能否正常打开。
这个任务设计得很简单，但它能验证 Codex 的完整链路：
| 验证点 | 你要看什么 |
|---|---|
| 是否能理解目标 | 它是否给出合理计划 |
| 是否能创建文件 | 目录里是否出现 HTML/CSS/JS |
| 是否能说明结果 | 它是否告诉你怎么打开 |
| 是否能自检 | 它是否检查文件或预览方式 |
| 是否方便回滚 | Git Diff 是否清楚 |
Codex 运行时，你可能会看到它读取目录、创建文件、运行命令、总结结果。这就是第一次实战最重要的体验：它不是只给你一段代码，而是真的在项目里推进任务。
七、第一次完成后，你要怎么验收？
不要只看 Codex 最后说“完成了”。你要自己确认。
建议按这个顺序检查：
ls git status git diff
如果它生成了 index.html，你可以直接用浏览器打开。
如果它启动了本地服务，注意看它给你的地址，比如：
http://localhost:3000 http://127.0.0.1:5173
如果页面能打开，文件也能看到，Git Diff 也能读懂，那你的第一次运行就算跑通了。
八、新手第一次最容易卡在哪里？
下面这些卡点非常常见，不用慌。
1. codex 命令不存在
现象：
command not found: codex
可能原因：
- CLI 没安装成功
- 安装目录没进 PATH
- 终端没有重新打开
处理方式：
codex --version
如果仍然找不到，回到官方 Quickstart 重新确认安装步骤。
2. 登录卡住或浏览器打不开
如果普通登录流程失败，可以尝试设备码登录：
codex login --device-auth
如果你在公司网络里，还可能遇到代理、证书、TLS 拦截等问题。官方文档里也提到，可以通过 CODEX_CA_CERTIFICATE 指定企业证书 bundle。
3. Codex 一直在等你批准
这是正常的。Codex 要运行命令、读写文件、访问网络时，可能会向你请求批准。
如果你不确定，就选更小的权限，比如只批准这一次。不要第一次就开全权限。
你要记住：
审批不是麻烦，而是保护你的项目。
4. 选错目录
这是新手高频问题。
如果你以为自己在 first-codex-demo，但实际在别的目录，Codex 就会在错误的位置工作。
解决方式：
pwd git status
在 Codex App 里，也要确认当前打开的是正确项目。
5. Worktree 里项目跑不起来
如果你一开始就用了 Worktree，可能会遇到依赖缺失。
原因是：Worktree 是一个隔离目录，很多未提交、被 .gitignore 忽略的本地配置、依赖、环境文件可能不会自动带过去。
第一次建议先用 Local 模式。等你熟悉之后，再学习 Worktree。
6. 文件面板里出现很多“不是 Codex 改的文件”
如果你的项目本来就有未提交改动，Codex App 的 Review/Diff 面板可能会显示已有 Git 状态。
这不一定是 Codex 改了它们。
你可以：
- 开始前先保持工作区干净
- 用 git status 确认
- 在 App 里查看 Last turn changes
九、第一次成功后，下一步练什么？
如果你已经成功让 Codex 创建了一个静态网页，下一步可以逐步加难度。
练习 1：让它修改已有页面
请把页面改成响应式布局，适配手机屏幕。 完成后说明你改了哪些 CSS。
练习 2：让它添加交互
请给页面增加一个“复制 Prompt 模板”的按钮。 点击后复制一段固定文本，并显示复制成功提示。
练习 3：让它自检
请检查当前页面是否存在明显的移动端布局问题。 如果有，请先列出问题，再修改。
练习 4：让它写 README
请为这个 Demo 写一个 README.md。 包括项目介绍、文件结构、如何运行、后续可扩展方向。
这样你就会逐渐理解 Codex 的协作方式：
明确目标 → 小步执行 → 查看结果 → 继续追问 → 再次验收
十、完整流程复盘
最后我们把第一次使用流程串起来：
1. 看官方 Quickstart，选择安装入口 2. 新手优先安装 Codex App 3. 使用 ChatGPT 账号登录 4. 创建空目录 first-codex-demo 5. git init 6. 在 App 中选择该目录 7. 选择 Local 模式 8. 发送静态网页 Demo Prompt 9. 查看生成文件 10. 打开页面预览 11. 用 git diff 检查改动 12. 继续提出小步修改需求
如果你完成了这 12 步，恭喜，你已经不只是“看过 Codex”，而是真正完成了第一次 Agent 协作。
十一、总结
Codex 的上手关键，不是记住多少命令，而是建立三个习惯：
- 选对工作目录。
- 给清楚任务边界。
- 自己验收结果。
第一次不要追求复杂。只要能让 Codex 在空目录里生成一个可打开的网页，你就已经跑通了最核心的闭环：
任务 → 执行 → 文件 → 预览 → Diff → 验收