实操手册-OpenClaw备用模型机制

背景在 OpenClaw 的日常使用中模型并非永远稳定运行。当主模型Primary因超时、限流、服务错误等原因不可用时如果没有备用机制会话就会直接报错中断。OpenClaw 提供了Fallback备用模型机制当主模型失败时自动降级到列表中的下一个可用模型保证服务的连续性。一、Fallback 是什么简单说Fallback 就是一个有序的备用模型列表。当主模型调用失败时OpenClaw 会按顺序尝试列表中的模型直到找到一个可用的为止。{ primary: qwen/deepseek-v4-flash, // 主模型 fallbacks: [ // 备用模型列表 qwen/qwen3.7-flash-2026-07-15, // ← 第一个备用 modelstudio/qwen3.5-plus, // ← 第二个备用 // ... 更多 ] }触发场景模型服务超时TimeoutAPI 返回错误如 429 Too Many Requests模型服务端异常5xx长上下文导致模型处理失败二、配置文件位置配置文件路径~/.openclaw/openclaw.json这是一个 JSON5 格式的文件支持注释和尾逗号OpenClaw Gateway 会自动监听文件变化并热重载修改后无需重启服务。三、配置结构详解3.1 完整路径agents.defaults.model3.2 配置示例{agents:{defaults:{model:{primary:qwen/deepseek-v4-flash,fallbacks:[qwen/qwen3.7-flash-2026-07-15,modelstudio/qwen3.5-plus,qwen/qwen3.6-plus,qwen/qwen3-max-2026-01-23]}}}}3.3 Models 注册表Fallback 列表中的模型建议同时在agents.defaults.models中注册否则 OpenClaw 可能不认识该模型标识{agents:{defaults:{models:{qwen/deepseek-v4-flash:{},qwen/qwen3.7-flash-2026-07-15:{},modelstudio/qwen3.5-plus:{},qwen/qwen3.6-plus:{}}}}}四、Fallback 配置策略4.1 省钱策略推荐核心思路把有免费额度的模型放在 Fallback 列表的最前面日常使用付费主模型降级时优先走免费额度。{primary:qwen/deepseek-v4-flash,// 付费主力模型fallbacks:[qwen/qwen3.7-flash-2026-07-15,// 免费额度省钱首选modelstudio/qwen3.5-plus,// 备用// ...]}优点主模型正常运行时不增加成本主模型异常时自动切到免费模型避免服务中断的同时控制成本。4.2 质量优先策略如果追求降级后的回答质量建议把性能相近的模型放在前面{primary:qwen/deepseek-v4-flash,fallbacks:[qwen/qwen3-max-2026-01-23,// 高质量备用qwen/qwen3.6-plus,// 次选qwen/qwen3.5-plus// 兜底]}4.3 冗余策略多 provider如果某个 provider 整体不可用建议混用不同 provider 的模型作为 fallback{primary:qwen/deepseek-v4-flash,fallbacks:[modelstudio/deepseek-v4-flash,// 不同 provider 的同模型qwen/qwen3.7-flash-2026-07-15,// 同一 provider 的免费模型modelstudio/qwen3.5-plus// 不同 provider 的备用]}五、操作指南5.1 查看当前配置# 查看所有 fallback 模型openclaw models fallbacks list# 查看主模型openclaw config get agents.defaults.model.primary5.2 查看当前会话状态# 查看当前运行的模型和 fallback 列表openclaw status输出示例 Model: qwen/deepseek-v4-flash · api-key (qwen:default) Fallbacks: qwen/qwen3.7-flash-2026-07-15, ...5.3 手动修改配置直接编辑~/.openclaw/openclaw.json找到agents.defaults.model部分修改后保存即可。Gateway 会自动热重载。5.4 热重载验证# 检查配置是否生效openclaw config get agents.defaults.model七、FAQQ: Fallback 触发后用户体验会受影响吗A: 一般情况下切换过程是无感的用户只会看到回复继续正常生成。但不同模型的回答风格和准确性可能略有差异。Q: Fallback 列表越长越好吗A: 不是。列表过长会导致失败时重试时间增加。建议保留 5~10 个即可覆盖不同 provider 和价位即可。Q: 如何知道 Fallback 有没有被触发A: 查看会话状态中的Model字段如果显示的不是主模型说明当前正在使用 Fallback 模型。Q: 主模型恢复后会自动切回去吗A: 当前会话会继续使用 Fallback 模型但新会话会重新从主模型开始尝试。八、相关文档openclaw中文在线文档