OpenClaw Harness抽象完整详解

Sirius Wu

189人浏览 · 2026-07-16 11:23:58

Sirius Wu · 2026-07-16 11:23:58 发布

一、核心定义与两层概念区分

在 OpenClaw / UpClaw 体系内，Harness 存在两个层面定义，必须区分清楚：

广义：Harness Engineering（驾驭层工程，架构思想）
Harness 是包裹大模型的完整受控运行外骨骼。LLM 仅负责认知、思考；Harness 承载所有工程约束、状态管理、安全边界、执行循环、观测、资源管控。
通俗类比：

LLM = 大脑；Harness = 神经系统+骨骼+免疫系统+执行操作系统。
Prompt Engineering：教会模型怎么理解指令；
Context Engineering：控制模型“看见什么信息”；
Harness Engineering：搭建一套可靠、可控、可观测的运行环境，约束模型能干什么、如何执行、如何兜底。
狭义代码层：Agent Harness（运行时抽象接口，技术契约）
AgentHarness 是标准化底层执行器接口，负责驱动单轮Agent Turn（一轮推理循环）。
- 普通标准LLM接口（HTTP/WebSocket）使用 Model Provider 插件；
- 拥有原生独立会话循环、内置上下文管理、自有ReAct机制的专属模型/智能体（Codex、Claude-CLI、自研本地编码Agent服务），实现自定义 AgentHarness；
边界铁则：不要为普通REST LLM API开发Harness，应当实现Provider；只有具备独立原生Runtime的智能体才需要Harness插件。

Harness 核心设计哲学

策略在上，执行在下：Gateway、全局安全规则、会话策略、权限、观测由OpenClaw内核统一管控；Harness只负责“执行本轮Agent循环”，不能擅自修改顶层安全策略；
内外边界清晰：OpenClaw内核准备好完整RuntimePlan（工具策略、上下文预算、沙箱策略、权限快照），再交付Harness执行；
可插拔、可替换：同一套上层网关、渠道、技能、安全体系，可以无缝切换内置OpenClaw Harness / Codex Harness / 第三方自定义Harness；
状态双向受控：会话转录、记忆、工作区所有权归OpenClaw内核，Harness仅持有只读/受控操作句柄，禁止绕过内核直接篡改会话持久态。

二、Harness整体分层架构（三层标准抽象）

OpenClaw完整链路分层自上而下：

渠道层（Channel Adapter）
        ↓
Gateway 网关控制平面（消息路由、会话管理、Per-Request上下文、SessionLock、事件总线Hook）
        ↓
【内核准备阶段】构建RuntimePlan、加载六层提示词、权限校验、工具策略、预算约束
        ↓
Agent Harness（本轮Turn执行运行时）
        ↓
模型Provider / 原生智能体后端

Harness内部自身又划分为三层抽象边界：

Layer1：契约层（Harness Interface 标准接口）

所有Harness必须实现统一契约，内核调用不受底层模型实现影响：

interface AgentHarness {
  // 启动一轮Agent执行循环
  runTurn(attempt: PreparedAttempt): Promise<TurnResult>;
  // 中断正在执行的Turn（超时、用户取消）
  abortTurn(turnId: string): void;
  // 获取运行时能力声明：是否支持流式、原生思考、内置工具循环、内置上下文压缩
  getCapabilities(): HarnessCapability;
}

入参 PreparedAttempt（内核预先组装好的执行包）包含：

标准化会话转录 transcript
RuntimePlan：全局统一策略包（工具白名单、推理预算、最大工具轮次、沙箱策略、观测标签）
任务指令、子任务上下文快照
流式回调句柄、观测Span句柄

Layer2：适配层（Harness Adapter）

负责打通 OpenClaw 标准抽象与底层模型私有协议：

将标准化transcript、六层Prompt组装结构翻译成模型原生消息格式；
监听模型原生事件（原生thinking事件、原生tool_call、原生tool_result流）；
将底层模型私有事件统一转换为OpenClaw标准生命周期事件，向外触发全局Hook；
协调资源：上下文视图、工具调用转发、结果回流；

典型实现：

builtin-openclaw-harness：默认内置标准ReAct循环实现；
codex-harness：适配OpenAI Codex原生编码智能体运行时；
claude-cli-harness：对接Anthropic官方本地CLI智能体；

Layer3：原生执行层（Native Runtime）

模型/智能体自身的内部循环：原生思考管理、内置工具解析、自研上下文管理。

关键隔离约束：
如果底层Runtime自带Context Compaction、工具循环，必须服从上层RuntimePlan预算约束，不能无视全局配置自行无限扩张上下文、无限调用工具。

三、Harness 完整生命周期（一轮Turn标准时序）

1. 渠道消息抵达Gateway，创建Per-Request上下文
2. Gateway抢占SessionLock（同一会话串行保护）
3. 内核执行前置全量准备：
   a. 加载三层配置分层视图（global/agent/tenant）
   b. 组装六层提示词体系
   c. ContextEngine执行前置预裁剪（Stage1压缩）
   d. 构建RuntimePlan：合并安全规则、工具策略、推理预算、沙箱策略
   e. 创建顶层Trace、初始化ContextEngineSpan
4. 内核根据agentRuntime.id路由，选择匹配的AgentHarness
5. 构造 PreparedAttempt 执行包，交付 harness.runTurn()
===== Harness内部执行阶段 =====
6. Harness Adapter：标准化消息 → 模型私有格式
7. 发起推理/原生Agent循环；
   - 支持流式分片，持续回调on_stream_chunk（Observability Per-Request Hook自动透传快照上下文）
8. 解析模型输出：识别思考内容、工具调用指令
9. Harness将工具调用请求**回传给OpenClaw内核统一分发执行**
    ⚠️【重要安全边界】Harness**禁止直接调用工具**，所有工具请求必须上交内核，由三层Tool治理、沙箱双层防护统一校验执行。
10. 工具执行结果回流Harness，继续下一轮内部ReAct循环（受RuntimePlan最大轮次限制）
11. 任务收敛，生成最终回答
===== 返回内核阶段 =====
12. TurnResult标准化封装返回Gateway
13. Gateway推送回复至对应Channel
14. 触发after_agent_turn全局Hook：
    异步记忆写入、上下文视图更新、Langfuse Span关闭
15. 释放SessionLock，允许下一条会话消息执行

一条核心安全红线

Harness只拥有执行权，不拥有策略制定权。
工具黑白名单、最大工具调用次数、上下文token上限、是否允许子代理、沙箱权限全部由内核RuntimePlan锁定；Harness不能绕过规则直接发起工具、突破预算。

四、Harness 与全体系模块联动（UpClaw整套能力交汇点）

1. 联动六层提示词工程

内核在交付Harness之前完成六层MD拼装；Harness接收组装完成的完整System上下文；
自定义Harness可以选择是否分层透传提示边界标签，用于原生Runtime区分规则层/技能层/动态上下文层。

2. 联动 Context Compaction（4阶段压缩+反抖动+CJK）

两种模式兼容：

内核托管压缩（默认）：所有压缩由OpenClaw ContextEngine执行，传递干净视图给Harness；适合绝大多数通用LLM；
Harness原生压缩（特殊智能体）：Codex等自带上下文管理的Harness，内核仅传递预算上限，压缩交由原生Runtime，但必须遵守softTrimRatio/hardClearRatio阈值约束。

3. 联动深度推理自适应

内核onReasoningStart完成复杂度打分，计算thinking预算，写入RuntimePlan；
Harness读取预算，透传给底层模型原生思考参数；
Harness执行结束，把实际思考token消耗回传给内核，用于自适应闭环校准。

4. 联动三层Tool治理 + 代码沙箱双层防护

Harness解析出tool_call后，不直接执行，向上转发至ToolAdapter插槽；
依次经过：rules静态拦截 → 沙箱正则Preamble权限管控 → 资源限额；
执行完成tool_result原路回流Harness。

杜绝风险：即使模型Harness存在漏洞，也无法绕过全局工具安全防线。

5. 联动 SubAgent 三层安全约束（黑白名单/防递归/防污染）

当Harness解析出spawn_subagent委派指令：

请求上交内核；
内核执行递归深度检测、子代理权限收缩、创建独立子Session、独立子RequestContext；
子代理拥有独立Harness执行环境；
仅结构化摘要回流父会话，遵循防污染隔离规则。

6. 联动并发安全（Per-Request + SessionLock + CronContextHolder）

用户对话流量：Harness绑定Per-Request上下文；
Cron定时心跳任务触发的Agent循环：Harness绑定CronContextHolder；
所有Harness内部产生的观测事件，自动复用当前活跃上下文载体，配合Observability Per-Request Hook，杜绝Trace串扰。

7. 联动四层Langfuse观测体系

Harness内部所有事件（推理启动、流式分片、工具请求、原生思考事件）通过Per-Request Hook生成子Span：
GenerationSpan、ToolRunSpan全部挂载在顶层Trace下；
自定义Harness必须透传链路标识，保证父子链路完整。

8. 联动三层配置分层 + ${VAR:default}

Harness自身参数（是否启用原生思考、是否接管上下文、最大内部循环轮次）通过agentRuntime.id绑定配置，遵循三层配置优先级：
内置默认 < global.yaml < agent.yaml < tenant.yaml < env变量。
同时支持ConditionalOnProperty条件开关动态启用/禁用特定Harness实现。

五、两种运行模式：内置标准Harness vs 第三方自定义Harness

模式A：builtin-openclaw-harness（默认标准）

适用场景：GPT-4o、Claude通用API、Ollama通用开源模型
特征：

ReAct循环完全在内核侧实现；
Context Compaction、提示词组装、工具调度全部由OpenClaw内核管控；
模型仅负责生成文本/结构化工具调用；
迁移成本最低，安全策略统一，企业生产首选。

模式B：自定义插件Harness（codex-harness / claude-cli-harness）

适用场景：自带独立会话管理、原生工具循环、内置上下文管理的专用智能体
约束清单（生产强制）：

不能绕过RuntimePlan突破全局安全预算；
所有工具调用请求必须回传给OpenClaw内核校验执行；
会话持久态（transcript、memory）所有权属于OpenClaw，Harness仅持有只读快照；
流式事件、生命周期事件必须转换为标准Hook事件，保证观测链路完整；
子代理委派指令上交内核，不允许Harness私自创建子会话。

六、Harness常见误区澄清

❌ 误区1：Harness = LLM模型适配器
✅ 纠正：普通模型API适配器是Provider；Harness是完整Agent Turn运行时，包含推理+工具循环调度；只有具备独立Agent循环的智能体才需要Harness。

❌ 误区2：自定义Harness可以自行执行工具调用
✅ 纠正：所有工具调用必须上交内核统一校验；一旦允许Harness直调工具，三层Tool治理、沙箱安全防线会出现逃逸缺口。

❌ 误区3：Harness可以自主修改会话历史、绕过上下文压缩策略
✅ 纠正：会话原始转录由内核管理；Harness只能操作本轮交付的只读视图；如需修改上下文，必须调用内核ContextEngine标准接口。

❌ 误区4：Harness和Channel Adapter是同一层级
✅ 纠正：Channel Adapter是外部接入层（南北向，对接IM/Web客户端）；Harness是Agent执行层（东西向，对接模型智能体）；Gateway位于两者中间。

七、Harness抽象优缺点

优势

模型层彻底解耦
上层网关、渠道、安全、观测、技能体系完全不用关心底层是通用LLM还是Codex这类原生智能体；切换Harness无需改造业务层代码。
安全策略全局统一收敛
无论使用哪种底层智能体，工具权限、子代理约束、Token预算、沙箱防护全部在内核统一校验，不会出现不同模型运行时安全标准不一致。
观测、并发模型一套标准
所有Harness输出统一标准化生命周期事件，Per-Request Hook、四层Langfuse追踪无需针对每种智能体单独开发埋点。
渐进式兼容
通用LLM使用标准内置Harness；专用智能体开发自定义Harness，两套模式无缝共存于同一网关实例。