8 月 19 日，OpenAI 官方博客宣布全面开源 Codex Harness（Apache-2.0，github.com/openai/codex）——驱动 Codex App、CLI、IDE 扩展与 macOS 应用运行的底层 Agent 执行框架。这不是一个模型，而是「让模型变成能干活 Agent 的那套脚手架」：任务循环、跨轮记忆、工具调度、沙箱执行、审批门、进度流式输出，全在里面。
🏗️ 本教程适合：想把自己的产品 / 工具嵌进 Codex 级 Agent 能力的开发者。我们拆解 Harness 五大职责、三层接口（exec / SDK / app-server）与架构，并用 ARC-AGI-3 数据讲清「为什么 Harness 比模型更值得投入」。
先搞懂：Agent = 模型 + Harness
行业共识正在收敛：模型提供智力上限，Harness 决定模型能否在真实多步任务中触达这个上限。同一个模型套上不同的 Harness，行为可以完全不同：
| 层 | 职责 | 谁在管 |
|---|---|---|
| 模型 | 思考、推理、生成 | OpenAI / 任意模型网关 |
| Harness | 任务循环、上下文、工具、沙箱、审批、持久化 | 开发者（现在可开源自建） |
| 客户端 | 交互界面（CLI/IDE/App） | 你（通过 app-server 对接） |
ARC-AGI-3 铁证：仅做「保留推理 + 上下文压缩」两项 Harness 调整，GPT-5.6 Sol 的得分从 13.3% 跃升到 38.3%，输出 token 还减少 6 倍——同一模型，更好的 Harness，三倍分数、六分之一成本。
Step 1：认识三层集成接口——从 CI 脚本到产品级嵌入
1 三种接入方式，覆盖全场景
本次开源打包三层接口：
1. codex exec（轻量一次性）
· 适合：CI 脚本、自动化运维、
后台一次性任务
· 特点：非交互、跑完即走
· 用法示例：
codex exec "修复这个
测试失败并跑通"
2. Codex SDK（程序化编排）
· 适合：在自有业务代码里
嵌入 Agent 能力
· 语言：TypeScript / Python
· 特点：可精确控制任务
生命周期、工具、回调
· 用法示例：
const result = await
codex.chat({ prompt,
sandbox: 'read-only' })
3. Codex app-server（持久会话）
· 适合：长时间自主运行的
复杂智能体任务
· 特点：双向 JSON-RPC、
实时事件流、断点续跑
· 也是 Codex 全产品共用的
底层服务
选型口诀：
一次性 → exec
嵌入业务 → SDK
深度产品化 → app-server💡 别一上来就上 app-server。先用 exec 跑通单任务、再用 SDK 编排流程，最后才考虑持久会话——层级越低，调试越简单。
Step 2：codex exec——把 Agent 塞进自动化流水线
2 轻量接入：CI 与运维场景
codex exec 设计目标：
· 非交互运行
· 一条命令完成一个任务
· 适合嵌入流水线
典型场景：
1. CI 修复
· 构建失败时让 Agent
分析日志并提交修复
2. 自动化运维
· 诊断告警、生成处理建议
· 低危操作直接执行
3. 批处理任务
· 批量重构 / 批量文档更新
安全默认：
· 默认只读沙箱
· 高危操作（写文件/执行）
需显式授权
· 审批门可配置
与
《自改进 Agent》
的「验证工作」理念一致：
改完必须跑测试，
测试通过才算完成exec 不是「无人值守魔法」：它是「有护栏的自动化」。权限配置、沙箱策略、审批流要在接入流水线之前就写好，否则等于把 CI 机器钥匙交给 Agent。
Step 3：Codex SDK——用代码编排 Agent 生命周期
3 程序化控制：任务、工具、回调
SDK 能做什么：
· 创建会话与线程
· 精确注入工具集
（shell / 文件 / MCP / skills）
· 监听事件流
（进度 / 审批请求 / 完成）
· 控制沙箱边界
（只读 / 临时目录 / 全权）
· 中断、恢复、超时控制
典型集成方式：
import codex
agent = codex.Agent(
model='your-gateway',
sandbox='workspace',
tools=['shell', 'read-only-fs']
)
for event in agent.run(prompt):
if event.type == 'approval':
event.approve() # 或拒绝
权限策略统一管理：
· MCP server 与 skills 走
同一套策略模型
· 模型无关：可接私有
模型网关（企业内网）
适合：把 Agent 嵌入
运维看板、安全排查工具、
内部业务平台——AI 原生
融入现有工作流，而不是
把业务搬进聊天框💡 SDK 的杀手锏是「事件驱动」：把 approval 事件接到你现有审批系统（企微/飞书/工单），人审环节自然融入团队流程——参考《企微 CLI 接入》。
Step 4：app-server——持久会话与 JSON-RPC 架构
4 架构拆解：线程管理器与核心会话
app-server = 双向 JSON-RPC
+ 长驻进程
进程四件套：
1. stdio reader
· 读入客户端 JSON-RPC 请求
2. message processor
· 翻译请求为核心操作
· 把内部事件转成
稳定的 UI 通知
3. thread manager
· 每个线程一个核心会话
· 负责创建/恢复/派生
4. core threads
· 真正跑 Agent 循环
传输：JSON-RPC over stdio
（JSONL 分帧）
线程生命周期：
· create：新建对话
· resume：断线重连接回
一致的时间线
· fork：派生新分支
· archive：归档
这就是「长任务自主续跑」
的底座：单任务可连续运行
数小时，崩溃可断点续跑app-server 是重武器：适合产品级嵌入（IDE、桌面应用、SaaS 后端）。如果只是自己用，exec/SDK 就够——别为持久会话付出运维复杂度。
Step 5：为什么 Harness 工程是「第三战场」
5 模型之后，竞争转移到运行时
行业信号（8 月集中爆发）：
· OpenAI 开源 Codex Harness
· DeepSeek Harness 一周三更，
GitHub Star 破 17 万
· NVIDIA AVO 在 ARC-AGI-3
公开测试集拿 100% 满分
· Anthropic 四大 Agent API
转 GA（8-20）
· 字节 Seed 重构 Agent
研发链路
共识：Agent 的核心竞争力
已从「模型谁更聪明」转向
「运行时谁更可投产」——
工具编排、上下文管理、
工程反馈闭环。
ARC-AGI-3 案例拆解：
· 加「保留推理」：模型思考
过程跨步保留，不丢链
· 加「上下文压缩」：无关内容
压缩出上下文，省 token
· 结果：13.3% → 38.3%，
输出 token 减 6 倍
Terminal-Bench 也把
「模型 + Harness」当作
一个整体来评分——单测
模型分数已经没有意义。
与
《Harness 插件生态》
《云原生底座》
放在一起看：Agent 基础设施
正在成为新的护城河💡 想验证 Harness 的价值？不需要重写整套系统——先在你的 Agent 上加「验证环节」（改完跑测试再交付），再试「上下文压缩」，两步就能看到任务完成率的变化。
Step 6：安全管控与模型无关接入
6 生产级部署的最后两块拼图
安全管控体系：
1. 隔离沙箱
· 代码执行与文件访问
在沙箱内完成
2. 高危操作人工审批
· 强制人在回路
· approval 事件可接
企业审批系统
3. 凭证脱敏与权限恢复
· resumed/forks 线程恢复
原权限档案
· 不会静默回落到当前默认
模型无关兼容：
· 框架不绑定 OpenAI 模型
· 可对接私有模型网关
（企业内网 / 私有化）
· 依托 AGENTS.md 规范
读取项目文档
· 精简上下文、降低幻觉
部署检查清单：
□ 沙箱策略与你的
风险等级匹配
□ 审批流已接入
现有审批系统
□ AGENTS.md 已写
□ 凭证管理已最小化
□ 有日志可审计
参考
《CISO 四问法》
做一次上线前安全体检开源 ≠ 免费午餐：Harness 开源的是一层「可检查、可改造」的集成面，模型访问与托管服务仍是闭源。看清边界再规划，别把「开源」误解成「自托管一切」。
常见问题速查
| 你遇到的现象 | 大概率原因 & 解决 |
|---|---|
| exec 跑不了长任务 | exec 定位一次性任务：长任务用 app-server 或 SDK 的持久会话 |
| 审批流太烦 | 分级审批：只读操作自动放行，写操作审批，高危操作双人审批 |
| 想接自己的模型 | 模型无关设计：配好模型网关与凭证即可，无需改框架 |
| 上下文太大很贵 | 启用上下文压缩 + AGENTS.md 精简：ARC 案例显示输出 token 可减 6 倍 |
| 担心沙箱逃逸 | 沙箱 + 最小权限 + 审批门组合：高危操作永远有人审，参考《安全沙箱》 |