01 · Codex 到底是什么

⏱️ 预计阅读 12 分钟 ｜ 🎯 目标：把 Codex 从"会写代码的聊天框"重新理解成"能进入项目现场的工程协作 Agent"

这是新手最容易搞错的第一步，也是后面所有概念立得住的地基。把这一篇读透，AGENTS.md、审批、沙箱、MCP、Skills、Subagents、Hooks 这些后续的名词就不再零散，会变成同一套系统的不同部件。

🎬 先看一个场景

你打开项目，想让 AI 帮你修一个登录失败的 bug：

帮我修一下登录失败的问题。

这句话对人类同事都不够。如果你扔给一个新来的工程师，他至少会反问你三件事：发生在哪？我能不能改代码？怎么验证修对了？

同一句话，问不同对象会发生什么：

🤔 差别在哪？ 不在 AI 聪不聪明，而在 它有没有进入你的项目现场。 这一篇就是要把这件事讲清楚 —— 而且讲透之后，你给 Codex 的提示词会立刻变得不一样。

🧭 从 AI 到 Codex：四层概念递进

很多人一上来把 AI、ChatGPT、Agent、Codex 混着说。日常聊天没事，但学工具时必须分清。这四层从大到小一层套一层：

flowchart TB
    AI["🌐 AI<br/>让机器表现出智能行为"]
    LLM["📚 大语言模型<br/>擅长理解和生成语言、代码、文本"]
    Assistant["💬 AI 助手<br/>把模型包装成对话产品<br/>例:ChatGPT 聊天框"]
    Agent["🤖 Agent<br/>围绕目标自主使用<br/>上下文、工具、反馈"]
    Coding["👨‍💻 Coding Agent<br/>面向编程任务的 Agent<br/>例:Codex ⭐"]

    AI --> LLM
    LLM --> Assistant
    Assistant -."演进为".-> Agent
    Agent --> Coding

    style Coding fill:#dcfce7,stroke:#22c55e,stroke-width:2px

逐层展开一下：

• 🌐 AI 不只是聊天。识别图片、推荐视频、语音识别、自动驾驶、下棋 —— 都是 AI。不是所有 AI 都是大语言模型。
• 📚 大语言模型 是当下最常见的一类 AI。核心能力是理解和生成序列：一句话、一段代码、一份配置、一段报错、一篇文档，它都能处理。
• 💬 AI 助手 是产品形态。你打开聊天框、输入问题、它回答你 —— 这时你面对的是助手，不是裸模型。
• 🤖 Agent 是再进一步：它不只是回答，而是围绕目标行动。读上下文、定步骤、调工具、看结果、再决定下一步。
• 👨‍💻 Coding Agent 是 Agent 在编程场景的具体形态。

💡 核心区分：助手负责「回答」，Agent 负责「行动」。这一字之差，决定了后面所有差异。

🤖 什么是 Agent

Agent 这个词最近被说滥了。为了让新手能立刻抓住，先别用技术定义，用一个工作流定义：

Agent = 目标 + 上下文 + 工具 + 记忆 / 状态 + 反馈循环

少任何一个，Agent 就不再完整：

• 只有目标和回答，没有工具 → 更像聊天助手
• 有工具但没有目标 → 只是自动化脚本
• 有目标和工具但没有反馈 → 只能执行一次，不能修正
• 有反馈但没有边界 → 可能越做越危险

🎯 所以 Agent 不是单点功能，是一套系统。 这就是为什么后面要花整整 4 篇讲上下文、AGENTS.md、审批沙箱 —— 它们都是这套系统的一部分。

🆚 Codex 不是聊天机器人，差别在哪

新手最大的误解：把 Codex 当成"会写代码的 ChatGPT"。这个误解会直接毁掉你怎么提需求。

一句话总结这张表：

⚠️ 因为 Agent 真的会动手，它的错误从"答错"变成了"做错" —— 答错可以再问，做错可能改坏代码。 所以你不能用对聊天机器人的要求来对它。Agent 需要更明确的任务边界。

🛠️ Agent 又和自动化脚本有什么不同

自动化脚本也能执行任务：跑测试、格式化代码、部署网站。它和 Agent 区别在哪？

输入参数
   ↓
执行固定步骤
   ↓
输出结果

理解目标
   ↓
读取上下文
   ↓
判断下一步 → 调用工具 → 观察结果
   ↑                          ↓
   └──────── 调整计划 ←─────────┘
   ↓
完成并验证

举一个具体对比：

• 「运行 pnpm test」 → 用脚本就够了。每次步骤都一样，没什么可判断的。
• 「测试失败后判断原因，定位文件，提出最小修复方案」 → 更适合 Agent。每次原因都不同，需要边读边判断。

🎯 Codex 的价值就在这里：编程任务经常不是固定步骤，而是需要判断和反馈。 一旦任务里出现「先看看…再决定…」、「如果…就…否则…」，脚本就处理不了了，Agent 才登场。

👨‍💻 Coding Agent = AI 进入工程现场

普通 Agent 处理的是文字任务（写邮件、做摘要、查信息）。Coding Agent 处理的是 工程现场。

mindmap
  root((工程现场))
    代码层
      代码文件
      Git diff
      团队规则
    依赖层
      package.json
      lockfile
    工具链
      构建脚本
      测试
      Lint / 类型检查
    运行层
      运行日志
      浏览器页面
      报错信息

工程现场里的每一项都是约束。Coding Agent 要做的不是"凭空写代码"，而是 在这些约束里完成任务：

这两个问题完全不同。前者是教科书题目，后者是工程任务。

所以 Codex 一句话定义：

🎯 Codex 是一个面向编程任务的 AI Coding Agent。 它能读项目、改文件、调用工具、运行验证，并把结果交给你审查。

💡 Codex 的"现场感"

一个真正的工程任务一定发生在现场里。现场包括：

• 📁 代码库现在的结构
• 🛠️ 已经采用的技术栈
• ✍️ 团队约定的写法
• 🌿 当前分支上已有的改动
• ▶️ 测试和构建命令
• 🐛 真实错误信息
• 🚦 你允许它做和不允许它做的事

Codex 的价值，就在于它可以进入这个现场，而不是只在脑海里想象一个项目。

这也是为什么你第一次使用 Codex 时，不应该马上让它写新功能。更好的第一步是让它先建立现场感：

请先阅读当前项目，不要修改文件。

这句话看似保守，其实非常重要。它让 Codex 把项目"装进脑子"再开始动手。

📖 一个例子讲透：同一个需求，三种问法

需求：我想给网站加一个订阅表单。

你用什么方式问 Codex，决定了它给你什么。看完这三种问法的对比，你就理解了 Codex 提示词为什么要这么写。

❌ 问法 A · 当聊天工具用

怎么写一个订阅表单？

Codex 给的：一段标准 React 代码，包含输入框、按钮和提交函数。代码本身没问题。

问题在哪：

• ❌ 不知道你项目用什么框架
• ❌ 不知道有没有现成 Button 组件
• ❌ 不知道 API 是 /api/subscribe 还是 Mailchimp
• ❌ 不知道错误提示的视觉风格
• ❌ 不知道是否需要移动端适配

➡️ 你拿到的是 代码片段，不是项目交付。复制进项目大概率要返工。

⚠️ 问法 B · 当代码助手用

请在当前项目里加一个订阅表单。

Codex 给的：会读项目、找页面、改文件，比 A 好很多。

问题在哪：

• ⚠️ 没限定范围，它可能顺手新建组件、加样式、写 API、接第三方服务
• ⚠️ 甚至改全局布局
• ⚠️ 你最后审查 diff 时会发现"它改的远比我想要的多"

➡️ 进入项目现场了，但任务边界不清。

✅ 问法 C · 当 Coding Agent 用

请在首页底部添加一个邮件订阅表单。

🎯 目标：
- 使用项目已有输入框和按钮组件
- 表单包含 email 输入框、提交按钮、成功提示和错误提示
- 只调用现有 /api/newsletter,不新增外部服务

🚧 边界：
- 只改首页和必要的局部组件
- 不新增依赖
- 不改全局样式和现有 API 结构

✅ 验证:
- 桌面和移动端布局正常
- 空邮箱和非法邮箱有提示
- 提交成功和失败都有反馈
- 运行相关测试或说明人工验收步骤

请先给计划,等我确认后再修改。

Codex 给的：先出计划 → 你确认 → 它修改 → 它跑测试 → 它汇报。

➡️ 这才是 Codex 最适合的工作方式：在明确目标、边界、验证下完成任务。

💡 这三种问法的递进关系，就是你和 Codex 合作能力的成长曲线。 看懂这个例子，你就理解了为什么 Codex 提示词不该只有"做什么"，还要有"怎么算做完"。

⚖️ Codex 适合 / 不适合直接做什么

💡 不是 Codex 做不了，而是新手阶段风险太高。从适合的开始练手，再逐步放权。 等你能稳定写出"问法 C"那种提示词，再去碰右边的任务也不迟。

🎓 新手最该养成的三个习惯

任何任务，把这三句话连起来用，就能避开 80% 的踩坑场景。这三步是 Codex 的"安全带"。

1️⃣ 让 Codex 先 复述 任务

请先复述你对任务的理解，不要修改文件。

➡️ 作用：提前发现误解。

你心里想的"修一下登录" 和它理解的"重写整个登录系统" 经常是两回事。在改之前先对齐，比改完才发现错的方向便宜得多。

2️⃣ 让 Codex 先 列边界

请说明你准备修改哪些文件，哪些文件不会碰。

➡️ 作用：把改动范围圈出来。

这一步会让 Codex 主动暴露它的"想象边界"。你看到清单后能立刻发现"诶，它怎么打算改这个文件？"，趁早叫停。

3️⃣ 让 Codex 最后 交验证

请列出你运行过的验证命令、结果，和仍需人工检查的地方。

➡️ 作用：避免"看起来完成"。

没有验证的"完成了" 不是完成。验证才是交付的证据，而且 Codex 会在汇报时主动说出哪些自己没把握——这恰好是你该重点检查的地方。

🎯 三句话的核心思路：把不可见的判断（它在想什么）变成可见的产物（复述/边界/验证清单）。让 Agent 工作变成可审查的协作。

🚫 常见误解 → ✅ 正确理解

🤝 类比：把 Codex 想成新加入项目的高级同事。 能力很强，但第一次接手任务，仍然需要你交代项目背景、任务目标、不能碰的地方、和怎么验收。 一个好的 Codex 提示词，本质上就是一次清晰的工作交接。

🔍 想再深一层（点击展开）

我描述需求
  ↓
AI 生成代码片段
  ↓
我复制到项目里
  ↓
我运行测试
  ↓
报错后我再把错误贴回去
  ↓
AI 继续给建议

✅ 把 AI 放进项目现场
✅ 让 AI 参与验证闭环

flowchart LR
    A["1️⃣ 问答型<br/>问概念、生成片段"]
    B["2️⃣ 辅助型<br/>读项目、解释代码、提计划"]
    C["3️⃣ 交付型<br/>给目标、边界、验收<br/>它完成修改并报告"]

    A --> B --> C

    style A fill:#fef3c7,stroke:#f59e0b
    style B fill:#dbeafe,stroke:#3b82f6
    style C fill:#dcfce7,stroke:#22c55e

这个仓库交给你了，优化一下。

我第一次在这个项目里使用 Codex。请先不要修改文件。

请你像一位新加入项目的工程师一样做入场了解：
1. 阅读项目说明、依赖配置和主要目录
2. 判断这个项目的技术栈和运行方式
3. 找出最适合新手阅读的 5 个文件
4. 说明哪些任务适合交给你
5. 说明哪些任务不建议直接交给你
6. 给我 3 个适合下一步开始的小任务

要求：
- 不修改文件
- 不安装依赖
- 不执行有副作用的命令
- 不确定的信息明确说"不确定"

📝 本章自检

读完这一章，看你能不能回答下面三道题。如果有任何一道答不出来，回到对应章节再读一遍。

✅ 过关标准：能用一句话说清 —— "Codex 不是聊天窗口，而是能进入代码现场完成任务的 Coding Agent。"

只要这个理解建立起来，后面的 AGENTS.md、审批、沙箱、MCP、Skills、Subagents、Hooks 都会变得更容易理解。它们不是一堆孤立名词，而是围绕同一个核心问题展开：

🎯 如何让一个 AI Agent 在真实工程现场里安全、稳定、可验证地完成任务？

📚 下一篇

• ➡️ 02 · 一次任务是怎么完成的 —— Codex 从目标到交付的完整过程
• 📖 00 新手必读 —— 快速上手与术语
• 🚪 01 产品入口 —— App、IDE、CLI、Cloud 各自怎么用