模型 Fallback 机制

当主模型不可用（限速、超时、错误）时，OpenClaw 自动切换到备用模型。

配置 Fallback 链

{
  "ai": {
    "primary": "claude-sonnet-4-6",
    "fallback": [
      "claude-haiku-4-5",
      "gpt-4o-mini"
    ],
    "fallbackOn": ["rate_limit", "timeout", "server_error"]
  }
}

触发条件

错误类型	说明
rate_limit	API 速率限制（429）
timeout	请求超时
server_error	服务端错误（5xx）
context_length	超出上下文窗口

多提供商 Fallback

配合 XaAPI 等聚合网关，可以跨提供商 Fallback：

{
  "ai": {
    "providers": {
      "primary": {
        "baseURL": "https://xaapi.ai",
        "apiKey": "sk-...",
        "model": "claude-sonnet-4-6"
      },
      "fallback": {
        "baseURL": "https://api.openai.com/v1",
        "apiKey": "sk-...",
        "model": "gpt-4o-mini"
      }
    }
  }
}

监控 Fallback 事件

# 查看 Fallback 日志
openclaw logs --filter fallback

# 示例：
# [Fallback] Primary model rate limited, switching to claude-haiku-4-5
# [Fallback] Request succeeded with fallback model