Codex Harness 架构：状态、压缩、接口与安全边界

OpenAI 在 Codex as a platform 中把 Harness 描述为支撑 Codex 各种客户端体验的开源执行系统。模型提出下一步动作；Harness 收集上下文、执行工具、保存状态，并在配置边界内继续工作或请求批准。

这比“模型调用工具，直到任务结束”的循环多出几项生产级职责：任务要能跨多次模型请求继续，历史过长时不能丢掉目标，客户端要收到结构化事件，有副作用的动作还必须同时经过权限约束和审批策略。

状态模型与执行循环

Codex App Server 使用 Thread → Turn → Item 表示运行状态。Thread 是持续会话，Turn 表示一次用户任务，Item 则记录消息、推理、命令、文件修改和工具结果。Item 会进入后续 Turn 的上下文，因此 Harness 保存的是执行轨迹，而不只是聊天文本。

当前的 Turn 执行源码 会为每个 Turn 捕获上下文，并在模型窗口接近上限时先触发压缩。一个 Turn 内的模型会话还会跨重试复用，以保留连接和路由状态。

压缩是状态迁移

压缩实现 不会简单删除旧消息。它先让模型生成摘要，再用摘要、必要的用户消息和重新注入的初始上下文替换历史。压缩发生在 Turn 开始前还是执行中途，会影响初始上下文插入的位置。

这项区别直接影响长任务的可靠性。压缩后仍需保留用户目标、工作目录、权限和未完成任务；否则摘要虽然更短，Agent 却可能忘记自己在哪里、允许做什么，或者把已经完成的步骤再做一次。因此，压缩应作为带不变量的状态转换来测试，而不是普通的 Token 清理。

三种接入深度

接口	适合的任务	应用需要承担什么
codex exec	CI、脚本和边界明确的非交互任务	准备输入并消费最终结果
Codex SDK	由程序启动、继续或流式观察 Agent	管理 CLI 子进程、Thread ID、事件与版本
App Server	编辑器、桌面应用和企业工作台	管理持久会话、事件流、审批界面与协议兼容

TypeScript SDK 当前会启动 codex CLI，并通过 stdin/stdout 交换 JSONL 事件。App Server 则公开 Thread、Turn、Item、审批和压缩协议，还能生成与当前 Codex 版本匹配的 TypeScript 类型与 JSON Schema。两者复用同一运行时思路，却不是相同的客户端抽象。接入时应按产品需要掌管的生命周期与交互深度选择。

沙箱与审批是两道边界

Codex 的安全文档把沙箱与审批分开：沙箱决定命令技术上能够访问哪些文件和网络，审批策略决定何时必须停下来询问用户。默认配置关闭网络，并把写权限限制在工作区；访问网络或修改工作区外文件时再请求批准。

关闭审批不会自动解除沙箱；反过来，只有确认弹窗而没有操作系统级隔离，也不能形成可靠边界。danger-full-access 解除文件系统与网络沙箱限制，但审批策略仍可单独配置；--dangerously-bypass-approvals-and-sandbox 才会同时绕过两层控制。即使运行在容器中，这类高权限配置也可能让恶意项目读取容器里可访问的凭据和数据。

Codex 的开源清单包括 CLI、SDK 与 App Server 等组件，但 IDE 扩展和 Codex Cloud 并未开源。开源 Harness 让运行逻辑与协议可检查、可修改，不代表模型、托管服务或整个产品栈开放。

Codex 这个案例说明，生产级 Harness 的重点不在循环本身，而在循环周围的状态连续性、协议兼容、安全边界和失败恢复。通用职责可继续参考 AI 编程 Harness、Agent 循环模式、上下文工程与工具契约。