![](data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="%23D95C41" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><line x1="12.1" y1="11.9" x2="18.9" y2="8.2" /><line x1="12.1" y1="12.1" x2="20.3" y2="12.9" /><line x1="12.2" y1="12.4" x2="16.6" y2="19.1" /><line x1="11.8" y1="12.4" x2="7.3" y2="19.2" /><line x1="11.9" y1="12.1" x2="3.7" y2="13.3" /><line x1="11.8" y1="11.7" x2="7.8" y2="4.4" /></svg>)
拆解 Codex 的 harness 设计
2026 年 8 月 19 日，OpenAI 在《Codex as a platform: build on the open agent harness》里宣布：把驱动 Codex 的整个 harness 以 Apache-2.0 协议全面开源。这不是又一个 CLI 工具开源——OpenAI 把自家顶级 AI 智能体的"发动机"直接交给了开发者，让你可以在自己的产品、工程工具、运营看板里嵌入完整的智能体循环，而不是把业务流程硬塞进一个通用聊天框。
Codex 可能是四款产品里和"harness 原教旨"绑定最深的一个。那篇定义了整个领域名字的《Harness Engineering》，本身就是 OpenAI 团队用 Codex 写产品时的经验总结。如今 Codex 把 harness 从"产品里的隐藏层"变成了"开源平台"，等于把那篇文章背后的工程实践连同源码一起公开了。
Codex 的哲学可以浓缩成一句话：可复用的部分是智能体循环（agent loop），仓库即事实来源，AGENTS.md 只是目录页，工程的价值在于设计环境、表达意图、构建反馈循环。
一句话定位
OpenAI 团队用 Codex 在几周内交付了一个最终上百万行代码的产品，每一行代码都是 Codex 写的（原文见 Harness Engineering 的 "Designing for growth" 一节）。他们的实践回答了一个问题：当工程师的角色从"写代码"变成"设计 harness"时，系统该怎么组织。
如今这套 harness 已经作为开源平台发布，核心是一个 Rust 实现的单体二进制（github.com/openai/codex，Apache-2.0，Rust 占 96.4%）。它管理会话状态、流式执行、工具调用，强制配置好的沙箱与审批策略，并把工作跨回合地推进。它对 harness 的贡献主要在约定（convention）、上下文工程和可嵌入的智能体循环上，而不是花哨的扩展点。
harness 的价值：ARC-AGI-3 的硬数据
在拆架构之前，先看 OpenAI 用来证明"harness 设计能改变结果"的一组数据（见《How enabling two settings tripled our scores on the ARC-AGI-3 benchmark》，2026 年 7 月）：
在难度极高的 ARC-AGI-3 基准测试中，官方 harness 用了滚动截断（rolling truncation）并丢弃每步的推理过程。OpenAI 只做了两项调整——保留推理（retained reasoning） 和 上下文压缩（compaction）——GPT-5.6 Sol 的得分就从 13.3% 飙升到 38.3%（约 3 倍），同时输出 token 减少了 6 倍。
这个结果直接说明了课程的核心论点：评测很少只测模型，它也测了一堆看不见的 API 设置、harness 设计和提示工程。这两项设置（保留推理 + 压缩）正是 Codex 在生产环境里默认部署的方式——好的 harness 设计甚至能让模型脱胎换骨。
平台架构：三层集成入口
Codex 开源后最大的变化是：它不再只是一个 CLI 工具，而是一个可以选择集成深度的平台。OpenAI 官方把集成入口分成三层（见《Codex as a platform》的 "Choose the right integration layer" 一节）：
codex exec（非交互执行）：跑脚本、CI 任务、一次性后台任务。运行一个有边界的 agent 工作流，返回结构化输出。支持--json（JSON Lines 事件流）、--output-schema（按 JSON Schema 约束最终输出）、--sandbox（沙箱策略）、--ephemeral（不持久化会话）。这是"简单、粗暴、高效"的自动化入口。- Codex SDK（编程式接口）：支持 TypeScript / Python，用代码启动、恢复或流式传输 Codex 任务。适合需要精准控制线程与任务生命周期的应用程序。
- Codex app-server（产品嵌入）：当 agent 需要成为产品本身的一部分时使用。通过文档化的 JSON-RPC 2.0 客户端协议，让应用连接到本地 Codex 进程，保持对话开启、流式接收事件、中断工作、暴露工具、响应审批请求。
三层共享同一个开源 harness 内核。开源层是 harness 和集成面；模型访问与托管服务保持独立。
开源组件地图
| 组件 | 位置 | 是否开源 |
|---|---|---|
| Codex CLI | openai/codex | 是（Apache-2.0） |
| Codex SDK | openai/codex/sdk | 是 |
| Codex App Server | openai/codex/codex-rs/app-server | 是 |
| Skills（可复用技能） | openai/skills | 是 |
| Universal 云环境 | openai/codex-universal | 是 |
| IDE 扩展 | — | 否 |
| Codex Web | — | 否 |
（详见官方《Open Source》页面。）
指令子系统：AGENTS.md 是目录页，不是百科全书
这是 Codex 对 harness 理论最有影响力的一条设计：
单个巨型指令文件不利于机械化检查（覆盖率、更新状态、所有权、交叉链接），偏离现实的情况无法避免。因此我们不再把 AGENTS.md 视为百科全书，而是将其视为目录页。代码库知识位于结构化的文档中，AGENTS.md 负责指向它们。
（以上是 《Harness Engineering》原文 中 "AGENTS.md should be a directory page" 一节的直接转述。）
课程第四讲说"单个巨型指令文件会失败"，Codex 直接给出了正解：AGENTS.md 控制在 100 行左右（原文建议约 100 行，接近上限就拆到 docs/），放不下就拆分到 docs/ 目录，让 agent 按需去读。这是"给地图，不给说明书"的权威出处。
配套的原则叫执行不变量，不要微管实现（原文："don't micromanage the implementation；focus on invariants"）：AGENTS.md 只写不可违反的硬约束和验证命令，具体怎么实现交给模型。这直接对应课程第二讲"约束而非微操"。
上下文子系统：Write-Select-Compress-Isolate
Codex 的上下文工程可以概括为四个策略，这是社区在 "context engineering" 成为独立学科后总结出来再映射回 Codex 的框架（框架出处见 Context Engineering for Codex CLI）：
- Write（写出去）：把上下文持久化到窗口之外——结论写进文档、状态写进文件，而不是留在对话里。对应"仓库即事实来源"。
- Select（选进来）：只把需要的 token 拉进窗口——AGENTS.md 指路、按需读文件，而不是全仓塞进去。
- Compress（压缩）：保留真正重要的——Codex 有自动压缩和手动
/compact，可以自定义compact_prompt。上面 ARC-AGI-3 的数据已经证明：把滚动截断换成压缩，模型就能更好地跨长任务保留学到的知识，用更少的 token 拿更高的分。 - Isolate（隔离）：把上下文切到不同边界——用子智能体（subagent）隔离不同任务的上下文，一个前端子智能体永远看不到后端的数据库 schema。
社区对 codex-harness-internals 的源码分析还揭示了一个很细的环境上下文设计：build_environment_update_item 只在环境变化时输出变更字段（CWD、git 分支、文件系统），而不是每轮都把完整系统上下文粘一遍。这是"上下文里不养重复 token"的工程细节。
app-server：把智能体循环变成可嵌入的协议
app-server 是这次开源最耀眼的组件。它让 Codex 不再是"你打开的一个工具"，而是"嵌入你产品里的引擎"。它的设计直接体现了"harness 的可复用部分是智能体循环"这一理念。
协议设计。 app-server 采用 JSON-RPC 2.0 消息（线上省略 "jsonrpc":"2.0" 头），和 MCP 一样支持双向通信。支持的传输方式包括：stdio（换行分隔 JSON，默认）、websocket、Unix socket、off。客户端可以生成对应版本的 TypeScript schema 或 JSON Schema bundle，保证类型与版本精确匹配。
三个核心原语。 这是 app-server 对"harness 该暴露什么"的回答（详见官方《app-server 文档》）：
- Thread（线程）：用户与 agent 之间的一段对话。线程包含多个 Turn。支持
thread/start（新建）、thread/resume（恢复）、thread/fork（分支历史到新线程）、thread/rollback（丢弃最近 N 个回合）、thread/compact/start（触发历史压缩）。 - Turn（回合）：一次用户请求及随后的 agent 工作。支持
turn/start（开始）、turn/steer（向进行中的回合追加输入）、turn/interrupt（请求取消）。回合结束时发出turn/completed。 - Item（条目）：输入或输出的最小单位——用户消息、agent 消息、命令执行、文件变更、工具调用等。
生命周期控制。 连接后先 initialize 握手，再 initialized 确认；然后 thread/start 开会话、turn/start 驱动对话、持续读取 stdout 上的通知流（item/started、item/completed、item/agentMessage/delta 等）。这套生命周期把"会话状态管理 + 流式执行 + 审批处理"做成了可编程的运行时控制——产品团队可以决定 agent 在哪跑、能访问哪些文件、哪些操作要审批、怎么观察、结果怎么回到事实来源。
工具与边界：worktree 隔离 + 子智能体 + 沙箱
Codex 的核心 harness 机制：
1. git worktree 隔离环境。 《Harness Engineering》原文 的 "Environment" 一节写明：每个任务在独立的 git worktree 里运行，配合本地的可观测性栈（日志、指标、追踪），让每个变更都在独立环境中验证。这就是课程第七讲"给 agent 划清每次任务的边界"的物理实现——边界不是靠指令恳求，而是靠环境隔离强制。
2. 沙箱与审批策略。 开源后这些控制变成了可配置的运行时策略。codex exec 默认只读沙箱，可选 --sandbox workspace-write（允许编辑）或 --sandbox danger-full-access（完全访问，仅在隔离的 CI 容器里用）。app-server 则让宿主应用决定 agent 能访问哪些文件和工具、哪些操作需要审批。审批策略和计划模式（plan mode）把"任务边界"和"人类决策权"变成了运行时控制。
3. 内核级子智能体。 Codex 的 spawn_agent / wait_agent 是内核级工具：模型显式地创建子智能体、给它独立的会话历史与工具集、等待结果。子智能体继承父级的 AGENTS.md 指令，但运行在自己的上下文里。配置放在 .codex/agents/*.toml，可以指定不同模型和指令（细节见 Context Engineering for Codex CLI 的 Sub-agents 一节）。这是"上下文隔离"的直接实现——也是课程第十二讲"交接"精神的体现：每个子智能体是一个有清晰边界的工作单元。
反馈子系统：验证命令写进规范
OpenAI 实践里最强调的一点：在 AGENTS.md 里显式列出验证命令，把"怎么确认做对了"变成仓库的一部分。Codex 的工程流程里，测试、CI、文档、可观测性配置——全部由 Codex 生成，并且全部是"可执行的验证路径"。模型能力强但不可靠的解法，不是祈祷模型自觉，而是让验证路径成为 harness 的默认组件。
codex exec 在 CI 里的用法就是这个理念的产品化：它可以跑有边界的 agent 工作流、输出 JSON Lines 事件流、按 JSON Schema 约束最终输出，天然适合接进 CI 流水线做自动修复。OpenAI 官方还提供了 openai/codex-action GitHub Action，专门为 CI 场景降低了 API key 暴露风险。
围绕真实工作流构建软件
OpenAI 在《Codex as a platform》里反复强调的一个观点，值得单独拎出来：
与其要求每个团队把他们原本熟悉的工作流搬进一个通用代码助手，不如把 agent 带进那些围绕真实工作设计的软件里。
安全分析师看的是预警队列、受影响的服务状态；客服工程师看的是账户历史、产品日志；产品经理看的是需求看板。对这些真实的打工人来说，重要的不是那个聊天框，而是他们眼前的业务看板——界面本身就是最重要的上下文。
OpenAI 用一个叫 Relay 的示例应用演示了这种模式：在虚构的发货看板旁嵌入 Codex agent，连接应用拥有的 MCP 工具，凡是有后果的写入操作都需要人类审批。harness 负责智能体循环、会话状态、流式活动和工具交互；产品继续拥有自己的看板、记录和控制。GitHub、JetBrains、Cisco 等已经在公开实现中采用了这种集成模式。
映射到课程框架
| 子系统 | Codex 的实现 | 评价 |
|---|---|---|
| 指令 | AGENTS.md 目录页 + docs/ 拆分 + 执行不变量 | 教科书级，定义了"给地图不给说明书" |
| 工具 | codex exec / SDK / app-server 三层入口 + MCP + 沙箱策略 | 从 CLI 到产品嵌入，集成深度可选 |
| 环境 | 独立 worktree + 可观测性栈 + 沙箱策略 | worktree 隔离是其招牌 |
| 状态 | Write 策略 + Thread/Turn/Item 原语 + 压缩 + fork/rollback | 依赖约定而非内建记忆，app-server 补齐了会话生命周期管理 |
| 反馈 | 验证命令入规范 + 审批策略 + plan mode + CI 自动修复 | 反馈路径默认化，值得抄 |
Codex 和 Claude Code 的对比很有意思：Claude Code 是"加法"——把记忆、权限、子智能体全做进内核；Codex 是"减法"——内核尽量克制，把更多责任放在仓库约定和上下文工程上。开源之后，Codex 又往前走了一步：把"harness 该暴露什么"做成了一个有协议、有原语、有生命周期的可嵌入平台。这也是为什么社区常说"Codex 的 harness 哲学比它的代码更值钱"——而现在代码也开源了。
值得借鉴的设计
- AGENTS.md 当目录页写：控制在 100 行左右，指向 docs/ 里的细节，可机械化检查。
- 只写不变量，不微管实现：硬约束 + 验证命令，剩下的交给模型。
- 保留推理 + 压缩：别用滚动截断丢弃模型刚想的思路，用压缩保留学到的知识——ARC-AGI-3 的 3 倍提升就是证据。
- 用 worktree 做环境隔离：任务边界靠环境强制，不靠指令恳求。
- 环境上下文只传增量：每轮只输出变更字段，别重复粘贴完整系统上下文。
- 把智能体循环做成可嵌入的协议：Thread/Turn/Item 原语 + 生命周期控制，让产品拥有界面和审批，harness 只负责底层循环。
- 子智能体做上下文隔离：拆任务的同时拆上下文，别让子任务污染主循环。
参考来源（原文 / 源码）
每条论断都能回溯到下面的原文或源码，避免凭印象转述：
- OpenAI《Codex as a platform: build on the open agent harness》（2026-08-19）：harness 全面开源、三层集成入口（exec / SDK / app-server）、可复用部分是智能体循环、围绕真实工作流构建软件、Relay 示例、GitHub/JetBrains/Cisco 集成案例。本篇平台架构部分的主要出处。
https://developers.openai.com/blog/codex-as-a-platform - OpenAI《How enabling two settings tripled our scores on the ARC-AGI-3 benchmark》（2026-07-29）：保留推理 + 压缩让 GPT-5.6 Sol 从 13.3% 升到 38.3%、输出 token 减少 6 倍的硬数据。
https://openai.com/index/how-two-settings-tripled-our-arc-agi-3-scores/ - OpenAI《Harness Engineering》：AGENTS.md 目录页与约 100 行建议、executive invariants / don't micromanage、worktree 隔离 + 可观测性栈、验证命令入规范、上百万行产品案例。本篇核心论断的主要出处。
https://openai.com/index/harness-engineering/ - Codex app-server 官方文档：JSON-RPC 2.0 协议、传输方式、Thread/Turn/Item 原语、生命周期（initialize → thread/start → turn/start → 流式事件 → turn/completed）、fork/rollback/compact 等会话控制 API。
https://developers.openai.com/codex/app-server - Codex 非交互模式官方文档：
codex exec的--json、--output-schema、--sandbox、--ephemeral、resume 等 CI 集成细节。
https://developers.openai.com/codex/non-interactive-mode - Codex 开源组件指南：CLI / SDK / app-server / Skills / codex-universal 的开源位置与开源状态。
https://developers.openai.com/codex/open-source - Codex CLI 开源仓库（Rust 实现的单体二进制，Apache-2.0）：
https://github.com/openai/codex - OpenAI 官方《AGENTS.md》规范（AGENTS.md 作为跨工具约定的标准）：
https://openai.com/index/agents-md/ - Context Engineering for Codex CLI（社区）：Write-Select-Compress-Isolate 框架、
/compact与compact_prompt、spawn_agent/wait_agent子智能体与.codex/agents/*.toml配置。
https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/ - codex-harness-internals（社区源码分析）：
build_environment_update_item增量环境上下文等实现细节。
https://github.com/AlexKenbo/codex-harness-internals
相关讲义：第三讲 · 让代码仓库成为唯一的事实来源 ｜ 第四讲 · 把指令拆分到不同文件里 ｜ 第七讲 · 给 agent 划清每次任务的边界