深入理解 Codex 智能体循环

来源：OpenAI 官方文章
原文链接：https://openai.com/zh-Hans-CN/index/unrolling-the-codex-agent-loop/
原文日期：2026-01-23
整理日期：2026-05-20

核心主题：Codex 不是“模型直接写代码”，而是一套运行框架在不断组织上下文、调用模型、执行工具、观察结果、压缩历史，直到任务完成。

1. 一句话结论

Codex 的核心不是单次问答，而是“智能体循环”：用户提出目标，模型判断下一步，Codex 执行工具，把结果重新放回上下文，再让模型继续判断，直到模型停止调用工具并给出最终回复。

我需要记住的是：

• 模型负责推理和决策。
• Codex 运行框架负责组织上下文、执行工具、管理权限和控制循环。
• 工具调用的结果会变成下一次推理的输入。
• 代码改动本身也是智能体的输出，不只是最后那句话。
• 上下文、缓存、压缩和权限，是 Agent 能不能稳定工作的关键。

2. 先看一张总览图

flowchart LR
  U["用户目标<br/>我要完成什么"] --> H["Codex 运行框架<br/>组织上下文、权限和工具"]
  H --> M["模型<br/>推理下一步"]
  M -->|"需要操作环境"| T["工具<br/>读文件、改代码、跑命令、查资料"]
  T --> O["环境反馈<br/>文件内容、命令输出、测试结果"]
  O --> H
  M -->|"任务完成"| R["最终回复<br/>总结改动和验证结果"]

这张图要表达的是：Codex 不是模型直接控制电脑，而是 Codex 运行框架在中间负责调度。

模型像“大脑”，工具像“手和眼睛”，Codex 运行框架像“项目经理 + 安全边界 + 上下文管理器”。

3. 原文核心信息

主题	原文讲了什么	对我的启发
Codex 定位	Codex 包含 CLI、Cloud、VS Code 扩展等软件智能体产品，本文重点讲底层运行框架	不要只把 Codex 理解成一个命令行工具，它背后是一套 Agent 执行系统
Agent loop	智能体会在“模型推理”和“工具调用”之间反复循环	AI 编程不是一次生成，而是不断观察、执行、修正
工具调用	模型可以请求运行 shell、搜索、调用 MCP 工具等	Agent 真正强的地方是能操作环境，而不只是回答文字
上下文增长	每轮对话都会把历史消息和工具结果带入下一次请求	对话越长，越容易消耗上下文窗口
提示缓存	旧提示作为新提示的精确前缀，有利于命中缓存	固定指令和工具顺序很重要，频繁改配置会影响性能
压缩机制	当上下文太长时，Codex 会自动压缩历史	长任务不是无限堆上下文，而是要把关键状态总结出来
沙盒权限	Codex 会给 shell 工具注入权限说明，但 MCP 工具需要自己负责防护	工具边界和权限控制是 Agent 安全的核心

4. 我需要先理解的几个概念

4.1 Codex 不是模型本身

很多人会把 Codex 理解成“一个会写代码的模型”，但这篇文章强调的是：Codex 更像一个运行框架。

可以拆成三层：

层级	作用	类比
模型	根据上下文推理下一步	大脑
Codex harness	编排模型、工具、上下文和权限	项目经理 + 执行调度器
工具	读文件、改文件、跑命令、查资料	手和眼睛

flowchart TB
  A["模型层<br/>负责理解、推理、决策"] --> B["运行框架层<br/>负责上下文、权限、工具编排"]
  B --> C["工具层<br/>负责真实环境操作"]
  C --> D["工程环境<br/>代码仓库、终端、文件系统、外部服务"]
  D --> B

所以，Agent 能工作，不是因为模型一次性知道所有答案，而是因为它可以：

• 先读文件。
• 根据文件内容制定下一步。
• 修改代码。
• 跑测试。
• 看报错。
• 再继续修。

这就是 Agent 和普通聊天机器人的根本差异。

4.2 一次对话不等于一次模型调用

我给 Codex 发一句话，比如：

帮我修复这个构建问题

从用户视角看，这是一次请求。

但从 Codex 内部看，可能发生很多轮：

用户目标
  -> 模型推理：先看 package.json
  -> 工具调用：读取 package.json
  -> 模型推理：再看构建配置
  -> 工具调用：读取配置文件
  -> 模型推理：修改脚本
  -> 工具调用：写文件
  -> 模型推理：运行 build
  -> 工具调用：执行 pnpm build
  -> 模型推理：总结结果
  -> 回复用户

这整串过程，才是一个完整的 Agent loop。

5. 智能体循环是怎么跑起来的

sequenceDiagram
  participant User as 用户
  participant Codex as Codex 运行框架
  participant Model as 模型
  participant Tool as 工具
  participant Env as 工程环境

  User->>Codex: 提出任务目标
  Codex->>Model: 发送上下文和可用工具
  Model-->>Codex: 请求读取文件
  Codex->>Tool: 执行读取
  Tool->>Env: 访问文件系统
  Env-->>Tool: 返回文件内容
  Tool-->>Codex: 返回工具结果
  Codex->>Model: 追加结果后继续推理
  Model-->>Codex: 请求修改并验证
  Codex->>Tool: 写文件、运行测试
  Tool-->>Codex: 返回验证结果
  Codex->>Model: 继续判断是否完成
  Model-->>User: 输出最终总结

这张时序图更接近真实开发过程：用户只看到“发任务”和“收到结果”，中间其实发生了多轮模型推理和工具调用。

5.1 第一步：把用户输入变成提示

用户输入只是提示的一部分。Codex 在真正请求模型之前，会把很多信息组合进去：

• 系统或开发者指令。
• 当前沙盒权限。
• 当前工作目录。
• 用户 shell。
• 项目里的 AGENTS.md 等说明文件。
• 可用工具列表。
• 用户当前输入。

这解释了为什么我写好 AGENTS.md 很重要。

因为 Agent 并不是只看我最后那句话，它会把项目规则、权限限制和环境信息一起带给模型。

5.2 第二步：模型推理下一步

模型收到上下文后，不一定直接回答。

它可能做两类输出：

• 直接给用户最终回复。
• 发起工具调用。

软件工程任务里，更多时候是第二种。

例如模型可能判断：

我需要先读取 package.json，确认构建命令。

于是它会请求 Codex 执行 shell 工具。

5.3 第三步：Codex 执行工具

模型本身不能直接操作我的电脑。

真正执行命令、读文件、写文件的是 Codex 运行框架。

这也是为什么权限控制很关键：

• 哪些目录可写？
• 网络能不能访问？
• 什么时候需要用户批准？
• 是否允许执行危险命令？

文章中特别提到，Codex 注入的沙盒规则主要约束 Codex 自带的 shell 工具。其他 MCP 工具如果能操作外部系统，需要工具自身提供安全边界。

我的理解：

Agent 越强，权限边界越重要。 能干活的工具，也一定可能干坏事。

5.4 第四步：工具结果回到上下文

工具执行结果不会丢掉。

Codex 会把它追加到 input 里，作为下一次模型推理的上下文。

这就形成了一个闭环：

模型提出动作
Codex 执行动作
环境返回结果
模型基于结果继续判断

这也是为什么工具输出质量很重要。

如果命令输出太乱、太长、缺少关键错误信息，模型下一步判断就会变差。

6. 为什么上下文管理很重要

6.1 对话越长，输入越大

每次继续对话时，Codex 都要把之前的消息、工具调用和工具结果带进去。

这会带来两个问题：

• 成本变高。
• 上下文窗口可能被耗尽。

软件任务尤其容易触发这个问题，因为 Agent 可能在一轮任务里调用很多工具。

例如：

• 搜索代码。
• 读取多个文件。
• 修改文件。
• 跑测试。
• 读错误日志。
• 再修改。
• 再跑测试。

如果不管理上下文，任务还没做完，上下文窗口可能先满了。

flowchart LR
  A["初始上下文<br/>规则 + 用户目标"] --> B["第 1 轮<br/>读取文件结果"]
  B --> C["第 2 轮<br/>修改方案 + diff"]
  C --> D["第 3 轮<br/>测试日志"]
  D --> E["上下文变长<br/>成本增加、窗口变紧"]
  E --> F["压缩摘要<br/>保留关键状态"]
  F --> G["继续执行<br/>用更小上下文推进任务"]

这张图说明：长任务不能无限堆历史，需要把关键状态总结出来，再继续推进。

6.2 提示缓存为什么重要

文章里有一个很关键的性能点：新提示最好让旧提示成为它的精确前缀。

简单理解：

第一次请求：
A + B + C

第二次请求：
A + B + C + D

如果前面的 A + B + C 完全没变，就更容易复用之前的计算。

这就是提示缓存的价值。

对我使用 Agent 的启发：

• 不要在长任务中频繁改规则。
• 不要频繁切换模型。
• 不要随意改变工具列表。
• 项目规则要稳定放在前面。
• 变化的信息尽量追加在后面。

这和前端工程里的缓存思想类似：稳定部分越稳定，缓存命中率越高。

6.3 为什么 Codex 不依赖 previous_response_id

文章提到，Responses API 支持 previous_response_id 来减少反复发送历史，但 Codex 当前选择保持请求无状态。

原因主要是：

• 让不同 Responses API 提供方更容易实现。
• 支持零数据保留场景。
• 避免服务端必须保存完整历史。

我的理解：

==Codex 更偏向“客户端掌握完整上下文，服务端尽量无状态”。==
==这会带来更大的请求体，但换来更清晰的数据边界和兼容性。==

7. 压缩：长任务必须会“归纳状态”

当上下文太长时，Codex 会进行压缩。

压缩不是简单删除历史，而是把之前发生过的重要事情整理成更小的上下文，让 Agent 还能继续工作。

这对我有一个很实际的提醒：

在长任务里，我自己也应该主动帮助 Agent 归纳状态。

例如可以让 Agent 在关键节点总结：

请总结当前任务状态，包括：
1. 已完成什么。
2. 还剩什么。
3. 哪些文件被改过。
4. 当前风险是什么。
5. 下一步应该做什么。

这样能降低上下文噪声，也方便中断后继续。

8. 从前端架构师视角看这篇文章

8.1 Agent 不是外包，它更像“可调用工具的工程同事”

如果把 Agent 当外包，会只关心结果。

但从这篇文章看，Agent 更像一个运行在工程环境里的同事：

• 它会读项目上下文。
• 它会遵守项目规则。
• 它会调用工具。
• 它会根据反馈调整方案。
• 它也会受上下文窗口和权限影响。

mindmap
  root((Agent 协作能力))
    目标
      背景清楚
      验收明确
      不做什么
    上下文
      项目规则
      目录结构
      构建命令
    工具
      读文件
      改代码
      跑测试
    安全
      沙盒权限
      私密目录
      人工确认
    验收
      Git diff
      构建结果
      风险说明

所以我管理 Agent 的重点不是“让它多写代码”，而是：

• 给清楚目标。
• 给清楚边界。
• 给清楚验收标准。
• 让它先探索再修改。
• 要求它跑验证。

8.2 项目文档就是 Agent 的工程接口

AGENTS.md、README、目录结构、脚本命名、测试命令，本质上都是 Agent 和项目之间的接口。

如果这些内容混乱，Agent 就会做错事。

我应该在项目里沉淀：

• 构建命令。
• 测试命令。
• 目录职责。
• 禁止修改的范围。
• 提交前检查清单。
• 常见错误处理方式。

这不是给人看的文档而已，也是给 Agent 用的上下文。

8.3 工具输出要可读、可控、可验证

Agent 很依赖工具调用结果。

所以工程化上要尽量做到：

• 构建错误清晰。
• 测试输出明确。
• lint 规则稳定。
• 脚本职责单一。
• 日志不要过度噪声。

否则模型看到的上下文会很脏，下一步判断也会变差。

9. 我以后使用 Codex 的实践准则

9.1 发任务前

我应该先写清楚：

目标：
背景：
允许修改：
禁止修改：
验收方式：
风险点：

不要只说“帮我优化一下”。

9.2 执行过程中

我应该要求 Agent：

• 先读代码再动手。
• 先讲计划再改关键文件。
• 每次改动后运行相关验证。
• 遇到权限或不确定信息时停下来说明。
• 长任务中定期总结状态。

9.3 验收时

我不能只看最后一句回复。

我要检查：

• Git diff 是否符合目标。
• 有没有改到不该改的文件。
• 构建和测试是否真的通过。
• 是否泄露了私密目录或账号内容。
• 是否留下临时文件或调试代码。

10. 这篇文章对我当前知识库的启发

我现在正在搭一个“Obsidian 写作 + 自动生成文章 + AI 协作”的知识库。

结合这篇文章，我应该这样设计：

• build/ 作为工具和生成器目录，默认隐藏。
• 学习/、AI工作流/、文章/、日记/ 作为公开内容目录。
• 账号/、公司/ 永远不参与构建。
• 构建脚本要有明确的排除规则。
• 每次让 Agent 改知识库，都要检查产物里是否混入私密内容。

这其实就是把 Codex 文章里的思想落到自己的项目里：

Agent 能力越强，项目边界越要清晰。
自动化越方便，安全排除规则越不能模糊。

flowchart TB
  A["Obsidian 写作"] --> B["公开内容目录<br/>学习、AI工作流、文章、日记"]
  A --> C["私密内容目录<br/>账号、公司"]
  B --> D["构建脚本扫描"]
  C --> X["强制排除<br/>不进 Git、不进发布产物"]
  D --> E["静态站点<br/>首页、分类页、文章页"]
  E --> F["Cloudflare Pages 发布"]

这张图可以直接对应我的知识库：公开目录进入自动构建，私密目录必须在构建规则里被排除。

11. 我的行动清单

• 继续完善 AGENTS.md，让 Agent 明确知道我的回答风格、目录规则和安全边界。
• 给知识库构建脚本补充“敏感目录扫描”检查。
• 给常用项目建立 Agent 任务模板。
• 每次长任务后让 Agent 输出状态总结。
• 不把 AI 的最后回复当结果，要以文件变更、构建结果和验收标准作为结果。

12. 最终理解

Codex 的本质不是“更聪明的自动补全”，而是一套能把模型、工具、上下文和权限串起来的工程系统。

我使用 Codex 的能力，也不只是会写 prompt，而是要学会设计一个适合 Agent 工作的工程环境：

• 目录清晰。
• 规则明确。
• 工具可靠。
• 输出可验证。
• 权限有边界。
• 长任务可压缩、可恢复。

这就是 AI 时代工程师需要升级的地方：从写每一行代码，转向设计 Agent 能稳定工作的系统。