夜雨聆风
〖OpenClaw系列〗模型故障切换与多模型策略
上篇回顾
〖OpenClaw系列〗模型配置完整指南
第11篇我们深入讲解了 OpenClaw 的模型配置体系：从 providers 配置到模型别名，从参数控制到多提供商接入。但生产环境充满不确定性——API 限流、服务过载、认证失效、网络超时——单一模型就像单点故障的命门。
本文将解决一个关键问题：当主模型不可用时，如何确保 AI 助手依然可用？
为什么需要 Fallback
单点故障的现实风险
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Fallback 的价值
无 Fallback: 主模型故障 → 服务完全中断 → 用户流失
有 Fallback: 主模型故障 → 自动切换备用 → 服务持续
核心收益：
-
高可用性：消除单点故障 -
成本优化：优先使用高性价比模型，故障时降级 -
用户体验：无感知切换，对话不中断 -
灵活策略：按错误类型选择不同备用模型
多模型架构总览
后面所有配置和策略，都可以回到这张图上对照——每条 Fallback 路径都是图中的一条降级箭头。
Fallback 配置基础
基础配置结构
Fallback 在 OpenClaw 中通过 fallbacks 数组配置：
{
agents: {
defaults: {
// 主模型 + 备用链
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: [
"anthropic/claude-sonnet-4-6", // 第一备用：同厂商降级
"openai/gpt-5.2", // 第二备用：跨厂商
"ollama/llama3.1" // 最终备用：本地模型
]
},
// 允许使用的模型白名单
models: {
"anthropic/claude-opus-4-6": {},
"anthropic/claude-sonnet-4-6": {},
"openai/gpt-5.2": {},
"ollama/llama3.1": {}
}
}
}
}
配置验证
# 验证配置语法
openclaw config validate
# 查看解析后的模型链
openclaw config get agents.defaults.model
# 预期输出
# {
# "primary": "anthropic/claude-opus-4-6",
# "fallbacks": ["anthropic/claude-sonnet-4-6", "openai/gpt-5.2", "ollama/llama3.1"]
# }
故障检测机制
OpenClaw 的故障检测基于 FailoverReason 分类系统：
错误类型对照表
|
|
|
|
|
|---|---|---|---|
rate_limit |
|
|
|
overloaded |
|
|
|
timeout |
|
|
|
auth |
|
|
|
auth_permanent |
|
|
|
billing |
|
|
|
model_not_found |
|
|
|
format |
|
|
|
session_expired |
|
|
|
unknown |
|
|
|
把这 10 种错误按”流量类 / 认证类 / 请求类”分组，得到下面这棵决策树：
特殊处理：上下文溢出
// 来自源码 model-fallback.ts
if (isLikelyContextOverflowError(errMessage)) {
throw err; // 上下文溢出不触发 Fallback
}
原因：上下文溢出是输入问题，切换模型无法解决（其他模型可能上下文更小）。
网络层错误识别
// 以下错误码自动识别为 timeout
[
"ETIMEDOUT", "ESOCKETTIMEDOUT", "ECONNRESET",
"ECONNABORTED", "ECONNREFUSED", "ENETUNREACH",
"EHOSTUNREACH", "EHOSTDOWN", "ENETRESET",
"EPIPE", "EAI_AGAIN"
]
多层级 Fallback 策略
下面四种策略，本质都是同一张流程图的不同分支。先把这张图记在脑子里，后面再看每段 JSON 就不会迷路：
策略一：同厂商降级
{
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: [
"anthropic/claude-sonnet-4-6", // 能力接近，成本更低
"anthropic/claude-haiku-4-5" // 快速响应
]
}
}
优势：
-
保持一致的输出风格 -
减少跨厂商兼容问题 -
API 格式完全一致
策略二：跨厂商备份
{
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: [
"openai/gpt-5.2", // 跨厂商备份
"google/gemini-2.5-pro" // 第三选择
]
}
}
优势：
-
规避单一厂商全局故障 -
利用不同厂商的定价策略 -
覆盖更多地域/网络环境
策略三：本地模型兜底
{
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: [
"openai/gpt-5.2",
"ollama/llama3.1" // 本地模型，零网络依赖
]
}
}
优势：
-
完全离线可用 -
数据隐私保障 -
零外部 API 成本
三种策略并排对比，特点一目了然：
Cooldown 冷却机制
机制原理
当某个 provider 连续失败时，OpenClaw 会将其放入”冷却”状态，避免反复尝试无效的 provider：
请求 Primary (Anthropic) → 失败 (rate_limit)
↓
标记 Anthropic 进入 cooldown
↓
直接尝试 Fallback 1 (OpenAI)
↓
后续请求跳过 Anthropic，直到冷却结束
把上面这段文字流抽出来，就是下面这条时间轴：
图中底部的波动曲线表示该 provider 的可用性随时间变化：触发失败时陡降，进入 Cooldown 期间持续低位（被屏蔽），探测成功后回升至正常水平。
探测策略
// 来自源码 model-fallback.ts
const MIN_PROBE_INTERVAL_MS = 30_000; // 最小探测间隔 30 秒
const PROBE_MARGIN_MS = 2 * 60 * 1000; // 探测余量 2 分钟
const PROBE_STATE_TTL_MS = 24 * 60 * 60 * 1000; // 状态保留 24 小时
探测规则：
-
主模型：冷却即将结束前（2分钟内）尝试探测 -
备用模型：仅在 rate_limit/overloaded/unknown时探测 -
认证/计费问题：跳过探测，直接切换
配置影响
{
// 单 provider 配置（无 fallback）
model: "anthropic/claude-opus-4-6"
// 行为：即使 cooldown 也会持续重试，因为无其他选择
// 多 provider 配置（有 fallback）
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5.2"]
}
// 行为：Anthropic cooldown 期间优先使用 OpenAI
}
按 Agent 配置 Fallback
场景：不同 Agent 使用不同策略
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-sonnet-4-6",
fallbacks: ["openai/gpt-5.2"]
}
},
list: [
{
id: "coding",
name: "编程助手",
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: [
"anthropic/claude-sonnet-4-6",
"openai/gpt-5.2"
]
}
},
{
id: "quick",
name: "快速问答",
model: {
primary: "openai/gpt-5.2",
fallbacks: ["ollama/llama3.1"]
}
}
]
}
}
三个 Agent 三种 Fallback 链，一张图看完：
禁用 Fallback
{
agents: {
list: [
{
id: "strict",
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: [] // 空数组 = 禁用 fallback
}
}
]
}
}
图片模型的 Fallback
图片生成模型同样支持 Fallback：
{
agents: {
defaults: {
imageModel: {
primary: "openai/dall-e-3",
fallbacks: [
"stability/sd-xl",
"ollama/stable-diffusion"
]
}
}
}
}
区别：图片模型的 fallback 链独立配置，不与文本模型共享。
成本优化策略
智能降级策略
{
agents: {
defaults: {
model: {
// 默认使用性价比模型
primary: "anthropic/claude-sonnet-4-6",
// 高价值场景才使用旗舰模型
fallbacks: ["anthropic/claude-opus-4-6"]
}
}
}
}
运行时模型选择
# 高价值会话使用旗舰模型
openclaw chat --model "anthropic/claude-opus-4-6" --session-id important
# 普通会话使用默认配置
openclaw chat --session-id normal
踩坑
坑1：Fallback 链过长导致延迟
现象：用户反馈 AI 回复很慢，日志显示多次模型切换。
排查：
# 查看详细日志
OPENCLAW_LOG_LEVEL=debug openclaw logs -f | grep fallback
# 预期输出
# [DEBUG] model-fallback: candidate_failed (attempt 1/4)
# [DEBUG] model-fallback: candidate_failed (attempt 2/4)
# [DEBUG] model-fallback: candidate_succeeded (attempt 3/4)
解决：
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: [
"anthropic/claude-sonnet-4-6"
// 移除不可靠的备用，缩短链条
]
}
}
}
}
坑2：模型白名单限制 Fallback
现象：配置了 fallback 但切换时提示 “model not allowed”。
原因：agents.defaults.models 白名单未包含 fallback 模型。
解决：
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5.2"]
},
models: {
// 必须包含所有可能使用的模型
"anthropic/claude-opus-4-6": {},
"openai/gpt-5.2": {} // 遗漏此项导致错误
}
}
}
}
坑3：跨厂商切换导致输出风格不一致
现象：同一会话中，前面回复很详细，后面突然变简短。
原因：从 Claude 切换到 GPT 时，模型特性差异导致输出风格变化。
缓解：
<!-- 在 SOUL.md 中强化风格定义 -->
## Output Style
无论使用何种模型，你必须：
- 保持回复长度一致（200-300字）
- 使用中文回复
- 包含至少一个具体例子
坑4：Cooldown 期间无法强制使用主模型
现象：明知主模型已恢复，但请求仍走 fallback。
解决：重启 Gateway 清除 cooldown 状态
openclaw gateway restart
或等待探测间隔（默认 30 秒）。
FAQ
Q1: Fallback 切换时用户能感知吗？
默认情况下无感知。但日志会记录：
[WARN] Model "anthropic/claude-opus-4-6" not found.
Fell back to "openai/gpt-5.2".
如需显式通知，可在客户端监听 fallbackNotice 事件（需自定义开发）。
Q2: 可以配置按错误类型选择 Fallback 吗？
目前不支持细粒度路由。但可通过以下方式间接实现：
{
// 方案：为不同场景创建不同 Agent
agents: {
list: [
{
id: "rate-limit-agent",
// 使用本地模型规避限流
model: { primary: "ollama/llama3.1" }
},
{
id: "quality-agent",
// 优先保证质量
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5.2"]
}
}
]
}
}
Q3: 如何监控 Fallback 频率？
# 统计 fallback 次数
openclaw logs | grep -c "candidate_failed"
# 查看最近 fallback 记录
openclaw logs | grep "Fell back" | tail -20
Q4: Session 级别的模型覆盖会影响 Fallback 吗？
会。Session 指定的模型优先级最高：
Session 覆盖模型 > Agent 配置 > 全局默认值
但 fallback 链仍遵循配置层级：
// 来自源码 agent-scope.ts
exportfunctionresolveEffectiveModelFallbacks(params: {
cfg: OpenClawConfig;
agentId: string;
hasSessionModelOverride: boolean;
}): string[] | undefined{
const agentFallbacksOverride = resolveAgentModelFallbacksOverride(params.cfg, params.agentId);
if (!params.hasSessionModelOverride) {
return agentFallbacksOverride;
}
// Session 覆盖模型时，使用全局 fallback
const defaultFallbacks = resolveAgentModelFallbackValues(params.cfg.agents?.defaults?.model);
return agentFallbacksOverride ?? defaultFallbacks;
}
完整配置示例
生产环境推荐配置
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-sonnet-4-6",
fallbacks: [
"anthropic/claude-opus-4-6", // 同厂商升级（特殊场景）
"openai/gpt-5.2", // 跨厂商备份
"ollama/llama3.1" // 本地兜底
]
},
models: {
"anthropic/claude-sonnet-4-6": {
alias: "fast"
},
"anthropic/claude-opus-4-6": {
alias: "power"
},
"openai/gpt-5.2": {
alias: "backup"
},
"ollama/llama3.1": {
alias: "local"
}
}
}
},
models: {
providers: {
anthropic: {
baseUrl: "https://api.anthropic.com",
apiKey: "${ANTHROPIC_API_KEY}"
},
openai: {
baseUrl: "https://api.openai.com",
apiKey: "${OPENAI_API_KEY}"
},
ollama: {
baseUrl: "http://localhost:11434"
}
}
}
}
总结
本文深入讲解了 OpenClaw 的 Fallback 机制：
|
|
|
|---|---|
| 配置语法 | model: { primary, fallbacks: [] } |
| 故障检测 |
|
| 冷却机制 |
|
| 策略选择 |
|
| Agent 隔离 |
|
关键认知：Fallback 不是简单的”备用”，而是一套完整的故障自愈系统——自动检测、智能切换、渐进恢复。
下一篇预告
第13篇：接入本地模型：Ollama/LM Studio
将 Fallback 链的最后一环落地：
-
Ollama 安装与模型下载 -
LM Studio 配置与 OpenClaw 集成
延伸阅读：Fallback 策略在生产环境中如何与监控告警联动？后面会有（高可用架构：多区域部署与故障转移）和（监控告警与 SRE 实践）。想了解不同模型在 OpenClaw 上的真实性能数据，（性能基准测试与优化指南）。
-
本地模型的性能优化与资源管理 -
纯离线环境的完整部署方案
本文是系列第12篇。你已掌握 OpenClaw 的高可用模型配置策略。
📌 觉得有用？点个「在看」 👇 👨💻 关注「敏叔侃技术」，每周更新 OpenClaw 实战干货 ⭐ 收藏这篇文章，作为生产环境 Fallback 配置的参考手册