Codex智能体：从零系统学习智能体

核心结论：Codex智能体的本质是一套“Harness（运行框架）”，它把模型能力封装成可管理的执行循环。从零系统学习，意味着先理解这个循环的四个基本动作（组装提示、推理、调用工具、判断终止），再掌握三个工程约束（上下文窗口管理、提示缓存、沙箱边界），最后通过最小可运行的系统把原理“跑”一遍。

一、Codex智能体的准确定义：Harness，而非“模型+提示词”

在OpenAI的术语体系中，“Codex”涵盖Codex CLI、Codex Cloud和VS Code扩展等一系列产品。但这些产品共享的底层执行系统，称为Harness（运行框架）。它是智能体循环的核心逻辑，负责协调用户、模型和工具三者的交互。

这个区分至关重要。很多人把智能体理解为“一个会调用工具的模型”，但Harness存在的意义恰恰说明：模型本身不维护会话状态、不执行命令、不管理上下文窗口。这些职责全部由Harness承担。Codex的开源策略也印证了这一点：公开的是Harness层，模型访问本身仍是独立的付费服务。

二、智能体循环的四个基本动作

Codex的Agent Loop可以拆解为四个循环执行的步骤：

第一步：组装提示（Prompt Assembly）。 智能体不会把用户输入直接交给模型，而是拼接一个结构化的JSON负载，包含四类内容：系统指令（智能体通用规则，如编码标准）、工具列表（可调用的MCP服务器）、输入内容（用户消息、AGENTS.md、环境信息）、对话历史。

第二步：推理（Inference）。 提示词被转换为Token序列，送入模型采样，生成输出Token。输出可能触发两类事件：一条给用户的最终消息，或一个工具调用请求。

第三步：工具调用与结果回填。 如果模型请求工具调用，Harness执行该工具（运行命令、读写文件、调用MCP），将输出结果追加到原始提示中，然后再次查询模型。

第四步：终止判断。 循环持续，直到模型不再发出工具调用，而是生成一条“助手消息”（assistant message）。这条消息标志着本轮对话的结束，控制权交还用户。

从零理解这个循环，比学习任何框架都重要。GitHub上的agentic-ai-engineering项目明确指出：“先自己构建循环、工具执行器和记忆层，然后再引入框架。了解每个抽象层隐藏了什么，再让它替你隐藏。”

三、三个必须掌握的工程约束

循环的逻辑是简单的，让它稳定运行却需要处理三个工程问题。

约束一：上下文窗口管理

智能体在一个对话轮次中可能发起数百次工具调用，每次调用和结果都追加到提示中。提示长度持续增长，而模型的上下文窗口有硬性上限。Codex的应对策略是压缩（compaction）：当对话长度超过设定阈值时，调用特殊端点生成会话的紧凑表示，替换之前的完整输入。

从零学习的重点在于理解：上下文管理不是“优化”，是正确性问题。不处理，智能体在复杂任务中就会因窗口耗尽而失效。

约束二：提示缓存与Token效率

OpenAI工程师在博客中透露了一个关键数据：LLM推理性能与发送到Responses API的JSON数量呈二次方关系。提示缓存是把它变成线性的唯一手段。

Codex CLI早期的一个真实bug说明了缓存的脆弱性：MCP工具列表的枚举顺序不一致，导致缓存频繁失效。修复方式是以一致顺序枚举工具。这个细节的启示是：智能体开发中，任何“看起来无害”的不一致性（工具顺序、文件路径格式、时间戳）都可能破坏缓存，带来成本骤增。

约束三：沙箱与权限边界

Codex的Harness在OS层面强制执行沙箱策略。环境类型有三种：none（无需计算环境）、openai_hosted（OpenAI托管的沙箱）、self_hosted（自有基础设施）。

自定义子智能体时，权限可以在agent文件中单独指定。一个典型的只读侦察兵配置使用 sandbox_mode = "read-only"，强制该智能体只能读取、不能修改。这种按agent粒度控制权限的设计，是多智能体系统的安全基础。

四、从零系统学习的推荐路径

基于上述原理，系统学习可以按三个阶段推进。

阶段一：手写最小循环（1-2天）。 不引入任何框架，用Python或Node直接调用Responses API，实现“发送消息→接收工具调用→执行工具→回填结果→再次查询”的完整循环。目标是亲手写出一个能运行ls命令并基于结果继续推理的智能体。这个练习会暴露所有基础问题：工具Schema设计、错误处理、循环终止条件。

阶段二：加入工程约束（3-5天）。 在最小循环基础上，依次加入：简单的上下文压缩（如摘要最近N轮）、工具列表的稳定排序（保护缓存）、沙箱边界的模拟（限制可执行命令的范围）。Codex Agentic Patterns项目提供了21个生产级模式的参考实现，覆盖提示链、路由、并行化、沙箱升级等方向。

阶段三：理解平台化集成（1周+）。 当需要构建产品级应用时，理解Codex的三层集成选项：codex exec用于脚本和CI任务，Codex SDK用于应用内程序化控制，app-server用于需要完整生命周期管理的产品集成。从零学习的终点不是“会调API”，而是知道在什么场景下选择哪一层抽象。

五、一个被低估的学习原则

Codex的开源Harness为“从零学习”提供了独特条件：你可以阅读生产代码来验证自己的理解。GitHub上的 openai/codex 仓库包含了智能体循环、工具系统、沙箱机制的真实实现。artvandelay/codex-agentic-patterns项目则直接从Codex CLI中提取模式，提供带运行代码的教学材料。

学习的正确顺序是：先自己构建，再看生产实现，然后对比差异。直接读源码而不先自己构建，你会把“Codex的实现选择”误认为是“智能体的必然设计”。反之，先动手写一个能跑的最小循环，再看Codex如何处理缓存、压缩、权限，你才能理解每一个工程决策在解决什么问题。