文章结构化摘要

文章主旨：

OpenAI 开源 Codex Harness，将编码助手升级为可嵌入任意产品的可编程智能体执行平台（AgentOS），其设计核心是「应用掌控产品上下文，Harness 专注跑好 Agent Loop」，为 AI 能力融入业务系统提供了第三条路径。

关键要点：

• Codex 本质上是一个开源、可嵌入任何产品的 agent harness（执行系统），App、CLI、IDE 插件皆为其三种"皮肤"；
• 通过 codex-core（33 万行 Rust）实现业务逻辑与 UI 完全解耦，采用线程→会话→轮次三级状态管理，并使任务流程可插拔；
• 上下文工程是核心竞争力：增量式、有界、可缓存，动态压缩与按差异注入显著降低成本与延迟，实测 ARC-AGI-3 得分从 13.3% 提升至 38.3%，输出 token 减少 6 倍；
• 安全边界采用「一套策略 + 三套原生沙箱（Seatbelt / bubblewrap+seccomp / restricted token）+ 纵深防御」体系，通过统一策略语义在多平台强制执行隔离；
• 利用 app-server（JSON-RPC 2.0 协议）、双向通信、MCP 双向接入、插件/Hooks/Skills 多智能体协作机制，构建完整的可扩展平台生态。

内容结构：

一、核心概念：Agent、Harness 与 Platform

• Agent 是能自主完成任务的程序，需具备上下文维护、外部信息检查、工具调用、进度暴露、失败恢复、请求审批等能力；
• Harness 是模型之外整套「周围执行系统」，包含上下文管理、工具、安全护栏与外部通信协议；
• Platform 使 Codex 可嵌入任何产品——不是「整车销售」而是「发动机+底盘销售」，可被装入货车、救护车、拖拉机。

二、三张「皮肤」背后的统一核心

• 同一个 codex-core 可驱动 App、CLI、IDE 扩展、非交互式 exec 以及第三方产品内嵌 agent；
• 界面、上下文、工具与运行边界均由应用决定，示例 Relay（货运运营应用）展示了用户在自己的产品中调用 agent 并嵌入审批流程；
• 实证数据表明 harness 设计能直接显著改变模型表现。

三、任务执行旅程

• 以终端执行「修复 bug」为例：启动 CLI → 创建线程 → 包装轮次 → 采样循环 → 工具调用 → 审批 → 应用补丁 → 轮次结束 → 持久化日志到 JSONL/SQLite；
• 模型只负责思考，harness 决定「谁在思考、用什么工具、能碰什么、必须问谁」。

四、仓库规模与架构分区

• 约 146 万行 Rust、135 个 crate、3287 个源码文件，另含 TypeScript 与 30 个 GitHub Actions 工作流；
• codex-rs 为核心，codex-core 设为「抵制增长」上限（33 万行），新功能放入扩展 crate。

五、codex-core 的 Agent Loop

• 三层结构：ThreadManager → CodexThread → Session（submission_loop 消息通道无限循环）；
• run_turn 核心流程：预压缩 → 解析输入 → 捕获 StepContext → 构建请求 → 流式采样 → 并行工具执行 → 决策；
• 四种可插拔任务：常规、评审、压缩、用户!shell 命令；
• 工具面按暴露等级分类：Direct / Deferred / Hidden，防止上下文塞满。

六、上下文工程

• 原则：增量式、有界、可缓存；WorldState 只注入变化部分，提示缓存按前缀计费；
• 三条压缩路径：本地摘要、远程压缩（64K 预算+重试）、Token 预算耗尽直接开新窗口；
• InitialContextInjection 机制按轮次前后插入位置有差异，体现对模型行为习惯的精细建模。

七、平台化：app-server 与 JSON-RPC 协议

• 五种传输：stdio://、ws://、unix://、in-process、remote-control；含背压机制返回 -32001；
• 协议为 MCP 风格 JSON-RPC 2.0：三个顶层原语 Thread / Turn / Item；方法覆盖 thread、turn、fs、process、command 等；
• 双向通信：服务端通知与请求流，让人工审批成为协议一等公民；
• 类型安全：宏自动生成 TypeScript 绑定与 JSON Schema；空闲线程自动卸载。

八、安全边界：一套策略，三套沙箱

• 统一 SandboxMode 映射到 PermissionProfile，再由三套 OS 原生机制强制执行（macOS Seatbelt / Linux bubblewrap+seccomp / Windows restricted token+WFP）；
• 纵深防御：进程加固（防调试/转储/注入）、特权升级管控（补丁 zsh 包装）、Starlark 执行策略引擎、受管网络代理（MITM）；
• 核心哲学：不信任 agent，只信任边界。

九、多智能体与扩展生态

• 多智能体：AgentControl 控制面 + mailbox 通信 + Guardian 审批；子智能体按角色（explorer / worker）继承环境并做有界配置；
• MCP 双向打通：既作为客户端连接工具，又作为服务器暴露 Codex 工具供其他 agent 调用；
• 插件 + Marketplace、生命周期 Hooks、SKILL.md 技能注入，形成应用商店模式的能力分发。

十、执行环境远程化

• codex exec-server：app-server 可连接多个 exec-server，且可跨 OS 驱动执行；
• 通信线格式为 Noise 加密通道内 protobuf relay 帧；
• 安全上下文在 executor 侧强制执行，适合企业 SSH / 云工作负载。

十一、工程启示

1. 单一核心、多前端：行为一致，换皮不换脑；
2. 协议优先的平台化：协议即契约，SDK 仅为薄封装；
3. 执行与判定分离：语义、实现、策略三层解耦；
4. 核心抵制膨胀：外围扩展疯狂生长；
5. 构建系统严谨：Bazel 8 + hermetic 工具链 + ~20 个三方补丁，追求可复现。

结语：Harness 的哲学

• 应用负责「拥有产品上下文」，Codex 负责「跑好 agent loop」，永远在边界内运行；
• 模型会过时，但 harness 是应用与模型之间可替换、可观察、可编程的稳定层；
• 给开发者提供了第三条路：不造运行时、不用别人的聊天窗，而是把 harness 嵌入自身产品；
• 最好的 agent 不是「长得像 ChatGPT 的工具」，而是「长在你工作流里的同事」。

文章总结：

本文由资深技术专家从工程视角全面剖析 OpenAI Codex Harness，基调为深度技术分析兼平台化架构的赞赏，核心结论是「Harness 质量与模型质量同等重要」，建议开发者在构建 AI 产品时考虑将现成 agent 执行系统嵌入自有工作流，而非从零自研。

软件质量报道

查看原文：深度解析(绝不夸张)：智能体的Codex Harness架构、源码和应用

文章来源：

软件质量报道

扫码关注公众号