OpenClaw Harness回退（Harness Fallback）完整详解

一、核心定义与两大回退维度区分基础前置Harness分为两类专用外部Harnesscodex-harness、claude-cli-harness依赖独立外部服务/CLI进程存在离线、崩溃、鉴权失败风险内置标准Harnessbuiltin-openclaw-harnessruntimepi/openclaw内核原生实现无外部依赖作为全局兜底。Harness回退 两层独立降级体系不可混淆Harness插件自身回退插件内fallback强制指定agentRuntime: codex时codex-harness插件不可用是否自动切内置pi-harness由embeddedHarness.fallback控制。模型候选链驱动的Harness重选全局模型故障转移主模型绑定codex-harness调用失败自动切换fallback备用模型备用模型重新执行一次完整Harness选择流程自动匹配对应运行时。设计目标外部专用Harness服务宕机、鉴权失效、超时崩溃时业务不中断区分「插件级故障降级」与「模型链路级故障转移」两套机制独立可控兼顾强隔离场景仅允许codex、失败直接报错与通用容灾场景自动切内置内核循环回退全程遵循内核统一安全策略、观测链路、并发约束不会绕过三层Tool治理、沙箱防护。关键边界红线Harness回退不能绕过RuntimePlan全局策略降级后上下文预算、工具黑白名单、子代理限制、沙箱规则保持统一自定义外部Harness失败回退至内置harness后ReAct循环完全由网关内核接管不再依赖外部进程modelSelectionLocked: true锁定会话运行时时插件级fallback仍可触发但不会自动切换模型候选链。二、第一维度Harness插件内置回退embeddedHarness.fallback1. 配置入口与三档模式配置路径providers.models[].embeddedHarness.fallback仅对显式绑定runtime的模型生效agentRuntime: codex。三枚举取值pi生产默认推荐外部Harness故障 → 自动回退内置builtin-openclaw-harnessnone严格模式无回退外部Harness不可用直接抛出运行异常会话失败self仅内部重试外部Harness重试耗尽仍失败则报错不切内置。providers:openai:models:-id:codex-v1agentRuntime:codexembeddedHarness:fallback:pi# 故障自动切内置harnessretryCount:2# 外部harness重试次数2. 触发外部Harness故障的判定标准满足任意即触发回退插件未启用claw.plugin.codex.enablefalse网关启动未加载该Harness外部服务连接失败端口不可达、TCP连接超时、进程崩溃鉴权永久失败API密钥失效、许可过期、计费额度耗尽执行运行时致命错误进程OOM、CLI异常退出、内部死循环卡死、abortTurn中断超过最大重试次数仍无法正常执行runTurn。3. 完整插件回退执行时序单模型、锁定runtime场景1. Harness Selector根据model配置选中codex-harness 2. 实例化codex harness发起外部进程/服务连接 3. 连接/初始化失败进入重试逻辑retryCount次 a. 重试全部失败 b. 读取embeddedHarness.fallback配置 4. 分支1fallbackpi - 销毁失效codex harness实例 - 动态切换为内置builtin-openclaw-harness - 使用同一套RuntimePlan、六层提示词、会话上下文继续执行本轮Turn - Langfuse标记标签 harness_fallbacktrue, original_runtimecodex 5. 分支2fallbacknone - 终止本轮请求抛出HarnessUnavailableError返回用户系统繁忙 6. 分支3fallbackself - 重试耗尽无降级直接抛出异常4. 锁定会话(modelSelectionLocked)下的特殊行为会话runtime锁定仅控制下一轮模型路由不重新选择runtime本轮执行中外部Harness崩溃fallbackpi依然可以临时切内置harness完成当前轮次本轮执行完毕释放后下一轮仍会优先尝试原锁定runtimecodex不会永久切换内置。三、第二维度模型候选链驱动Harness重选全局Fallback模型故障转移1. 基础逻辑主模型绑定外部Harnesscodex执行失败触发全局模型fallback候选链切换到备用模型后重新完整走一遍Harness Selector选择流程备用模型可绑定内置pi-harness实现跨运行时自动降级。配置入口agents.defaults.model.fallbacks会话/租户独立fallback列表。2. 触发模型级故障转移的错误类型外部Harness返回5xx、429限流、服务过载长超时、连续工具执行失败、上下文超限无法恢复永久鉴权/计费失败主模型无法恢复。3. 跨Harness降级完整链路示例# 配置示例agents:defaults:model:primary:openai/codex-v1# 主模型 runtimecodexfallbacks:[openai/gpt-4o]# 备用模型 runtimeauto→pi内置providers:openai:models:-id:codex-v1agentRuntime:codexembeddedHarness.fallback:pi-id:gpt-4oagentRuntime:auto# 自动选中内置harness执行流程主模型codex-v1选中codex-harness外部服务宕机先执行插件内部fallback逻辑尝试切内置pi场景A插件回退成功 → 本轮直接用内置harness完成不切换模型场景B插件回退仍失败极少→ 进入全局模型fallback链切换备用模型gpt-4o重新执行Harness选择auto模式无专用外部Harness匹配自动使用builtin-openclaw-harness完整复用同一会话上下文、SessionLock、安全约束继续执行Langfuse同时标记model_fallbacktrue, harness_fallbacktrue双降级标签。4. 会话持久化模型覆盖触发模型候选链切换后会话写入临时覆盖标记modelOverrideSource:auto本轮及后续轮次优先使用备用模型冷却期后主模型恢复可自动切回主运行时。四、两种回退机制优先级与覆盖规则插件内置fallbackembeddedHarness优先执行同一模型内部外部Harness故障优先尝试切内置pi不立即切换模型减少模型切换带来的上下文差异。插件回退失效/配置fallbacknone时才推进全局模型fallback候选链两层回退独立开关可组合配置组合1标准容灾fallbackpi 配置全局fallback模型双层兜底组合2强管控研发场景fallbacknone 无fallback模型codex不可用直接报错组合3轻量化兜底fallbackpi 无备用模型仅插件内降级。五、回退后统一约束与隔离规则安全不可突破1. 上下文与提示词一致性回退前后使用完全相同的六层提示词、ContextEngine上下文视图外部codex-harness自有压缩逻辑失效后切换为内核四阶段Context CompactionCJK优化、反抖动、深度推理自适应参数完全继承RuntimePlan配置不会丢失策略。2. 安全体系统一生效三层Tool治理、正则/Preamble代码沙箱双层防护、子代理黑白名单/防递归/防污染完全不变回退至内置harness后所有tool_call强制上交内核校验不存在外部Harness直调工具的逃逸风险Cron定时任务触发的Harness回退仍使用CronContextHolder隔离上下文不污染前台会话。3. 并发安全不破坏SessionLock会话串行锁持续持有回退过程不释放锁不会出现同会话并发消息乱序Per-Request上下文全程透传观测链路不丢失traceId、tenantId子代理独立Harness回退不影响父会话运行时。4. 观测埋点完整区分四层Langfuse自动增加专属标签用于成本、故障统计harness_fallback: true/false是否触发插件级Harness降级original_harness_runtime故障前原运行时IDcodexmodel_fallback: true/false是否切换备用模型fallback_reason故障原因connect_fail/auth_timeout/plugin_disabled。六、回退配套兜底控制能力1. 重试冷却与会话级跳过缓存环境变量控制失效Harness短期跳过避免频繁重试无效服务OPENCLAW_FALLBACK_SKIP_TTL_MS60000外部Harness鉴权失败后同一会话60秒内不再重试该runtime直接走回退逻辑主模型永远不缓存跳过标记保证定时探测恢复。2. 全局总熔断开关通过ConditionalOnPluginEnable一键禁用外部Harness插件所有绑定该runtime的模型自动触发fallbackpiclaw.plugin.codex.enable:false3. 回退告警策略Observer观测插件监控两类指标并触发告警harness_fallback_count单位时间Harness插件降级次数突增代表codex服务不稳定harness_permanent_fail连续多轮无回退直接失败代表生产容灾失效。七、典型配置模板三种生产场景场景1研发网关双层容灾推荐codex不可用先切内置harness仍失败切换通用GPT4o备用模型providers:openai:models:-id:codex-v1name:Codex代码智能体agentRuntime:codexmodelSelectionLocked:trueembeddedHarness:fallback:piretryCount:2agents:defaults:model:primary:openai/codex-v1fallbacks:[openai/gpt-4o]场景2严格生产研发环境仅允许codex无降级codex服务离线直接报错禁止切通用模型防止代码能力不足引发业务风险models:-id:codex-v1agentRuntime:codexembeddedHarness:fallback:noneagents.defaults.model.fallbacks:[]# 无备用模型场景3混合网关客服通用模型无外部Harness无需回退models:-id:gpt-4o-customeragentRuntime:auto# 自动匹配内置pi-harness无外部组件不存在回退需求八、常见误区澄清❌ 误区1设置全局fallback模型等同于Harness插件回退✅ 纠正全局模型切换是第二层兜底插件fallback是同一模型内部运行时降级优先级更高、开销更小。❌ 误区2回退至内置harness会丢失原有codex会话状态✅ 纠正会话transcript、记忆、上下文所有权属于OpenClaw内核Harness仅为执行载体切换不改变会话持久数据。❌ 误区3modelSelectionLocked锁定runtime后无法触发回退✅ 纠正锁定仅控制下一轮路由选择本轮执行外部Harness崩溃依然可以临时降级内置完成当前请求。❌ 误区4fallbackpi会永久切换运行时✅ 纠正仅本轮临时降级下一轮消息进入会重新尝试原codex runtime服务恢复后自动切回。九、优缺点总结优势双层兜底容灾外部专用智能体服务宕机不中断业务兼顾研发专用能力与通用高可用回退后安全、并发、观测体系完全统一不会出现降级后权限逃逸、链路丢失问题可精细化管控严格模式无降级/轻量插件内降级/完整模型切换三层策略按需选择故障分层可观测能区分是外部codex服务故障还是主模型链路故障便于运维定位。短板两层回退叠加会轻微增加本轮执行延迟重试重新初始化内置Harnesscodex与内置harness能力存在细微差异极端复杂代码任务降级后输出质量下降可通过告警监控高频回退及时修复外部服务配置项较多需区分embeddedHarness.fallback与全局model.fallbacks易混淆。十、排障诊断手段查看当前Harness配置claw harness list --detail查看各runtime fallback模式模拟模型路由回退链路claw route test openai/codex-v1打印预期降级逻辑查看回退事件日志开启日志级别claw.log.level.harnessdebug打印重试、切换、失败原因Langfuse筛选标签harness_fallback:true统计降级频次与故障时段紧急关停外部Harness插件修改yamlclaw.plugin.codex.enablefalse所有codex模型自动切内置pi。