category
library
Created time
Feb 19, 2026 04:39 PM
date
Feb 3, 2026
icon
password
slug
unrolling-codex-agent-loop
status
Published
summary
揭秘 OpenAI Codex 的智能体循环（Agent Loop），探讨其核心逻辑及在本地环境中实现高效代码修改的机制。
tags
OpenAI
工程实践
type
post
Unrolling the Codex agent loop | OpenAI
Codex CLI 是 OpenAI 推出的跨平台本地软件智能体（Agent）。它的目标很简单：在保证安全的前提下，高效地帮你完成高质量的代码修改。
自今年 4 月发布以来，我们在构建顶级软件智能体方面积累了大量经验。为了分享这些洞察，我们开启了这个系列博客。本文是第一篇，我们将深入探讨 Codex 的核心逻辑——智能体循环（Agent Loop）。
如果你想看更硬核的代码实现，可以去翻我们的开源仓库：https://github.com/openai/codex。
术语说明：在 OpenAI，“Codex” 包含 CLI、云端服务和 VS Code 插件。本文重点讨论支撑这些体验的核心引擎——Codex Harness（即智能体循环逻辑）。
1. 什么是智能体循环？
智能体循环是 AI 的“大脑”：它负责协调用户、模型和工具之间的交互。
基本流程如下：
- 输入：智能体接收用户指令，将其包装成 Prompt（提示词）。
- 推理（Inference）：将 Prompt 发送给模型。模型将文本转化为 Tokens，经过计算后再转回文本。
- 决策：模型会做出两种选择：
- (1) 直接给出最终回复。
- (2) 请求调用工具（Tool Call）（例如：“运行
ls命令并告诉我结果”）。
- 执行与反馈：如果是后者，智能体执行工具，将结果追加到 Prompt 中，再次请求模型。
这个过程会不断重复，直到模型给出最终的 Assistant Message（助手消息）。
在 Codex 中，智能体的产出不仅是对话，更是它在你机器上实际修改的代码。每完成一次“用户输入 -> 最终回复”的过程，我们称之为一轮 Turn（对话轮次）。
2. 模型推理：Prompt 是如何构建的？
Codex CLI 通过 Responses API 与模型通信。
构建 Prompt 时，Codex 会根据**角色（Role）**分配权重，优先级从高到低依次为：
system > developer > user > assistant。- Instructions（指令）：从本地配置文件读取，定义模型的基本行为。
- Tools（工具）：模型可以调用的工具列表（如
shell、update_plan或通过 MCP 协议接入的第三方工具）。
- Input（输入）：包含沙箱权限说明、开发者自定义指令、项目文档（如
AGENTS.md）以及当前的环境上下文（当前目录、使用的 Shell 类型等）。
3. 性能优化：Prompt Caching（缓存）
随着对话进行，Prompt 会变得非常长。如果每次都重新计算，速度会慢得无法忍受。
关键技术：Prompt Caching。
只要新请求的 Prompt 前缀与之前的完全一致，模型就能复用之前的计算结果。这意味着：模型采样变成了线性增长，而非平方级增长。
为了最大化缓存命中率，Codex 遵循以下原则：
- 静态内容在前：将指令、工具定义等固定内容放在 Prompt 开头。
- 动态内容在后：将用户输入、工具执行结果放在末尾。
- 保持顺序一致：Codex 曾因 MCP 工具排序不一致导致缓存失效，现在已修复。
4. 上下文管理：Compaction（压缩）
模型能处理的 Token 数量是有上限的（即 Context Window）。
当对话太长快要“爆表”时，Codex 会执行 Compaction（压缩）：
- 调用特殊的
/responses/compact接口。
- 将冗长的历史对话总结成一个精简的列表。
- 腾出空间，同时让模型保留对之前对话的“记忆”。
总结与预告
智能体循环是 Codex 的基石。通过精妙的 Prompt 构建、缓存机制和自动压缩，Codex 实现了在本地环境下的高效运作。
接下来的文章中，我们将深入探讨 Codex 的架构设计、工具实现细节以及沙箱安全模型。敬请期待。