OpenAI 把 Codex 的”大脑”开源了：Codex Harness 上手指南，三层接口从 CI 到产品全打通

8 月 19 日，OpenAI 做了一件让开发者社区炸锅的事：他们把驱动 Codex Agent 运转的底层执行框架——Codex Harness——以 Apache 2.0 协议完全开源了。注意，开源的不是模型，GitHub 仓库里找不到 GPT-5.6 的权重文件。OpenAI 放出来的是模型的”外骨骼”：对话状态管理、工具调用、沙箱执行、流式输出、人工审批、上下文压缩，以及一套三层集成接口。

截至 8 月 21 日，这个仓库已经冲到 107,443 Star、16,354 Fork。为什么热度这么高？因为 OpenAI 自己放出了一组让工程师坐不住的数据：同一模型 GPT-5.6 Sol，不换权重、不换架构，仅靠 Harness 的两处设计调整（保留推理链 + 压缩上下文），在 ARC-AGI-3 上的得分从 13.3% 直接涨到 38.3%，输出 token 还减少了 6 倍。

这个数据点说明了一件事：Agent 时代，竞争的重心正在从”谁的模型更强”下移到了”谁的 harness 更懂怎么调用模型”。

Harness 到底是什么？别和 Codex 产品搞混

很多人第一次听到 Codex Harness 会误以为它是 Codex App 或者 VS Code 插件的开源版。其实不是。

你平时用的 Codex App、命令行里的 codex、IDE 里的插件——这些都是前端。它们背后共享着同一套基础设施：一个用 Rust 写的核心引擎（codex-rs），加上一个通过 JSON-RPC 对外暴露的 app-server。这套共享基础设施就是 Harness。

用 OpenAI 官方博客的话说：”Your application owns product context, business rules, and tools; Codex app-server provides the agent loop.”（你的产品负责上下文、业务规则和工具；app-server 负责 Agent 循环。）

换句话说，Harness 解决的是那些模型不会替你操心的事：任务怎么拆解、工具调用失败了怎么重试、上下文太长怎么压缩、什么时候该停下来问人、多轮对话的状态怎么持久化。这些才是让 Agent 从”能跑”变成”能落地”的关键。

三层接口，对应三种真实场景

这次开源的核心是 Harness 的三层集成接口。你可以根据团队规模和技术栈，选一层先上手。

第一层：codex exec——给 CI/CD 用的”一键执行”

如果你只需要 Agent 帮你做一件有边界的事——比如重构一个函数、跑一遍测试、修几个 lint 错误——codex exec 是最轻的入口。它不维持持久会话，任务跑完自动退出，非常适合塞进 CI 流水线。

安装只需要一条命令（支持 macOS 和 Linux）：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

curl -fsSL https://chatgpt.com/codex/install.sh | sh

装完之后，直接扔任务给它：

# 给函数加错误处理
codex exec "Refactor the fetchData function in src/utils.ts to add error handling"

# 跑测试并修失败用例
codex exec --cwd /path/to/project "Run tests and fix failed test cases"

# 给函数加错误处理
codex exec "Refactor the fetchData function in src/utils.ts to add error handling"

# 跑测试并修失败用例
codex exec --cwd /path/to/project "Run tests and fix failed test cases"

codex exec 的背后会临时启动一个 exec-server，任务完成后自动销毁。它返回的是结构化结果，你可以直接把输出接进下游脚本。对于已经用 GitHub Actions 或 GitLab CI 的团队来说，这几乎是无缝接入。

第二层：Codex SDK——把 Agent 缝进你的产品

如果你在做自己的应用，想内嵌一个 Agent 来帮用户完成复杂工作流，SDK 层就是为你准备的。Codex SDK 提供 TypeScript 和 Python 两种接口（目前 TypeScript 接口文档更完整），让你可以用代码控制 Agent 的完整生命周期：启动任务、暂停、恢复、流式读取事件、切换模型、设置审批策略。

一个典型的 TypeScript 接入示例：

import { CodexAgent } from '@openai/codex-sdk';

const agent = new CodexAgent({
  model: 'gpt-5.6',              // 也支持 OpenAI 兼容端点
  cwd: '/path/to/project',
  approvalPolicy: 'suggest'      // auto | manual | suggest
});

const thread = await agent.thread.start({
  input: 'Analyze performance bottlenecks and suggest optimizations'
});

for await (const event of agent.stream(thread.id)) {
  if (event.type === 'item/agentMessage/delta') {
    process.stdout.write(event.delta);
  }
  if (event.type === 'turn/completed') {
    console.log('Token usage:', event.usage);
    break;
  }
}

import { CodexAgent } from '@openai/codex-sdk';

const agent = new CodexAgent({
  model: 'gpt-5.6',              // 也支持 OpenAI 兼容端点
  cwd: '/path/to/project',
  approvalPolicy: 'suggest'      // auto | manual | suggest
});

const thread = await agent.thread.start({
  input: 'Analyze performance bottlenecks and suggest optimizations'
});

for await (const event of agent.stream(thread.id)) {
  if (event.type === 'item/agentMessage/delta') {
    process.stdout.write(event.delta);
  }
  if (event.type === 'turn/completed') {
    console.log('Token usage:', event.usage);
    break;
  }
}

SDK 的一个关键设计是 approvalPolicy。auto 模式下 Agent 自己决定什么时候调用工具；manual 模式下每次工具调用都要等人点确认；suggest 介于两者之间，会告诉你它想干什么，但你不拦它它就继续。对于面向用户的产品，我强烈建议从 suggest 开始——既不会打断用户，也不会让 Agent 在没人看管的情况下乱来。

第三层：Codex app-server——生产级 Agent 的持久会话层

如果你的产品需要 Agent 和用户进行长时间、多轮、跨会话的交互——比如一个嵌入在运营后台的 AI 助手，或者一个需要持续追踪长期目标的自动化系统——app-server 层就是答案。

它通过双向 JSON-RPC 协议对外暴露能力，支持：
– 实时事件流（Agent 每做一步都推送给你的应用）
– 中途打断（用户可以随时介入、改需求、撤销上一步）
– 暴露自定义工具（把你自己的 API 注册给 Agent 调用）
– 拦截高危操作（比如删除数据库、调用支付接口前强制人工审批）

一个很多人没注意到的事实：你不用非得用 OpenAI 的模型

这是 Harness 开源后最被低估的一点。官方文档明确写了：Harness 支持连接 OpenAI 托管 API、ChatGPT 认证、Azure，以及兼容 Responses API 的本地模型。

这意味着什么？你可以把 gpt-oss 或者 Ollama 本地跑的模型 接进 Harness，然后用同一套 SDK 控制它。对于数据不能出内网的团队，这是一个比直接用 Codex App 更务实的路径。

与 DeepSeek Harness 的对比：两条路线，两种哲学

8 月 14 日我刚写过 DeepSeek 开源的 Harness，两周后 OpenAI 也开源了同名框架。名字一样，但设计哲学差别不小：

两条路线没有绝对的优劣。DeepSeek Harness 更像一个”开箱即用的 AI 编程 IDE”，适合快速验证和团队内部使用；Codex Harness 更像一组”乐高积木”，适合想把 Agent 能力嵌入自有产品的团队。

我的三个踩坑提醒

1. 开源的不是模型，别指望白嫖 GPT-5.6。 这是最容易产生的误解。Harness 是执行框架，模型仍需通过 API Key 或本地部署接入。如果你想省 API 费用，正确的做法是把 gpt-oss-20b 或 Qwen2.5 这类本地模型接进 Harness，而不是幻想仓库里藏着 GPT-5.6 的权重。

2. codex exec 的 exec-server 是临时进程，不适合长任务。 官方文档说得很清楚，exec-server 在任务完成后自动退出。如果你需要 Agent 持续追踪一个跨小时甚至跨天的目标（比如”把仓库里所有 flaky test 修完”），别用 codex exec，直接上 SDK 或 app-server。

3. 别把 Harness 当成万能胶水。 Harness 擅长的是”围绕模型的执行循环”，不是”替代你的业务逻辑”。如果你的产品已经有一套复杂的权限系统、审批流、数据校验层，Harness 不会自动适配它们。你需要在 SDK 层或者 app-server 的回调里自己桥接。期待”装个 Harness 就能让 Agent 接管一切”的，多半会失望。

适合谁，不适合谁

适合：
– 想把 Agent 能力嵌入自有产品的团队（SDK + app-server 层）
– 已经在用 CI/CD、想让 Agent 自动修 lint / 补测试的开发者（codex exec 层）
– 对 DeepSeek Harness 感兴趣、但技术栈偏 Rust/TS 的团队

不适合：
– 只想找个”免费 GPT-5.6″的个人用户（模型没开源）
– 没有 API Key、也不想本地部署模型的读者（Harness 本身不会生成回答）
– 希望零代码配置就能让 Agent 接管整个开发流程的团队（Harness 是框架，不是 SaaS）

下一步建议

如果你打算上手，我建议按这个顺序：

1. 先跑 codex exec：找一个小任务（比如重构一个函数、补全单测），感受单次调用的响应质量和输出格式。
2. 再试 SDK：在自己的项目里装 @openai/codex-sdk，写一个最小可运行的脚本，观察流式事件的结构和 token 消耗。
3. 最后评估 app-server：如果你在做产品，评估 JSON-RPC 的事件流是否能满足你的实时性要求，以及自定义工具的注册流程是否顺畅。

Harness 开源只是第一步。真正有意思的是看社区会用它搭出什么——自定义 IDE、自动化的代码审查机器人、内嵌在运营后台的 Agent 助手，还是完全想不到的新品类。

本文部分技术细节基于 OpenAI 官方博客、GitHub 仓库文档及 CSDN / 今日头条 / 微博专栏的中文报道整理。