Codex Harness：模型之外，任务是怎么真正跑起来的

从 Agent loop、上下文、工具、沙箱、审批、事件流和产品集成理解 Codex Harness，并区分 Codex CLI、App Server、SDK 与普通模型 API。

内容更新 2026-08-29

先看结论

模型负责推理，Harness 负责把推理放进一个可持续、可控制、可观察的任务循环；产品质量不能只看模型名字。

模型、Harness 和产品界面怎么分层

  • 模型：理解输入、推理、生成下一步动作或文本。
  • Agent loop：反复执行观察 → 推理 → 工具调用 → 读取结果 → 决定下一步，直到完成、失败或被中断。
  • Harness：准备上下文、管理会话、执行工具、应用权限、记录事件、处理审批与中断。
  • 产品界面：IDE、桌面 App、工单系统或客户后台展示状态，让用户查看、介入和验收。
  • 评估层：用固定任务和真实失败类型判断整套系统，不把单一 benchmark 当生产质量。

App Server 适合什么

  • 官方文档称 App Server 是 Codex 丰富客户端使用的接口，支持认证、对话历史、审批和流式 Agent 事件。
  • 协议以 Thread、Turn 和 Item 为核心；客户端完成 initialize 后启动或恢复 Thread，再持续读取事件。
  • 它适合在自己的产品界面中深度嵌入 Codex，不是一个只返回最终答案的普通 HTTP 文本接口。
  • 非本地连接必须使用安全 WebSocket、认证和 TLS；明文 WebSocket 只适合 localhost 或 SSH 转发。

视频中的数字为什么没写进结论

  • 本地自动转写得到“43% 提升到 38%”这一自相矛盾的句子，无法确认原始数字。
  • 视频还提到 Token 数量大幅下降，但没有给出可核验的任务集、模型配置和官方链接。
  • 这类性能结论必须绑定评测名称、任务版本、Harness 配置、模型版本和测量口径；缺一项就不应写成通用事实。

参考来源

适合谁看

  • 想把 Codex 能力嵌入自己的 IDE、后台或工作台
  • 想理解同一个模型为什么在不同 Agent 工具里表现不同
  • 需要历史、审批、工具执行和实时进度，而不是一次性文本回答

操作步骤

  1. 先确定使用面：人机交互用 Codex App、IDE 或 CLI；自动化和 CI 优先评估 SDK；深度产品界面集成评估 App Server
  2. 为每个任务写清 cwd、允许工具、沙箱、审批策略、完成条件和不可触碰区域
  3. 把 Thread、Turn、Item 和工具事件当作产品状态，不只保存最终一段回答
  4. 高风险工具调用在执行前请求人工确认，失败时保留状态和可恢复证据
  5. 用真实任务集评估 Harness + 模型组合，分别记录成功率、用量、耗时和失败类型，不引用来源不明的营销数字

需要解决的问题

  • 只换更强模型，但长任务仍会丢上下文、误用工具或无法收尾
  • 把模型 API、Codex CLI、App Server 和 SDK 当成同一种接口
  • 看到“Harness 开源”就以为相关代码是最近一次性发布的

先理解这些

  • Harness 管理上下文、Thread/Turn、工具调用、命令执行、沙箱权限、审批和事件展示
  • OpenAI 官方文档将 App Server 定位为深度产品集成接口，将 SDK 定位为自动化任务和 CI 接口
  • GitHub 历史显示 TypeScript SDK scaffold 和独立 app-server 目录在 2025-09-29 至 2025-09-30 已进入仓库，近期文章更像重新定位和解释

遇到困难时

  • 只是本地改代码时直接使用 Codex CLI 或 App，不必先自建 App Server 客户端
  • 只需后台跑固定任务时优先看 Codex SDK，避免自己实现完整会话协议
  • App Server WebSocket 远程模式在官方文档中仍标为实验性且不支持生产；不要未经认证直接暴露到公网