模型故障转移：打造高可用 AI 服务
故障转移（Failover）是"让 AI 服务持续可用"的兜底能力。当主模型因配额耗尽、网络故障或 API 限流而失效时，OpenClaw 会自动切换到备用模型。
🎯 核心机制
OpenClaw 的故障转移是两层的：
- 认证轮换：同一 Provider 内，轮换不同的认证配置
- 模型回退：跨 Provider，按顺序尝试备用模型
请求 → 主模型/认证1 → 认证2 → 认证3 → 备用模型1 → 备用模型2 → ... → 失败⚙️ 最小可用配置
基础回退（5 分钟上手）
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-sonnet-4-5",
fallbacks: [
"openai/gpt-4o",
"ollama/llama3", // 本地兜底
],
},
},
},
}多认证轮换（适合团队账号）
{
models: {
providers: {
anthropic: {
apiKey: "sk-ant-xxx1",
credentials: {
profile2: {
apiKey: "sk-ant-xxx2",
},
profile3: {
apiKey: "sk-ant-xxx3",
},
},
},
},
},
}🏗️ 推荐架构
个人用户方案
主力：国产模型（性价比高）
↓
备用：GPT-4o-mini（均衡）
↓
兜底：本地 Llama3（免费）团队/生产方案
主集群：Claude Sonnet × 3（多认证轮换）
↓
备集群：GPT-4o × 2（多认证轮换）
↓
本地：Ollama/vLLM（紧急兜底）🔧 诊断与验证
检查当前状态
# 查看所有模型状态
openclaw models status
# 探测性测试（会实际调用 API）
openclaw models status --probe
# 查看故障转移链
openclaw models fallbacks list模拟故障测试
# 临时禁用主模型，测试切换
# 编辑配置后将主模型设为无效值，观察是否自动切换📊 实战场景
场景一：成本敏感型
{
agents: {
defaults: {
model: {
primary: "qwen/qwen-turbo", // ¥0.008/1k tokens
fallbacks: [
"deepseek/deepseek-chat", // ¥0.001/1k tokens
"ollama/qwen2", // 免费
],
},
},
},
}场景二：质量优先型
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: [
"anthropic/claude-sonnet-4-5",
"openai/gpt-4o",
"qwen/qwen-max", // 国产兜底
],
},
},
},
}场景三：混合部署（海外 + 国内）
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-sonnet-4-5",
fallbacks: [
"qwen/qwen-plus", // 国内节点快
"ollama/llama3", // 本地兜底
],
},
},
},
}🛠️ CLI 管理
# 列出当前回退链
openclaw models fallbacks list
# 添加备用模型
openclaw models fallbacks add qwen/qwen-plus
# 移除备用模型
openclaw models fallbacks remove qwen/qwen-plus
# 清空所有备用（保留主模型）
openclaw models fallbacks clear⚠️ 注意事项
性能考虑
- 每次切换会增加请求延迟（约 1-3 秒）
- 建议备用模型选择响应速度快的
- 本地模型虽免费但硬件要求高
成本控制
- Claude/GPT 作为备用时，留意费用突增
- 建议设置告警监控
- 定期检查主模型是否恢复
配额管理
- 多认证轮换可延长单厂商配额
- 注意各厂商的 RPM/TPM 限制
🔗 相关文档
💡 最佳实践
- 永远配置本地兜底：即使很慢，也比完全不可用强
- 定期测试故障转移：不要等到真的出问题才验证
- 监控切换频率：频繁切换说明主模型有问题
- 记录故障模式：是配额耗尽？网络问题？还是 API 变更？