企业官网建设流程全解析

一、核心定义与两大回退维度区分

基础前置

Harness分为两类：

1. 专用外部Harness：codex-harness、claude-cli-harness，依赖独立外部服务/CLI进程，存在离线、崩溃、鉴权失败风险；
2. 内置标准Harness：builtin-openclaw-harness（runtime=pi/openclaw），内核原生实现，无外部依赖，作为全局兜底。

Harness回退 = 两层独立降级体系，不可混淆

1. Harness插件自身回退（插件内fallback）
   强制指定agentRuntime: codex时，codex-harness插件不可用，是否自动切内置pi-harness；由embeddedHarness.fallback控制。
2. 模型候选链驱动的Harness重选（全局模型故障转移）
   主模型（绑定codex-harness）调用失败，自动切换fallback备用模型，备用模型重新执行一次完整Harness选择流程，自动匹配对应运行时。

设计目标

1. 外部专用Harness服务宕机、鉴权失效、超时崩溃时，业务不中断；
2. 区分「插件级故障降级」与「模型链路级故障转移」，两套机制独立可控；
3. 兼顾强隔离场景（仅允许codex、失败直接报错）与通用容灾场景（自动切内置内核循环）；
4. 回退全程遵循内核统一安全策略、观测链路、并发约束，不会绕过三层Tool治理、沙箱防护。

关键边界红线

• Harness回退不能绕过RuntimePlan全局策略；降级后上下文预算、工具黑白名单、子代理限制、沙箱规则保持统一；
• 自定义外部Harness失败回退至内置harness后，ReAct循环完全由网关内核接管，不再依赖外部进程；
• modelSelectionLocked: true锁定会话运行时时，插件级fallback仍可触发，但不会自动切换模型候选链。

二、第一维度：Harness插件内置回退（embeddedHarness.fallback）

1. 配置入口与三档模式

配置路径：providers.models[].embeddedHarness.fallback，仅对显式绑定runtime的模型生效（agentRuntime: codex）。
三枚举取值：

1. pi（生产默认推荐）：外部Harness故障 → 自动回退内置builtin-openclaw-harness；
2. none（严格模式）：无回退，外部Harness不可用直接抛出运行异常，会话失败；
3. self：仅内部重试外部Harness，重试耗尽仍失败则报错，不切内置。

providers:openai:models:-id:codex-v1agentRuntime:codexembeddedHarness:fallback:pi# 故障自动切内置harnessretryCount:2# 外部harness重试次数

2. 触发外部Harness故障的判定标准（满足任意即触发回退）

1. 插件未启用：claw.plugin.codex.enable=false，网关启动未加载该Harness；
2. 外部服务连接失败：端口不可达、TCP连接超时、进程崩溃；
3. 鉴权永久失败：API密钥失效、许可过期、计费额度耗尽；
4. 执行运行时致命错误：进程OOM、CLI异常退出、内部死循环卡死、abortTurn中断；
5. 超过最大重试次数仍无法正常执行runTurn。

3. 完整插件回退执行时序（单模型、锁定runtime场景）

1. Harness Selector根据model配置选中codex-harness 2. 实例化codex harness，发起外部进程/服务连接 3. 连接/初始化失败，进入重试逻辑（retryCount次） a. 重试全部失败 b. 读取embeddedHarness.fallback配置 4. 分支1：fallback=pi - 销毁失效codex harness实例 - 动态切换为内置builtin-openclaw-harness - 使用同一套RuntimePlan、六层提示词、会话上下文继续执行本轮Turn - Langfuse标记标签 `harness_fallback=true, original_runtime=codex` 5. 分支2：fallback=none - 终止本轮请求，抛出HarnessUnavailableError，返回用户系统繁忙 6. 分支3：fallback=self - 重试耗尽无降级，直接抛出异常

4. 锁定会话(modelSelectionLocked)下的特殊行为

• 会话runtime锁定仅控制下一轮模型路由不重新选择runtime；
• 本轮执行中外部Harness崩溃，fallback=pi依然可以临时切内置harness完成当前轮次；
• 本轮执行完毕释放后，下一轮仍会优先尝试原锁定runtime（codex），不会永久切换内置。

三、第二维度：模型候选链驱动Harness重选（全局Fallback模型故障转移）

1. 基础逻辑

主模型绑定外部Harness（codex）执行失败，触发全局模型fallback候选链；切换到备用模型后，重新完整走一遍Harness Selector选择流程，备用模型可绑定内置pi-harness，实现跨运行时自动降级。
配置入口：agents.defaults.model.fallbacks会话/租户独立fallback列表。

2. 触发模型级故障转移的错误类型

• 外部Harness返回5xx、429限流、服务过载；
• 长超时、连续工具执行失败、上下文超限无法恢复；
• 永久鉴权/计费失败（主模型无法恢复）。

3. 跨Harness降级完整链路示例

# 配置示例agents:defaults:model:primary:openai/codex-v1# 主模型 runtime=codexfallbacks:["openai/gpt-4o"]# 备用模型 runtime=auto→pi内置providers:openai:models:-id:codex-v1agentRuntime:codexembeddedHarness.fallback:pi-id:gpt-4oagentRuntime:auto# 自动选中内置harness

执行流程：

1. 主模型codex-v1，选中codex-harness，外部服务宕机；
2. 先执行插件内部fallback逻辑，尝试切内置pi；
   场景A：插件回退成功 → 本轮直接用内置harness完成，不切换模型；
   场景B：插件回退仍失败（极少）→ 进入全局模型fallback链；
3. 切换备用模型gpt-4o，重新执行Harness选择；
4. auto模式无专用外部Harness匹配，自动使用builtin-openclaw-harness；
5. 完整复用同一会话上下文、SessionLock、安全约束继续执行；
6. Langfuse同时标记model_fallback=true, harness_fallback=true双降级标签。

4. 会话持久化模型覆盖

触发模型候选链切换后，会话写入临时覆盖标记modelOverrideSource:auto，本轮及后续轮次优先使用备用模型；冷却期后主模型恢复，可自动切回主运行时。

四、两种回退机制优先级与覆盖规则

1. 插件内置fallback（embeddedHarness）优先执行
   同一模型内部外部Harness故障，优先尝试切内置pi，不立即切换模型；减少模型切换带来的上下文差异。
2. 插件回退失效/配置fallback=none时，才推进全局模型fallback候选链；
3. 两层回退独立开关，可组合配置：
   • 组合1（标准容灾）：fallback=pi+ 配置全局fallback模型，双层兜底；
   • 组合2（强管控研发场景）：fallback=none+ 无fallback模型，codex不可用直接报错；
   • 组合3（轻量化兜底）：fallback=pi+ 无备用模型，仅插件内降级。

五、回退后统一约束与隔离规则（安全不可突破）

1. 上下文与提示词一致性

回退前后使用完全相同的六层提示词、ContextEngine上下文视图；

• 外部codex-harness自有压缩逻辑失效后，切换为内核四阶段Context Compaction；
• CJK优化、反抖动、深度推理自适应参数完全继承RuntimePlan配置，不会丢失策略。

2. 安全体系统一生效

1. 三层Tool治理、正则/Preamble代码沙箱双层防护、子代理黑白名单/防递归/防污染完全不变；
2. 回退至内置harness后，所有tool_call强制上交内核校验，不存在外部Harness直调工具的逃逸风险；
3. Cron定时任务触发的Harness回退，仍使用CronContextHolder隔离上下文，不污染前台会话。

3. 并发安全不破坏

• SessionLock会话串行锁持续持有，回退过程不释放锁，不会出现同会话并发消息乱序；
• Per-Request上下文全程透传，观测链路不丢失traceId、tenantId；
• 子代理独立Harness回退不影响父会话运行时。

4. 观测埋点完整区分

四层Langfuse自动增加专属标签用于成本、故障统计：

• harness_fallback: true/false：是否触发插件级Harness降级；
• original_harness_runtime：故障前原运行时ID（codex）；
• model_fallback: true/false：是否切换备用模型；
• fallback_reason：故障原因（connect_fail/auth_timeout/plugin_disabled）。

六、回退配套兜底控制能力

1. 重试冷却与会话级跳过缓存

环境变量控制失效Harness短期跳过，避免频繁重试无效服务：

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

• 外部Harness鉴权失败后，同一会话60秒内不再重试该runtime，直接走回退逻辑；
• 主模型永远不缓存跳过标记，保证定时探测恢复。

2. 全局总熔断开关

通过ConditionalOnPluginEnable一键禁用外部Harness插件，所有绑定该runtime的模型自动触发fallback=pi：

claw.plugin.codex.enable:false

3. 回退告警策略

Observer观测插件监控两类指标并触发告警：

1. harness_fallback_count：单位时间Harness插件降级次数，突增代表codex服务不稳定；
2. 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仅为执行载体，切换不改变会话持久数据。

❌ 误区3：modelSelectionLocked锁定runtime后无法触发回退
✅ 纠正：锁定仅控制下一轮路由选择；本轮执行外部Harness崩溃，依然可以临时降级内置完成当前请求。

❌ 误区4：fallback=pi会永久切换运行时
✅ 纠正：仅本轮临时降级；下一轮消息进入会重新尝试原codex runtime，服务恢复后自动切回。

九、优缺点总结

优势

1. 双层兜底容灾，外部专用智能体服务宕机不中断业务，兼顾研发专用能力与通用高可用；
2. 回退后安全、并发、观测体系完全统一，不会出现降级后权限逃逸、链路丢失问题；
3. 可精细化管控：严格模式无降级/轻量插件内降级/完整模型切换三层策略按需选择；
4. 故障分层可观测，能区分是外部codex服务故障还是主模型链路故障，便于运维定位。

短板

1. 两层回退叠加会轻微增加本轮执行延迟（重试+重新初始化内置Harness）；
2. codex与内置harness能力存在细微差异，极端复杂代码任务降级后输出质量下降；可通过告警监控高频回退及时修复外部服务；
3. 配置项较多，需区分embeddedHarness.fallback与全局model.fallbacks，易混淆。

十、排障诊断手段

1. 查看当前Harness配置：claw harness list --detail，查看各runtime fallback模式；
2. 模拟模型路由+回退链路：claw route test openai/codex-v1，打印预期降级逻辑；
3. 查看回退事件日志：开启日志级别claw.log.level.harness=debug，打印重试、切换、失败原因；
4. Langfuse筛选标签harness_fallback:true，统计降级频次与故障时段；
5. 紧急关停外部Harness插件：修改yamlclaw.plugin.codex.enable=false，所有codex模型自动切内置pi。