Codex 新手指南：先读项目、控权限、看 diff、小步改代码，再用 Git 和测试兜底。
原文标题：Codex 入门指南，从零基础到实战，看这一篇就够了！
原文作者：图灵编辑部
冷月清谈：
文章梳理了 Codex 的主要入口：桌面应用适合新手，IDE 扩展适合长期使用 VS Code、Cursor 等编辑器的人，CLI 更适合熟悉终端的开发者，Web / 云端适合 GitHub 后台任务和 PR 流程。文中还强调 Git 检查点、权限审批、沙箱、diff 审阅、测试验证的重要性，并给出多种可直接复用的提示词模板，包括读项目、修 bug、加功能、代码评审和 UI 任务。
进阶部分介绍了 AGENTS.md 的作用，可以把项目约定、测试命令、代码风格和禁改目录写给 Codex，减少重复沟通。文章核心观点是：使用 Codex 的安全路径是先理解项目、给出方案、小步修改、审阅 diff、运行测试，再逐步迭代。
怜星夜思：
2、如果团队已经有代码规范，你会把哪些规则写进 AGENTS.md？
3、Codex 这类编码智能体会不会改变程序员学习编程的方式？
4、你会让 Codex 直接在真实项目里改代码吗？什么情况下可以，什么情况下不行？
原文内容
一份面向新手的 OpenAI Codex 入门指南，覆盖 Codex 应用、IDE 扩展、CLI、Web / 云端，以及权限、沙箱、Git 检查点、AGENTS.md 和提示词模板。
本文中提到的 Codex，指的是 OpenAI 当前的 Codex 编码智能体。它可以帮你读代码、看懂陌生的仓库、做代码评审、排查问题，并通过 Codex 应用、IDE 扩展、CLI 和 Web / 云端这几个入口为你工作。
文中截图来自 OpenAI 的官方页面或官方 GitHub 仓库，实际界面可能随时间变化。
这份指南写给谁
这份指南面向从未用过 Codex 的人，也包括目前还不太会写代码的读者。你不需要先把所有 AI 智能体相关概念都搞懂，只需要先记住一句话：
Codex 不只是一个 AI 聊天窗口。它可以进入一个代码项目，读文件、改文件、执行命令，并把改完之后的 diff 呈现给你看。
正因为 Codex 能动到项目里的文件，新手最关键的习惯，不是一上来就让它帮我做一个完整的项目，而是先学会：
-
先让它把项目读一遍；
-
让它先给出方案；
-
一次只改一小处；
-
看 diff；
-
跑测试；
-
提前打好 Git 检查点。
下面开始今天的内容：
1. Codex 是什么？
Codex 是一个可以在代码项目里干活的 AI 编码助手。
你可以用自然语言描述任务，例如：
请帮我解释一下这个项目是做什么的。
请找出这个 bug 的原因，并做最小必要的修复。
请为这个函数加一个单元测试。
Codex 可以读取项目文件、分析代码，必要时修改文件、执行命令或运行测试，然后把结果和 diff 反馈给你。
简单说：ChatGPT 像是在聊天窗里问问题，而 Codex 更像是有人坐在你的项目目录里跟你一起干活。
Codex 的基本工作流程
其中最关键的是最后一步：结果仍然由你审阅。
Codex 很强，但它不是一个自动上线工具。对新手来说，最安全的心态是：把它当成一个能力很强、但产出仍需要复核的助手。
2. Codex 长什么样？
图 1：Codex 欢迎 / 登录界面
第一次打开 Codex 应用，通常会看到欢迎界面，可以用 ChatGPT 账号登录，或填入 API Key。
Codex 欢迎登录界面
图 2：选择项目文件夹
Codex 不只是一个聊天工具，它通常需要知道自己在哪个项目里工作。你可以选择一个项目文件夹或 Git 仓库。
Codex 项目选择界面
图 3：第一次任务输入
选好项目之后，就可以描述你想让 Codex 做什么。第一次任务，建议让它解释项目，而不是改代码。
Codex 首次任务输入
图 4：Codex 应用主界面
Codex 应用是一个桌面工作台，可以同时运行多个会话，配合 worktree、自动化任务，以及集成 Git 工作流。
Codex 应用主界面
图 5：本地 / Worktree / 云端模式
在 Codex 应用里，每个会话可以使用不同模式：本地（Local）、Worktree、云端（Cloud）。
-
本地：直接在当前项目目录下工作。
-
Worktree：把改动隔离在一个新的 Git worktree 里。
-
云端：在已配置的远端云环境中运行。
Codex 应用模式选择
图 6：Git 提交面板
Codex 应用内置了 Git 工具，可以展示 diff，并辅助暂存、提交、推送和创建 Pull Request。
Codex Git 提交面板
图 7：集成终端
每个会话都可以使用集成终端。常用命令包括：
git status
npm test
pnpm run lint
Codex 集成终端
图 8：内置浏览器
对于前端项目，Codex 可以使用内置浏览器预览本地页面、查看元素、验证 UI 修复效果。
Codex 内置浏览器
图 9：VS Code / Cursor / Windsurf 中的 Codex 扩展
如果你已经在用 VS Code、Cursor、Windsurf，或其他兼容 VS Code 的编辑器，可以使用 Codex 的 IDE 扩展。
Codex IDE 扩展入口
图 10：IDE 中的权限模式
Codex IDE 扩展支持 Chat、Agent、Agent Full Access 等模式。新手应当先从 Chat 或普通 Agent 模式起步，而不是一上来就开 Full Access。
Codex IDE 审批模式
图 11：CLI 界面
Codex CLI 让编码智能体直接在你的终端里工作，更适合已经熟悉命令行的人。
Codex CLI 终端界面
图 12：在 GitHub 上请求 Codex 评审
配置好 Codex 云端 / GitHub 集成之后，可以在 GitHub PR 的评论里通过 @codex review 请求评审。
在 GitHub 上请求 Codex 评审
图 13：Codex 在 GitHub PR 中的评审评论
Codex 可以在 PR 中留下评审意见，并指向具体的代码位置和问题。
Codex 在 GitHub 上的评审示例
3. 新手需要知道的五个关键词
|
关键词
|
通俗解释
|
为什么重要
|
|---|---|---|
|
项目文件夹
|
装着你代码的那个文件夹
|
Codex 需要知道在哪里干活
|
|
Git
|
一种代码版本管理工具
|
出错时可以回滚
|
|
diff
|
改动前后的差异
|
Codex 改完后，先看 diff 再决定要不要接受
|
|
PR / Pull Request
|
一组提交去申请合并
|
常出现在 Codex 云端和 GitHub 流程里
|
|
沙箱 / 审批
|
限定 Codex 能做什么、什么时候要问你
|
帮新手避免误删或执行危险命令
|
如果暂时只能记住一个词，记住 diff。Codex 改完文件之后，不要只看它的总结，要看 diff，因为 diff 才是它真正改了什么。
4. 选入口：App、IDE、CLI 还是 Web？
Codex 有好几个入口，很多新手就卡在不知道从哪里开始这一步。
|
入口
|
适合人群
|
主要用法
|
|---|---|---|
|
Codex 应用
|
新手
|
桌面应用，选好项目然后发任务
|
|
IDE 扩展
|
已经在用 VS Code、Cursor、Windsurf 或 JetBrains 的人
|
从编辑器侧边栏唤起 Codex
|
|
CLI
|
习惯终端的人
|
从终端让 Codex 读、改、跑一个项目
|
|
Web / 云端
|
需要后台跑活的 GitHub 项目
|
在云端执行任务，看 diff，发 PR
|
我的推荐很简单：新手先用 Codex 应用。已经天天住在编辑器里的开发者，用 IDE 扩展。终端用得顺手之后再试 CLI。需要后台任务或自动 PR 的 GitHub 项目，用 Web / 云端。
5. 第一次使用：从 Codex 应用开始
5.1 账号与套餐
Codex 的可见性、配额和可用功能，会受到你的 ChatGPT 套餐、工作区权限和登录方式影响。
使用 Codex 应用时，通常可以用 ChatGPT 账号登录，也可以填入 OpenAI API Key。用 API Key 登录时，部分云端相关功能可能不可用。
5.2 下载、打开、登录
新手按这个顺序来：
-
安装 Codex 应用；
-
用 ChatGPT 账号登录；
-
选一个练手用的项目文件夹；
-
第一次任务用本地（Local）模式；
-
第一次任务让它解释项目，而不是改代码。
5.3 推荐的第一条提示词
请暂时不要修改任何文件，用中文向我解释这个项目：
1. 这个项目大致是做什么的？
2. 主要的目录分别是做什么用的？
3. 入口文件可能在哪里？
4. 如果我想跑起来，通常要执行哪些命令？
5. 有哪些你不确定的地方？请直接说“不确定”，不要猜。
核心思想是：先读，不急着改。
6. 第一条提示词：在动手之前，先让 Codex 读
新手最常见的一个坑，是上来就这样问：
帮我把整个项目重构一遍。
帮我做一个完整的网站。
帮我把所有 bug 都修了。
这种任务太宽，你自己也很难判断 Codex 做得对不对。
更安全的顺序是这样：
第一次任务可以这样问：
请暂时不要修改任何文件。先讲解一下这个项目的整体结构，并告诉我新手应该优先阅读哪些文件。
确认 Codex 对项目的理解足够清楚之后，再进入下一步。
7. 第一次改代码：只改一小处
熟悉了 Codex 对项目的理解之后，让它做一个非常小的修改。
第一次的好目标是 README：
请只修改 README.md，新增一节叫“新手如何启动这个项目”。
要求：
- 不要修改任何其他文件。
- 不要安装新的依赖。
- 不要改任何代码。
- 改完之后告诉我你改了什么。
- 如果项目里没有明确写启动命令，请直接说“不确定”，不要凭空编造命令。
Codex 改完之后，再做两件事：
git status
git diff
如果用的是 Codex 应用，也可以直接在审阅面板或 diff 面板里查看改动。
看 diff 时要看什么？
-
Codex 是否动了你没允许它动的文件？
-
是否引入了你不认识的依赖？
-
是否删除了重要的配置？
-
文字或代码内容是否符合你的要求？
-
diff 是否真的支撑了它在总结里讲的那些话？
作为新手，不需要马上看懂每一行代码。先学会“看动了哪些文件”，这一招就能避免一大半问题。
8. 可以直接抄的提示词模板
8.1 通用结构
目标：
我希望你完成什么？
上下文：
有哪些相关文件、报错、复现步骤或截图？
范围：
你可以修改哪些文件？哪些文件绝对不能动？
约束：
有哪些必须避免的事？例如：不要加依赖，不要改数据库结构，不要改 API 字段。
验证：
完成之后你要跑哪些命令？如果跑不了，要说明原因。
输出：
列出改了哪些文件、验证结果、风险点和后续建议。
这个结构很朴素，但很有用，因为它能减少“猜”的成分。
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 给新手的权限建议
|
模式
|
适合做什么
|
给新手的建议
|
|---|---|---|
|
Chat / 只读
|
解释项目、回答问题、写方案
|
先用这个
|
|
Agent / 自动
|
小范围改文件、跑测试
|
接受前看 diff
|
|
完全访问
|
跨目录、联网、复杂任务
|
不要把它当默认起点
|
9.2 遇到审批弹窗怎么办
当 Codex 请求审批时，先看它到底想干什么。
下面这些动作要特别小心：
rm -rf
sudo
curl ... | sh
npm install some-package-you-do-not-understand
Accessing system directories or directories outside the project
不确定时，选范围更窄的那个选项，或者拒绝，然后让 Codex 解释为什么需要这条命令。
9.3 不要把这些秘密交给 Codex
下面这些东西，不要直接粘到项目里、提示词里、日志里或截图里：
-
API Key
-
数据库密码
-
生产环境令牌
-
客户隐私数据
-
个人敏感信息
-
公司内部不允许外传的资料
-
生产数据库连接串
报错日志要特别小心，里面可能藏着令牌、Cookie、URL 参数或数据库连接信息。粘贴之前先扫一眼。
9.4 改之前先打 Git 检查点
在项目目录里执行：
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 或云端
请在隔离的分支或 worktree 里，尝试实现下面这个小功能：[功能描述]
要求：
- 先给方案。
- 改动保持小。
- 完成后说明如何验证。
目标：学会在隔离环境里尝试更复杂的改动。
11. 进阶：用 AGENTS.md 教 Codex 认识你的项目
经常用 Codex 之后，可以考虑在项目根目录加一个 AGENTS.md 文件。
把它当成一份写给 AI 智能体看的项目说明书。Codex 在开始工作之前会读这些约定，从而更贴合你们团队的规范。
示例：
# AGENTS.md
## 项目约定
- 修改 JavaScript 文件之后，请运行 npm test。
- 在用户确认之前，不要新增生产依赖。
- 修改公共工具函数时，相应文档也要更新。
- 最终总结里，请列出改动文件、验证情况和风险。
适合写进 AGENTS.md 的内容包括：
-
启动命令；
-
测试、构建、lint 命令；
-
代码风格；
-
绝对不能动的目录；
-
发布流程；
-
PR 要求；
-
数据库和 API 的兼容规则。
一个实用的判据：当你不得不第二次提醒 Codex 同一件事时，就该考虑把它写进 AGENTS.md。
12. 常见问题
Q1：我不会写代码，可以用 Codex 吗？
可以，但要从“解释项目”“整理文档”“看懂这条报错”“写学习路线”这类任务开始，不要一上来就让它做大幅重构。
你可以把 Codex 当作学习助手，但它改完文件之后，你仍然要看 diff、验证结果。
Q2：到底用 Codex 应用、IDE、CLI 还是 Web？
新手先用 Codex 应用。如果你已经每天用 VS Code、Cursor 或 Windsurf，那就用 IDE 扩展。终端用得顺手之后再上 CLI。GitHub 项目需要后台任务或建 PR 时，用 Web / 云端。
Q3：Codex 改错了怎么办？
先看 diff。不满意就让它再调整。如果项目已经被改乱，用 Git 回滚。
如果你还没学 Git，先在练习项目上练，再让 Codex 在重要项目里做大改动。
Q4：Codex 让我批准一条命令，要不要同意？
只批准你能看懂的命令。
特别留意这些场景：删除文件、安装依赖、访问项目之外的目录、从网络下载、执行脚本。
不懂的时候，可以这样问 Codex：“请解释一下这条命令是做什么的，为什么必要，有没有更安全的做法。”
Q5：我必须要 API Key 吗？
不一定。
Codex 应用可以用 ChatGPT 账号登录，也可以用 OpenAI API Key。使用 API Key 时，云端会话等部分功能可能不可用。
Q6：Codex 能直接帮我部署吗？
不要让 Codex 在没有人复核的情况下操作生产环境。
更安全的流程是小任务 -> 审 dif -> 跑测试-> 看风险-> 提交 / PR -> 上线前由人确认
最后
开始用 Codex 的正确方式，不是一把帮我把整个项目做好。
而是：先解释项目-> 给方案-> 改一小处-> 看 diff-> 跑测试-> 迭代
任务小一点、权限收紧一点、把验证讲明白，你就可以从第一天起，安全地用 Codex 来读代码、改代码、评审代码。
用好 Codex 这些书也推荐你看看👇
《图解 Skill：AI 提效实战指南》
宝玉 | 著
知名 AI 应用专家宝玉结合自身实战经验，撰写了这本技能实操指南，旨在帮助读者将个人经验转化为智能体可执行的技能，摆脱“AI 工具人”困境，真正实现工作自动化。 作者手把手教你掌握：3 个单技能模板、1 条组合式写作工作流、1 套技能工程方法论、1 次从零开始完整迭代的技能项目实战。本书不绑定平台，扣子、Claude Code、OpenClaw 均可使用。也不要求读者具备编程基础，只要你想用 AI 提效，就可以通过本书学会技能，并立刻投入使用。
覃立波，冯骁骋，刘乾｜译
