Vibe Coding - 深入剖析 Codex Agent Loop

文章目录一、为什么要研究 Codex 的 Agent Loop二、Agent Loop模型 工具的闭环1. Agent Loop 的基本结构2. 工具调用本质上仍是“文本生成”三、Codex 请求体instructions、input、tools 三段式设计1. instructions给模型装上「人格 工作流」2. input多源上下文的统一拼装3. assistant 消息与 phase 字段4. tools统一的函数工具接口四、一次完整工具调用的生命周期1. 模型生成工具调用消息2. CLI 端解析与执行3. 工具输出回流模型4. MCP 工具的映射五、Skills 与 AGENTS.md给 Agent 装上“插件系统”1. Skill 元数据与 AGENTS.md2. Skills 与 MCP 的关系六、Agent 优化的两条路线提示词工程 vs 训练 Agent1. 路线一基于执行反馈的「无训练」工作流training-free2. 路线二固定多轮 refinement loop 训练 Agent七、对工程实践的几点启示八、小结 态本篇面向有一定编程基础的开发者、对 Agent / 工具调用 / MCP 框架感兴趣的研究者和技术爱好者假定你对「大模型 工具调用」已有基本概念。一、为什么要研究 Codex 的 Agent LoopCodex 代表的是一类高度工程化的「代码智能体」coding agent它不仅是一个大模型接口而是一个围绕模型构建起来的完整 Agent 系统。作者通过 MITM 抓包 Codex CLI 的网络请求再对照 OpenAI 官方公开的《Unrolling the Codex Agent Loop》文档把当前主流 Agent 的技术路径拆开给你看。重点不在「模型本身有多强」而是聚焦三个问题一个现代 Agent以 Codex 为代表在协议层、请求体结构上长什么样。工具调用、MCP、Skills 等概念是如何通过提示词和 JSON schema 被绑定到模型上的。目前围绕 Agent 的优化与训练大致有哪两条路线各自的优劣势是什么。理解这些对你自建 Agent、调试 CLI 工具、设计自己的技能体系都有直接参考价值。二、Agent Loop模型 工具的闭环1. Agent Loop 的基本结构当前主流 Agent 的技术实现路径高度收敛几乎都是围绕「Agent Loop」展开的多轮闭环推理。典型流程大致如下用户输入被结构化为 Prompt含历史对话、工具输出等。请求进入模型推理inference模型输出两种东西之一普通自然语言回复Agent Response工具调用描述Tool Calls。工具调用只是「调用请求」的文本表示实际执行在本地 CLI/服务端完成。工具执行结果作为新的上下文再喂回模型进入下一轮推理。循环若干次后模型最终不再发出工具调用而是生成一条带assistant角色且phase final_answer的消息作为本轮对话的最终输出。模型并不知道「自己在调用哪个本地程序」它只是在一个统一的协议下输出结构化文本真正的工具调用逻辑解析、校验、执行完全在 Agent 容器如 Codex CLI中实现。2. 工具调用本质上仍是“文本生成”Tool calls 是模型输出的一部分是一种“广义文本生成”。即使模型「原生」不支持函数调用只要你统一协议约定 JSON schema用instructions织入足够强的约束提示词就可以让模型按 schema 生成合法的工具参数。这意味着工具调用能力不必成为模型训练时的内建能力而可通过后期工程协议层实现。在工程实践上这给了你一个重要启示不要神话「原生 Tool Calling 模型」更多时候是你协议层和提示词没有设计好。三、Codex 请求体instructions、input、tools三段式设计通过 MITM 抓包可以拿到一份完整的 Codex 请求体并对其结构进行了拆解。整体来说Codex 请求体可分为三大块instructions模型的基础人格与行为规范。input由多条 message 组成的对话与上下文。tools函数式工具定义包括本地 CLI 工具和 MCP 导出的工具。1.instructions给模型装上「人格 工作流」若~/.codex/config.toml中配置了model_instructions_fileCodex 会从该文件加载instructions否则使用内置的base_instructions例如gpt-5.2-codex_prompt.md。这段长 prompt 做了非常细致的约束大致包含几个层次角色定位「You are Codex, a coding agent based on GPT-5」强调其是代码智能体与用户共享工作区共同达成目标。核心价值观清晰必须显式、具体地展开推理和权衡。务实聚焦能推动目标前进的方案。严谨要求推理自洽主动暴露假设和不确定性。交互风格语言简洁不煽情、不打鸡血没有多余寒暄。优先给出可执行的指导而非抽象哲学。工具偏好搜索文件/文本优先使用rg而非grep强调实际效率。编辑约束默认使用 ASCII避免无意义引入 Unicode。少写废话注释只在复杂代码块前写简要说明。小范围改动优先用apply_patch避免用脚本大面积乱改。工作区可能是脏的绝不回滚用户未授权的改动避免破坏别人现场。禁用危险 git 操作如非用户明确要求不能执行git reset --hard或git checkout --。工作模式默认假定用户希望你「直接动手」而非只讲思路。需要从分析到实现到验证一条龙完成除非用户明确要求停在分析。特殊任务规范代码 review 时先列出问题和风险再做总结按严重程度排序并附文件/行号。前端设计时避免千篇一律「AI 风格」强调排版、色彩、动效、背景的整体设计不要用默认字体堆砌。输出格式与中间更新使用 GitHub 风格 Markdown禁止嵌套列表多层结构拆成多个段落。区分commentary与final两种 phase前者用于中间进度更新后者用于最终答案。长时间思考过程要频繁发中间进度避免长时间“失联”。从工程视角看这段instructions实际是一份「产品规范 工程规范 UI 规范 运维规范」的集合通过 prompt 而非代码约束模型行为。2.input多源上下文的统一拼装在用户真正输入之前Codex 会自动往input里插入几类 message沙盒权限描述roledeveloper描述sandbox_mode例如danger-full-access、网络是否开启、审批策略等。强调sandbox_permissions字段不要乱用否则命令会被拒绝。说明该沙盒仅对 Codex 自带的 shell 工具生效MCP 工具需自行保证安全。协作模式说明roledeveloper当前在Default模式还有Plan等其他模式。request_user_input工具在默认模式下不可用若需要信息应直接向用户提问而不是调用该工具。模式只会被新的 developer 指令修改用户输入或工具描述不会隐式切换模式。AGENTS.md聚合内容roleuser并非来自单一文件而是从多个来源聚合$CODEX_HOME下的AGENTS.override.md与AGENTS.md。从项目根目录往上逐级查找 AGENTS 类文件受总大小限制。已配置 skills 的元数据与「如何使用 skills」的一段说明。最终以一段# AGENTS.md instructions for ...开头的大文本送入模型包含当前可用 skills 列表名称、描述、文件路径。触发规则用户显式提到$SkillName或任务语义吻合就必须使用对应 skill。使用流程先按需打开SKILL.md只读必要内容引用的scripts/、references/等路径如何解析如何控制上下文大小等。安全与回退策略skill 缺失或路径不可读时如何优雅降级。本地环境描述roleuser指定当前工作目录与 shell例如 /Users/mbolin/code/codex5 zsh这些信息让模型能推断当前工程上下文与命令环境。之后才是用户自己的请求消息比如IDE 上下文当前活跃文件example.py、已打开的 tab 等。自然语言请求「你好使用一些 function。」这些都被打包进input数组统一作为模型的多轮对话输入。3.assistant消息与phase字段Codex 通过phase字段区分内部过程与最终输出例如一条roleassistant, phasecommentary的消息内容为「好的」用于中间确认或状态更新。最后一条roleassistant, phasefinal_answer的消息内容为「最终答案」代表本轮对话的闭环输出。你在自建 Agent 时完全可以借鉴这种设计把「模型内部推理进度」和「给用户看的最终答案」显式区分有利于做流式展示、进度条、日志追踪等。4.tools统一的函数工具接口请求体中的tools字段是一个列表包含所有可由模型调用的函数工具包括本地 CLI 工具如exec_command、多 Agent 管理工具如spawn_team以及 MCP 导出的 Playwright 工具等。每个工具都有统一结构{type:function,name:exec_command,description:Runs a command in a PTY, returning output or a session ID for ongoing interaction.,strict:false,parameters:{type:object,properties:{cmd:{type:string,description:Shell command to execute.},...},required:[cmd],additionalProperties:false}}模型只需要遵守parameters中定义的 JSON Schema 即可生成合法调用参数。四、一次完整工具调用的生命周期以exec_command为例演示一下工具调用在协议层的完整生命周期。1. 模型生成工具调用消息在看到tools列表后模型根据用户请求决定要调用哪个工具并生成一条类型为function_call的消息例如{type:function_call,name:exec_command,arguments:{\cmd\:\$i0; Get-Content example.py | ForEach-Object { $i; if($i -ge 60 -and $i -le 95){ {0,6}: {1} -f $i, $_ } }\},call_id:call_cS4cdkFfY012HOc2aDN7sgil}几个要点arguments是一个字符串其内容是一个 JSON 对象的序列化结果。该 JSON 对象结构必须符合tools[].parameters的 JSON Schema。call_id用于在后续的function_call_output中关联这次调用与单次对话中的其他调用区分。2. CLI 端解析与执行CLI 收到这一消息后大致会执行如下流程consttoolregistry[item.name];// 找到 exec_commandconstargsJSON.parse(item.arguments);// 反序列化为对象validate(args,tool.schema);// 按 JSON Schema 校验constresultawaittool.handler(args);// 调用底层实现这里的handler就是真正执行的 shell 命令封装返回 stdout、exit code 等信息。3. 工具输出回流模型执行完成后CLI 会生成一条function_call_output消息再发回模型继续推理例如{type:function_call_output,call_id:call_cS4cdkFfY012HOc2aDN7sgil,output:Chunk ID: 70865e\nWall time: 3.8904 seconds\nProcess exited with code 0\nOriginal token count: 421\nOutput:\n 60: example text for showcase}模型在新的上下文中看到这条消息后就相当于「看到了一次命令行执行结果」可以基于此继续生成新的function_call或assistant自然语言回复。4. MCP 工具的映射对于 MCPModel Context Protocol服务导出的工具CLI 也会把它们统一映射为typefunction的工具并放入tools列表中。严格来说 MCP 还支持Tools由模型控制的工具调用。Resources由应用控制的数据源。Prompts用户可定义和复用的模板。但在 Codex 的请求体中当前主要以「工具」这一维度呈现未来这部分预计会被更系统地抽象为 Skill。一个 MCP 工具/资源/Prompt 定义示例mcp.tool()defadd(a:int,b:int)-int:Add two numbersreturnabmcp.resource(greeting://{name})defget_greeting(name:str)-str:returnfHello,{name}!mcp.prompt()defgreet_user(name:str,style:strfriendly)-str:returnfWrite a{style}greeting for{name}.通过 MCP这些能力可以被统一暴露给模型侧的 Agent 调用。五、Skills 与 AGENTS.md给 Agent 装上“插件系统”除了工具Codex 还强调了 Skills 的概念它与 MCP 更偏「远程能力」不同Skills 更像是「本地工作流 知识包」的组合。1. Skill 元数据与 AGENTS.md以sync-fork-upstream为例Skill 元数据来自其SKILL.md文件的 YAML 头部***name:sync-fork-upstreamdescription:Sync a long-lived fork with its upstream repository by fetching latest upstream commits,creating a fresh sync branch/worktree,and merging or cherry-picking only the useful changes into the fork. Use when a fork is not merged back upstream and you need to selectively incorporate upstream updates.***Codex CLI 会收集所有可用 skill 的元数据并在生成的AGENTS.md文本中给出名称、描述、文件路径如/.codex/skills/xxx/SKILL.md。同时在「How to use skills」一段中详细说明了使用规范例如触发规则显式命名或语义匹配。使用流程读多少SKILL.md、如何按需加载scripts//references/等。上下文控制尽量摘要、避免大段粘贴。多 skill 协作如何选择最小集合并声明使用顺序。错误处理skill 不存在或路径不可读时如何降级。从模型角度看它并不知道「Skill 是一个本地文件」它只看到了「一段说明中列出的能力 使用规则」但这已足够指导其在特定任务下遵循本地的工作流设计。2. Skills 与 MCP 的关系当前 MCP 的工具部分在协议层和 function calling 上已经基本统一但在未来更合理的形态是把 MCP 工具和本地指令以 Skill 为单位封装形成统一的「插件系统」。对自建系统而言可以借鉴的思路用 Skill 将一组「业务工作流、最佳实践、工具调用模式」固化在一个SKILL.md 脚本目录中用 AGENTS 文档向模型宣告有哪些 Skill、触发条件和使用流程用 MCP 把远程资源和工具包装成 Skill 可见的能力。六、Agent 优化的两条路线提示词工程 vs 训练 Agent「如何让 Agent 更强」这一问题主要有两条主线研究方向。1. 路线一基于执行反馈的「无训练」工作流training-free这一路线依赖「不改模型只改工作流」的思路通过手工设计的 refinement heuristics精心设计的改写/分解/验证策略结合执行反馈进行决策。例如先让模型给出方案再通过执行结果决定是否重试、如何改写、是否增加额外上下文等。优点无需训练基础模型适合直接套用现成 API。开发周期短灵活可调。缺点上限受基础模型能力限制尤其是在「模型未专门训练的任务」上比如 CUDA 编程。复杂启发式很容易变成“if-else 地狱”难以系统化维护。文章引用的观点指出对于 CUDA 这类 base model 能力缺失的任务training-free 的改写和多轮 refinement 只能有限提升性能上限被模型本身严重限制。2. 路线二固定多轮 refinement loop 训练 Agent另一条研究路线则是「围绕一个固定的多轮 refinement loop对基础模型进行微调甚至用执行反馈做 RL」。思路是设计一个固定形态的 Agent loop例如「生成方案 → 执行 → 观测 → 修正 → …」。大量采集真实使用数据或合成数据对模型进行监督微调或强化学习。优点可以显式教会模型特定任务的 debug、搜索、profiling 策略。对垂直任务如 CUDA coding能获得远高于 training-free 的收益。缺点固定 loop 会浪费上下文每轮都要包含所有历史解答。反过来约束了 Agent 的自主性难以学习更灵活的调试/搜索模式。训练成本高数据采集要求高。有团队选择用 MITM 方式对各种 Agent 框架进行「透明代理」在网关上截取 token 级别请求和响应数据用于构建大规模 RL 训练数据集OpenAI Chat Completions / Responses 端点。Claude 的messages端点。Gemini 的beta端点。这类方案的核心判断是现代互联网大量应用基于前后端分离MITM 能在不侵入应用代码的前提下抓到最底层的真实请求参数与返回结果是一种高性价比的数据采集方式。此外AReal 这类系统通过完全异步的 RL 训练管线提高算力利用率、降低成本。但作者也提醒目前围绕 Agent 的脚手架、基础设施仍很混乱LangChain、CAMEL-AI、Claude Code 等生态割裂严重现在下场重投入未必是最佳时机更稳妥的做法是先观察生态演化。七、对工程实践的几点启示把工具调用当成“文本协议问题”来设计统一 JSON schema、定义好 tool 列表、明确参数含义和必选字段再用 instructions 将这套约束“灌”进模型即可。不必强依赖某个厂商的「原生工具调用」作为前置条件。为 Agent 设计一份「工程级行为规范」类似 Codex 的instructions要覆盖人格、风格、工具使用、防护措施、编辑规范等。对 git、文件操作等高风险行为做明确禁止和例外说明。把本地最佳实践抽象成 Skill 文档使用类似SKILL.md的文件组织你的工作流结合 AGENTS 文档向模型暴露这些能力。这比单纯写几段 prompt 可靠得多也更容易随着团队共识演化。接入 MCP 但不要停留在「工具列表」层面MCP 给你的是一个通用「远程工具/资源/Prompt」框架你需要在上层用 Skill 和 AGENTS 等文档把这些能力组织成可解释、可发现的插件体系。在训练前先把 training-free 工作流打磨到极致先通过抓包、日志、user study 把工作流设计好再考虑把这套 loop 固化进模型训练。否则一旦训练错误行为后续纠偏成本会很高。八、小结 态强 Agent 不是靠一个「更大的模型」堆出来的而是模型 工具协议 instructions Skills 数据闭环 的综合工程产物。如果你正在构建自己的 Agent 系统或者评估如何利用 Codex/Claude Code 等工具协助开发这篇分析提供了非常具体的参考样板请求体怎么组织、工具如何暴露、Skill 如何注入、工作流如何设计、训练与非训练路线如何取舍都有相对明确的工程路径可循。