Why Harness

Harness 指的是把语言模型接入真实环境、并使其能够持续完成任务的外层执行系统。这个概念在 AI Coding 语境下变得显性，原因是用户开始稳定地感知到：同样是 coding agent，Codex、Claude Code、OpenClaw 在可用性、可控性、恢复能力和长期任务稳定性上的差异，无法仅用底层模型差异解释。

这个词已经进入官方表述，但直接用 harness 进行定义的一手材料并不多。OpenAI 在 2026 年 1 月 23 日发布的 Unrolling the Codex agent loop 中，将 Codex 的外层逻辑描述为 agent 或 “harness”；Anthropic 在 How Claude Code works 中将 Claude Code 定义为 around Claude 的 agentic harness。OpenClaw 没有一篇完全对应的 “what is harness” 说明文，因此后文对 OpenClaw 的讨论主要依赖其 runtime、architecture、approvals 和 session 文档作为分层证据。

AI Coding 最初常被理解为 “语言模型 + 工具调用”。这个表述能够覆盖最小工作流，但无法解释长时任务中的关键差异。真实的软件任务通常包含代码搜索、跨文件编辑、命令执行、测试验证、失败恢复、权限确认和人工接管。这些步骤会在多轮循环中持续发生，并伴随可见的副作用。单次工具调用不能刻画这种过程。

Harness 这个概念用来描述模型之外的那套系统责任。它不负责模型参数本身，也不等同于 prompt 模板；它负责把用户任务组织成一个持续运行的 agent loop，并管理循环中的状态转移、工具协议、上下文预算、执行边界、验证策略和恢复机制。只要 agent 能在环境中读写文件、运行命令或与外部系统交互，这一层就会从实现细节上升为核心能力。

AI Coding 场景使这一层更早暴露出来。代码仓库是高状态密度环境，shell 命令具有真实副作用，测试和构建系统会不断返回新观察，用户还会要求 agent 在必要时暂停、回滚或继续推进。这些要求共同构成了一个系统问题。Harness 正是这个系统问题的名称。

2026 年围绕这个概念的讨论已经开始分化出几条稳定路线。The Harness Is the Product 这一类文章强调，用户体验的主导因素越来越是工具调用、UX 和 agentic orchestration 的组合，而不是模型名称本身。Harness Engineering Is the Primary Lever for Agent Reliability in 2025–2026 这一类文章则将 harness 表述为可靠性的主要杠杆，重点放在 execution control、verification、retry、termination rules 和 observability。还有一类更进一步的讨论，例如 The Intent Harness，开始把 harness 往上拆出一个更靠近需求澄清和规格形成的层。这几条路线的共同点，是都把关注点从“模型会不会答”转向“系统能不能稳定工作”。

What Harness Really Means in Agent Systems

Harness 是位于用户任务、语言模型与执行环境之间的控制层。它负责把自然语言目标转成一个可持续推进的任务过程，并在过程中维持以下对象：

  1. 当前任务状态；
  2. 可调用工具集合；
  3. 上下文窗口中的工作记忆；
  4. 执行权限与安全边界；
  5. 验证结果与恢复点；
  6. 人类介入的切换点。

这个定义包含两层边界。

第一层边界是对象边界。Harness 包含 agent loop、工具运行时、上下文管理、审批与沙箱、补丁落地、验证与回滚。Harness 不包含底层模型权重本身，也不包含单独某个工具的业务逻辑实现。

第二层边界是时间边界。Harness 处理的是持续过程，而不是单个响应。只要系统需要在多个观察和动作之间保持连贯状态，Harness 就开始发挥作用。

From Model to Agent: The Layers Inside a Harness

Computation Path

AI Coding 中一个典型的 harness 计算路径可以写成：

user task -> context gathering -> model inference -> tool selection -> bounded execution -> new observation -> verification -> patch/retry/escalation

在这条路径里，模型负责局部推理，harness 负责过程编排。用户任务先被放入当前会话状态，随后系统读取必要上下文，并把可用工具、历史消息、规则文件和环境约束一起提供给模型。模型产出下一步动作意图后，harness 检查该动作是否落在允许边界内。允许的动作被执行，并产生新的命令输出、文件差异、测试结果或网络响应。新的观察再回流到上下文中，驱动下一轮决策。只有当验证通过、任务结束或用户中断时，这个循环才停止。

agent harness overview
图1: Harness 连接用户任务、模型推理与真实执行环境，并在动作之间维持状态、边界与验证循环。

这个计算路径表明，harness 的核心职责是把模型置于一个带约束的闭环之中。闭环是否稳定，决定了 agent 更接近一次性代码生成器，还是更接近能够持续推进任务的工程执行体。

Task Loop

Task loop 负责定义 agent 的最小循环单位。Anthropic 在 Claude Code 文档 中将其写成 gather context -> take action -> verify results。OpenAI 在 Codex agent loop 一文中则把重点放在 orchestrating the interaction between user, model, and tools。两者描述不同，但对象一致：系统必须在观察、动作和验证之间反复切换，并把前一轮结果作为下一轮输入。

这层决定 agent 是否具备长链条任务能力。没有 loop，工具调用只会以零散插件形式出现；有了 loop，系统才会对 “先看什么、后做什么、做完如何检查” 形成稳定策略。

Tool Runtime

Tool runtime 负责定义模型能够调用哪些动作，以及这些动作如何返回结构化观察。工具集合通常至少包括文件读写、内容搜索、shell 执行、网络检索、补丁应用和版本控制接口。Anthropic 的文档把这些能力分成 file operations、search、execution、web、code intelligence 等类别。Codex 文档和开源仓库则将 shell、apply patch、rules、skills、subagents 等能力组织成统一产品面。

这层处理的是“如何把动作空间变成可持续编排的运行时”。一旦命令输出很长、文件修改很多、工具失败模式不一致，运行时就必须处理结果截断、错误格式、重试、超时和后续动作依赖。

Context Management

Context management 负责维持工作记忆。AI Coding 任务会快速产生大量中间状态，例如代码片段、测试输出、文件 diff、规则文件、环境变量和历史决策。缺少上下文管理时，系统会出现早期指令丢失、历史观察淹没关键状态、工具输出挤占上下文窗口等问题。

Claude Code 的文档把 compaction、skills、subagents 直接作为上下文管理机制来讲。它会在接近上下文上限时清理旧工具输出，并在必要时总结历史。OpenClaw 将这一层显式拆为 session management、compaction 与 session pruning。其中 compaction 会在接近窗口上限时总结并持久化会话，session pruning 会在每次请求前修剪旧工具结果。这些机制共同把上下文从“聊天记录”转变成“可维护的工作内存”。

Execution Boundary

Execution boundary 负责定义 agent 可以在多大范围内自主行动。这个边界通常由沙箱、审批策略、网络权限和可写目录共同构成。

Codex 的 Sandboxing 文档将 sandbox 与 approvals 分开表述：前者定义技术边界，后者定义什么时候需要人工确认。文档中给出了 read-only、workspace-write、danger-full-access 等模式，以及 untrusted、on-request、never 等审批策略。Claude Code 的 文档 也把 permissions 和 checkpoints 作为并列安全机制。OpenClaw 则提供独立的 approvals 体系，可分别针对 local、gateway 或 node 主机管理执行许可。

这层的目标是把信任关系从隐式习惯转成可配置系统。边界一旦清楚，agent 的自治程度才具有可解释性。

Patch, Checkpoint, and Rollback

Patch、checkpoint 与 rollback 负责把修改变成可恢复状态。AI Coding 系统需要在执行编辑之前保留恢复点，并在失败或用户撤销时回到稳定状态。Claude Code 文档将 checkpoints 描述为 undo file changes 的本地机制。Codex 的文档则把补丁应用、权限控制和沙箱联动放入同一套配置与操作流中。

恢复能力直接影响 agent 的实用性。软件任务中的错误不可避免，harness 的职责是缩小错误半径，并提供明确的撤销路径。

Verification

Verification 负责把模型输出放回真实约束中检查。验证形式包括运行测试、执行构建、检查类型错误、对比命令输出、重新读取被修改文件，或者根据明确的验收条件进行二次判断。Anthropic 将 verify 作为 agent loop 的固定环节。OpenAI 在 Codex 官方材料中也将运行命令、执行测试和持续推进任务作为 coding agent 的主要能力描述。

验证层将 agent 的目标推进到“生成可被环境证实的变更”。

Human Control

Human control 负责保留人工介入点。中断、确认、切换权限模式、恢复历史状态、调整规则文件、重新指定目标范围，都属于这一层。Claude Code 的文档明确把用户写入 agent loop，用户可以 interrupt and steer。Codex 的权限模式和 rules 也把人工接管设计成常态操作，而不是异常处理。OpenClaw 通过更显式的 gateway、session、approval 结构，让人工接管可以发生在系统配置层而不只是聊天界面。

agent harness layers
图2: Agent harness 的主要层次。模型推理位于中间，持续任务能力来自外层 loop、runtime、context、boundary、verification 与 recovery 机制。

Why Harness Matters More Than It First Appears

Harness 影响的对象并不只是“工具能不能接上”。只要任务持续时间拉长，系统就会暴露出几个更基础的问题：上下文如何保真，动作如何落边界，失败之后如何恢复，用户如何在中途接管。AI Coding 场景中的“靠谱不靠谱”，往往对应的就是这些系统问题是否被处理干净。

这一层的重要性可以从反面理解。缺少 loop 时，系统会退化成一次性响应器；缺少上下文管理时，系统会在长会话中丢失早期约束；缺少验证时，系统只能生成 diff 而无法证明变更有效；缺少恢复机制时，用户很难在出错后继续信任 agent。Harness 将这些问题统一收敛到一个执行系统中，因此它直接决定了 coding agent 的产品感和可放手程度。

这一点在近期工程文章中也有较一致的表述。Closing the Loop: Coding Agents, Telemetry, and the Path to Self-Improving Software 将 coding agents 视为能够自主写、测、调的 harnessed systems，并把 telemetry、闭环验证和 trace 视为继续提升的关键前提。Building a (Bad) Local AI Coding Agent Harness from Scratch 则用一个极小实现反向说明：即使只有最简陋的本地 agent，也必须同时具备 model access、agent loop、tool use 和 sandboxing，系统才开始像 harness。这两类文章分别从生产系统和最小原型两端，给出了同样的结论。

Codex, Claude Code, and OpenClaw Through the Harness Lens

这一节将 Codex、Claude Code 与 OpenClaw 作为代表性实现，用来检验前文给出的 harness 定义是否具有解释力。这里的证据分成两类：

  1. 直接定义 harness 或 agent loop 的材料；
  2. 对 task loop、runtime、approvals、sessions、compaction 等层进行展开的系统文档。

第二类材料并不直接定义 harness，但可以用来验证 harness 的内部层次是否真实存在，因此这里的结论属于系统归纳而非性能排行。

Codex

Codex 的公开材料集中呈现了一个以边界管理和产品化自治为中心的 harness。OpenAI 在 2026 年 1 月 23 日的 官方文章 中，将 agent loop 定义为 user、model、tools 之间的编排逻辑，并直接使用 harness 一词。Sandboxing 文档 进一步将 sandbox_mode、approval_policy、writable_roots 与 rules 做成明确配置，说明 Codex 把执行边界视为一等对象。Help Center 页面还补充了 cloud delegation、isolated sandbox、Codex app 中的 multiple agents、worktree support、skills 与 automations。

这些材料共同指向一种较稳定的系统取向：Codex 将自治能力、执行边界和恢复/隔离机制统一为产品面。前文定义中的 task loop、execution boundary、human control 与 patch/recovery 在 Codex 中都具有明确入口。

Claude Code

Claude Code 的官方文档几乎按 harness 分层来组织。How Claude Code works 先定义 agentic loop，再依次展开 tools、execution environments、sessions、context window、compaction、skills、subagents、checkpoints 与 permissions。文档明确将 Claude Code 描述为 around Claude 的 agentic harness。

从系统分层看，Claude Code 的核心特征是把持续交互过程暴露得更清楚。gather context -> take action -> verify results 定义了 loop；sessions、auto memory、skills 和 subagents 负责长期上下文；checkpoints 与 permission modes 负责恢复和边界；用户则被直接放入 loop 中作为可随时中断和改向的控制点。前文定义中的 task loop、context management、verification 与 human control 在 Claude Code 中具有较高可见度。

OpenClaw

OpenClaw 的资料更适合作为“可检查 harness”样本。其 Gateway Architecture 文档将 gateway 定义为长期运行的控制平面，并显式负责 channels、nodes、sessions 与 hooks。Agent Runtime 文档进一步给出 skills、sessions 与 steering while streaming 这类运行时行为。Session Management 文档将 gateway 设为 source of truth，同时定义会话键空间、maintenance、reset policy、session pruning 与 pre-compaction memory flush。Exec Approvals 与 Approvals 文档则把 exec approvals 做成可以分别作用于 local、gateway、node 主机的策略系统。Skills 与 Compaction 文档进一步把扩展能力和上下文压缩做成显式模块。

这些资料说明，OpenClaw 将 harness 的许多内部部件直接公开成架构对象。前文定义中的 tool runtime、context management、execution boundary 与 human control 在 OpenClaw 中并未被收拢成单一产品表面，而是以平台组件形式对外暴露。

harness comparison across products
图3: 三个代表性实现强调的 harness 重点不同。Codex 更集中于 bounded execution surface，Claude Code 更集中于 interactive loop，OpenClaw 更集中于 explicit runtime structure。

三个样本放在一起后，harness 的解释力会变得更清楚。Codex 将外层系统尽量收敛成清晰的产品能力；Claude Code 将持续交互循环放到前台；OpenClaw 将大量运行时部件作为开放结构暴露出来。三者都实现了 loop、context、boundary、verification 和 recovery，只是实现方式和暴露方式不同。

What Makes a Good Harness

一个好的 harness 至少需要满足四个条件。

第一，状态必须可见。用户需要知道 agent 当前在读什么、做什么、为什么暂停。

第二，边界必须可控。沙箱、审批、可写目录、网络权限不能依赖隐式猜测，而需要有清晰规则。

第三，恢复必须低成本。checkpoint、rollback、session fork 或等价机制是长期任务可用性的基础。

第四，验证必须进入主循环。测试、构建、差异检查和验收条件需要成为默认步骤，而不是额外补丁。

Closing Thoughts

Harness 这个词之所以在 AI Coding 里变得重要，原因在于它为一个长期存在但没有被清楚命名的问题提供了统一对象。用户真正感知到的可用性、可控性和恢复能力，大多来自模型外面的那套执行系统。对 coding agent 的理解，如果只停留在“它用了什么模型”，很难解释真实产品之间的差异。把观察点转向 harness 之后，很多体验差异会变得可分解、可比较，也更容易继续追问。

References

[1] OpenAI, Unrolling the Codex agent loop, January 23, 2026.
[2] Anthropic, How Claude Code works, accessed March 24, 2026.
[3] OpenAI Developers, Sandboxing, accessed March 24, 2026.
[4] OpenAI Help Center, Using Codex with your ChatGPT plan, updated March 24, 2026.
[5] OpenClaw Docs, Gateway Architecture, accessed March 24, 2026.
[6] OpenClaw Docs, Agent Runtime, accessed March 24, 2026.
[7] OpenClaw Docs, Session Management, accessed March 24, 2026.
[8] OpenClaw Docs, Exec Approvals, accessed March 24, 2026.
[9] OpenClaw Docs, Approvals, accessed March 24, 2026.
[10] OpenClaw Docs, Compaction, accessed March 24, 2026.
[11] OpenClaw Docs, Skills, accessed March 24, 2026. [12] Hari Krishnan, The Intent Harness, February 23, 2026.
[13] Max, Harness Engineering Is the Primary Lever for Agent Reliability in 2025–2026, February 18, 2026.
[14] Gareth Brown, Building a (Bad) Local AI Coding Agent Harness from Scratch, February 22, 2026.
[15] Dave Beckett, The Harness Is The Product, March 6, 2026.
[16] Arize, Closing the Loop: Coding Agents, Telemetry, and the Path to Self-Improving Software, February 17, 2026.