一、Harness：让模型真正干活的运行系统
多数人理解AI Agent时，脑海中只有“Prompt + 大模型”两个元素。但一个能在真实环境中稳定工作的Agent，远不止这些。它需要管理上下文、循环调用模型、执行工具、维护会话状态、处理权限审批、在沙箱中运行代码，还要应对错误和中断。包裹在模型外部、负责调度这一切的“运行系统”，就是OpenAI此次开源的Harness。
可以这样类比：模型是大脑，Prompt是临时指令，工具是手脚，上下文是工作记忆，会话状态是进度条，沙箱是活动边界，审批是重大操作的门禁，而Harness则是把这些部分串联起来的神经系统与调度中枢。OpenAI官方对Harness的定义也很直接：它负责维护会话状态、流式执行、调用工具、执行沙箱和审批策略，并让工作能够跨多个Turn持续进行。
这里值得注意的一点是：开源Harness并不等于开源模型权重。模型访问和Codex Cloud等托管服务仍是独立的。这意味着，OpenAI真正想开放的是“如何构建一个生产级Agent”的工程范式，而非模型本身。对于开发者而言，这反而更有价值——因为模型能力会快速迭代，而Agent的骨架设计才是长期沉淀的资产。
二、Codex整体分层：从入口到核心
打开Codex仓库时，不要急着钻进几千行Rust代码。先建立一张整体地图。Codex的结构可以简化为四层：使用入口、App Server、Codex Core、执行与安全层。
使用入口包括Codex CLI/TUI、IDE插件、桌面客户端，以及Python SDK、TypeScript SDK等。这些入口都通过同一套协议连接到App Server。App Server是产品集成层，它不像是一个独立Agent，而更像一个面向客户端的后端服务，负责协议路由、线程管理、事件流和审批交互。Codex Core则是业务逻辑核心，实现了Agent Loop、上下文管理、模型调用、Session/Turn管理和工具调度。执行层负责Shell命令、文件读取、Apply Patch、MCP调用等实际操作；安全与状态层则包含Sandbox、Approval、Policy以及Thread Store等持久化机制。
如果拿Web开发来类比，Codex Core相当于业务领域层和运行时，App Server相当于FastAPI或WebSocket服务层，协议相当于前后端约定的DTO，而各种客户端就是不同的前端。这种分层设计非常清晰，值得所有Agent项目借鉴——把业务逻辑与接口协议分离，才能支撑多端接入和快速迭代。
三、核心概念：Thread、Turn、Item与Agent Loop
理解Codex的关键不是读目录，而是追踪一条完整的任务流。官方称之为Agent Loop：用户输入触发一个Turn，系统组装上下文，调用模型，模型可能返回最终消息，也可能要求调用工具。如果调用工具，Harness执行工具后把结果追加到上下文，再次请求模型，如此循环直到模型输出最终消息。
在App Server的协议中，Thread、Turn、Item是三个最基本的概念。Thread代表一整段会话，可以包含多个Turn；Turn是用户发起的一轮任务，从输入开始到最终消息结束；Item则是Turn内部的具体事件，包括用户消息、推理内容、Shell命令、工具调用、文件修改、审批请求等。所有Item都会被持久化，并作为后续会话的上下文。这种设计把“聊天记录”和“Agent实际动作”统一成了可追踪的数据结构，对业务Agent的日志审计和状态恢复非常有参考价值。
App Server的典型生命周期是：initialize → thread/start或thread/resume → turn/start → 持续接收Item事件 → turn/completed。默认基于stdio的JSONL双向通信，每行一个JSON消息。WebSocket传输虽然已在代码中出现，但官方仍标记为实验性，不建议生产依赖。想深入研究，建议重点阅读codex-rs/app-server/src/message_processor.rs和thread_state.rs，前者追踪请求路由，后者追踪线程状态转换。
四、实战：用Codex解剖Codex的“一纵三横”法
面对Codex这种大型单体仓库，直接让AI“分析整个项目”通常只会得到目录总结。更有效的方法是“一纵三横”：纵向追踪一个完整任务（从用户输入到Turn完成），横向理解三个关键层面——上下文如何组装、工具如何调度、状态如何持久化。
以下是一套可直接复制的提示词，引导Codex自动克隆源码、追踪调用链并生成中文架构文档。使用时请先记录当前commit hash，因为Codex迭代很快，确保分析版本可复现。
提示词示例：“请克隆OpenAI Codex仓库（记录commit hash），然后从App Server的message_processor.rs入手，追踪一次turn/start请求的完整调用链，重点说明：1）请求如何被解析并传递给Codex Core；2）Agent Loop中模型调用与工具执行的循环条件；3）Thread、Turn、Item在代码中如何表示和持久化；4）审批与沙箱在什么节点介入。最后用中文输出一份架构文档，包含关键模块路径和调用流程图。”执行时建议让Codex以子Agent模式运行，分步验证每一步的代码引用，避免幻觉。
通过这种方式，你不仅能深入理解Codex的设计哲学，还能掌握一套分析任何大型Agent项目的通用方法论。这正是开源Harness带给开发者的最大礼物——不是代码本身，而是它展示的生产级Agent工程标准。