Pular para o conteúdo principal
O ChatCLI suporta uma cadeia de failover automático entre provedores LLM. Quando o provedor primário falha (rate limit, timeout, erro de servidor), o sistema tenta automaticamente o próximo provedor na cadeia, de forma totalmente transparente.

​
Como Funciona

A cadeia de fallback e uma lista ordenada de provedores. Cada request percorre a lista até obter sucesso ou esgotar todas as opcoes: 
Request -> OpenAI (primário)
             | falhou (rate limit)
           Claude (secundário)
             | falhou (timeout)
           Google AI (terciario)
             | sucesso
           Resposta retornada ao usuário

​
Configuração

# Lista ordenada de provedores (primeiro = maior prioridade)
export CHATCLI_FALLBACK_PROVIDERS="OPENAI,CLAUDEAI,GOOGLEAI,OPENROUTER,ZAI,MINIMAX,COPILOT"

# Modelo específico por provedor (opcional)
export CHATCLI_FALLBACK_MODEL_OPENAI="gpt-5.4"
export CHATCLI_FALLBACK_MODEL_CLAUDEAI="claude-sonnet-4-6"
export CHATCLI_FALLBACK_MODEL_GOOGLEAI="gemini-2.5-flash"
export CHATCLI_FALLBACK_MODEL_OPENROUTER="anthropic/claude-sonnet-4"
export CHATCLI_FALLBACK_MODEL_ZAI="glm-5"
export CHATCLI_FALLBACK_MODEL_MINIMAX="MiniMax-M2.7"
export CHATCLI_FALLBACK_MODEL_COPILOT="gpt-4o"

# MiniMax no modo Anthropic-compatível (opcional)
export MINIMAX_API_COMPAT="anthropic"

# Controle de retentativas e cooldown
export CHATCLI_FALLBACK_MAX_RETRIES="2"       # tentativas por provedor
export CHATCLI_FALLBACK_COOLDOWN_BASE="30s"    # cooldown base
export CHATCLI_FALLBACK_COOLDOWN_MAX="5m"      # cooldown máximo

​
Classificacao de Erros

O sistema classifica automaticamente cada falha para decidir a estrategia:
ClasseComportamentoExemplos
rate_limitAguarda backoff, depois retentaHTTP 429, “too many requests”
timeoutRetenta até maxRetriesDeadline exceeded, connection timeout
server_errorRetenta até maxRetriesHTTP 500, 502, 503
auth_errorTenta refresh do token OAuth e retenta uma vez; se falhar, avanca na cadeiaHTTP 401, 403, “invalid api key”
model_not_foundNão retenta — avanca na cadeiaHTTP 404, “model not found”
context_too_longNão retenta — avanca na cadeia”context length exceeded”

​
Cooldown Exponencial

Após falhas consecutivas, o provedor entra em cooldown com backoff exponencial:
Falhas ConsecutivasCooldown
130s
260s
3120s
4240s
5+300s (max)
No modo CLI interativo, erros de autenticação (401) disparam automaticamente o refresh do token OAuth e retentam o request. No modo servidor (fallback chain), erros de autenticação recebem cooldown máximo imediato (5m). Um request bem-sucedido limpa todo o cooldown do provedor. Use ResetCooldowns() para limpar manualmente (ex: após atualizar credenciais).

​
Monitoramento de Saude

A cadeia rastreia o estado de cada provedor em tempo real: 
health := chain.GetHealth()
for _, h := range health {
    fmt.Printf("Provider: %s, Available: %v, Fails: %d, Cooldown: %v\n",
        h.Name, h.Available, h.ConsecutiveFails, h.CooldownUntil)
}
Campos rastreados por provedor:
CampoDescrição
AvailableSe o provedor está disponível para requests
ConsecutiveFailsNúmero de falhas consecutivas
LastErrorClassTipo da ultima falha
CooldownUntilQuando o cooldown expira
LastErrorAtTimestamp da ultima falha

​
Tool Use com Fallback

A cadeia de fallback também suporta SendPromptWithTools para provedores que implementam a interface ToolAwareClient. Provedores sem suporte a tool use nativo são automaticamente ignorados na cadeia de tool calls.

​
Boas Praticas

Ordene por custo-beneficio

Coloque o provedor mais barato/rápido primeiro na cadeia.

Diversifique provedores

Misture provedores de diferentes empresas para resiliencia real.

Configure modelos por provedor

Use modelos equivalentes em capacidade para manter qualidade.

Monitore a saude

Verifique regularmente se algum provedor está em cooldown persistente.
Fallback nativo do OpenRouter: Além do sistema de fallback do ChatCLI (entre provedores), o OpenRouter oferece seu próprio roteamento de fallback dentro do provedor. Configure OPENROUTER_FALLBACK_MODELS com modelos alternativos (ex: openai/gpt-4o,google/gemini-2.5-flash). Se o modelo principal falhar, o OpenRouter tenta os alternativos antes de devolver o erro ao ChatCLI. Os dois mecanismos são complementares.
Cada provedor na cadeia precisa de sua propria API key configurada. Certifique-se de configurar as chaves de todos os provedores listados em CHATCLI_FALLBACK_PROVIDERS.