官方教程中文版新手必读
快速上手 Codex
基于 OpenAI 官方 Quickstart，帮助新手选择 Codex 入口，并完成第一次安全、可验证的使用。
Quickstart 的重点不是“装哪个最专业”，而是先选对入口、做一个低风险任务、学会检查结果。
订阅、套餐、可用地区和默认额度都可能变化。开始前以官方 Quickstart、Pricing 和账号后台显示为准。
四个入口
flowchart LR
Task["你的任务"] --> App["App"]
Task --> IDE["IDE extension"]
Task --> CLI["CLI"]
Task --> Cloud["Cloud"]Codex 不是只有一个用法：
- App：桌面应用，适合在本机项目里直接使用。
- IDE extension：把 Codex 放进 VS Code、Cursor、Windsurf 这类编辑器。
- CLI：在终端里使用，适合熟悉命令行和本地工程流程的人。
- Cloud：在浏览器里的云端环境运行任务，适合后台执行、查看日志、创建 PR。
如果你还不确定，从 App 或 IDE extension 开始。CLI 和 Cloud 更适合已经知道项目结构、权限边界和验证方式的人。
官方 quickstart 的共同步骤
不同入口界面不同，但第一条路径基本一致：
- 安装或打开入口。
- 登录 ChatGPT account 或 API key。
- 选择项目或连接 repository。
- 发送第一条低风险消息。
- 查看 Codex 的解释、计划、diff 或日志。
- 用 Git 和测试确认结果。
App、IDE extension、CLI、Cloud 都围绕同一件事：让 Codex 在一个明确项目里完成受控任务。区别只是任务运行在本机、编辑器、终端还是 cloud environment。
第一次不要做什么
第一次使用 Codex，不要直接让它：
- 重构项目。
- 做完整产品。
- 全面优化。
- 升级依赖。
- 改认证、支付、权限。
- 处理生产故障。
这些任务范围太大，新手很难判断结果好坏。
第一条消息最好是只读任务：
请先阅读这个项目，告诉我它的主要结构、启动方式、关键目录，以及你建议我从哪里开始做一个小改动。不要修改文件。这条消息的价值是确认三件事：Codex 是否在正确项目里、是否理解现有结构、是否能用仓库证据说话。
第一个小改动怎么选
选这样的任务：
- 只影响 1 到 2 个文件。
- 有明确预期行为。
- 可以用现有测试、lint、build 或手动检查验证。
- 不涉及账号、支付、权限、部署、数据迁移。
- 即使失败也容易回滚。
示例：
请把这个页面的空状态文案改得更清楚，只修改相关组件和测试。改完后运行这个组件对应的测试。如果找不到测试，说明你检查过哪里。不建议：
请全面优化这个项目，让它达到生产级。后者没有边界，也没有验收方式。
安全上手流程
建议按这个顺序完成第一次使用：
- 选择一个真实但不关键的项目。
- 确认 Git 工作区干净，或至少知道当前有哪些改动。
- 让 Codex 先做只读项目介绍。
- 让它提出一个很小的修改计划。
- 只批准一个边界明确的小任务。
- 查看 diff，确认没有无关文件。
- 运行测试、lint、build 或项目已有验证命令。
把 Codex 当成会改代码的协作者，不是一次性外包工具。每一步都要能看见边界和证据。
各入口怎么选
App 适合：
- 想用官方桌面应用处理本地项目。
- 不想先理解 CLI 参数。
- 希望从 local workflow 开始。
IDE extension 适合：
- 主要在 VS Code、Cursor 或 Windsurf 里开发。
- 希望一边看代码一边对话。
- 想让 Codex 跟随当前编辑器上下文。
CLI 适合：
- 熟悉终端。
- 能看懂命令输出、Git diff、测试结果。
- 希望在脚本化或本地工程流里使用 Codex。
Cloud 适合：
- 想把任务放到云端环境后台执行。
- 需要连接 GitHub 仓库并创建 PR。
- 能审查日志、diff 和最终分支。
常见坑
- 在错误文件夹里启动 Codex。
- 一上来给超大任务，导致结果不可审查。
- 没看 diff 就接受改动。
- Codex 说跑了测试，但你没有核对输出。
- 不知道当前是 local 还是 cloud。
- 用 API key 登录后，误以为所有 ChatGPT 登录能力都完全一样。
- Cloud environment 没配好，就把问题归因给模型能力。
判断第一次成功
第一次成功不等于做出一个大功能，而是完成一个可控闭环：
- Codex 能正确识别项目结构。
- 你知道它在哪个目录工作。
- 它没有修改只读任务里的文件。
- 第一个小改动只影响预期文件。
- diff 能看懂。
- 至少有一种验证方式能证明改动可用。
完成这个闭环后，再继续学习 prompt、配置、安全权限、Cloud environment 和团队流程。
新手常用 prompt 模板
只读项目理解：
Read this project without editing files. Explain its purpose, main modules, run commands, test commands, and the safest first small task.小范围修改：
Make the smallest change needed for this behavior. Before editing, list the files you expect to touch. After editing, run the narrowest validation command.结果审查：
Review your own diff. List any unrelated changes, unverified assumptions, and tests that still should be run.这些模板的重点是让 Codex 先声明范围，再执行，再证明。