一、核心定义与两层概念区分在 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必须实现统一契约内核调用不受底层模型实现影响interfaceAgentHarness{// 启动一轮Agent执行循环runTurn(attempt:PreparedAttempt):PromiseTurnResult;// 中断正在执行的Turn超时、用户取消abortTurn(turnId:string):void;// 获取运行时能力声明是否支持流式、原生思考、内置工具循环、内置上下文压缩getCapabilities():HarnessCapability;}入参PreparedAttempt内核预先组装好的执行包包含标准化会话转录 transcriptRuntimePlan全局统一策略包工具白名单、推理预算、最大工具轮次、沙箱策略、观测标签任务指令、子任务上下文快照流式回调句柄、观测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_chunkObservability 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 Compaction4阶段压缩反抖动CJK两种模式兼容内核托管压缩默认所有压缩由OpenClaw ContextEngine执行传递干净视图给Harness适合绝大多数通用LLMHarness原生压缩特殊智能体Codex等自带上下文管理的Harness内核仅传递预算上限压缩交由原生Runtime但必须遵守softTrimRatio/hardClearRatio阈值约束。3. 联动 深度推理自适应内核onReasoningStart完成复杂度打分计算thinking预算写入RuntimePlanHarness读取预算透传给底层模型原生思考参数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生成子SpanGenerationSpan、ToolRunSpan全部挂载在顶层Trace下自定义Harness必须透传链路标识保证父子链路完整。8. 联动 三层配置分层 ${VAR:default}Harness自身参数是否启用原生思考、是否接管上下文、最大内部循环轮次通过agentRuntime.id绑定配置遵循三层配置优先级内置默认 global.yaml agent.yaml tenant.yaml env变量。同时支持ConditionalOnProperty条件开关动态启用/禁用特定Harness实现。五、两种运行模式内置标准Harness vs 第三方自定义Harness模式Abuiltin-openclaw-harness默认标准适用场景GPT-4o、Claude通用API、Ollama通用开源模型特征ReAct循环完全在内核侧实现Context Compaction、提示词组装、工具调度全部由OpenClaw内核管控模型仅负责生成文本/结构化工具调用迁移成本最低安全策略统一企业生产首选。模式B自定义插件Harnesscodex-harness / claude-cli-harness适用场景自带独立会话管理、原生工具循环、内置上下文管理的专用智能体约束清单生产强制不能绕过RuntimePlan突破全局安全预算所有工具调用请求必须回传给OpenClaw内核校验执行会话持久态transcript、memory所有权属于OpenClawHarness仅持有只读快照流式事件、生命周期事件必须转换为标准Hook事件保证观测链路完整子代理委派指令上交内核不允许Harness私自创建子会话。六、Harness常见误区澄清❌ 误区1Harness LLM模型适配器✅ 纠正普通模型API适配器是ProviderHarness是完整Agent Turn运行时包含推理工具循环调度只有具备独立Agent循环的智能体才需要Harness。❌ 误区2自定义Harness可以自行执行工具调用✅ 纠正所有工具调用必须上交内核统一校验一旦允许Harness直调工具三层Tool治理、沙箱安全防线会出现逃逸缺口。❌ 误区3Harness可以自主修改会话历史、绕过上下文压缩策略✅ 纠正会话原始转录由内核管理Harness只能操作本轮交付的只读视图如需修改上下文必须调用内核ContextEngine标准接口。❌ 误区4Harness和Channel Adapter是同一层级✅ 纠正Channel Adapter是外部接入层南北向对接IM/Web客户端Harness是Agent执行层东西向对接模型智能体Gateway位于两者中间。七、Harness抽象优缺点优势模型层彻底解耦上层网关、渠道、安全、观测、技能体系完全不用关心底层是通用LLM还是Codex这类原生智能体切换Harness无需改造业务层代码。安全策略全局统一收敛无论使用哪种底层智能体工具权限、子代理约束、Token预算、沙箱防护全部在内核统一校验不会出现不同模型运行时安全标准不一致。观测、并发模型一套标准所有Harness输出统一标准化生命周期事件Per-Request Hook、四层Langfuse追踪无需针对每种智能体单独开发埋点。渐进式兼容通用LLM使用标准内置Harness专用智能体开发自定义Harness两套模式无缝共存于同一网关实例。短板额外一层适配转换开销自定义Harness需要适配消息格式双向转换原生智能体独有的高级特性专属事件、原生调试接口需要额外开发适配器映射边界契约复杂自定义Harness开发门槛高于普通Provider插件。八、横向对比原生AgentScope无标准化Harness抽象推理循环硬编码绑定模型无法无缝替换运行时缺少内核与执行层安全边界隔离。OpenAI Codex独立服务Codex自带内置Harness但不存在上层统一网关、全局安全策略层单独运行时缺少多租户管控、集中观测、统一沙箱防线。Claude Code本地单会话内置循环没有标准化Harness插件契约无法作为可插拔组件接入多租户网关架构。OpenClaw Harness抽象内核策略平面与Agent执行平面强制隔离的标准化插件契约兼顾通用大模型与原生专用智能体是支撑UpClaw多租户、多模型混合部署的核心底层抽象。九、典型落地场景场景1混合架构网关同一网关同时承载两类业务通用客服对话使用内置openclaw-harness对接Claude API代码研发任务启用codex-harness对接Codex原生智能体两套业务共享同一套ChannelWeb/飞书、统一rules安全基线、同一套Langfuse观测。场景2私有化本地开源模型使用标准内置Harness对接Ollama全部ReAct循环、上下文压缩、工具治理由OpenClaw内核管控无需开发自定义运行时。场景3自研垂直行业智能体自研智能体拥有原生规划循环、内置状态管理开发自定义AgentHarness插件遵循契约接入网关复用整套企业安全、并发、观测底座。