概述
OpenClaw 内置了两级故障转移机制，确保当主模型不可用时能够自动切换到备用选项，最大程度保证 AI 助手的持续可用性。理解这套机制有助于你根据自身使用场景做出最合理的配置决策。
两级故障转移架构
OpenClaw 的模型切换按照以下顺序依次尝试：
第一级：同一提供商内的认证配置轮换 当某个 API Key 触发频率限制或认证失败时，系统优先在同一模型提供商内切换到其他可用的认证配置（如你配置了多个 API Key 或 OAuth 账户）。
第二级：跨提供商的模型回退
当第一级的所有认证配置都耗尽或进入冷却状态时，系统才会切换到 agents.defaults.model.fallbacks 中配置的备用模型。
配置主备模型
在 ~/.openclaw/openclaw.json5 中配置主模型和故障转移链：
{
agents: {
defaults: {
model: {
// 主模型：优先使用的模型
primary: "anthropic/claude-opus-4-6",
// 备用模型列表：按优先级从高到低排列
// 主模型所有认证配置耗尽后依次尝试
fallbacks: [
"anthropic/claude-sonnet-4-6",
"kilocode/anthropic/claude-opus-4.6",
"openai/gpt-4o",
"moonshot/moonshot-v1-8k"
]
}
}
}
}
多认证配置轮换
为同一提供商配置多个 API Key，可以在不触发跨模型切换的情况下大幅提升可用性和吞吐量：
{
auth: {
profiles: {
// 主 Anthropic API Key
"anthropic:default": {
type: "api_key",
key: { source: "env", id: "ANTHROPIC_API_KEY_1" }
},
// 备用 Anthropic API Key（主 Key 限流时自动切换）
"anthropic:backup": {
type: "api_key",
key: { source: "env", id: "ANTHROPIC_API_KEY_2" }
}
},
// 指定认证配置使用顺序
order: {
anthropic: ["anthropic:default", "anthropic:backup"]
}
}
}
冷却退避策略
当某个认证配置触发错误时，系统会对其施加冷却期，按以下指数退避时间表逐步延长：
| 错误次数 | 冷却时长 |
|---|---|
| 第 1 次 | 1 分钟 |
| 第 2 次 | 5 分钟 |
| 第 3 次 | 25 分钟 |
| 第 4 次及以上 | 1 小时（上限） |
触发冷却的条件包括：认证失败、频率限制（429）、超时、响应格式错误等。冷却状态存储在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 中，格式如下：
{
usageStats: {
"anthropic:default": {
lastUsed: 1736160000000,
cooldownUntil: 1736160600000, // 冷却截止时间戳（毫秒）
errorCount: 2
}
}
}
账单错误的特殊处理
与普通错误的短暂冷却不同，账单相关错误（如额度耗尽、付款失败）会触发更长时间的禁用：
{
auth: {
cooldowns: {
// 首次账单错误的禁用时长（小时），默认 5 小时
billingBackoffHours: 5,
// 每次账单错误后禁用时长翻倍，最长不超过此值（默认 24 小时）
billingMaxHours: 24,
// 连续多少小时无错误后重置计数器（默认 24 小时）
failureWindowHours: 24,
// 可按提供商分别配置账单退避策略
billingBackoffHoursByProvider: {
anthropic: 3,
openai: 6
}
}
}
}
会话内的配置固定（Pinning）
在一次会话开始时，系统会选定一个认证配置并将其固定（pin）到该会话，直到：
- 会话重置或手动切换模型
- 上下文压缩（Compaction）完成
- 当前固定的配置进入冷却状态
手动锁定认证配置：使用 /model @<profileId> 命令可以强制锁定到特定配置，锁定状态在遇到错误时不会自动轮换，而是直接触发模型回退。
自动固定（推荐）：系统自动选择时会记录偏好，遇到限流会先在提供商内轮换，全部耗尽才会切换模型。
查看故障转移状态
# 查看当前认证配置状态（包括冷却信息）
openclaw config get auth.profiles
# 查看模型使用统计
openclaw models stats
# 实时监控模型切换日志
openclaw logs --filter model --level info
# 重置特定认证配置的冷却状态
openclaw config unset auth.profiles."anthropic:default".cooldownUntil
实用技巧
回退链设计原则：回退链中的模型建议按成本从高到低排列，将高性能旗舰模型作为主模型，低成本模型作为最终保底。这样既能保证日常质量，又能在主力模型全部不可用时维持基本功能。
跨供应商分散风险：在回退链中同时包含 Anthropic、OpenAI、国产模型（如 Moonshot、Qwen）等不同供应商，避免因单一供应商维护或网络故障导致全链路不可用。
本地模型兜底：如果你在本地运行了 Ollama，将其配置为最后一级回退，可以在所有云端模型不可用时仍然保持基本的 AI 交互能力，实现真正的零停机。