Codex Harness 解析：开源的不是一个壳，而是一套 Agent 运行时

这是 Codex 系列的一篇补篇。

前面几篇已经讲过 Codex 的入口选择、权限边界、AGENTS.md、Skills、MCP、GitHub 和团队治理。那些文章更多站在使用者角度：怎样把 Codex 放进日常工程工作流。

这篇稍微往下挖一层，回答一个最近被反复问到的问题：

Codex Harness 近期开源了吗？

我的短答案是：

是，Codex Harness 的关键运行时和协议面已经能在 openai/codex 里看到；但它不是一个独立叫 codex-harness 的仓库，也不能被理解成 Codex 产品整体开源。

这个答案看起来绕，但绕的地方正是重点。Harness 不是一个普通组件名，它更像一组运行时责任：模型怎样循环调用工具，状态怎样保存，命令怎样审批，沙箱怎样限制，客户端怎样收到流式事件，任务中断后怎样恢复。

如果把这层看清楚，Codex 就不再只是“一个会改代码的聊天框”。它更像一套围绕模型搭起来的工程运行时。

这篇解决什么问题

读完这篇，我希望你能带走三样东西：

本文不会把 openai/codex 每个目录逐行拆完，也不会分析未开源的 Codex Cloud 内部实现。重点是建立一张足够准确的地图：你知道这套系统大概怎样组织，后面读源码或使用 Codex 时不会迷路。

版本与证据说明

本文把资料分成两类：OpenAI 官方资料用于确认 Codex 的事实，例如“哪些组件开源”“App Server 如何定义 Thread / Turn / Item”；外部文章只用于理解 Harness Engineering 的工程语境，例如自验证、上下文供给、长任务状态和人工审批。社区推文可以作为线索，但不作为本文事实判断依据。

第一次阅读可以先看哪里

• 只想知道是否开源：读第 1、3 节。
• 想理解 App Server：读第 4、5 节。
• 准备读源码：读第 6 节。
• 只是想更好使用 Codex：读第 8、9、10 节。
• 想和 Harness Engineering 放在一起理解：读第 2、7、11 节。

一分钟概览

先记住这九点：

1. Codex Harness 不是独立仓库名。 当前公开可看的主体在 openai/codex。
2. Codex Core 是核心入口。 OpenAI 明确说 agent logic 和 core agent loop 位于 Codex Core。
3. App Server 是协议入口。 它把 Thread、Turn、Item、审批、流式事件和客户端集成暴露出来。
4. 一次 Codex 任务不是普通 request / response。 它会产生消息、命令、diff、审批、失败、恢复和完成等事件。
5. 开源边界要分清。 CLI、SDK、App Server、Skills、Plugins 等有公开组件；IDE extension 和 Codex Cloud 产品本身不在官方开源组件表中。
6. App Server 很重要，但仍有实验边界。 当前文档对部分方法、字段和 transport 保留 experimental / unsupported 提醒。
7. MCP 不是 App Server 的替代品。 当前 Codex MCP Server 文档已经把 codex mcp-server 标为 deprecated，新深度集成应优先看 App Server。
8. 使用者真正该改变的是任务写法。 给目标、上下文、边界、验证和剩余风险，比单纯追求更长 Prompt 更重要。
9. 开发者真正该学的是责任拆分。 模型、Core、工具、沙箱、审批、事件、客户端和用户验收各有位置。

图 1：Codex Harness 的运行时地图。多个客户端通过 App Server 复用 Codex Core，再连接模型、工具、沙箱、审批与状态。

移动端可打开图 1 原始 SVG放大查看。

1. 先把一句话说准

我看到“Codex Harness 是否开源”这个问题时，最容易出现三种说法。

第一种是：

Codex Harness 已经全部开源了。

这句话太满。OpenAI 的 Codex Open Source 页面确实列出了不少公开组件，包括 Codex CLI、SDK、App Server、Skills、Plugins 等；但同一张表也把 IDE extension 和 Codex cloud 标为 not open source。公开关键运行时，不等于整个产品所有部分都开源。

第二种是：

没看到 codex-harness 仓库，所以没开源。

这也不对。OpenAI 在 Unlocking the Codex harness 里讲得很明确：agent logic 和 core agent loop 位于 Codex CLI 代码库里的 Codex Core；App Server 的源码也在同一个开源仓库里。

第三种说法更接近事实：

Codex Harness 的关键运行时和协议面，
已经以 Codex Core、App Server、SDK、CLI、Skills、Plugins 等形式公开；
但它不是一个独立仓库，也不是 Codex 产品整体开源。

这也是本文采用的表述。

为什么要这么较真？因为“开源了什么”会影响后续判断。如果你以为 Codex 产品整体开源，就容易把看不到的云端能力也脑补成仓库里的实现；如果你以为没有单独仓库就等于没开源，又会错过 openai/codex 里真正值得学习的运行时结构。

2. Harness 不是一个更大的 Prompt

OpenAI 在 Unrolling the Codex agent loop 里，把 Codex 的基础循环拆得很清楚：

用户输入
  -> 构造模型输入
  -> 模型生成
  -> 如果是最终回答，结束本轮
  -> 如果是工具调用，执行工具并把结果放回上下文
  -> 再次请求模型

这就是 Agent Loop 的骨架。但 Coding Agent 进入真实项目后，问题会马上变多：

这次运行属于哪个 thread？
历史上下文怎样恢复？
哪些工具可用，哪些工具需要审批？
命令在哪个 cwd 和 sandbox 里运行？
工具输出怎样进入下一次模型输入？
文件 diff 怎样展示给客户端？
用户拒绝审批后 turn 怎样结束？
任务中断以后下一次怎样继续？

这些问题都不是“系统提示词写得更长”能稳定解决的。

Prompt 可以提醒模型：

危险命令先询问用户。
完成后运行测试。
不要修改无关文件。

但真正能让这些规则生效的是运行时：

审批路径能暂停工具调用；
沙箱能限制文件和网络边界；
事件流能记录命令、diff 和结果；
线程状态能支持 resume 和 fork；
验证命令能给最终回答提供证据。

所以我会把 Codex Harness 理解成：

Codex Harness
  = Agent Loop
  + Thread lifecycle / persistence
  + Context management
  + Config / auth
  + Tool execution
  + Sandbox / approvals
  + Event stream
  + MCP / Skills / Plugins / Hooks
  + Client integration protocol

更短一点：

模型负责提出下一步可能做什么；Harness 负责决定这一步能否执行、怎样执行、如何记录、怎样恢复、如何证明。

这也是为什么我觉得 Harness 这个词很有价值。它把大家从“模型到底聪不聪明”带回一个更工程化的问题：模型周围的系统有没有把任务、权限、状态和证据组织好。

3. 开源边界：哪些能看，哪些不能外推

截至 2026-08-25，OpenAI 官方开源组件可以整理成下面这张表。

这张表里最重要的不是“是”或“否”，而是中间那几行：

Codex Core
Codex App Server
App Server Protocol
Codex SDK

Core 让我们看到 Agent 怎样运行，App Server 让我们看到客户端怎样驱动 Agent，Protocol 让我们看到事件和状态怎样被命名，SDK 让我们看到更高层的程序化入口。

换句话说，Codex 公开的不是一个空壳，而是相当关键的一段 Agent 运行时。

但它也不是一个“拿来就等于复刻 Codex 产品”的完整包。Cloud 环境、产品 UI、组织策略、账号体系、托管执行和实际线上运维，都不能只靠公开仓库倒推出完整事实。

这一点要反复提醒，因为开源项目解读最容易犯两个错误：要么把源码读成全部真相，要么因为不是全部真相就否认源码价值。

4. App Server 是这件事的关键入口

如果只用传统 CLI 眼光看 Agent，很容易把它想成：

输入一条命令
等待它运行
拿到退出码和输出

但一次 Codex 任务并不是这样。比如“帮我修复一个测试失败”，过程可能是：

读取项目结构
生成计划
运行测试
发现失败
修改文件
展示 diff
请求用户批准
继续执行命令
再次运行测试
输出最终说明

这里面有很多中间产物。客户端不能只等一个最终字符串，它需要持续知道：

• 现在读了什么文件；
• 是否开始执行命令；
• 命令输出了什么；
• 是否需要审批；
• 用户同意或拒绝后状态如何变化；
• 最后到底是 completed、failed、interrupted，还是 declined。

OpenAI 的 App Server 文章把它描述成两件事：

一套客户端与服务端之间的 JSON-RPC 风格协议；
一个托管 Codex Core threads 的长期运行进程。

一个简化的结构是：

Client / IDE / App
        |
        | JSON-RPC lite
        v
Codex App Server
        |
        +-- message processor
        +-- thread manager
        +-- core threads
        |
        v
Codex Core

这就是为什么 App Server 比“把 CLI 包成 API”更重要。它把 Codex Core 的状态、事件、审批和线程生命周期整理成客户端能理解的协议。

如果你只是普通使用者，App Server 不一定需要直接碰。但理解它以后，你会更容易明白为什么 Codex App / IDE 能展示那么多过程状态，也会更容易判断什么时候该用 CLI、什么时候该用 SDK、什么时候才值得做深度客户端。

这里也要保留官方边界。当前 Codex App Server 文档明确存在 experimental surface；部分方法或字段需要通过 capabilities.experimentalApi 开启；WebSocket transport 也被标为 experimental / unsupported，不建议当作生产稳定承诺。

我的理解是：

App Server 是理解 Codex Harness 的关键协议面，但现在读它更像读一个开放中的产品内核接口，而不是读一份已经永久定型的企业集成标准。

5. Thread / Turn / Item：Agent 协议为什么要拆这么细

App Server 最值得学习的抽象，是三个 conversation primitives。

这三个词看似只是协议命名，实际解决的是 Coding Agent 的核心问题：最终回答不是任务的全部输出。

图 2：一次 Codex 任务的事件流。客户端创建 Thread、启动 Turn，App Server 流式返回 Item，并在需要时发起审批请求。

移动端可打开图 2 原始 SVG放大查看。

一个简化流程大概是：

Client / IDE / App
  -> initialize
  -> thread/start
  <- thread/started
  -> turn/start
  <- turn/started
  <- item/started
  <- item/agentMessage/delta
  <- item/commandExecution/requestApproval
  -> accept / decline
  <- item/completed
  <- turn/completed

这个流程比普通聊天复杂，但复杂得有必要。

如果 Codex 说“我修复了测试”，我真正关心的是：

它读了哪些文件？
它改了哪些 diff？
它执行了哪些命令？
命令在哪个目录和 sandbox 里运行？
有没有被审批？
测试输出是什么？
最终 turn 是 completed、interrupted、failed，还是 declined？

Thread / Turn / Item 就是为了让这些东西不丢。它们让客户端可以展示过程，让用户可以审查行为，让任务可以恢复，也让失败状态不必被揉成一句“抱歉，出错了”。

这也是我最喜欢 App Server 的地方：它没有把 Agent 过程伪装成一次普通问答，而是承认真实过程本来就是事件流。

6. 打开 openai/codex，先追三条线

openai/codex 仓库很大。如果目标是理解 Harness，不建议一开始按目录逐个读。更好的方式是按问题追。

先看 codex-rs/ 下面这些目录：

openai/codex
└── codex-rs/
    ├── core/                    # agent loop、thread runtime、工具调度、核心状态
    ├── core-api/                # Core 与外部调用方之间的 API 边界
    ├── app-server/              # 长驻 App Server 进程与 JSON-RPC 方法处理
    ├── app-server-protocol/     # Thread / Turn / Item 等协议类型
    ├── app-server-client/       # 客户端侧协议支持
    ├── app-server-daemon/       # App Server 守护进程相关能力
    ├── exec/                    # 一次性命令执行与自动化入口
    ├── sandboxing/              # 沙箱策略与执行隔离
    ├── mcp-server/              # Codex 作为 MCP server 的历史入口
    ├── config/                  # 配置加载与默认值
    ├── prompts/                 # 系统提示词与上下文构造材料
    ├── skills/                  # Skill 发现与运行时集成
    ├── hooks/                   # 生命周期 hook
    ├── memories/                # 记忆相关状态
    └── tui/                     # 终端 UI

但真正开始读时，我会只追三条线：

这三条线读通以后，再读其他目录就会顺很多。

我建议的 60 分钟阅读路线是：

不要一上来就试图解释所有 Rust 类型。先回答这三个问题：

谁创建长期任务？
谁推进一次用户请求？
谁决定工具能不能执行？

这三个问题比“哪个文件是 main”更能抓住 Harness。

7. 和其他 Harness 文章放在一起看

这篇不是孤立出现的。过去一年，很多 Agent 文章都在谈 Harness，只是角度不同。

Martin Fowler 更关心 coding agent 用户怎样构造自己的外部 harness：仓库文档、测试、反馈、检查和人类判断如何影响 Agent 表现。

LangChain 更强调运行时能力：模型自己不能持久保存状态、执行代码、准备环境或访问实时知识；自验证、环境上下文和测试循环会显著影响 Agent 质量。

Anthropic / Claude 的几篇文章则更关注长任务：怎样把进度写入文件，怎样用 evaluator / generator 分工，怎样避免 Agent 做太多、测太少，怎样动态选择工作流。

把它们放在一起看，我会这样理解：

这些文章的共同点不是发明了一个新名词，而是都在说：

Agent 质量不只来自模型，也来自模型周围的工作环境。

Codex 的特别之处在于：OpenAI 把自己的 Coding Agent 运行时和协议面相当一部分放进了公开仓库。对使用者，这是理解产品行为的窗口；对开发者，这是一个成熟 Agent runtime 的设计样本。

8. App Server、CLI、SDK、codex exec、MCP 怎么选

理解 Harness 以后，一个自然问题是：我平时到底该用哪个入口？

图 3：Codex 入口选择图。日常使用优先 App / IDE / CLI，一次性自动化看 codex exec，程序化工作流看 SDK，产品级客户端再看 App Server。

移动端可打开图 3 原始 SVG放大查看。

我的选择表是：

我自己的口诀是：

日常用现成入口；
脚本用 exec；
程序用 SDK；
做客户端再用 App Server；
接外部工具看 MCP / Apps / Plugins。

这里特别提醒 codex mcp-server。当前 Codex MCP Server 文档 已经把它标为 deprecated，并建议使用 Codex App Server。原因很直观：MCP 是通用工具协议，适合把能力暴露给其他 Agent；App Server 是 Codex 自己的客户端协议，更能表达 Thread、Turn、Item、审批、事件流和生命周期。

不要为了“更底层”直接上 App Server。App Server 的价值在于长期连接、事件流、审批、线程生命周期和客户端集成。如果你只是想让 Codex 在 CI 里跑一次 review，更轻的入口通常更合适。

9. 理解 Harness 后，怎么更好地使用 Codex

这篇文章最不希望停在“源码里有哪些目录”。对大多数人来说，理解 Harness 以后，真正该改变的是使用方式。

我的核心建议是：

少把 Codex 当成“更会写代码的聊天框”，多把它当成“带运行时边界的工程协作者”。

具体可以落到七个习惯。

9.1 给任务，不只给愿望

不要只写：

帮我优化这个项目。

更好的写法是：

请先阅读当前仓库结构、README、AGENTS.md 和测试入口，
找出登录流程里可能导致 token 过期后白屏的问题。

要求：
1. 先解释相关文件和调用链；
2. 再给最小修改方案；
3. 修改后运行对应测试；
4. 最终列出改动文件、验证命令和剩余风险。

Harness 能帮 Codex 读文件、执行工具、记录事件，但它仍然需要你给出清晰目标和验收边界。目标越像工程任务，Codex 越容易把工具调用组织成正确路线。

9.2 先让 Codex 建地图，再让它动手

对陌生仓库，一个更稳的开局是：

先不要修改文件。
请阅读项目结构、关键配置、AGENTS.md、测试命令和最近相关模块，
总结：
1. 这个项目如何运行；
2. 这个需求可能涉及哪些文件；
3. 你建议的最小改动路径；
4. 需要先确认的风险。

很多失败不是模型不会写代码，而是它没拿到正确上下文。先让它建立项目地图，再让它修改，通常比直接动手更稳。

9.3 大任务用 thread / resume / fork 思维组织

Codex 有 thread lifecycle 和 persistence，就不要每次都从零开始解释整个背景。

Thread 是 Harness 保存上下文、事件和状态的容器。任务边界切得好，Codex 的恢复、压缩和验证都会更稳定。

9.4 保留 sandbox 和 approval

从 Harness 视角看，sandbox 和 approval 不是麻烦，而是系统边界。

日常开发里，我更推荐：

允许 Codex 在工作区内读写；
高风险命令、网络访问、跨目录写入、删除操作需要审批；
不要在普通项目中长期绕过审批和沙箱。

模型提出动作，Harness 决定动作能否执行。你可以信任 Codex 帮你工作，但不应该让任何 Agent 默认拥有无限本地权限。

9.5 让 Codex 自证结果

LangChain 的 Harness Engineering 文章提醒了一个很常见的失败模式：Agent 写完代码，粗略扫一眼自己的改动，然后宣布完成。Coding Agent 的可靠性，很多时候来自“写完以后能不能真正验证”。

所以任务里可以直接写：

完成后请给出：
1. 改了哪些文件；
2. 为什么这样改；
3. 运行了哪些验证；
4. 验证输出说明什么；
5. 哪些测试没有跑；
6. 还有什么残余风险。

这正是 Harness 中事件流和工具输出的价值。Codex 可以修改代码，也可以运行命令；你应该让它把证据带回来，而不是只给一个完成声明。

9.6 把重复规则沉淀到 AGENTS.md、Skills 和 Hooks

如果一条规则每次都要重复提醒，它就不该只留在 Prompt 里。

个人用 Prompt 可以解决一次任务。团队长期使用 Codex，更应该把规则放到 Harness 能读取和执行的位置。

9.7 深度集成前，先问三个问题

如果你想把 Codex 接进自己的工具链，先不要直接写 App Server 客户端。先问：

只是跑一次任务并拿结果？用 codex exec。
需要在自己的程序里启动、恢复和消费输出？优先看 SDK。
需要做自己的 IDE / 桌面客户端，展示事件、diff、审批和 thread？再看 App Server。

App Server 是强接口，但也是更重的接口。它适合你要“成为一个 Codex 客户端”的时候，而不是每个自动化脚本的第一选择。

10. 一个可直接复用的任务模板

下面这个模板适合给 Codex App、CLI 或 IDE 使用。它的目的不是写得漂亮，而是把 Harness 能发挥作用的关键信息补齐。

任务：
请完成 [一句话目标]。

背景：
- 项目/模块：
- 当前现象：
- 相关文件或入口：
- 已知限制：

执行方式：
1. 先阅读项目结构、AGENTS.md、README、相关配置和测试入口；
2. 先说明你理解到的调用链和最小改动方案；
3. 再进行代码或文档修改；
4. 修改后运行最相关的验证命令；
5. 如果遇到需要审批的命令，请说明原因、工作目录和预期影响；
6. 最后输出改动摘要、验证结果和剩余风险。

验收标准：
- [标准 1]
- [标准 2]
- [标准 3]

边界：
- 不要改动 [不相关模块]；
- 不要引入 [不希望的依赖或框架]；
- 如需扩大范围，先说明原因。

这份模板背后的思想就是 Harness Engineering：给 Agent 足够上下文，给工具明确边界，给完成状态可验证证据。

11. 我的判断

Codex Harness 开源的意义，不只是“开发者可以读源码”。

更重要的是，它让我们看到一个成熟 Coding Agent 产品如何把模型放进工程系统里：

模型负责提出下一步；
Core 负责运行 agent loop；
工具系统负责接触真实环境；
Sandbox 和 approval 负责动作边界；
Thread / Turn / Item 负责状态和事件；
App Server 负责把这些能力交给客户端；
用户和团队规则负责定义什么叫完成。

这比“写一个更长的系统提示词”更接近真实 Agent 工程。

如果你是 Codex 使用者，理解 Harness 后最该改变的是工作方式：任务要有边界，仓库要有规则，修改要有验证，风险操作要保留审批，长任务要利用 thread 和 resume，而不是每次重新开聊。

如果你是 Agent 开发者，openai/codex 值得看的也不是某个神秘技巧，而是一整套责任拆分：Core 不等于 UI，App Server 不等于模型，MCP 不等于完整客户端协议，最终文本不等于真实完成。

所以，回到开头的问题：

Codex Harness 近期开源了吗？

我的答案会保留这个精确版本：

Codex Harness 的关键运行时和协议面已经公开在 openai/codex 中，尤其值得阅读的是 Codex Core 与 Codex App Server。它不是一个单独的壳，而是一套把模型、工具、上下文、权限、状态和客户端事件组织起来的 Agent 运行时。

这也是它最值得研究的地方。

收藏清单

如果只收藏这一篇，我建议记住这几条：

• Codex Harness 不是独立仓库名，关键公开入口是 openai/codex。
• Codex Core 是 agent logic 和 core agent loop 的主要所在地。
• App Server 是 Codex Harness 的客户端协议面，适合深度客户端集成。
• Thread / Turn / Item 比 request / response 更适合表达 Coding Agent 的真实过程。
• Codex CLI、SDK、App Server、Skills、Plugins 等有公开组件；IDE extension 和 Codex Cloud 产品本身不等于开源。
• App Server 当前仍有 experimental / unsupported 边界，不能把所有能力当作稳定生产协议。
• codex mcp-server 当前已被官方文档标为 deprecated，新集成优先看 App Server。
• 使用 Codex 时要给目标、上下文、边界、验证和剩余风险要求。
• 团队重复规则应沉淀到 AGENTS.md、Skills、Hooks 或外部工具集成里。
• 开源价值不是照抄实现，而是理解成熟 Agent 运行时怎样分配责任。

参考资料

OpenAI 官方资料

• OpenAI：Unlocking the Codex harness: how we built the App Server
• OpenAI Developers：Codex as a platform: build on the open agent harness
• OpenAI：Unrolling the Codex agent loop
• Codex Manual：Open Source
• Codex Manual：App Server
• Codex App Server README
• GitHub：openai/codex
• Codex Manual：MCP Server

外部解析与延伸阅读

• Martin Fowler：Harness engineering for coding agent users
• LangChain：The Anatomy of an Agent Harness
• LangChain：Improving Deep Agents with harness engineering
• Anthropic：Effective harnesses for long-running agents
• Anthropic：Harness design for long-running application development
• Claude：A harness for every task