Codex CLI / Agent Harness

Codex Agent Loop 流程图

这个页面基于 OpenAI 官方工程文章整理，展示 Codex 如何在一个会话 turn 中把用户请求、模型推理、工具调用和工具结果串成循环，直到返回最终回复或继续追问。

主循环

点击左侧步骤查看说明。右侧流程图会高亮当前步骤。

接收用户输入

Codex 从用户请求开始，准备把这条请求和已有会话历史、环境信息、指令、可用工具一起送入模型。

INPUT 用户请求

用户描述希望 Codex 完成的软件工作。

CONTEXT 构建 prompt

组合 instructions、tools、input、环境和历史。

INFERENCE 模型推理

通过 Responses API 采样模型输出。

BRANCH 最终回复或工具调用

模型要么回答用户，要么请求执行工具。

TOOL 执行工具

Codex harness 负责运行命令、读写文件或调用 MCP 工具。

OBSERVATION 观察结果

工具输出被追加回上下文，进入下一轮推理。

END assistant message

模型停止请求工具，Codex 把本轮结果交还给用户。

一个 turn 不是一次模型调用，而是可能包含多轮 inference 与 tool call。
工具执行可能产生真正的外部效果，例如修改本地代码或运行测试。
随着历史增长，Codex 需要管理上下文窗口、缓存命中和自动压缩。

Prompt 里有什么

OpenAI 文章重点说明了 Codex 不是只把用户文本发给模型，而是组织一组结构化输入。

初始输入

  • 模型或用户配置中的 instructions。
  • 可用工具定义，例如 shell、计划工具、web search 或 MCP 工具。
  • AGENTS.md、skills、项目说明等用户指令来源。
  • 当前工作目录、shell、沙箱和审批模式等环境信息。
  • 用户刚刚发送的请求。

循环追加

  • 模型请求的工具调用会被执行。
  • 工具输出会作为新的输入追加到上下文。
  • Codex 再次调用模型，让模型基于新观察继续判断。
  • 当模型输出 assistant message，而不是工具调用时，本轮结束。

工程上的关键点

Agent loop 的难点不只是流程控制，还包括安全、性能和上下文管理。

安全边界

  • Codex 提供的 shell 工具受沙箱和审批模式影响。
  • MCP 工具通常需要由各自服务实现自己的保护规则。
  • 一次 turn 的主要产物可能是代码变更，而不只是聊天文本。

性能边界

  • prompt 前缀尽量保持稳定，以便利用 prompt caching。
  • 中途改变工具、模型、工作目录或沙箱配置可能影响缓存命中。
  • 上下文接近限制时，Codex 会通过 compaction 继续保留有效状态。

资料来源

本页是中文整理和可视化，不是 OpenAI 官方译文。