Codex 编程智能体入门指南

什么是 Codex？

Codex 是 OpenAI 推出的一款云端软件工程智能体（AI agent），它能够编写和编辑代码、运行测试、修复错误，甚至发起拉取请求供人审查。与 ChatGPT 擅长回答问题、头脑风暴和对话式起草不同，Codex 被设计用来处理另一种类型的任务——它可以跨文件、跨工具、跨可重复工作流来推进实际工作。一个简单的理解方式：ChatGPT 帮助思考工作怎么做，而 Codex 帮助把工作本身往前推进。

Codex 并非只是一个能写代码的模型，它是一个能够检阅代码仓库、运行命令、审查变更，并在多个工作面上运作的智能体。每个任务都在自己独立的云沙箱环境中运行，并预装了用户的代码仓库。

在哪里使用 Codex

Codex 提供了多种使用入口，用户可以根据自己的工作习惯灵活选择：

命令行界面（CLI）是最原始也最流行的使用方式，零依赖安装，支持强大的斜杠命令（如/compact、/fork、/new），并且可以与 ChatGPT 应用集成。

Codex 应用则提供了更丰富的图形界面体验，可以轻松地在多个工作区并行运行任务，拥有更好更灵活的差异对比视图，为技能（skills）、工作树（worktrees）和自动化提供了出色的可视化界面，尤其适合处理超出单纯代码编写的工作流程。

IDE 集成（VS Code、JetBrains、Xcode）让 Codex 自然地融入基于 IDE 的工作流程中，适合增量式任务和快速协助，非常适合“聊天式”的使用场景。

无论选择哪种入口，Codex 的核心性能是一致的，只是各客户端的功能细节略有不同。

Codex 的核心：智能体循环

每一个 AI 智能体的核心都是一套被称为“智能体循环”（Agent Loop）的运行机制。理解这个循环，就理解了 Codex 是如何工作的。

整个流程从用户输入开始。智能体获取用户的输入，将其整合为给模型的文本指令——也就是提示词（prompt）。接下来进入推理阶段：智能体将指令发送给模型，要求模型生成响应。在推理过程中，文本提示词首先被转换为 Token 序列，这些 Token 被用来对模型进行采样，生成新的输出 Token，再转换回文本作为模型的响应。

推理完成后，模型会产生两种结果之一：要么生成对用户原始输入的最终响应，要么请求调用某个工具（例如“运行 ls 命令并返回结果”）。如果是后者，智能体就会执行这个工具调用，将工具的输出追加到原始提示中，然后带着更新后的上下文开始新一轮推理。

这个过程会循环往复，直到模型不再发起工具调用，转而生成一条面向用户的消息为止。由于智能体能够执行修改本地环境的工具调用，它的“输出”并不局限于消息本身——在许多场景下，最主要的输出其实是它在计算机上直接编写或修改的代码。

从用户输入到智能体响应的完整过程，被称为一次对话轮次（或对话线程）。一次对话轮次中，模型推理与工具调用之间可能进行多次循环迭代。

上下文：智能体的工作记忆

在 Codex 的工作过程中，“上下文”是一个至关重要的概念。上下文是智能体完成任务所拥有的全部信息。Codex 可以在上下文中同时容纳数百份文档——大约相当于 400 到 600 页文本的体量。

上下文之所以重要，是因为聚焦的上下文能够带来更安全、更准确、更一致的智能体执行结果。如果上下文过于杂乱或信息不足，智能体的判断就可能出现偏差。

Codex 会自动管理上下文。当 Token 使用量超过模型特定的阈值（约为 90%）时，智能体循环中会自动运行上下文压缩（auto compaction）。这种智能压缩机制确保了 Codex 在长时间、多轮次的复杂任务中依然能够保持高效和准确。

用 AGENTS.md 让 Codex 更聪明

Codex 在每次运行时对项目的了解是有限的。而AGENTS.md文件的作用，就是让项目的规范和流程自动加载到 Codex 的上下文中。可以把它理解为一个面向智能体的开放式 README 文件。

AGENTS.md的发现遵循特定的优先级顺序：

• 全局级别（~/.codex/AGENTS.md）：位于用户主目录，用于存放个人默认设置，应保持简洁。
• 项目级别（仓库根目录的AGENTS.md）：从项目根目录开始。
• 目录级别（子目录中的AGENTS.md）：从根目录向下逐级查找到当前工作目录，多个文件会从根目录向下合并，距离当前目录越近的文件优先级越高。

一份好的AGENTS.md通常包含以下内容：仓库地图（关键目录和重要模块）、项目运行方式（安装、构建、测试、lint 命令）、工程规范（代码约定、PR 期望、“不要做”的规则、安全约束），以及验证标准（什么算“完成”、如何验证）。

AGENTS.md的最佳实践是保持简短且可操作——命令、路径、规则和常见陷阱即可，不需要泛泛的解释。OpenAI 内部大部分AGENTS.md文件都不到 100 行。同时，可以在主AGENTS.md中引用其他针对特定任务的支持文档，比如PLANS.md（用于大型任务的规划）、Code_review.md（代码审查指令）、Architecture.md（架构修改相关说明）。

用户随时可以让 Codex 做一次复盘并更新AGENTS.md，从而避免重复犯错，更快地达成最终结果。

如何在软件开发生命周期中使用 Codex

Codex 在整个软件生命周期中都能为工程师提供加速。一个典型的上手流程包括：发送一个只读的提示（可以配合@提及相关文件）、构建一个简单的功能并运行测试、用“计划模式”构建更复杂的功能、添加图片作为上下文、在部署前审查代码，以及记录变更。

关键的理念是：把工作委托给 Codex，让自己有更多精力去深入思考架构和设计。

有效委托的四个原则

要想高效地使用 Codex，有三个核心原则值得牢记：

第一，与其追求完美的提示词，不如构建完美的上下文。Codex 的表现高度依赖于它所能获取的上下文质量。与其花大量时间雕琢提示词的措辞，不如确保相关文件、错误信息、项目规范等关键信息都已经被正确地提供给 Codex。

第二，更快的验证带来更好的结果。验证环节越快捷、越自动化，迭代速度就越快，最终结果也就越好。

第三，用智能体来学习，而不是盲目“氛围编程”。Codex 不仅是代码生成工具，更是一个学习伙伴。通过观察它如何处理任务、如何理解代码库，使用者本身也能加深对项目的理解。

提示词撰写的实用技巧

好的提示词能够设定范围、约束和成功标准，让 Codex 可预测地执行任务。

保持精简：目标 + 约束 + “完成条件”就足够了。Codex 在有清晰目标和明确终点线时表现最佳，长篇大论反而容易分散注意力。必要时告诉 Codex“不要做什么”。

内嵌验证方式：明确说明如何验证结果（测试、lint、构建）。如果 Codex 无法自行运行这些验证，它应该告诉用户具体该运行什么命令、检查什么输出。

用@提及提供明确的代码定位：在提示中引用代码库中的相关文件，让编辑范围更精准。

粘贴完整的堆栈跟踪：调试时把错误信息、复现步骤和环境细节都提供给 Codex，它能更快地定位根因。

有意识地使用开放式提示：当需要的是建议而非具体实现时，可以主动询问方案选项、权衡取舍、风险和推荐做法。

Codex 在团队中的实际应用

Codex 已经深度融入了许多团队的工作流程。

代码审查是 Codex 最常见的应用场景之一。它可以自动或响应式地进行代码审查，加速审查流程，预防生产环境中的问题。在 OpenAI 内部，100% 的 PR 都由 Codex 进行审查。Datadog 的工程经理 Brad Carter 对此评价道：“Codex 改变了我对代码审查的看法。重点不在于复制我们最优秀的人类审阅者，而在于发现那些人类在孤立地审查变更时难以看到的关键缺陷和边缘情况。”Datadog 有超过 1000 名工程师每周使用 Codex，22% 的历史 incidents 中存在的风险曾被 Codex 标记出来。

Slack 和 Linear 集成让委托任务变得极其简单。在 Slack 频道或 Linear 问题中@Codex，它就会自动收集上下文、选择合适的环境，并返回一个指向已完成任务的链接。这种“零代码”的任务委托方式让非技术团队成员也能轻松调用 Codex 的能力。

Codex SDK则让开发者可以构建自己的集成——比如自动修复 CI 失败，或在 incident 被声明时自动启动根因分析。Codex SDK 支持将 Codex 嵌入 CI/CD 流水线、GitHub Actions 等工作流中。

真实的成效数据

在 OpenAI 内部，Codex 带来的改变是实实在在的。每月节省超过 1500 个工程小时。OpenAI 首席工程师 Ryan Brady 表示：“最大的收益来自于我们不再把 Codex 当作一个工具，而是开始把它当作团队的一部分。”缺陷修复速度提升了10 到 15 倍，构建时间减少了20%。

日本乐天（Rakuten）使用 Codex 后，平均修复时间（MTTR）降低了约 50%。乐天 AI 总经理 Yusuke Kaji 指出：“我们关心的不仅是快速生成代码，更关心安全地交付。速度没有安全就不算成功。我们的角色不再是逐行检查代码，而是明确定义我们想要什么、建立如何验证的标准。”

Sora 安卓版的开发则是一个更为惊人的案例：一支 4 人的工程师团队，在 28 天内从原型到全球发布，其中约 85% 的代码由 Codex 编写，人类工程师专注于架构和审查。最终实现了 99.9% 的崩溃-free 率，获得了 4.9/5 的用户评分，并登顶 Google Play。

从何处开始

对于想要上手 Codex 的新用户，建议的路径很简单：在一个真实的代码仓库中使用 Codex、设置好AGENTS.md、然后交给它真正的任务。

官方提供了丰富的学习资源，包括Codex 文档（developers.openai.com/codex）、Codex Cookbooks（cookbook.openai.com/topic/codex）以及Codex 更新日志（developers.openai.com/codex/changelog）。

Codex 代表的不仅是一个新的编程工具，更是一种全新的工作范式——从“自己动手写每一行代码”转向“定义目标、委托执行、审查结果”。在这个范式转换中，工程师的角色从执行者逐渐演变为架构师和审阅者，而 Codex 则成为那个不知疲倦、随时待命的协作伙伴。