《8000字讲透 ｜ Codex零基础入门教程》
作者: govin.eth | G哥 @goan999999
本《Codex零基础入门教程》保证你和你的兄弟姐妹都能看懂，只要小学毕业就能看明白。这不是功能词典，而是一名普通学习者从第一次打开 Codex，到真正让它完成一个可验收任务的完整路线，以最通俗易懂的语言传递给你。建议您先收藏，后边慢慢看！
第一次打开 Codex 时，我犯的错误和很多人一样：把它当成一个“更会写代码的 ChatGPT”。我在输入框里写了一句“帮我做一个网站”，然后盯着它生成文件。几分钟后页面确实能打开，但按钮有的不能点，移动端会溢出，刷新后数据消失，我也不知道它改了哪些文件。
那一刻我才明白：会生成代码，不等于会交付项目。 Codex 真正厉害的地方，不是某一次回答写得多漂亮，而是它能进入一个真实项目，读取文件、理解约束、修改代码、运行命令、检查结果，再根据反馈继续迭代。它更像一个能操作电脑和项目环境的执行者，而不是只在聊天框里给建议的问答机器人。
这也意味着，使用 Codex 的门槛并不只是“会不会写提示词”。你还要学会给它正确的工作目录、合适的权限、足够但不过量的上下文，以及明确的验收标准。只要这四件事没处理好，再强的模型也可能在错误方向上跑得很快。
这篇教程不要求你是程序员。你只需要会创建文件夹、安装软件、复制命令，并愿意在每一步查看结果。我会用一个“个人任务看板”作为练习项目，把安装、第一次对话、需求拆解、修改文件、运行测试、代码审查、长期规则和重复工作复用全部串起来。跟着做完，你得到的不只是一个 Demo，而是一套以后做网页、自动化脚本、数据工具和 AI 产品都能复用的方法。
一、先理解 Codex：它不是“替你写几段代码”，而是替你完成一段工作循环
过去我使用普通 AI 编程工具时，流程通常是：我描述问题，AI 给出代码，我复制到编辑器，报错后再把报错复制回来。上下文在聊天框、编辑器和终端之间来回搬运，最累的不是写代码，而是不断解释“我刚才做了什么”。
Codex 把这条链路接了起来。它可以在授权范围内查看项目文件、搜索代码、编辑文件、执行构建或测试命令，并把结果继续作为下一步判断依据。一个完整循环通常是：
- 理解目标：确认你到底要解决什么问题。
- 检查环境：读取目录、关键文件、项目说明和依赖。
- 制定计划：把大任务拆成可验证的小步骤。
- 执行修改：创建或编辑文件，必要时运行命令。
- 验证结果：执行测试、构建、类型检查或实际预览。
- 审查差异：确认没有误改文件，没有引入明显回归。
- 交付说明：告诉你改了什么、验证了什么、还剩什么风险。
真正有价值的是第五步和第六步。只生成代码的 Agent 很容易给你一种“已经完成”的错觉，而一个合格的 Agent 应该拿证据证明结果。以后每次下任务，我都会在结尾加一句：
这一句看起来普通，却能明显减少“代码写完了但不能用”的情况。
二、四种入口怎么选：新手先选离工作最近的那个
Codex 目前不是单一形态。你会看到桌面应用、IDE 扩展、CLI 命令行和 Web/云端。它们不是谁替代谁，而是适合不同的工作位置。
适合第一次接触 Codex 的人。你可以选择本地项目、查看文件变化、开多个任务，也不必先熟悉终端。它更像一个“AI 工作台”，不仅能处理代码，也能处理文档、表格、网页和其他文件型任务。
适合已经在 VS Code、Cursor 或 Windsurf 里写代码的人。它能直接利用当前打开的文件、选中的代码和编辑器上下文。小范围修改、解释代码、修复当前报错时，IDE 入口通常最顺手。
适合想把 Codex 放进终端工作流的人。它能在项目目录中直接运行，适合批量改动、脚本化、CI 或需要频繁执行命令的任务。本文会重点讲 CLI，因为它最能让你看清 Codex 如何读取项目、申请权限和验证结果。
适合把任务交给远程环境长时间运行，或者并行处理多个项目问题。它的优势不是“界面更简单”，而是任务可以脱离你当前电脑持续执行。但云端环境与本地环境并不完全相同，依赖、密钥、网络权限需要单独配置。
我的选择方法很简单：第一次学习用桌面应用或 CLI；正在写代码时用 IDE；需要并行或长时间执行时再用云端。不要一开始把四种入口全部配置一遍。入口越多，不代表效率越高，反而容易把注意力耗在配置上。
三、开始前只准备三样东西：项目文件夹、Git 和一个可验证的小目标
很多教程一上来就讲模型、MCP、Skills 和复杂配置。我照着配置了一堆东西，最后连第一个任务都没跑通。后来我把准备工作缩成三项：
第一，准备一个独立项目文件夹：
不要第一次就让 Codex 扫描桌面、下载目录或整个硬盘。工作目录既决定它看到什么，也决定它默认能改什么。新手最好创建一个专门练习目录：
mkdir codex-first-project
cd codex-first-project第二，安装 Git，并养成任务前后留检查点的习惯：
Git 不是程序员专属工具，它更像项目的“撤销历史”。在 Codex 动手前提交一次，任务完成后再看差异，即使修改不满意，也能准确知道发生了什么。
git init
git add .
git commit -m "before codex task"第三，选择一个能在 30 到 60 分钟内验收的小目标：
第一次不要做“完整电商平台”“微信替代品”或“全自动赚钱系统”。目标越大，你越难判断问题来自需求、模型、环境还是代码。本文的练习目标是：
四、安装 Codex 和 CLI：先用官方方式，再处理系统差异
官方当前为 macOS 和 Linux 提供独立安装脚本。在终端中运行：
curl -fsSL https://chatgpt.com/codex/install.sh | sh安装后启动并验证版本：
codex --version
codex --help第一次启动时，按界面提示选择“使用 ChatGPT 登录”或其他可用的登录方式。
优先使用官方 Windows 桌面应用或 WSL。关键是让 Codex、Git、Node/Python 和项目文件处于同一个可访问环境。最常见的 Windows 坑就是项目在 Windows 盘、依赖装在 WSL、终端又从另一个环境启动，导致命令找不到或权限异常。
五、第一次不要让它写代码：先让它解释自己看到了什么
我第一次真正建立信任，不是因为 Codex 生成了页面，而是因为我先让它做了一次只读检查。我输入：
1. 现在有哪些文件；
2. 这是一个什么状态的项目；
3. 为了完成“本地个人任务看板”，你建议采用什么最小技术方案；
4. 需要我确认的选择有哪些。
这一步有三个作用：确认它真的在正确目录、确认它理解目标、在写代码前看到技术选择。 接着让它把目标转换成可验证的验收清单：
六、提示词不用写成论文，只要补齐四个字段
新手提示词的主要问题不是不够长，而是缺字段。高质量任务必须归纳为四部分：
回答“要改变什么”。不要只说“优化一下”，而要说“新增任务时支持回车提交，并阻止纯空格内容”。
回答“应该先看哪里”。指定相关文件、目录、截图、报错或参考实现，让 Agent 先读真正相关的材料。
回答“不能破坏什么”。例如不引入新框架、不修改公共接口、不读取 .env、保持现有风格。
回答“如何证明完成”。例如测试通过、构建成功、指定交互可复现、没有新增 lint 错误。
🛠️ 交互工坊：Codex 结构化 4 字段提示词组装器
七、权限怎么选：不是越大越省事，而是刚好够用
Codex 能执行命令、修改文件和访问网络，权限过大不仅增加风险，也会让你失去观察它工作过程的机会。
🛡️ 交互工坊：Codex 权限选择与安全边界评估台
允许在当前工作区目录内创建、修改文件与执行测试命令，严格限制在选定文件夹范围内，外部系统敏感目录受到物理沙箱隔离。
我的简单规则是：读代码用只读，正常改项目用工作区，安装依赖和访问网络按次确认，删除文件、重置历史、强制推送和生产环境操作必须单独检查。权限的目标不是阻止 Codex 工作，而是让错误的影响半径可控。
八、必须认识的命令：先学 8 个，其他需要时再查
/status查看当前会话、上下文使用量和限制状态。任务越长，越应该偶尔看一次。
/model为当前任务选择模型。小修改优先速度，复杂架构和长任务提高模型能力。
/reasoning调整推理投入。低强度适合边界清楚的小改动，中高强度适合跨文件排错。
/permissions选择当前任务允许的操作范围（只读、工作区沙箱写入、全盘模式）。
/init为当前项目生成 AGENTS.md 初始模板，生成后需根据实际情况精简补充。
/plan进入规划模式，在需求不明确或任务庞大时先把实施路线定下来。
/review针对未提交修改或指定分支换位审查代码，寻找缺陷而不是单纯赞美。
/compact聊天过长时压缩早期上下文，保留目标、约束与决策，减少旧信息噪声。
九、AGENTS.md：把每次都要重复的话变成项目规则
当我连续三次提醒 Codex“不要使用 npm，请用 pnpm”“修改后要跑测试”“不要碰生成目录”时，我才理解 `AGENTS.md` 的价值。它相当于写给 Agent 的项目说明，Codex 进入项目时会自动读取相关层级的规则。
- 优先保持代码简单、可读，避免过度抽象。
- 不修改与当前任务无关的文件。
- 不读取或输出任何密钥、环境变量和个人文件。
- 每次交付都验证新增、完成切换、删除和刷新持久化。
- 最终说明必须列出修改文件、验证结果和剩余风险。
⚠️ AGENTS.md 两大禁忌： 1. 严禁写成几千字的愿望清单（充满“深度思考”等模糊大词）；2. 严禁把一次性需求写进去（如“今天把按钮改成绿色”）。长期规则必须稳定、可执行、能反复使用。
十、真正跑通一次：计划、执行、验证、审查
现在回到任务看板。第一轮不要同时追求功能和精美视觉，先让它完成最小闭环：
第一版出来后，做一轮手动验收：新增三条任务、输入空格拦截、标记完成、删除任务、刷新页面、移动端窄屏测试。发现问题时，提供最小可复现用例：
功能通过后，再单独做视觉轮次。最后运行 `/review` 从代码审查视角检查 diff。把失败变成可定位、可修复、可回归验证的问题，你真正训练的是交付能力，而不是抽卡能力。
十一、上下文管理：给得太少会猜，给得太多会迷路
把上下文合理拆解为四层：
- 第一层（当前任务）：这一次要做什么、问题如何复现、完成标准是什么（短而明确）。
- 第二层（项目规则）：放在 `AGENTS.md`，包括目录结构、运行命令与工程约束。
- 第三层（可复用流程）：当同一套步骤反复执行时，用 Skill 封装（如代码审查清单、发布规范）。
- 第四层（外部动态信息）：当数据在 GitHub、Sentry、Figma 且持续变化时，通过 MCP 连接。
十二、模型与推理强度：按任务难度选，不要把最高档当默认
- 低/中等推理：文件解释、文案微调、明确的单文件修改。
- 中等/高推理：多文件功能、常规重构、测试补全。
- 高/更高推理：疑难 Bug、架构迁移、长链路任务、安全审查。
选择模型时看三个维度：任务是否复杂、错误代价是否高、你是否能快速验证。
十三、MCP、Skills 和插件：先跑通人工流程，再自动化
黄金法则：没有手动重复三次的流程，暂时不自动化。
新手最合理的升级顺序是：先完成纯本地项目 → 写好 AGENTS.md → 将重复审查做成 Skill → 最后按需接入外部 MCP。
十四、我踩过的 10 个坑，以及更直接的修正方式
- 在错误目录启动。修正：启动后第一件事查看工作目录和文件清单。
- 一句话要求完成大型项目。修正：先定义最小闭环，把大目标拆成每轮可验收的任务。
- 没有 Git 检查点。修正：任务前提交一次，完成后查看 diff，再决定是否保留。
- 只描述想要什么，不说不能改什么。修正：明确依赖、接口、目录和数据安全边界。
- 把“运行成功”当成“需求完成”。修正：用用户动作写验收清单，运行测试只是证据之一。
- 发现 Bug 后让它大规模重构。修正：先要求根因分析，再做最小修改，最后补回归检查。
- 一开始就给全盘权限。修正：只读探索，工作区执行，高风险动作单独确认。
- 把所有规则塞进每次提示词。修正：长期规则写入 AGENTS.md，重复流程做成 Skill。
- 同一个长会话处理不相关任务。修正：一个会话对应一个连贯目标，过长就整理并压缩，分叉就新开。
- 相信最终总结，不看实际差异。修正：查看修改文件、命令输出、测试结果和 Git diff。Agent 的自述不是证据，执行记录才是。
十五、5 个可以直接复制的入门提示词
先不要修改文件。请从当前项目中识别：项目用途、主要目录、启动入口、依赖管理方式、构建/测试命令和最可能出问题的三个区域。每个结论都标明依据文件。最后给我一条从零启动项目的最短路径；如果信息不足，明确说缺什么，不要猜。
我想做【填写想法】。先不要写代码，请像产品经理和工程师一起审需求：指出目标用户、核心场景、最小功能闭环、明确不做的范围、关键风险和可验证验收标准。最多向我提出 5 个会影响方案的关键问题；等我回答后，再输出分阶段实施计划。
目标：【功能】。上下文：【相关文件/报错/参考】。约束：【不能改的接口、依赖、目录和风格】。完成标准：【测试、构建和用户操作结果】。先读取相关文件并给出最多 6 步计划；只做与目标有关的最小修改；完成后运行相关验证，列出修改文件、命令结果和剩余风险。
问题现象：【实际结果】。复现步骤：1.【步骤】2.【步骤】3.【步骤】。预期结果：【应该发生什么】。请先定位根因并指出证据，不要立即重构；然后提出最小修复方案。实施后按同一组步骤验证，并补充能防止回归的测试或检查。不要修改无关文件。
在结束前做一次交付审查：逐条对照原始目标和验收标准；查看 Git diff 是否包含无关修改；运行与本次变更相关的测试、构建、lint 或类型检查；检查错误处理和边界场景。最后只输出四部分：已完成、验证证据、未完成、风险与下一步。没有证据的项目不要标记为完成。
用后感悟与核心公式
用了一段时间后，我对 Codex 最大的认知变化是：提示词只是任务入口，真正决定结果的是工作系统。
一个可靠的系统包括正确的工作目录、可恢复的 Git 检查点、足够清楚的目标与边界、刚好够用的权限、能被执行的验收标准、持续更新的项目规则，以及任务完成后的测试和审查。模型能力越强，这套系统越重要，因为强大的 Agent 能更快放大正确方向，也能更快放大错误假设。
Codex 交付质量 = 清晰目标 × 有效上下文 × 合理权限 × 可执行验收
任何一项接近零，最终结果都会打折。把这四项练熟，你得到的就不只是一个会写代码的 AI，而是一套能持续放大个人执行力的工作方式。