Agent Harness 深度研究报告

深度探讨：OpenAI Codex Harness 架构与实践

1. 架构全景

Codex Harness 是 OpenAI 官方的生产级 Agent 运行时，设计理念是"一个 Harness，多平台统一体验"——无论你是用 CLI、IDE 插件还是 Web 界面，底层都是同一套 Harness。

┌─────────────────────────────────────────────────────────────┐
│                      客户端层                                │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────────────┐ │
│  │Codex CLI│  │VS Code  │  │JetBrains│  │Codex Desktop App│ │
│  │         │  │Extension│  │  Plugin  │  │                 │ │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────────┬────────┘ │
│       └─────────────┴─────────────┴────────────────┘         │
│                         │                                    │
│              JSON-RPC over stdio/WebSocket                   │
│                         │                                    │
├─────────────────────────┼────────────────────────────────────┤
│                      App Server                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐  │   │
│  │  │Stdio Reader │  │Msg Processor│  │Thread Manager│  │   │
│  │  └─────────────┘  └─────────────┘  └──────────────┘  │   │
│  └──────────────────────────────────────────────────────┘   │
│                         │                                    │
├─────────────────────────┼────────────────────────────────────┤
│                      Harness 层                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Firecracker microVM 沙箱（安全隔离的执行环境）         │   │
│  │  ┌──────────────────────────────────────────────┐    │   │
│  │  │  Agent Loop → 工具调用 → 文件系统 → 命令执行  │    │   │
│  │  └──────────────────────────────────────────────┘    │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

2. 核心组件详解

#### 2.1 App Server：双向 JSON-RPC 协议

OpenAI 抛弃了传统的 REST API，采用双向 JSON-RPC over stdio：

为什么是 JSON-RPC？

• 有状态：不像 REST 的无状态请求-响应，Agent 需要长时间保持连接
• 双向通信：服务器可以主动推送事件（工具调用进度、流式输出）
• 低开销：JSONL 格式（每行一个 JSON），省去 HTTP 头部开销

// Request
{ "method": "thread/start", "id": 10, "params": { "model": "gpt-5.1-codex" } }

// Response
{ "id": 10, "result": { "threadId": "t_abc123" } }

// Notification（服务器主动推送）
{ "method": "tool/executing", "params": { "tool": "bash", "command": "npm test" } }

#### 2.2 Harness：Firecracker microVM 沙箱

每个 Codex 实例运行在独立的 Firecracker microVM 中：

• 冷启动 < 125ms：比传统 Docker 更快
• 内存开销 < 5MB：每个沙箱轻量级
• 硬件加速：可选 GPU 支持用于编译/测试
• 状态快照：会话可序列化、暂停、恢复

• 默认只读访问，需显式授权写操作
• 网络隔离，可配置允许的外联
• 文件系统命名空间隔离

用户输入
   ↓
┌─────────────────────────────────────┐
│ 1. 意图理解（Intent Understanding）  │
│    - 解析用户自然语言指令           │
│    - 确定任务类型（探索/编码/调试）  │
└─────────────────────────────────────┘
   ↓
┌─────────────────────────────────────┐
│ 2. 上下文加载（Context Loading）     │
│    - 读取 AGENTS.md                 │
│    - 加载相关文件片段               │
│    - 注入工具描述                   │
└─────────────────────────────────────┘
   ↓
┌─────────────────────────────────────┐
│ 3. 规划（Planning）                  │
│    - 分解任务为子步骤               │
│    - 确定工具调用序列               │
│    - 生成执行计划                   │
└─────────────────────────────────────┘
   ↓
┌─────────────────────────────────────┐
│ 4. 执行循环（Execution Loop）        │
│    while 任务未完成:                │
│      - 调用工具                     │
│      - 观察结果                     │
│      - 决定下一步                   │
│      - 流式返回进度                 │
└─────────────────────────────────────┘
   ↓
┌─────────────────────────────────────┐
│ 5. 验证（Verification）              │
│    - 运行测试                       │
│    - 类型检查                       │
│    - 代码审查                       │
└─────────────────────────────────────┘
   ↓
完成输出

3. Harness Engineering 实践

#### 3.1 AGENTS.md：活的约束系统

OpenAI 的突破性实践——把文档变成可执行的约束：

# Project: Codex App Server

## Overview
High-performance agent runtime using JSON-RPC over WebSockets

## Architecture
Types → Config → Repo → Service → Runtime → UI

## Constraints
- Agents MUST NOT bypass dependency layers
- All file writes MUST go through FileTool
- Network calls MUST use approved domains list

## Tool Usage Patterns
- Use `read` for files < 100 lines
- Use `search` for finding symbols
- Use `bash` for npm/pip commands only

## Common Failures
- ❌ "Can't find module": Check if npm install was run
- ❌ "Port already in use": Kill existing process first

关键洞察：AGENTS.md 不是一次性文档，而是每次失败后的迭代更新——Agent 遇到错误 → 人类分析根因 → 更新 AGENTS.md → 下次 Agent 自动避免。

#### 3.2 架构护栏：机械强制依赖层

Types → Config → Repo → Service → Runtime → UI
  ↑       ↑       ↑        ↑         ↑       ↑
基础类型 配置层  数据层   业务逻辑   运行时   界面层

实施方式：

• 自定义 Linter：检查跨层导入
• 结构测试：CI 中验证依赖流向
• Agent 训练：在 AGENTS.md 中强化约束

#### 3.3 可观测性驱动迭代

Agent 不是黑盒——它自己能看日志：

Agent 执行流程
   ↓
产生日志/指标/追踪
   ↓
Agent 读取遥测数据
   ↓
自主复现 Bug
   ↓
提出修复方案
   ↓
人类审查 PR

遥测数据类型：

• 日志：结构化日志（ERROR/WARN/INFO）
• 指标：延迟、吞吐量、错误率
• 追踪：分布式追踪（OpenTelemetry）
• 性能分析：CPU/内存火焰图

4. 状态管理：从 Stateless 到 Stateful

#### 4.1 状态快照（State Snapshotting）

场景：Agent 运行 2 小时后遇到限流

传统方式：
- 连接断开
- 进度丢失
- 从头再来

Codex Harness：
- 序列化 VM 状态
- 暂停连接
- 恢复时精确回到断点
- Agent 继续执行

实现细节：

• 内存状态 → 磁盘快照
• 文件系统 → 增量备份
• 网络连接 → 优雅重连

创建 Thread
   ↓
开始 Turn（用户输入）
   ↓
Agent Loop 执行
   ↓
生成 Items（消息、工具调用、结果）
   ↓
Turn 完成
   ↓
可选：暂停（suspend）
   ↓
可选：恢复（resume）
   ↓
可选：归档（archive）

持久化策略：

• 每 30 秒自动检查点
• 关键操作后立即持久化
• 支持显式 save() 调用

5. 工具系统：从调用到编排

#### 5.1 内置工具集

Agent 意图调用工具
   ↓
Harness 拦截请求
   ↓
验证权限
   ├─ 允许 → 继续
   └─ 拒绝 → 返回错误
   ↓
在沙箱中执行
   ↓
捕获输出
   ↓
清理/格式化
   ↓
返回给 Agent

#### 5.3 MCP 集成

Codex Harness 支持 Model Context Protocol：

// mcp.json 配置
{
  "servers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/mcp-server"],
      "env": { "NOTION_TOKEN": "${NOTION_TOKEN}" }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@github/mcp-server"]
    }
  }
}

Token 成本优化：

• 原始：所有 MCP 工具描述 ~134K tokens
• Tool Search 改进后：~5K tokens（按需加载）

6. 性能与成本数据

#### 6.1 OpenAI 内部实验结果

瓶颈不是模型，是 Harness：

• 前期：专注提示工程 → 进展缓慢
• 后期：专注 Harness 建设 → 速度起飞

• 传统：团队变大 → 协调成本 ↑ → 速度 ↓
• Harness：团队变大 → Agent 并行 ↑ → 速度 ↑

7. 对比：Codex vs Claude Code

8. 使用建议

#### 8.1 何时选择 Codex Harness？

✅ 适合：

• 大规模代码库（10万+ 行）
• 需要多平台统一体验
• 团队已用 OpenAI 生态
• 需要状态持久化和恢复
• 需要细粒度安全控制

• 简单的一次性脚本
• 需要完全开源方案
• 深度依赖 Claude 模型
• 预算敏感（Codex 调用成本较高）

□ 创建 AGENTS.md，描述项目结构和约束
□ 配置 mcp.json，接入所需工具
□ 设置 CI 流水线，自动验证 Agent 输出
□ 建立内部评估基准（参考 Cursor Bench）
□ 配置可观测性（日志、指标、追踪）
□ 定义安全策略（允许的工具、文件访问范围）

9. 未来展望

Harness as a Service (HaaS)：

• OpenAI 正在将 Codex Harness 云服务化
• 开发者只需关注业务逻辑
• Harness 层由 OpenAI 托管和优化

# 未来可能的 API
from openai import Agent

agent = Agent(
    model="gpt-5.1-codex",
    harness="production",  # 选择 Harness 配置
    tools=["git", "bash", "file"],
    constraints={"max_turns": 50}
)

result = agent.run("重构用户认证模块")

*深入探讨：小凯* *基于 OpenAI 官方 Harness Engineering 博客及社区分析*