Codex Harness – OpenAI 开源的 AI Agent 底层执行框架

1. Codex Harness是什么

Codex Harness 是 OpenAI 开源的 AI Agent 底层执行框架，定位为驱动智能体的"外骨骼"系统。它负责任务理解、记忆保持、工具调用、进度展示、失败处理及人类审批等完整执行循环，通过 CLI、SDK 和 app-server 三大组件，让开发者将 AI 智能体无缝嵌入自有产品、运营看板或业务系统，无需将工作流硬塞进通用聊天框。该框架强调前后端解耦与模型无关的编排能力，为 Agent 的工程化落地提供了基础设施层面的解决方案。

技术定位与领域： Codex Harness 属于 AI Agent 基础设施与执行编排层，介于底层模型与上层业务应用之间。与直接面向终端用户的聊天机器人产品不同，Harness 的独特定位在于"可嵌入产品的执行引擎"——它不提供界面，而是将 Agent 的完整运行循环封装为可编程、可集成的基础服务，使开发者能够在自有系统中获得 AI 执行能力。

研发背景： 该框架由 OpenAI 基于 Codex 系列产品的工程实践提炼而成。OpenAI 在长期运行 Codex 云服务的过程中，积累了关于任务循环、上下文管理、沙箱隔离与人工审批的系统性经验，并将这些内部基础设施以 Apache-2.0 协议开源，使外部开发者能够复用与 Codex 产品同级的 Agent 运行能力。

核心价值： Codex Harness 解决了"Agent 如何深度嵌入业务系统"这一工程难题。传统做法是将工作流放入通用聊天框，而 Harness 通过 JSON-RPC 协议、流式事件传输与前后端彻底解耦，让应用层掌控界面、上下文、工具与审批流程，Harness 层专注执行循环与沙箱运行，从而构建安全、可控、可审计的 Agent 工作流。

技术特点： 该框架的核心技术优势在于模型无关的编排架构、原生 Human-in-the-Loop 审批机制，以及内置的隔离沙箱执行环境。在 ARC-AGI-3 基准上，仅优化 Harness 层（保留推理与上下文压缩）即可将 GPT-5.6 Sol 的得分从 13.3% 提升至 38.3%，同时 Token 消耗减少 6 倍，验证了执行框架本身对 Agent 性能的重要影响。

2. 主要功能

• Agent 执行循环： 驱动 AI 智能体完成从任务理解、规划分解到结果输出的完整迭代流程。该循环是 Harness 的核心运行机制，支持多轮推理与自我修正，确保复杂任务能够被逐步拆解并最终落地执行，而非一次性生成结果。

• 上下文与记忆管理： 在长对话与多轮任务中保持上下文连贯，智能压缩和审查相关信息。这一机制解决了长任务中上下文窗口溢出的问题，通过动态筛选与压缩历史信息，在有限的上下文空间内保留关键决策依据。

• 工具与技能调用： 支持 AI 灵活调用外部 API、数据库及自定义业务工具。通过 MCP（Model Context Protocol）协议暴露工具接口，Harness 能够将业务系统自身的操作能力安全地开放给 Agent，使其在真实数据环境中执行操作。

• 沙箱安全执行： 提供隔离的运行时环境，确保文件系统与网络操作安全可控。沙箱对 Agent 的读写权限、网络访问范围进行严格限制，所有动作可审计、可回滚，有效降低 AI 自主执行带来的安全风险。

• 流式事件传输： 支持实时向应用前端推送 AI 的思考过程与执行进度。通过事件流机制，前端界面可以展示 Agent 的中间状态、工具调用记录与阶段成果，提升用户对 AI 执行过程的透明度和可控感。

• 人类审批介入： 在关键操作前自动暂停执行循环并请求人类确认，审批通过后才继续运行。这一原生 Human-in-the-Loop 机制适用于财税处理、系统变更等高容错率要求场景，实现安全的人机协作。

• 会话持久化： 支持跨会话保存和恢复对话状态、线程与任务生命周期。即使进程重启或应用切换，Agent 的执行进度与上下文仍可完整恢复，适配长周期、多阶段的工作流需求。

• 前后端解耦架构： 将审批界面、业务上下文与底层执行循环分离，通过 JSON-RPC 协议通信。应用层负责产品体验与业务规则，Harness 层专注 Agent 循环与沙箱执行，使得同一执行引擎可被多个前端场景复用。

3. 如何使用

1. 获取开源代码： 前往 GitHub 的 openai/codex 仓库克隆项目，即可获得完整的 Harness 工具库。仓库包含 CLI、SDK 与 app-server 三大组件的源码与构建配置，支持本地编译与二次开发。

2. CLI 快速执行： 使用 codex exec 命令行工具运行有边界的 Agent 工作流。该方式适合脚本任务、CI 流水线与后台一次性任务，执行完成后返回结构化结果，便于与其他自动化系统集成。

3. SDK 编程集成： 通过 TypeScript 或 Python 版官方 SDK，在应用代码中精准启动、恢复或流式传输 Codex 任务。SDK 提供了完整的编程接口，开发者可在代码中控制任务生命周期、订阅事件流并获取执行结果。

4. App-Server 产品嵌入： 部署 Codex app-server，通过 JSON-RPC 协议将 Agent 循环深度集成到自有业务系统。app-server 作为独立服务运行，与业务后端通过标准协议通信，支持持久会话、实时事件与中断审批等完整能力。

5. 暴露业务工具： 将应用自身的 API、数据库及操作接口通过 MCP 协议暴露给 Harness，让 AI 调用真实业务数据。工具定义需包含清晰的参数说明与权限边界，确保 Agent 只能在授权范围内执行操作。

6. 配置审批流程： 在前端接入审批界面，Harness 会在检测到关键操作时自动暂停并推送审批请求。业务端只需实现审批 UI 并响应 JSON-RPC 事件，即可建立完整的人机协作闭环。

7. 流式事件监听： 订阅 Harness 的流式事件输出，在应用前端实时展示 AI 的思考过程、工具调用与执行进度。事件流包含结构化数据，可直接驱动进度条、日志面板等可视化组件。

8. 注入业务上下文： 向 Harness 传入产品界面状态、用户行为及业务规则，让 AI 基于真实场景而非通用聊天框工作。上下文注入是提升 Agent 决策质量的关键步骤，建议在每次任务启动时同步当前业务状态。

4. 优缺点分析

5. 同类工具对比

选型建议： 若企业已有成熟的业务系统与前端界面，核心诉求是将 Agent 安全地嵌入现有产品流程，并需要严格的审批与审计机制，Codex Harness 的前后端解耦架构与原生沙箱能力提供了完整的工程化方案。特别是财税、运维等高合规性场景，其内置的 Human-in-the-Loop 机制能显著降低引入 AI 自主执行的风险。

其他场景： 如果团队的技术栈以 Python 为主，且工作流涉及复杂的状态流转与分支逻辑，LangGraph 的图状态机模型在编排可控性上更具优势；若目标是快速构建多智能体协作原型，AutoGen 的对话驱动机制上手更为直接；而深度使用 Claude 模型生态的团队，Claude Agent SDK 提供了与模型能力对齐的开发体验。整体而言，Codex Harness 更适合"产品嵌入"这一特定工程目标，而非通用实验框架。

6. 编辑总结

Codex Harness 在 AI Agent 工程化领域提供了一个值得关注的架构范式。其核心创新在于将"执行循环"从"模型能力"与"应用界面"中独立出来，形成专门的编排层——这种前后端彻底解耦的设计，使得 Agent 不再是依附于聊天框的附加功能，而是可以像数据库或消息队列一样作为基础设施嵌入业务系统。ARC-AGI-3 基准上的实测数据从侧面说明，执行框架的工程优化（而非模型参数）也能对 Agent 整体表现产生量级影响，这为行业提供了新的性能优化视角。

从实用价值来看，Harness 的沙箱执行、流式事件与原生审批机制直击企业级 AI 落地的安全与可控痛点。Apache-2.0 协议降低了采用门槛，开发者可以自由地将执行循环嵌入自有产品，同时保留对界面、上下文与审批流程的完全掌控。其适用人群明确：具备一定工程能力、正在将 AI Agent 产品化的技术团队，尤其是那些受限于通用聊天框交互模式、需要深度定制工作流的开发者。

在同类框架中，Codex Harness 与 LangGraph、AutoGen 的定位差异清晰——前者强调产品嵌入与执行管理，后者侧重流程编排与多智能体协作。随着 Agent 从原型验证走向生产部署，执行层的标准化与安全机制的重要性将持续上升。Codex Harness 以"外骨骼"的定位切入这一环节，其设计思路为 Agent 工程化提供了一套可参考的实践范式。

7. 应用场景

• 财税合规自动化： 嵌入税务准备工作流，AI 处理复杂税务逻辑并自动填充申报表，税务师在关键字段审批确认。该场景已验证可处理 7,000 份申报表，准备时间缩短约三分之一，体现了 Harness 在高合规要求场景下结合人工审批的实际价值。

• 企业云平台应用构建： 如 Cisco App Builder 的实践，客户在其云控制平台内使用自然语言创建自定义应用，Harness 在幕后处理权限校验与底层逻辑流转。该场景展示了 Harness 作为平台底层执行引擎的能力，让 AI 成为产品功能的一部分而非独立工具。

• 物流调度异常处理： 在物流看板中嵌入 Agent，调度员点击「Investigate delay」后，Agent 自动调用 MCP 工具获取实时运单数据、分析延误原因，任何改单操作都需人工审批。这一场景结合了实时数据调用与安全审批，提升了异常处理的效率与准确性。

• 运营仪表盘嵌入： 将 Agent 直接集成到现有运营看板中，实时分析业务指标、触发异常告警、执行修复动作，无需切换至独立聊天界面。通过流式事件传输，运营人员可以在看板中直接观察 AI 的分析过程与执行进度。

• 安全运维审批： 安全分析师在预警队列中直接调用 Agent 排查受影响服务状态，高危操作自动触发 Human-in-the-Loop 审批后执行。该场景利用沙箱隔离与审批机制，在提升响应速度的同时确保运维操作的安全边界。

8. 常见问题FAQ

Q：Codex Harness 是什么？和 Codex 模型有什么区别？
A：Harness 是驱动 AI Agent 的底层执行引擎，负责任务理解、记忆保持、工具调用、沙箱执行、流式事件和审批流程；而 Codex 模型是生成代码与推理的"大脑"。Harness 是"外骨骼"，模型是"大脑"，两者配合才能跑通完整的 Agent 工作流。

Q：开源协议是什么？可以免费商用吗？
A：采用 Apache-2.0 协议，可以完全免费商用。开发者可以自由嵌入自有产品、修改源码、二次分发，无需开源上层业务代码。

Q：必须绑定 OpenAI 的 GPT 模型吗？能用 Claude 或 DeepSeek 吗？
A：Harness 是模型无关的编排层，架构上不强制绑定特定模型。但当前官方实现默认对接 OpenAI API，若要替换为其他模型，需自行适配模型调用层。

Q：三大组件怎么选？什么场景用哪个？
A：codex exec 适合脚本、CI 流水线与后台一次性任务，返回结构化结果；Codex SDK 适合在应用代码中编程式启动、恢复或流式传输任务；Codex app-server 适合 Agent 作为产品的一部分，需要持久对话、实时事件、中断工作和审批处理的场景。

Q：已有业务系统，如何接入 Harness？
A：通过 Codex app-server 的 JSON-RPC 协议连接。应用负责提供"产品界面 + 业务上下文 + 审批流程"，Harness 负责"Agent 循环 + 沙箱执行"，双方通过 Context in / Events out 双向通信，对现有系统的侵入性较低。

Q：Human-in-the-Loop 怎么实现？对业务侵入大吗？
A：Harness 在检测到"需审批的操作"时自动暂停 Agent 循环，通过流式事件向前端推送审批请求；用户确认后 Harness 继续执行。业务端只需实现一个审批 UI 并响应 JSON-RPC 事件，侵入性极低。

9. 项目地址

1. 项目官网： https://developers.openai.com/blog/codex-as-a-platform
2. GitHub 仓库： https://github.com/openai/codex