01 · Codex 是什么

Codex 是 OpenAI 面向软件开发的 coding agent。它不是单纯回答“代码该怎么写”，而是能在你的项目上下文里读文件、提出计划、修改代码、运行命令，并把结果交给你审查。

理解 Codex 的关键，不是先背命令，而是先分清它和聊天助手、代码补全、自动化脚本的边界。

从 AI 到 Coding Agent

Codex 位于“AI -> 模型 -> 助手 -> Agent -> Coding Agent”这条链路的最后一层。

flowchart TB
    AI["AI<br/>让机器执行智能任务"]
    Model["大语言模型<br/>理解和生成文本、代码、结构化内容"]
    Assistant["AI 助手<br/>以对话形式回答问题"]
    Agent["Agent<br/>围绕目标读取上下文、调用工具、观察结果"]
    Coding["Coding Agent<br/>在代码库里推进工程任务"]
    Codex["OpenAI Codex"]

    AI --> Model --> Assistant --> Agent --> Coding --> Codex

这一层级关系有两个结论：

• Codex 不是一个“更会聊天的 ChatGPT”。
• Codex 也不是固定脚本，而是会根据项目现场调整步骤的 agent。

所以你给 Codex 的任务，不能只写“帮我优化一下”。你需要告诉它目标、边界、验证方式和不希望它碰的范围。

Codex 进入的是工程现场

工程现场不是一段孤立代码，而是一整套约束。

mindmap
  root((工程现场))
    代码
      文件结构
      Git diff
      依赖版本
    规则
      AGENTS.md
      项目规范
      团队边界
    工具
      测试
      Lint
      类型检查
      构建
    风险
      权限
      沙箱
      审批
      未提交改动

Codex 的价值在于它能围绕这些约束工作：

• 先看项目结构，而不是凭空写代码。
• 识别当前分支已有改动，而不是覆盖别人的工作。
• 根据测试、类型检查、构建结果继续调整。
• 在权限和审批边界内执行命令。
• 最后给出可审查的文件变更和验证结果。

这也是为什么 Codex 教程必须讲 AGENTS.md、sandbox、approval、MCP、skills、hooks。它们不是附加功能，而是 coding agent 能可靠工作的基础设施。

和聊天助手的区别

聊天助手更像“问答界面”。它能解释概念、给代码片段、分析报错，但通常不会直接进入你的工作树完成任务。

Codex 更像“受控的工程协作者”。它会围绕一个目标推进：

flowchart LR
    Task["任务"] --> Context["读取上下文"]
    Context --> Plan["形成计划"]
    Plan --> Action["调用工具 / 修改文件"]
    Action --> Observe["观察结果"]
    Observe --> Verify["验证"]
    Verify --> Review["交给人审查"]
    Observe -. "失败时调整" .-> Plan

这带来一个根本差异：

• 聊天助手错了，主要问题是“答错”。
• Codex 错了，可能是“做错”，因为它可能真的改文件、执行命令、影响项目状态。

因此，使用 Codex 时，最重要的能力不是写漂亮 prompt，而是设置正确边界。

和代码补全的区别

代码补全通常发生在光标附近。它根据当前文件和邻近上下文补出几行代码。

Codex 处理的是任务，而不是光标：

• 修一个跨文件 bug。
• 审查一个 PR 的风险。
• 把一组文档改成统一格式。
• 运行测试并定位失败原因。
• 根据现有架构实现一个小功能。

代码补全适合“下一行怎么写”；Codex 适合“这个任务该如何完成并验证”。

和自动化脚本的区别

脚本适合固定流程。输入稳定、步骤固定、结果可预测时，脚本更直接。

Codex 适合需要判断的流程。比如：

• 测试失败后判断是类型错误、依赖错误还是业务逻辑错误。
• 文档格式不统一时逐篇判断该保留什么、改掉什么。
• 在不知道文件位置时先搜索，再决定修改点。
• 修改后根据验证结果继续修正。

可以这样理解：

固定步骤 -> 脚本
需要判断 -> Codex
需要长期重复且规则稳定 -> 先让 Codex 做，再沉淀为脚本或工作流

Codex 不是要替代所有自动化。相反，好的使用方式是让 Codex 帮你发现流程，再把稳定流程沉淀成工具。

Codex 的四种常见形态

Codex 可以出现在不同入口里。学习时不要把入口和能力混为一谈。

• CLI：适合本地项目、终端工作流、文件修改、测试验证。
• IDE extension：适合在编辑器里结合代码阅读和局部修改。
• App：适合更完整的桌面工作流和任务管理。
• Cloud：适合把任务交给远程环境处理，再审查结果。

这些入口共享同一个核心概念：让 coding agent 在上下文、工具和权限边界内推进任务。

选择入口时看场景，而不是看哪个“更高级”：

• 本地项目改动多，优先 CLI。
• 编辑器内局部上下文强，优先 IDE。
• 需要统一任务入口，考虑 App。
• 需要远程环境或异步处理，考虑 Cloud。

新手最容易误用的地方

第一，把 Codex 当聊天框。只说“优化一下”，不说边界、不说验收，就会得到不可控的改动。

第二，把 Codex 当脚本。要求它机械执行很多固定步骤，却不给它判断空间，会浪费 agent 的价值。

第三，过度放权。为了省审批直接放开 sandbox 和 approval，短期方便，长期容易改坏项目。

第四，不看当前工作树。多人或多 agent 同时修改时，Codex 必须先确认哪些文件是自己负责的，不能覆盖别人的改动。

第五，不做验证。没有测试、类型检查、构建或人工审查，agent 的输出只能算“改过”，不能算“完成”。

一个合格任务应该怎么写

差的任务：

帮我优化这个项目。

更好的任务：

检查 content/docs/codex 下的文章格式，只处理未美化页面。
每批最多改 3 个文件，不要碰其他 agent 正在修改的文件。
改完跑 types:check 和单文件格式扫描，最后汇总剩余候选。

这个任务多了四类关键信息：

• 范围：只处理 content/docs/codex。
• 边界：每批最多 3 个文件，不碰别人文件。
• 标准：格式美化、不是随意改写。
• 验证：跑扫描和类型检查。

Codex 的输入越像工程任务单，输出越像可审查的工程产物。

继续学习顺序

理解 Codex 后，建议按这个顺序继续：

1. 先学 CLI、IDE、App、Cloud 的入口差异。
2. 再学 sandbox 和 approval，知道它能做什么、不能做什么。
3. 然后学 AGENTS.md 和项目上下文，让它按你的规则工作。
4. 再学 MCP、skills、hooks、subagents，把流程逐步沉淀。

Codex 的核心不是“让 AI 写更多代码”，而是让 agent 在工程现场里做可控、可验证、可审查的工作。