Appearance
OpenClaw 模型配置与回退链：AI 的"备胎"机制。主模型挂了自动切换到备用模型，三步配置从单点故障到高可用。
痛点：模型挂了怎么办
给 OpenClaw 配了一个模型，用得好好的。突然有一天：
- API 挂了
- 限流了
- 额度用完了
AI 直接罢工了。怎么办？等它恢复？还是手动切换？
OpenClaw 的答案是：自动切换到备用模型。这就是"回退链"。
核心概念速查
| 概念 | 说明 |
|---|---|
| primary | 主模型，日常使用的模型 |
| fallbacks | 回退链，按顺序尝试的备用模型列表 |
| models | 模型目录，定义可用的模型和别名 |
配置方法
配置文件方式
编辑 ~/.openclaw/openclaw.json：
json
{
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-sonnet-4-6",
"fallbacks": [
"openai/gpt-5.4",
"openrouter/meta-llama/llama-3.3-70b"
]
}
},
"models": {
"anthropic/claude-sonnet-4-6": {
"alias": "Sonnet"
},
"openai/gpt-5.4": {
"alias": "GPT"
}
}
}
}CLI 方式
bash
# 设置主模型
openclaw config set agents.defaults.model.primary "anthropic/claude-sonnet-4-6"
# 设置回退链
openclaw config set agents.defaults.model.fallbacks '["openai/gpt-5.4"]'
# 添加模型别名
openclaw config set agents.models.openai/gpt-5.4.alias "GPT"回退链工作流程
┌─────────────────────────────────────────────────────────────┐
│ 回退链工作流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ① 尝试主模型 │
│ └── primary 配置的模型 │
│ └── 成功 → 使用主模型 │
│ └── 失败 → 进入步骤② │
│ │
│ ② 同提供商轮换凭证 │
│ └── 同一个 API Key 用完了？换另一个 │
│ └── 成功 → 使用备用凭证 │
│ └── 失败 → 进入步骤③ │
│ │
│ ③ 切换到下一个回退模型 │
│ └── 按 fallbacks 列表顺序尝试 │
│ └── Claude 挂了 → 试 GPT │
│ └── GPT 也挂了 → 试 Llama │
│ └── 成功 → 使用回退模型 │
│ └── 失败 → 进入步骤④ │
│ │
│ ④ 全部失败 │
│ └── 返回错误摘要 │
│ └── 包含每个模型失败原因 │
│ └── 包含预计恢复时间 │
│ │
└─────────────────────────────────────────────────────────────┘触发回退的场景
| 场景 | 说明 | 检测方式 |
|---|---|---|
| 凭证失败 | API Key 过期、OAuth 登录失效 | HTTP 401 |
| 限流 | 请求频率超限 | HTTP 429 |
| 可用性问题 | API 服务商宕机 | HTTP 503 |
| 响应超时 | 模型响应时间过长 | 超时设置 |
冷却机制详解
什么是冷却期
当某个模型失败后，OpenClaw 会进入"冷却期"：
| 阶段 | 说明 |
|---|---|
| 冷却计时 | 模型失败后开始计时 |
| 冷却时长 | 通常是 30 秒到 5 分钟 |
| 冷却期间 | 不会再次尝试该模型 |
| 冷却结束 | 可以再次尝试该模型 |
配置冷却时间
json
{
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-sonnet-4-6",
"fallbacks": ["openai/gpt-5.4"],
"cooldown": "60s"
}
}
}
}冷却时间配置参考
| 模型类型 | 推荐冷却时间 | 原因 |
|---|---|---|
| OpenAI | 30s - 60s | 限流恢复快 |
| Anthropic | 60s - 120s | 相对稳定 |
| 本地模型 | 10s - 30s | 恢复快 |
| 开源模型 | 30s - 60s | 取决于服务商 |
多 API Key 轮换
为什么需要多 Key
| 问题 | 解决方案 |
|---|---|
| 单个 Key 额度不够 | 配多个 Key 轮流用 |
| 单个 Key 限流 | 多 Key 并行请求 |
| Key 过期 | 自动切换到有效 Key |
配置多 Key
json
{
"providers": {
"anthropic": {
"api_keys": [
"sk-ant-api01-xxx-1",
"sk-ant-api01-xxx-2",
"sk-ant-api01-xxx-3"
]
}
}
}轮换策略
| 策略 | 说明 |
|---|---|
| 轮询 | 按顺序轮流使用每个 Key |
| 随机 | 随机选择 Key |
| 最少使用 | 优先使用使用次数最少的 Key |
实用建议
推荐回退链配置
| 优先级 | 模型 | 说明 |
|---|---|---|
| 1 | Claude Sonnet 4.6 | 主模型，能力最强 |
| 2 | GPT-5.4 | 第一备胎，OpenAI 主力 |
| 3 | Claude 3.5 | 第二备胎，同提供商 |
| 4 | Llama 3.3 | 第三备胎，开源可本地 |
成本考虑
| 模型 | 成本 | 适用场景 |
|---|---|---|
| Claude Sonnet 4.6 | 中高 | 日常主力 |
| GPT-5.4 | 高 | Claude 挂了时使用 |
| Claude 3.5 | 中 | 成本优化 |
| Llama 3.3 | 免费 | 最后备胎 |
监控配置
bash
# 查看模型状态
openclaw models status
# 查看回退历史
openclaw models fallback-history
# 查看当前使用模型
openclaw models current错误处理
当所有模型都失败时
OpenClaw 会返回错误摘要：
json
{
"error": "All models failed",
"attempts": [
{
"model": "anthropic/claude-sonnet-4-6",
"reason": "Rate limit exceeded",
"retry_after": 30
},
{
"model": "openai/gpt-5.4",
"reason": "API key invalid",
"retry_after": null
}
],
"recommendation": "Check API credentials and retry after 60s"
}常见错误及解决
| 错误 | 原因 | 解决 |
|---|---|---|
| 401 Unauthorized | API Key 无效 | 检查 Key 配置 |
| 429 Rate Limited | 请求超限 | 等待冷却或加 Key |
| 503 Service Unavailable | 服务宕机 | 等待恢复或用备胎 |
| Timeout | 响应超时 | 调高超时时间 |
一句话总结
OpenClaw 回退链 = AI 的"备胎"机制。主模型挂了自动切换，不中断工作。
三步自动切换：
- 尝试主模型
- 同提供商轮换凭证
- 按回退链切换备胎
核心配置：primary + fallbacks + cooldown。
