Codex 入门指南 · 阅读笔记

Codex 不只是一个 AI 聊天窗口。它可以进入一个代码项目，读文件、改文件、执行命令，并把改完之后的 diff 呈现给你看。

新手的六个关键习惯

先让它把项目读一遍
让它先给出方案
一次只改一小处
看 diff
跑测试
提前打好 Git 检查点

1

Codex 是什么

Codex 是一个可以在代码项目里干活的 AI 编码助手。你可以用自然语言描述任务，例如：

请帮我解释一下这个项目是做什么的。
请找出这个 bug 的原因，并做最小必要的修复。
请为这个函数加一个单元测试。

它可以读取项目文件、分析代码，必要时修改文件、执行命令或运行测试，然后把结果和 diff 反馈给你。

ChatGPT 像是在聊天窗里问问题；Codex 更像是有人坐在你的项目目录里跟你一起干活。

它很强，但它不是自动上线工具。
结果仍然由你审阅。

2

五个必须认识的关键词

关键词	通俗解释	为什么重要
项目文件夹	装着你代码的那个文件夹	Codex 需要知道在哪里干活
Git	一种代码版本管理工具	出错时可以回滚
diff	改动前后的差异	改完后先看 diff，再决定要不要接受
PR	一组提交去申请合并	常出现在云端和 GitHub 流程里
沙箱 / 审批	限定它能做什么、什么时候要问你	避免误删或执行危险命令

只记一个词

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

3

选入口：先从哪里开始

入口	适合人群	主要用法
Codex 应用	新手	桌面应用，选好项目然后发任务
IDE 扩展	已在用 VS Code、Cursor、Windsurf 或 JetBrains 的人	从编辑器侧边栏唤起 Codex
CLI	习惯终端的人	从终端让 Codex 读、改、跑一个项目
Web / 云端	需要后台跑活的 GitHub 项目	在云端执行任务，看 diff，发 PR

新手 → Codex 应用编辑器常驻 → IDE 扩展终端顺手 → CLI 后台任务 → Web / 云端

4

第一次使用：从应用开始

按这个顺序来

安装 Codex 应用
用 ChatGPT 账号登录
选一个练手用的项目文件夹
第一次任务用本地（Local）模式
第一次任务让它解释项目，而不是改代码

账号的可见性、配额和可用功能，会受到 ChatGPT 套餐、工作区权限和登录方式影响。用 API Key 登录时，部分云端相关功能可能不可用。

新手最常见的坑

上来就这样问，任务太宽，你自己也很难判断 Codex 做得对不对：

帮我把整个项目重构一遍。
帮我做一个完整的网站。
帮我把所有 bug 都修了。

更安全的顺序

请暂时不要修改任何文件。先讲解一下这个项目的整体结构，并告诉我新手应该优先阅读哪些文件。

确认 Codex 对项目的理解足够清楚之后，再进入下一步。

6

第一次改代码：只改一小处

第一次的好目标是 README。

请只修改 README.md，新增一节叫"新手如何启动这个项目"。
要求：
- 不要修改任何其他文件。
- 不要安装新的依赖。
- 不要改任何代码。
- 改完之后告诉我你改了什么。
- 如果项目里没有明确写启动命令，请直接说"不确定"，不要凭空编造命令。

改完之后做两件事

git status
git diff

如果用的是 Codex 应用，也可以直接在审阅面板或 diff 面板里查看改动。

看 diff 时看什么

是否动了你没允许它动的文件？
是否引入了你不认识的依赖？
是否删除了重要的配置？
文字或代码内容是否符合要求？
diff 是否真的支撑了它在总结里讲的那些话？

不需要马上看懂每一行代码。先学会"看动了哪些文件"，这一招就能避免一大半问题。

7

可以直接抄的提示词模板

通用结构

目标：我希望你完成什么？
上下文：有哪些相关文件、报错、复现步骤或截图？
范围：你可以修改哪些文件？哪些文件绝对不能动？
约束：有哪些必须避免的事？例如不要加依赖、不要改数据库结构、不要改 API 字段。
验证：完成之后你要跑哪些命令？如果跑不了，要说明原因。
输出：列出改了哪些文件、验证结果、风险点和后续建议。

很朴素，但很有用，因为它能减少"猜"的成分。

读项目模板

请暂时不要修改文件，先帮我理解这个项目：
1. 这个项目是做什么的？
2. 用的是什么技术栈？
3. 入口在哪里？
4. 各个主要目录分别负责什么？
5. 作为新手，应该按什么顺序读代码？
6. 哪些地方你不确定？

修 bug 模板

我遇到了一个 bug，请帮我定位并修复。
现象：[把报错或行为粘贴到这里]
复现步骤：
1. [第一步]
2. [第二步]
3. [第三步]
要求：
- 先讲一下你判断的原因。
- 做最小必要的改动。
- 不要在没问我之前就加新依赖。
- 修复之后，跑相关测试，或说明为什么跑不了。
- 最后列出改动文件和风险。

加功能模板

请帮我加一个小功能。
功能目标：[功能描述]
范围：
- 可以改动：[文件 / 目录]
- 不要改动：[文件 / 目录]
要求：
- 先给一个简短方案。
- 每一步保持小步幅。
- 沿用现有代码风格。
- 如果需要新依赖，请先停下来问我。
- 完成后跑相关检查。
输出：
- 改了哪些文件
- 如何验证
- 哪些地方仍需要我手工检查

代码评审模板

请评审当前未提交的改动。
关注点：
1. 明显的 bug
2. 漏掉的边界情况
3. 可能造成的回归
4. 安全或性能风险
5. 是否需要补测试
要求：
- 先列高风险问题。
- 再列中、低风险建议。
- 不要修改任何文件，除非我明确要求。

UI 任务配截图模板

Codex 支持图片输入。UI 任务可以把截图、设计稿或报错截图一起提供。

请按附带的截图实现一个页面。
要求：
- 使用项目现有的技术栈。
- 在布局、间距和字号层级上，尽量贴近截图。
- 在没问我之前，不要引入新的 UI 库。
- 只加必要的组件。
- 完成后告诉我用哪个命令、打开哪个地址来查看效果。

8

安全使用：权限、沙箱与审批

模式	适合做什么	给新手的建议
Chat / 只读	解释项目、回答问题、写方案	先用这个
Agent / 自动	小范围改文件、跑测试	接受前看 diff
完全访问	跨目录、联网、复杂任务	不要把它当默认起点

这些动作要特别小心

rm -rf
sudo
curl ... | sh
安装你完全不了解的 npm 包
访问系统目录或项目之外的目录

不确定时，选范围更窄的那个选项，或者拒绝，然后让它解释为什么需要这条命令。

不要把这些秘密交给 Codex

API Key
数据库密码
生产环境令牌
客户隐私数据
个人敏感信息
公司内部不允许外传的资料
生产数据库连接串

报错日志要特别小心，里面可能藏着令牌、Cookie、URL 参数或数据库连接信息。粘贴之前先扫一眼。

改之前先打 Git 检查点

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

Codex 改完之后再跑：

git status
git diff

万一出问题，Git 给你留了一条退路。

在重要的生产项目里，不要在没有备份的情况下让 Codex 做大幅改动。

9

新手 7 天练习计划

D1 只读项目

请不要修改任何文件。解释这个项目是做什么的、目录结构、入口在哪里、怎么运行。

目标：先弄清楚这是个什么项目

D2 写项目概览

基于你对项目的理解，起草 docs/project-overview.md。
要求：面向新手；说明主要目录和启动步骤；不要修改任何代码文件。

目标：练习让它生成文档

D3 只改 README

请只修改 README.md，加上安装和启动说明。不要修改任何其他文件。

目标：练习审阅 diff

D4 修一个小 bug

报错如下：[粘贴报错]
复现步骤：
1. [第一步]
2. [第二步]
3. [第三步]
请找出原因，并做最小修复。修完跑一下相关检查。

目标：学会描述现象与复现步骤

D5 补一个测试

请为刚才修复的问题，补一个最小的测试。
要求：先讲清楚这个测试覆盖了什么；不要顺手大改动；完成后把测试跑一遍。

目标：不仅让它写代码，也让它去验证代码

D6 让它评审你的改动

请评审当前未提交的改动，关注 bug、边界情况、回归风险，以及是否需要补测试。暂时不要修改文件，只输出评审意见。

目标：把 Codex 当作多一双眼睛

D7 试一下 Worktree 或云端

请在隔离的分支或 worktree 里，尝试实现下面这个小功能：[功能描述]
要求：先给方案；改动保持小；完成后说明如何验证。

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

10

进阶：用 AGENTS.md 教它认识你的项目

经常用 Codex 之后，可以在项目根目录加一个 AGENTS.md，把它当成一份写给 AI 智能体看的项目说明书。Codex 开始工作之前会读这些约定，从而更贴合团队规范。

# AGENTS.md

## 项目约定
- 修改 JavaScript 文件之后，请运行 npm test。
- 在用户确认之前，不要新增生产依赖。
- 修改公共工具函数时，相应文档也要更新。
- 最终总结里，请列出改动文件、验证情况和风险。

适合写进去的内容

启动命令
测试、构建、lint 命令
代码风格
绝对不能动的目录
发布流程
PR 要求
数据库和 API 的兼容规则

当你不得不第二次提醒 Codex 同一件事时，
就该考虑把它写进 AGENTS.md。

11

常见问题

Q1 · 我不会写代码，可以用吗？

可以，但要从"解释项目""整理文档""看懂这条报错""写学习路线"这类任务开始，不要一上来就大幅重构。改完文件之后，你仍然要看 diff、验证结果。

Q2 · 到底用应用、IDE、CLI 还是 Web？

新手先用 Codex 应用。已经每天用 VS Code、Cursor 或 Windsurf，就用 IDE 扩展。终端用得顺手之后再上 CLI。GitHub 项目需要后台任务或建 PR 时，用 Web / 云端。

Q3 · 它改错了怎么办？

先看 diff。不满意就让它再调整。如果项目已经被改乱，用 Git 回滚。还没学 Git 的话，先在练习项目上练，再让它在重要项目里做大改动。

Q4 · 让我批准一条命令，要不要同意？

只批准你能看懂的命令。特别留意：删除文件、安装依赖、访问项目之外的目录、从网络下载、执行脚本。不懂时可以问它："请解释一下这条命令是做什么的，为什么必要，有没有更安全的做法。"

Q5 · 必须要 API Key 吗？

不一定。Codex 应用可以用 ChatGPT 账号登录，也可以用 OpenAI API Key。使用 API Key 时，云端会话等部分功能可能不可用。

Q6 · 能直接帮我部署吗？

不要让 Codex 在没有人复核的情况下操作生产环境。更安全的流程是：小任务 → 审 diff → 跑测试 → 看风险 → 提交 / PR → 上线前由人确认。

最后：正确的打开方式

开始用 Codex 的正确方式，不是"一把帮我把整个项目做好"。

而是：先解释项目 → 给方案 → 改一小处 → 看 diff → 跑测试 → 迭代。

任务小一点、权限收紧一点、把验证讲明白，你就可以从第一天起，安全地用 Codex 来读代码、改代码、评审代码。

从零基础到实战
看这一篇就够了