## 什么是模型故障转移
模型故障转移（Model Failover）是 OpenClaw 的高可用机制——当你配置的主模型不可用时，系统会**自动切换到备用模型**继续工作，而不是直接报错。
```
用户发送消息
↓
尝试主模型（GPT-4o）
↓ 失败！
自动切换备用模型（DeepSeek）
↓ 成功
返回回复给用户
```
对用户来说，这个切换过程是透明的——你可能只会感觉到回复稍慢了一点，但不会中断对话。
## 故障转移触发条件
以下情况会触发故障转移：
| 触发条件 | 说明 | 常见场景 |
|----------|------|---------|
| 请求超时 | 模型响应时间超过设定阈值 | 模型服务器负载过高 |
| HTTP 5xx 错误 | 服务端内部错误 | 模型服务宕机或维护 |
| HTTP 429 错误 | 请求频率超限（Rate Limit） | API 配额用完 |
| 网络连接失败 | 无法连接到模型 API | 网络问题、DNS 解析失败 |
| API Key 无效 | 认证失败 | Key 过期或余额不足 |
> 💡 HTTP 4xx 错误（除 429 外）通常不会触发故障转移，因为这类错误往往是请求本身的问题（如参数错误），换模型也解决不了。
## 配置故障转移
在 `openclaw.json` 中配置 fallback 列表：
```json
{
"model": {
"provider": "openai",
"model": "gpt-4o",
"fallback": [
{
"provider": "anthropic",
"model": "claude-3-5-sonnet-20241022"
},
{
"provider": "deepseek",
"model": "deepseek-chat"
},
{
"provider": "ollama",
"model": "llama3.1"
}
]
}
}
```
### 故障转移顺序
系统按 fallback 数组的顺序依次尝试：
```
1. GPT-4o（主模型）
↓ 失败
2. Claude 3.5 Sonnet（第一备用）
↓ 失败
3. DeepSeek Chat（第二备用）
↓ 失败
4. Ollama llama3.1（最终兜底，本地模型）
↓ 如果全部失败
5. 返回错误信息给用户
```
### 推荐配置策略
**国内用户推荐方案：**
```json
{
"model": {
"provider": "deepseek",
"model": "deepseek-chat",
"fallback": [
{
"provider": "qwen",
"model": "qwen-plus"
},
{
"provider": "ollama",
"model": "qwen2.5:7b"
}
]
}
}
```
**追求质量的方案：**
```json
{
"model": {
"provider": "openai",
"model": "gpt-4o",
"fallback": [
{
"provider": "anthropic",
"model": "claude-3-5-sonnet-20241022"
},
{
"provider": "deepseek",
"model": "deepseek-chat"
}
]
}
}
```
**零成本兜底方案：**
在 fallback 列表末尾加一个本地 Ollama 模型，确保即使所有云端 API 都挂了，智能体仍然能回复（虽然质量可能下降）：
```json
{
"fallback": [
{ "provider": "deepseek", "model": "deepseek-chat" },
{ "provider": "ollama", "model": "llama3.1" }
]
}
```
## 什么是流式传输
默认情况下，AI 模型会等**整个回复生成完毕**后才一次性返回。对于长回复，用户可能需要等待 10-30 秒才能看到内容。
流式传输（Streaming）改变了这个行为——模型会**边生成边发送**，用户可以实时看到回复逐字出现：
```
非流式（默认）：
用户发送 → [等待 15 秒] → 一次性显示完整回复
流式传输：
用户发送 → [1秒] 显示第一段 → [2秒] 显示第二段 → ... → 完成
```
## 流式传输配置
### 基本配置
在 `openclaw.json` 中启用流式传输：
```json
{
"blockStreaming": true
}
```
### 分块大小配置
`blockStreamingChunk` 控制每次发送的文本块大小（以字符数计）：
```json
{
"blockStreaming": true,
"blockStreamingChunk": 200
}
```
| 分块大小 | 效果 | 适用场景 |
|----------|------|---------|
| 50-100 | 更新频繁，接近实时 | 短回复、对话式交互 |
| 200（默认） | 平衡体验和性能 | 大多数场景 |
| 500-1000 | 更新较少，每次内容更多 | 长文档生成 |
### 合并策略
`blockStreamingCoalesce` 控制是否将多个小块合并为一条消息：
```json
{
"blockStreaming": true,
"blockStreamingCoalesce": true
}
```
- `true`：将所有分块合并为一条最终消息（推荐）
- `false`：每个分块作为独立消息发送
> 💡 大多数渠道建议开启合并（`true`），否则用户会收到大量碎片消息。
## 各渠道的流式传输差异
不同聊天渠道对流式传输的支持程度不同：
| 渠道 | 流式支持 | 说明 |
|------|---------|------|
| WebChat | ✅ 原生支持 | 通过 WebSocket 实时推送，体验最好 |
| Telegram | ⚠️ 需显式启用 | 通过编辑消息实现，需要设置 `blockStreaming: true` |
| WhatsApp | ❌ 不支持 | WhatsApp API 不支持消息编辑，只能等完整回复 |
| Discord | ✅ 支持 | 通过编辑消息实现 |
| 微信 | ❌ 不支持 | 微信接口限制，无法实现流式效果 |
| QQ | ❌ 不支持 | QQ Bot API 限制 |
| 飞书 | ⚠️ 部分支持 | 通过卡片消息更新实现 |
### Telegram 特殊配置
Telegram 需要显式启用流式传输，因为它通过"编辑已发送消息"来模拟流式效果：
```json
{
"channels": {
"telegram": {
"blockStreaming": true,
"blockStreamingChunk": 300
}
}
}
```
> ⚠️ Telegram 有消息编辑频率限制，分块太小（< 100）可能触发限流。建议 Telegram 的 chunk 设为 300 以上。
### WebChat 流式配置
WebChat 通过 WebSocket 原生支持流式传输，体验最流畅：
```json
{
"channels": {
"webchat": {
"blockStreaming": true,
"blockStreamingChunk": 50
}
}
}
```
WebChat 可以用更小的 chunk（50-100），因为 WebSocket 没有消息编辑的限制。
## 故障转移 + 流式传输
故障转移和流式传输可以同时使用。当主模型的流式连接中断时：
1. 系统检测到流式连接断开
2. 自动切换到备用模型
3. 从头开始生成回复（不会续接之前的部分内容）
```json
{
"model": {
"provider": "openai",
"model": "gpt-4o",
"fallback": [
{ "provider": "deepseek", "model": "deepseek-chat" }
]
},
"blockStreaming": true,
"blockStreamingChunk": 200,
"blockStreamingCoalesce": true
}
```
## 常见问题
### 故障转移后模型风格不一致怎么办？
不同模型的回复风格确实会有差异。建议：
- 在 SOUL.md 中明确定义语气和风格，所有模型都会遵守
- fallback 列表中选择风格相近的模型
- 接受轻微的风格差异，优先保证可用性
### 流式传输会增加成本吗？
不会。流式传输只是改变了回复的**传输方式**，Token 消耗和非流式完全相同。
### 如何知道当前用的是哪个模型？
查看日志可以看到实际使用的模型：
```bash
openclaw logs
```
日志中会显示类似信息：
```
[info] Using model: gpt-4o (primary)
[warn] Model gpt-4o failed, falling back to deepseek-chat
[info] Using model: deepseek-chat (fallback #1)
```
### 故障转移会重试主模型吗？
当前请求不会重试主模型。但下一次新请求会重新从主模型开始尝试。如果主模型恢复了，下次请求就会正常使用主模型。
## 小结
- 故障转移确保智能体的**高可用性**，主模型挂了自动切换备用
- 流式传输提升**用户体验**，让回复实时可见而非长时间等待
- 两者可以组合使用，建议所有生产环境都配置 fallback 列表
- 注意各渠道对流式传输的支持差异，按需配置
#模型故障转移 #流式传输 #高可用 #分块回复 #龙虾技能库