入门基础概览
背景：Codex 解决什么问题
如果你已经在用 Cursor、Copilot 或 ChatGPT 写代码，可能会遇到两类重复劳动：
- 向 AI 粘贴大段文件，上下文容易断。
- AI 只给文字建议，改文件、跑测试、看 diff 仍要你自己动手。
Codex 是 OpenAI 提供的 AI 编程助手。它可以在你的项目目录里读文件、改文件、执行命令；也可以在浏览器或 GitHub 上处理云端任务。和 ChatGPT 网页聊天的主要差别在于：Codex 默认以 Agent 模式工作，目标是产出可检查的代码变更，而不是只输出一段解释。例如，同样说「修这个测试失败」——ChatGPT 通常会给出排查步骤；Codex 会在仓库里定位相关文件、尝试修改并运行测试，把 diff 交给你审查。
平台能力、套餐限制以 OpenAI Codex 官方文档为准；本文写于 2026-06-24。
Codex 能做什么
对个人开发者，Codex 最常落在下面三类任务上。表格里的「前置条件」指任务开始前你最好先准备好的约束；没有这些约束，输出质量会明显下降。
| 任务类型 | 典型例子 | 你能得到什么 | 建议的前置条件 |
|---|---|---|---|
| 理解代码 | 「这个项目的路由是怎么组织的？」 | 按模块梳理入口、依赖和调用关系 | 指明仓库路径或关键目录 |
| 实现改动 | 「给登录页补一个忘记密码入口」 | 可运行的 diff，附基本验证步骤 | 说明验收标准；任务前做一次 Git 提交 |
| 排查修复 | 「修复这个 500 错误，改动尽量小」 | 定位路径 + 最小改动方案 | 提供报错信息、复现步骤或测试命令 |
上面三类任务有一个共同前提：你要能描述「什么叫完成」。例如「编译通过」「某个接口返回 200」「现有测试仍绿」。描述越具体，Codex 越不容易在无关文件上扩散改动。
哪些情况要先补约束
下面几类场景也可以交给 Codex，但直接动手往往代价更高。更稳妥的做法是先补约束，再发任务。
| 场景 | 风险从哪来 | 开工前先做什么 |
|---|---|---|
| 大范围重构 | 改动面大，回滚成本高 | 先提交 Git；拆成小任务逐步做 |
| 需求只有一句话 | 缺少验收标准，输出方向容易偏 | 写清输入、输出、边界和不要改的范围 |
| 生产环境变更 | 涉及密钥、权限或合规审批 | 先在本地或 staging 验证；敏感信息不要写进 prompt |
| 无 Git 的实验目录 | 改乱后难以恢复 | 初始化仓库或复制一份再试 |
权限、沙箱、命令执行边界会在后续「权限与安全」章节展开。本章先把「能跑起来」和「敢让它改」这两件事分开看。
四个入口，选哪个
Codex 有四个常用入口：桌面 App、IDE 扩展、CLI、Cloud。它们共享同一套能力，差别主要在操作界面和代码执行位置。
| 入口 | 适合谁 | 代码跑在哪 | 上手成本 |
|---|---|---|---|
| 桌面 App | 希望用图形界面管项目和对话 | 本机 | 安装应用 |
| IDE 扩展 | 已在 VS Code / Cursor 里写代码 | 本机 | 安装扩展 |
| CLI | 习惯终端、想把流程写进脚本 | 本机 | 一条安装命令 |
| Cloud | 不想占本机资源，希望在 GitHub 上异步改代码 | OpenAI 云端 | 浏览器 + GitHub 连接 |
安装步骤和第一条任务，见本章第二篇「30 分钟 Quickstart」。
本章五篇文章分别写什么
本章按「先跑通，再补全」排列。每篇开头有一段可直接执行的结论，不必从第一篇线性读到第五篇。
| 顺序 | 文章 | 读完后你应能回答的问题 | 预计用时 |
|---|---|---|---|
| 1 | 入门基础概览（当前页） | Codex 适合做什么、下一篇该读哪篇 | 5 分钟 |
| 2 | 30 分钟 Quickstart | 该用 App、CLI、IDE 还是 Cloud？怎么发出第一条任务？ | 30 分钟 |
| 3 | 登录与认证 | ChatGPT 登录和 API Key 各适合什么场景？无浏览器环境怎么登录？ | 15 分钟 |
| 4 | 桌面 App 安装 | macOS / Windows 怎么装、装完怎么确认成功？ | 10 分钟 |
| 5 | 订阅 ChatGPT 套餐 | Plus 够不够？国内常见订阅方式有哪些？ | 按需查阅 |
按你的情况选下一篇
第一次用 Codex，想尽快看到结果 → 读「30 分钟 Quickstart」。如果选桌面 App，可对照「桌面 App 安装」完成安装。
已经装了 App，卡在登录或套餐 → 读「登录与认证」和「订阅 ChatGPT 套餐」。
更习惯终端或 IDE，不想装桌面 App → 跳过安装篇，从 Quickstart 的 CLI / IDE 小节开始。
要在 CI 或无图形界面的服务器上用 Codex → 优先读「登录与认证」里关于 API Key 和无头登录的部分。
跑通本章后，可按「提示词与上下文工程 → 使用方式 → 实战项目」继续深入；各章概览见专栏目录。
新手常见卡点
下面这些问题在入门阶段出现频率较高。现象、原因和处理方式列在一起，方便对照。
| 现象 | 常见原因 | 本章里可以先做什么 |
|---|---|---|
| 登录后功能灰色或额度很少 | 免费套餐对 Codex 能力有限制 | 查「订阅 ChatGPT 套餐」 |
| Codex 改乱代码，难以恢复 | 任务前没有 Git 检查点 | 按 Quickstart 里的验证清单，任务前先提交 |
| Cloud 任务无法启动 | 未用 ChatGPT 登录，或 GitHub 未连接 | 查「登录与认证」 |
| 远程 SSH 里浏览器登录失败 | OAuth 回调地址指向本机 localhost | 查「登录与认证」的无头登录说明 |
| 输出和预期差很远 | 需求描述缺少验收标准 | 写清「做什么、不做什么、怎样算完成」后再发任务 |
你现在可以做的三件事
- 对照上文「四个入口」表格，选定一个入口。
- 打开「30 分钟 Quickstart」，按选定入口完成第一条带验收标准的任务。
- 任务前后各做一次 Git 提交，确认你能回滚 Codex 的改动。
本章达成标准：你在 Quickstart 里完成一条可验证任务，且能用 Git 回滚这次改动，即可进入本章下一篇。