实操手册-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", // ← 第二个备用 // ... 更多 ] }

触发场景：

• 模型服务超时（Timeout）
• API 返回错误（如 429 Too Many Requests）
• 模型服务端异常（5xx）
• 长上下文导致模型处理失败

二、配置文件位置

配置文件路径：

~/.openclaw/openclaw.json

这是一个 JSON5 格式的文件（支持注释和尾逗号），OpenClaw Gateway 会自动监听文件变化并热重载，修改后无需重启服务。

三、配置结构详解

3.1 完整路径

agents.defaults.model

3.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.primary

5.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

七、FAQ

Q: Fallback 触发后，用户体验会受影响吗？
A: 一般情况下，切换过程是无感的，用户只会看到回复继续正常生成。但不同模型的回答风格和准确性可能略有差异。

Q: Fallback 列表越长越好吗？
A: 不是。列表过长会导致失败时重试时间增加。建议保留 5~10 个即可，覆盖不同 provider 和价位即可。

Q: 如何知道 Fallback 有没有被触发？
A: 查看会话状态中的Model字段，如果显示的不是主模型，说明当前正在使用 Fallback 模型。

Q: 主模型恢复后会自动切回去吗？
A: 当前会话会继续使用 Fallback 模型，但新会话会重新从主模型开始尝试。

八、相关文档：

• openclaw中文在线文档