Codex 零基础使用指南：从小白到会让 AI 帮你读代码、改代码、交付代码

本文所说的 Codex，指 OpenAI 当前的 Codex coding agent。它可以帮助你读代码、理解陌生代码库、审查代码、调试问题，并可通过 Codex App、IDE 扩展、CLI、Web / Cloud 等入口使用。

本文截图来自 OpenAI 官方页面或 OpenAI 官方 GitHub 仓库中的界面图。实际界面可能随版本更新略有变化。

适合谁看？

这篇文章写给完全没用过 Codex，甚至不太会写代码的人。

你不需要先理解所有 AI Agent 概念。先记住一句话就够了：

Codex 不是只能聊天的 AI，它可以进入一个代码项目，读文件、改文件、跑命令，并把修改差异展示给你。

但也正因为它能动项目文件，新手最重要的不是一上来让它“做个完整项目”，而是学会：

• 先让它读项目；
• 再让它提计划；
• 只做小修改；
• 看 diff；
• 跑测试；
• 用 Git 留回退点。

目录

1. Codex 是什么
2. 先看真实界面：Codex 长什么样
3. 零基础先理解 5 个关键词
4. 选择入口：App、IDE、CLI、Web 怎么选
5. 第一次使用：推荐从 Codex App 开始
6. 第一次提问：先让 Codex 读项目，不要急着改代码
7. 第一次改代码：只改一个小地方
8. 提示词模板：直接复制就能用
9. 安全使用：权限、沙盒、审批、隐私
10. 7 天小白练习路线
11. 进阶：AGENTS.md 让 Codex 更懂你的项目
12. 常见问题 FAQ

1. Codex 是什么

Codex 可以理解为一个“会进入代码项目工作的 AI 编程助手”。

你可以用自然语言告诉它任务，例如：

请解释这个项目是做什么的。

请找出这个 bug 的原因，并做最小修改。

请为这个函数补一个单元测试。

它会读取项目文件、分析代码、必要时修改文件、运行命令或测试，然后把结果和修改差异展示给你。

更简单地说：ChatGPT 更像是在聊天窗口里回答你，Codex 更像是坐在你的项目目录里一起干活。

Codex 的基本工作流

  flowchart LR
    A[你提出任务] --> B[Codex 读取项目文件]
    B --> C[分析代码和上下文]
    C --> D[提出计划或直接修改]
    D --> E[运行命令 / 测试 / 检查]
    E --> F[展示总结和 diff]
    F --> G[你审查、追问、接受或回滚]

这里最关键的是最后一步：你仍然要审查结果。

Codex 很强，但它不是“自动上线机器”。新手最稳的用法，是把它当成一个能干活的助手，而不是一个不需要检查的自动驾驶。

2. 先看真实界面：Codex 长什么样

图 1：Codex 欢迎 / 登录界面

第一次打开 Codex App 时，可以看到欢迎页面，通常可选择使用 ChatGPT 账号继续，或输入 API key。

图 2：选择项目文件夹

Codex 不是只和你闲聊，它通常需要知道自己要在哪个项目里工作。你可以选择一个项目文件夹或 Git 仓库。

图 3：第一次输入任务

选择项目后，就可以在输入框里告诉 Codex 要做什么。第一次建议先让它解释项目，不要急着改代码。

图 4：Codex App 主界面：线程、项目、修改预览

Codex App 是桌面端工作台，可以并行处理多个线程，也能配合 worktree、自动化和 Git 功能使用。

图 5：Local / Worktree / Cloud 模式

Codex App 中，一个线程可以选择不同模式：Local、Worktree、Cloud。

• Local：直接在当前项目目录工作；
• Worktree：把改动隔离到新的 Git worktree；
• Cloud：在配置好的云环境中远程运行。

图 6：Git 提交面板

Codex App 内置 Git 工具，可以展示 diff，也可以 stage、commit、push、创建 PR。

图 7：内置终端

每个线程可以使用内置终端，常见用途包括：

git status
npm test
pnpm run lint

图 8：App 内置浏览器

做前端项目时，Codex 可以借助 App 内置浏览器预览本地页面、检查页面元素，或验证 UI 修复。

图 9：VS Code / Cursor / Windsurf 中的 Codex 扩展

如果你已经使用 VS Code、Cursor、Windsurf 或 VS Code 兼容编辑器，可以用 Codex IDE 扩展。

图 10：IDE 中切换权限模式

Codex IDE 扩展支持 Chat、Agent、Agent Full Access 等模式。新手建议先用 Chat 或普通 Agent 模式，不要一开始就给 Full Access。

图 11：CLI 终端界面

Codex CLI 是在终端里运行的 coding agent，更适合已经习惯命令行的开发者。

图 12：GitHub 中请求 Codex Review

当 Codex Cloud / GitHub 集成设置好后，可以在 GitHub PR 评论中使用 @codex review 请求代码审查。

图 13：Codex 在 GitHub PR 中发布 review

Codex 会在 PR 上留下 review comment，指出具体代码位置和问题说明。

3. 零基础先理解 5 个关键词

如果你现在只想记一个词，那就是 diff。

Codex 改完文件后，不要只看它的总结。一定要看 diff，因为 diff 才是它真正改了什么。

4. 选择入口：App、IDE、CLI、Web 怎么选

Codex 有多个入口。零基础用户最容易卡住的地方，就是不知道该从哪里开始。

  flowchart TD
    A[我要开始用 Codex] --> B{我会用代码编辑器吗?}
    B -- 不太会 --> C[优先用 Codex App]
    B -- 会用 VS Code / Cursor / Windsurf --> D[用 Codex IDE 扩展]
    B -- 会用终端 --> E[用 Codex CLI]
    A --> F{项目在 GitHub 上吗?}
    F -- 是，想让 Codex 后台跑任务或出 PR --> G[用 Codex Web / Cloud]
    F -- 否，本地文件夹为主 --> C

我的建议很简单：

小白优先 Codex App；开发者优先 IDE 扩展；命令行熟练后再用 CLI；GitHub 项目需要后台跑任务时再看 Web / Cloud。

5. 第一次使用：推荐从 Codex App 开始

5.1 账号与计划

Codex 的可见入口、额度和功能，会受你的 ChatGPT 计划、workspace 权限和登录方式影响。

如果你使用 Codex App，通常可以用 ChatGPT 账号登录，也可以使用 OpenAI API key。需要注意的是，用 API key 登录时，某些 Cloud 相关功能可能不可用。

5.2 下载、打开、登录

建议小白按这个顺序：

1. 安装 Codex App。
2. 使用 ChatGPT 账号登录。
3. 选择一个练习项目文件夹。
4. 第一次先选择 Local。
5. 第一次任务只让 Codex 解释项目，不要让它改代码。

5.3 第一次推荐输入

请先不要修改任何文件。请用中文解释这个项目：

1. 这个项目大概是做什么的？
2. 主要文件夹分别有什么作用？
3. 入口文件可能在哪里？
4. 如果我要运行它，通常要执行哪些命令？
5. 你有哪些不确定的地方？请明确说“不确定”，不要猜。

这条 prompt 的核心是：先读项目，不改项目。

6. 第一次提问：先让 Codex 读项目，不要急着改代码

新手最容易犯的错误，是第一次就说：

帮我重构整个项目。

帮我做一个完整网站。

把所有 bug 都修了。

这些任务范围太大，你很难判断 Codex 改得对不对。

更好的顺序是：

  flowchart TD
    A[第一步：解释项目，不改文件] --> B[第二步：让 Codex 提计划]
    B --> C[第三步：只改一个小地方]
    C --> D[第四步：运行检查或说明无法检查]
    D --> E[第五步：看 diff]
    E --> F[第六步：接受、追问或回滚]

第一次可以这样问：

请先不要修改文件。请解释这个项目的结构，并告诉我新手应该先读哪些文件。

等你确认 Codex 对项目理解基本正确，再进入下一步。

7. 第一次改代码：只改一个小地方

等你确认 Codex 已经大致理解项目后，再让它做一个很小的修改。

推荐从 README 开始：

请只修改 README.md，新增一个“小白如何启动项目”的小节。

要求：
- 不要修改其他文件
- 不要安装新依赖
- 不要改代码
- 改完后告诉我你改了哪里
- 如果项目里没有明确启动命令，请说明“不确定”，不要编造

改完后，你要看两件事：

git status
git diff

如果你用的是 Codex App，也可以直接看 review pane 或 diff pane。

看 diff 时重点看什么？

• 有没有改到你没让它改的文件；
• 有没有新增你不认识的依赖；
• 有没有删除关键配置；
• 文案或代码是不是符合你的需求；
• 它说“已完成”的事情，diff 里是否真的体现了。

新手不要怕看不懂全部代码。先从“它到底改了哪些文件”开始，就已经能避免很多风险。

8. 提示词模板：直接复制就能用

8.1 万能结构

目标：
我想让你完成什么？

上下文：
相关文件、错误信息、复现步骤、截图是什么？

范围：
允许你改哪些文件？不允许你改哪些文件？

约束：
不要做什么？例如不要新增依赖、不要改数据库结构、不要改接口字段。

验证：
完成后请运行哪些命令？如果不能运行，请说明原因。

输出：
请列出修改文件、验证结果、风险点和下一步建议。

这个结构不复杂，但很有用。它能减少 Codex 自己猜。

8.2 读项目模板

请先不要修改文件。请帮我理解这个项目：

1. 这个项目是做什么的？
2. 技术栈是什么？
3. 入口文件在哪里？
4. 主要目录分别负责什么？
5. 我作为新手应该按什么顺序阅读？
6. 你有哪些不确定点？

8.3 修 bug 模板

我遇到一个 bug，请帮我定位并修复。

现象：
[粘贴报错或描述现象]

复现步骤：
1. [第一步]
2. [第二步]
3. [第三步]

要求：
- 先解释你认为的原因
- 只做最小必要修改
- 不要新增依赖，除非先征得我同意
- 修完后运行相关测试或说明无法运行的原因
- 最后列出修改文件和风险点

8.4 新增功能模板

请帮我新增一个小功能。

功能目标：
[描述你要的功能]

范围：
- 可以修改：[文件/目录]
- 不要修改：[文件/目录]

要求：
- 先给出简短计划
- 每一步尽量小
- 保持现有代码风格
- 如需新增依赖，先停下来问我
- 完成后运行相关检查

输出：
- 改了哪些文件
- 如何验证
- 还需要我手动检查什么

8.5 代码审查模板

请审查当前未提交的修改。

重点看：
1. 是否有明显 bug
2. 是否有边界情况遗漏
3. 是否破坏现有行为
4. 是否有安全或性能风险
5. 是否需要补测试

要求：
- 先列高风险问题
- 再列中低风险建议
- 不要直接修改文件，除非我明确要求

8.6 带截图做 UI 的模板

Codex 支持图片输入。做 UI 时，可以把截图、设计稿或报错截图一起发给它。

请根据我附上的截图实现一个页面。

要求：
- 使用当前项目已有技术栈
- 尽量匹配截图中的布局、间距和字体层级
- 不要新增 UI 库，除非先问我
- 只新增必要组件
- 完成后告诉我运行哪个命令、访问哪个页面查看效果

9. 安全使用：权限、沙盒、审批、隐私

Codex 能读文件、改文件、运行命令，所以安全边界很重要。

9.1 小白推荐权限

  flowchart LR
    A[Chat / Read-only<br/>只读、解释、规划] --> B[Agent / Auto<br/>可在工作目录内读写和运行命令]
    B --> C[Full Access<br/>更大权限和网络访问]
    A -. 新手优先 .-> A
    B -. 小任务可用 .-> B
    C -. 谨慎使用 .-> C

9.2 审批弹窗怎么选

当你看到 Codex 请求批准时，先看它要做什么。

谨慎对待这些行为：

rm -rf

sudo

curl ... | sh

npm install 某个你不了解的包

访问系统目录或项目外目录

如果你不确定，就选更窄的批准方式，或者直接拒绝，让 Codex 解释为什么需要这个命令。

9.3 不要把这些内容交给 Codex

不要把以下内容直接放进项目、prompt、日志或截图里：

• API key
• 数据库密码
• 生产环境 token
• 客户隐私数据
• 身份证、银行卡、手机号等敏感信息
• 公司未授权共享的内部材料
• 生产数据库连接字符串

尤其要注意：很多错误日志里会带 token、cookie、URL 参数或数据库连接信息。粘贴前先看一眼。

9.4 每次改代码前先做 Git checkpoint

在项目目录里执行：

git status
git add .
git commit -m "checkpoint before codex task"

Codex 改完后执行：

git status
git diff

如果改坏了，可以用 Git 回退。

如果你还不会 Git，至少先做到一点：不要在没有备份的情况下，把 Codex 放进很重要的生产项目里大改。

10. 7 天小白练习路线

第 1 天：只读项目，不改文件

请不要修改文件。请解释这个项目的用途、目录结构、入口文件和运行方式。

目标：知道项目大概是什么。

第 2 天：让 Codex 写项目说明

请根据你对项目的理解，生成一份 docs/project-overview.md 草稿。

要求：
- 面向零基础读者
- 解释主要目录和启动方式
- 不要修改代码文件

目标：练习让 Codex 生成文档。

第 3 天：只改 README

请只修改 README.md，补充“安装依赖”和“启动项目”说明。
不要修改其他文件。

目标：练习看 diff。

第 4 天：修一个小 bug

这是报错信息：[粘贴错误]

复现步骤：
1. [第一步]
2. [第二步]
3. [第三步]

请定位原因并做最小修改。修完后运行相关检查。

目标：学会提供现象和复现步骤。

第 5 天：补测试

请为刚才修复的问题补一个最小测试。

要求：
- 先说明测试覆盖什么
- 不要大范围重构
- 完成后运行测试

目标：不要只让 Codex 改代码，也要让它验证。

第 6 天：让 Codex 审查你的改动

请审查当前未提交修改，重点看 bug、边界情况、回归风险和是否需要测试。
先不要修改文件，只输出审查意见。

目标：把 Codex 当第二双眼睛。

第 7 天：尝试 Worktree 或 Cloud

请在隔离分支或 worktree 中尝试实现这个小功能：[功能描述]

要求：
- 先给计划
- 改动尽量小
- 完成后说明如何验证

目标：学会在隔离环境里尝试更复杂的改动。

11. 进阶：AGENTS.md 让 Codex 更懂你的项目

当你经常使用 Codex，可以在项目根目录添加 AGENTS.md。

可以把它理解成“给 AI Agent 看的项目说明书”。Codex 开始工作前会读取这些项目指导，帮助它理解团队约定。

示例：

# AGENTS.md

## 项目约定

- 修改 JavaScript 文件后，请运行 npm test。
- 不要新增生产依赖，除非先征得用户确认。
- 修改公共工具函数时，请同步更新 docs/。
- 输出总结时，请包含：修改文件、验证方式、风险点。

适合写进 AGENTS.md 的内容包括：

• 项目启动方式；
• 测试、构建、lint 命令；
• 代码风格；
• 不能改的目录；
• 发布流程；
• PR 要求；
• 数据库和接口兼容性要求。

一个好用的原则是：当你第二次提醒 Codex 同一件事，就应该考虑把它写进 AGENTS.md。

12. 常见问题 FAQ

Q1：我完全不会代码，可以用 Codex 吗？

可以，但建议从“解释项目”“整理文档”“读报错”“写学习路线”开始，不要一上来让它做大范围重构。

你可以把 Codex 当成辅助学习工具，但它修改文件后仍然需要你审查 diff 和验证结果。

Q2：Codex App、IDE、CLI、Web 到底选哪个？

小白优先用 Codex App；已经每天用 VS Code、Cursor 或 Windsurf，就用 IDE 扩展；会终端再用 CLI；项目在 GitHub 上且想让 Codex 后台处理任务、生成 PR 时，用 Web / Cloud。

Q3：Codex 改错了怎么办？

先看 diff，不满意就让它继续改；如果项目已经被改乱，使用 Git 回滚。

如果你还没学 Git，建议先用练习项目，不要直接在重要项目上大范围改动。

Q4：Codex 要求批准命令，我该点同意吗？

看懂命令再同意。

涉及删除文件、安装依赖、访问项目外目录、联网下载、运行脚本的命令尤其要谨慎。

看不懂时，可以直接问：

请解释这个命令要做什么、为什么必须执行、有没有更安全的替代方式。

Q5：需要 API key 吗？

不一定。

Codex App 可以使用 ChatGPT 账号或 OpenAI API key 登录。但使用 API key 时，部分功能例如 cloud threads 可能不可用。

Q6：Codex 能直接替我上线吗？

不建议让 Codex 在无人审查的情况下直接操作生产环境。

更安全的流程是：

小范围任务
→ 查看 diff
→ 运行测试
→ 审查风险
→ commit / PR
→ 人工确认后再发布

最后总结

Codex 的正确入门方式不是：

帮我一次性做完整项目。

而是：

先解释项目
→ 再提出计划
→ 只做小修改
→ 看 diff
→ 跑测试
→ 再迭代

把任务拆小、把权限收紧、把验证写清楚，你就可以从零基础开始，安全地使用 Codex 帮你读代码、改代码和审查代码。🚀

参考资料

• Web - Codex | OpenAI Developers
• Prompting - Codex | OpenAI Developers
• Get started with Codex | OpenAI
• App - Codex | OpenAI Developers
• Quickstart - Codex | OpenAI Developers
• Features - Codex app | OpenAI Developers
• IDE extension - Codex | OpenAI Developers
• Features - Codex IDE | OpenAI Developers
• CLI - Codex | OpenAI Developers
• Code review in GitHub - Codex | OpenAI Developers
• Using Codex with your ChatGPT plan | OpenAI Help Center
• Features - Codex CLI | OpenAI Developers
• Agent approvals & security - Codex | OpenAI Developers
• How your data is used to improve model performance | OpenAI Help Center
• Custom instructions with AGENTS.md - Codex | OpenAI Developers