一、模型故障转移（Failover）

1. 核心作用

主模型服务异常时，自动按顺序切换备用模型，对话不中断、用户无感知，保障服务高可用。

2. 触发切换的场景

满足以下任意条件，会自动执行故障转移：

1. 接口请求超时
2. 服务端错误 5xx
3. 接口限流 429（请求超限 / 配额用尽）
4. 网络断开、DNS 解析失败
5. API Key 无效、余额不足

补充：普通 4xx 参数错误不会触发切换，属于配置 / 请求问题。

3. 全局故障转移配置

编辑主配置 ~/.openclaw/openclaw.json，标准写法：

json

{
  "model": {
    "provider": "deepseek",
    "model": "deepseek-chat",
    "fallback": [
      {
        "provider": "qwen",
        "model": "qwen-plus"
      },
      {
        "provider": "ollama",
        "model": "llama3"
      }
    ]
  }
}

执行顺序：主模型 → 列表内依次尝试备用模型 → 全部失败才返回报错。

4. 分场景推荐配置

方案 1：国内用户首选（全国内云端 + 本地兜底，稳定无翻墙）

json

{
  "model": {
    "provider": "deepseek",
    "model": "deepseek-chat",
    "fallback": [
      {
        "provider": "qwen",
        "model": "qwen-plus"
      },
      {
        "provider": "glm",
        "model": "glm-3-turbo"
      },
      {
        "provider": "ollama",
        "model": "llama3"
      }
    ]
  }
}

方案 2：追求模型能力（海外主力 + 国内外备用）

json

{
  "model": {
    "provider": "openai",
    "model": "gpt-4o",
    "fallback": [
      {
        "provider": "anthropic",
        "model": "claude-sonnet-4-20250514"
      },
      {
        "provider": "deepseek",
        "model": "deepseek-chat"
      }
    ]
  }
}

方案 3：纯离线兜底（仅本地模型，无云端依赖）

json

{
  "model": {
    "provider": "ollama",
    "model": "llama3",
    "fallback": [
      {
        "provider": "ollama",
        "model": "phi3"
      }
    ]
  }
}

5. 多智能体独立故障转移

多智能体场景下，可给不同 Agent 单独配置主模型与备用队列：

json

{
  "agents": {
    "main": {
      "model": {
        "provider": "deepseek",
        "model": "deepseek-chat",
        "fallback": [{"provider":"qwen","model":"qwen-plus"}]
      }
    },
    "work": {
      "model": {
        "provider": "deepseek",
        "model": "deepseek-coder",
        "fallback": [{"provider":"ollama","model":"codellama"}]
      }
    }
  }
}

6. 查看切换日志

通过日志判断当前使用模型、是否触发故障转移：

bash

运行

openclaw logs

关键字样：

plaintext

[info] Using model: deepseek-chat (primary)
[warn] Model failed, falling back to qwen-plus (fallback #1)

7. 常见问题

1. 切换后回答风格差异大 在 SOUL.md 统一人设、语气；fallback 尽量选择风格相近的模型。
2. 单次请求反复切换 当前请求只会遍历一次备用列表；新对话会重新从主模型开始尝试，主模型恢复后自动切回。
3. 兜底本地模型不生效 检查 Ollama 服务状态：ollama ps，确认端口 11434 正常。

---

二、流式传输（Streaming）

1. 两种模式对比

• 非流式（默认）：模型生成完整内容后一次性返回，长回复等待久。
• 流式传输：边生成、边推送，文字逐字 / 逐段实时展示，体验更流畅。

成本说明：流式仅改变传输方式，Token 消耗、计费和非流式完全一致。

2. 全局流式基础配置

json

{
  "blockStreaming": true,
  "blockStreamingChunk": 200,
  "blockStreamingCoalesce": true
}

参数说明：

1. blockStreaming：true 启用流式，false 关闭
2. blockStreamingChunk：单块字符数，控制推送频率
   • 50~100：更新频繁，适合 Web 对话
   • 200（默认）：均衡通用
   • 500+：推送频次低，适合长文档
3. blockStreamingCoalesce：
   • true（推荐）：所有分块合并为单条消息
   • false：每个分块单独发消息（易产生大量碎片消息）

3. 按渠道差异化配置

不同聊天渠道对流式支持不同，可单独配置：

WebChat（原生最优，WebSocket 推送）

支持极小分块，实时感最强：

json

{
  "channels": {
    "webchat": {
      "blockStreaming": true,
      "blockStreamingChunk": 60
    }
  }
}

Telegram（通过编辑消息模拟流式）

平台有编辑频率限制，分块建议 ≥300，避免限流：

json

{
  "channels": {
    "telegram": {
      "blockStreaming": true,
      "blockStreamingChunk": 300
    }
  }
}

不支持流式的渠道

微信、QQ、标准版 WhatsApp 接口限制，无法实现逐字推送，配置不生效，会自动降级为完整消息。

4. 故障转移 + 流式 组合使用

二者可同时开启。规则：

主模型流式连接中断 → 触发故障转移 → 备用模型重新完整生成并流式输出（不会接续上一段内容）。

完整组合示例（生产环境通用模板）：

json

{
  "model": {
    "provider": "deepseek",
    "model": "deepseek-chat",
    "fallback": [
      {
        "provider": "qwen",
        "model": "qwen-plus"
      },
      {
        "provider": "ollama",
        "model": "llama3"
      }
    ]
  },
  "blockStreaming": true,
  "blockStreamingChunk": 200,
  "blockStreamingCoalesce": true
}

---

三、全量配置校验与生效

1. 修改配置后，重启网关加载新规则：

bash

运行

openclaw gateway restart

1. 环境自检：

bash

运行

openclaw doctor

1. 测试：发送长文本提问，观察是否逐段输出；人为断开主模型网络，验证自动切换。

---

四、总结

1. 故障转移：核心用于高可用，云端 + 本地模型多层兜底，避免服务中断，生产环境必配。
2. 流式传输：优化交互体验，根据不同聊天渠道调整分块大小，微信 / QQ 等平台无需强行开启。
3. 两者可叠加使用，是线上服务、多用户场景的标准组合方案。
4. 依靠 openclaw logs 快速排查模型切换、流式异常问题。