Codex Harness 深度解读

还有你Y

510人浏览 · 2026-09-06 14:53:53

还有你Y · 2026-09-06 14:53:53 发布

Codex Harness 深度解读：当 Agent 的记忆不再是一段越来越长的聊天记录

引言：一个 Agent 连续工作 40 分钟后

一个 Agent 连续工作 40 分钟后，真正危险的时刻往往不是它写错了一行代码，而是它已经读过 20 个文件、跑过八次测试、做过三个关键取舍，却因为上下文窗口快满了，只能把一大段历史粗暴丢掉。下一轮它还记着任务，但忘了为什么不能改那张表、哪个测试是刚修好的、哪项操作必须等人审批。

这也是许多 Agent 看起来第一轮很聪明、任务一长就失忆的根源。

2026 年 8 月 19 日，OpenAI 在官方博客宣布，将驱动 Codex App、CLI 和 IDE 扩展运行的底层执行框架——Codex Agent Harness——正式完全开源，采用 Apache-2.0 协议，发布地址为 github.com/openai/codex。截至开源发布时，仓库已累计超 10 万 Star。这不是又一次 CLI 工具开源——OpenAI 把自家旗舰 AI 智能体的“发动机”直接交给了开发者。

本文将深度拆解 Codex Harness，重点看它如何处理长任务上下文（Context Compaction），以及企业可以从中学到什么。

一、Harness 是什么：模型之外的那层“执行系统”

很多人以为 AI 编程工具的核心竞争力是“模型够聪明”。但一个真正能干活儿的 Agent，除了模型之外，还需要一整套外围系统：

理解任务、拆解任务
在多轮交互中维护上下文
调用工具（读写文件、执行命令、访问 MCP 服务）
在受控边界内执行操作，必要时停下来请求人类批准
把进度实时流式推给用户，失败时优雅恢复

这套“包裹在模型外面的运行时基础设施”，就是 Harness。OpenAI 官方的定位非常直白：你的产品拥有业务上下文、业务规则和工具；Codex app-server 提供 Agent 循环——模型负责“想”，Harness 负责让 AI 真正把事干完。

用一个后端开发的类比：模型是数据库，Harness 是你搭在数据库外面的那一整层——连接池、缓存、重试、熔断、权限校验、任务调度。数据库再强，没有这一层，你写不出一个能上线的系统。模型再聪明，没有 Harness，Agent 就是一个聊天框。

二、那组改变认知的数据：同一模型，能力差三倍

Harness 的设计质量有多重要？OpenAI 给了一组硬数据。

在难度极高的 ARC-AGI-3 基准测试中，官方 Harness 原来用的是滚动截断并丢弃每步的推理过程。OpenAI 只做了两项调整——保留推理（retained reasoning）和上下文压缩（context compaction）——GPT-5.6 Sol 的得分就从 13.3% 飙升到 38.3%（约 3 倍），同时输出 Token 减少了 6 倍。

这两项调整全是 Harness 层面的优化，模型本体没动。

这个结果说明了两件事：

Agent 的工程层（执行系统）对最终效果的贡献，常常被低估
“省 Token”不是玄学，是执行层设计里可以量化的工程优化

同一个模型，换一套 Harness，得分可以从 13.3% 变成 38.3%。模型决定 Agent 的智商上限，Harness 决定它到底能不能干活。

三、Context Compaction：不是摘要，是交接机制

3.1 问题本质：长任务为什么容易“失忆”

模型一次调用的行为很简单：输入一段上下文，输出一段文本或工具调用。但一个能做真实工作的 Agent，还需要处理另一组问题：任务从哪里开始？读过哪些文件和日志？哪些工具可调用？哪些命令必须审批？任务中断后怎么恢复上下文？超长后保留什么、删掉什么？

上下文越长并不必然越好。旧日志、过期假设、已完成的尝试会占据注意力；关键约束若被埋没，Agent 会重复尝试或越权操作；每轮都塞入全部历史，成本和延迟会不断增加。

3.2 Codex 的解法：Context Compaction

当上下文窗口快满时，Codex 不是简单地丢弃历史或生成一段文本摘要。它会调用 /responses/compact 端点，返回一个加密的 encrypted_content 条目——它以更小的体积编码模型对历史的“隐式理解”，比文本摘要更省 token，也更保护隐私。

压缩完成后，Codex 会清掉一个 baseline 标记。下一轮开始时，它发现 baseline 不存在，就重新构造 initial context。这套机制确保压缩后的上下文仍然可恢复、可审计、可继续运行。

从 Codex 开源代码中的压缩 prompt 可以看到，它要求生成的并非普通摘要，而是一份交接记录：

当前进度与已作出的关键决策
重要上下文约束和用户偏好
未完成的工作与清晰的下一步
继续任务必须的关键数据示例或引用

这套要求背后的思想很清楚：不是“过去聊了什么”，而是“换一个模型接手，他需要知道什么才能不犯错地继续”。

一位开发者曾在 GitHub Issue 中评论：在 Codex Harness 中，模型在每次上下文压缩时“基本死掉”；但在 PI Agent Harness 配合 ContextMode 下，同样的模型表现却出奇地好。这说明问题不仅是模型本身，更在于 Harness 如何处理上下文压缩。

3.3 五个设计要点

基于 Codex 源码中 compact.rs、compact_token_budget.rs、压缩 prompt 与 observer 协议定义，可以看到至少五个明确的设计要点：

第一，压缩有两种触发方式：手动与自动。 客户端可以通过 thread/compact 立即发起压缩；同时存在自动压缩任务，当运行时判断当前上下文窗口临近边界时，Harness 可以在任务过程中自动压缩。设计要点是：压缩不能只依赖用户手工操作，必须成为长任务的自愈能力，但又必须对用户可见、可追踪。用户也可以在 config.toml 中设置 model_auto_compact_token_limit 来控制自动压缩的触发阈值。

第二，压缩前后都有 hook。 pre_compact 和 post_compact 任一阶段都可以阻止任务继续。企业可加入策略：压缩前检查待批准高风险操作，压缩后将检查点和权限级别写入审计。

第三，中途压缩与下一回合前压缩的历史结构不一样。 用摘要替换历史后，再注入完整初始上下文。适用于回合中途压缩，会把当前 world state 插在最后一条真实用户消息之前。

第四，压缩结果会进入持久化。 历史不止留在内存，Codex 把内存里的上下文和存档里的上下文一致性纳入了设计目标。

第五，还有一种 token budget compaction——重开窗口而非摘要。 同样触发 hook，同样产生 item。设计哲学是：compaction 的本质不是让 LLM 写摘要，而是以可控方式重建下一段执行所需的上下文。

四、架构全景：Thread、Turn、Item 三原语

要理解 Context Compaction，先要看 Codex 如何组织一项任务。

Codex Harness 的核心数据模型是三层结构：

Thread（线程） ：一次可持续、可恢复的任务会话。例如“修复支付服务的 CI”。Thread 承载完整的上下文容器。
Turn（轮次） ：用户输入后引发的一次 Agent 的工作。例如“先定位错误，再禁止改生产配置”。
Item（条目） ：一项可观察的输入、输出或行动。例如读文件、运行命令、工具调用、文件修改、审批请求。

这套划分不是为了好看，而是让长任务可管理。当 Agent 在改代码时，产品不必只等最后一句“完成了”——可以通过事件流看到任务开始了、正在执行哪条命令、生成了哪个 diff、在哪一步请求批准、上下文是否刚刚完成压缩。

官方把 Context Compaction 也建模为一种 Item——压缩不是幕后悄悄发生的字符串替换，而是任务履历中的一个明确事件。这带来两个好处：第一，可以在界面里展示 Agent 正在整理任务上下文，而不是让用户误以为系统卡死；第二，可以将压缩与失败、中断、审批、测试结果一起写入审计轨迹。

五、App Server：把 Agent 嵌进你的产品

如果 Harness 只能在 CLI 里运行，它仍然只是个人工具。Codex 的 App Server 使用双向 JSON-RPC 2.0 通信，支持 stdio、Unix socket 与 WebSocket 等传输方式。

它将 Thread、Turn、Item、审批请求、工具事件和压缩事件暴露给宿主应用。这使得企业可以制作真正贴合岗位的界面：

安全运营台做告警到工单的闭环
客服后台做客户记录到 CRM 的回写
研发工单做 CI 失败到 PR 的全流程

用户不需要每次都从零写 Prompt，系统可以根据他正在看的告警、工单或订单注入最小必要上下文，再让 Agent 在受控工具范围内工作。

OpenAI 官方博客的描述非常清晰：“你的应用拥有产品上下文、业务规则和工具；Codex app-server 提供 Agent 循环”。宿主应用决定业务边界，Harness 负责执行边界内的工作。 循环模型只是在循环中的推理引擎。企业真正需要拥有的不是另一个聊天框，而是任务的上下文、权限和最终决定权。

值得注意的安全提醒：官方文档明确提示，远程 WebSocket 仍处于实验状态，不应作为生产负载的默认方案。暴露到远程时必须启用 TLS 和身份验证。更重要的一条是：thread/shell_command 在沙箱外以完整权限运行，官方建议仅对显式的用户发起命令开放——Agent 有审批，不代表每一条执行路径都天然安全。

Harness 框架原生搭载沙箱隔离机制，所有执行操作优先运行在受限沙箱环境，高风险操作才触发人工审批。沙箱定义了技术执行的边界，包括 Codex 可以写入的位置、是否可以访问网络、哪些路径处于保护状态；审批策略则决定了 Codex 何时必须请求执行某项操作。

六、三层集成接口：从脚本到产品全覆盖

Codex Harness 开源后最大的变化是：它不再只是一个 CLI 工具，而是一个可以选择集成深度的平台。OpenAI 官方把集成入口分成三层：

第一层：codex exec（CLI 非交互执行） 。最轻量的接入方式，适合跑脚本、CI 流水线、一次性后台任务。运行一个有边界的 Agent 工作流，返回结构化输出。

第二层：Codex SDK（TypeScript / Python） 。程序化接口，可在应用代码里启动、恢复、监听 Codex 任务。

第三层：app-server（JSON-RPC 协议） 。把应用连接到本地 Codex 进程，支持持久化会话、事件流、任务中断、暴露专有工具与人工审批——适合把 Agent 真正嵌入产品。

截至 2026 年 8 月，Codex Harness 已在多个真实场景落地：

税务领域：合作方用该框架处理了约 7000 份申报表，准备时间缩短约三分之一
思科（Cisco） ：用 Codex SDK 在其云平台上构建了自然语言创建云应用的 App Builder
官方演示：虚拟物流仪表板里，选中延误货单后 Agent 自动关联数据、调用 MCP 工具、生成重订方案，并在执行写入前弹出人工审批对话框——界面、数据与审批权留在产品里，AI 只负责底层干活

整个 Harness 核心是一个 Rust 实现的单体二进制，Rust 代码占比高达 96.4%。从 TypeScript 迁移到 Rust 后，显著降低了启动时间和内存占用。codex-rs/ 包含约 120 个 crate，覆盖 app-server、exec-server、sandboxing、execpolicy、hooks、tools、thread-store、model-provider 等关键模块。

七、Codex Harness vs DeepSeek Harness：两种技术路线

DeepSeek Harness 的官方定位是“everything is a plugin”——模型、工具、记忆、界面等组件都围绕 Cordis 被设计为可组合插件，采用 MIT 协议，但仍处于 Developer Preview。

从 Harness 工程看，两者都在回答同一个问题：模型之外的系统如何支撑 Agent 的长期工作。但回答方式不同：

维度	Codex Harness	DeepSeek Harness
核心原则	Agent 安全嵌入已有产品与流程	Agent 所有能力可快速替换和组合
核心抽象	Thread / Turn / Item + Observer 生命周期	Plugin + Cordis 组合
上下文主线	会话状态、world state、检查点、压缩与恢复	通过插件组装记忆、工具、模型、控制
重点方向	沙箱、审批、事件流	插件生态与运行时扩展
工程成熟度	官方 SDK 和协议面较完整	仍为 Developer Preview