当开发者第一次使用 OpenAI Codex CLI 时，最直观的感受往往是「它真的在一步一步地帮我写代码」。这种感知背后是一套精心设计的代理循环机制：模型思考当前任务，决定调用哪些工具，观察执行结果，然后进入下一轮思考。整个过程循环往复，直到模型认为任务完成。理解这套循环的内部运作原理，不仅有助于更好地使用 Codex，也为构建自研代理系统提供了可复用的架构参考。
单代理 ReAct 循环的核心结构
Codex CLI 的核心循环遵循经典的 ReAct 模式，即「思考（Think）→ 工具调用（Act）→ 观察（Observe）→ 重复」的四阶段迭代。这一循环在 AgentLoop.run() 函数中实现，接收用户输入后构造完整的对话上下文，其中包括详细的系统提示词。系统提示词扮演着关键角色：它不仅是行为规范的载体，更是一份面向模型的「工具使用说明书」，将 Codex 支持的每个工具都编码为 mini-API 的形式，明确告诉模型应该如何格式化调用指令、如何解析返回值、何时应该停止请求工具。
在典型的交互流程中，用户输入类似「将 utils.ts 重构为箭头函数」这样的任务描述后，CLI 将其与系统提示词拼接，通过 OpenAI 的 Responses API 发送请求。模型在流式响应中可能声明需要调用工具，此时 CLI 拦截这些请求，验证其安全性后执行对应操作，再将标准输出、标准错误和退出码封装为观察结果反馈给模型。整个过程作为一次完整的迭代回合，与模型共享对话历史的累积上下文。这种单代理、顺序执行的架构避免了多代理并发带来的状态同步复杂性，使得执行路径清晰可追溯，同时为问题排查提供了明确的断点。
动作生成的约束与工具契约
Codex 的工具设计体现了「简约而约束」的原则。与其他代理系统提供大量专用工具不同，Codex 将能力收敛到单一的统一接口：通用的 shell 命令执行器。这意味着模型可以通过 cat 读取文件、通过 grep 或 find 搜索内容、通过 ls 列出目录、通过 apply_patch 生成统一格式的补丁来编辑文件。这种设计让模型能够复用熟悉的命令行工具链，无需学习新的 API 命名和参数规范。
文件编辑尤其值得单独分析。Codex 不要求模型输出完整的文件内容，而是生成符合统一 diff 格式的补丁片段。CLI 内部拦截 apply_patch 命令，将其解析为标准的统一 diff，渲染为红删绿增的彩色差异视图供用户审核。用户可以选择批准、拒绝或修改补丁内容后批准。这种 diff 优先的工作流天然支持小步迭代：每次修改都是可审计的最小变更，便于人类审查和通过 git 进行回滚。系统提示词中明确强调「使用 apply_patch 进行文件编辑」，将这一约束编码为模型的行为倾向，使其倾向于生成精简、可审查的补丁而非大段重写。
迭代终止的判定逻辑
代理循环何时结束是代理系统的核心问题之一。Codex 的终止判定相对简洁：当模型在响应中不再请求任何工具调用时，当前任务即被视为完成。模型输出最终答案后，循环结束，控制权返回用户或上层调用方。这一设计隐含了一个假设 —— 模型能够准确判断任务是否已经完成。然而实践中可能出现模型过早认为「完成」而遗漏细节的情况，因此 Codex 在系统提示词中加入了「运行项目自身的检查验证」的行为引导，鼓励模型通过执行测试、linter 或其他验证命令来确认变更的正确性，而非仅凭自身判断。
对于长时间运行的任务，Codex 通过 MCP 协议暴露的 threadId 实现会话持久化。每次工具调用都会返回 threadId，后续请求携带同一标识即可恢复对话上下文。这使得 Codex 能够被嵌入到更复杂的代理编排中，作为可中断、可恢复的组件使用。MCP 服务器模式下，调用方通过 codex-reply 工具在已有会话上继续交互，适用于需要人工介入审查或跨越多个会话完成的多阶段任务。
安全边界：审批模式与沙箱策略
赋予代理系统级访问权限带来的安全风险不容忽视。Codex 实现了多层防护机制，其中最外层是面向用户的审批模式。系统提供三种操作级别：Suggest 模式自动批准读取类操作而对修改和执行类命令要求确认；Auto-Edit 模式在展示补丁后自动应用更改，但仍会就执行命令请求许可；Full Auto 模式则给予完整自主权，仅受沙箱边界约束。审批逻辑通过 canAutoApprove 函数实现，根据操作类型（读取、写入、执行）和当前模式动态判定放行或拦截。
沙箱机制构成了另一道安全屏障。在 macOS 系统上，Codex 利用 Apple Seatbelt 配置文件限制文件系统访问范围，仅允许在项目目录内操作，并阻止所有网络访问（OpenAI API 除外）。在 Linux 系统上，则运行于 Docker 容器内部，配合 iptables 防火墙规则实现类似的访问控制。这些 OS 级别的约束确保即使代理被诱导执行危险命令（如 rm -rf 或访问 /etc/passwd），也会因为超出沙箱边界而被系统直接阻止。沙箱参数可通过命令行传递 sandbox 选项配置，支持 read-only、workspace-write 和 danger-full-access 三种级别，开发者可根据任务风险承受度选择合适的隔离程度。
工程实践中的配置要点
在生产环境或高频使用场景中，有几个配置参数值得特别关注。首先是审批策略的选择：对于需要频繁进行小规模编辑的日常开发任务，Auto-Edit 模式能够在保持人工审查的同时减少交互打断；对于自动化流水线或持续集成中的代理调用，Full Auto 模式配合严格的沙箱配置可以最大程度实现无人值守运行。其次是会话超时配置，MCP 服务器模式下的 client_session_timeout_seconds 参数决定了长时间闲置会话的存活时间，默认值通常较为保守，在需要代理处理耗任务时应适当调高。
对于需要将 Codex 嵌入自研代理系统的开发者，理解其 MCP 接口的两个核心工具至关重要。codex 工具接受任务提示并返回 threadId，用于开启新会话；codex-reply 工具携带 threadId 和后续提示，继续已有会话。通过 OpenAI Agents SDK，可以将 Codex 封装为团队中的特定角色（如「代码实现专家」），在多代理工作流中通过 handoff 机制将任务委派给它执行，同时由其他代理负责需求分析、测试验证或文档撰写等职责。这种编排方式将 Codex 的能力与自研系统的业务逻辑解耦，既利用了成熟代理的能力，又保持了架构的灵活性。
资料来源：本文技术细节参考 OpenAI Codex 官方文档及 PromptLayer 对 Codex 内部机制的深度分析。