Skip to main content
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:

​
Configuração

Um CHATCLI_FALLBACK_PROVIDERS (ou --fallback-providers) não vazio é o único interruptor; o servidor não lê nenhuma variável separada para ligar, e nem o Helm chart nem o operator gravam uma. Um provedor sem CHATCLI_FALLBACK_MODEL_<PROVIDER> roda o próprio modelo padrão (a variável de modelo dele, como OPENAI_MODEL, depois o padrão embutido); só o provedor primário fica com o modelo do servidor. maxRetries: 0 (ou CHATCLI_FALLBACK_MAX_RETRIES=0) passa para o próximo provedor sem tentar de novo.

​
Classificacao de Erros

O sistema classifica automaticamente cada falha para decidir a estrategia:

​
Cooldown Exponencial

Após falhas consecutivas, o provedor entra em cooldown com backoff exponencial:
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). No servidor a chain atende toda requisição que não nomeia provider nem modelo e não encaminha credencial (SendPrompt, StreamPrompt, InteractiveSession, AnalyzeIssue, AgenticStep); uma requisição em streaming só faz failover até o primeiro chunk, nunca depois de texto exibido, e a resposta nomeia o provider e modelo que responderam.

​
Monitoramento de Saude

A cadeia rastreia o estado de cada provedor em tempo real:
Campos rastreados por provedor:

​
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.
As entradas da cadeia são identificadas pelo nome do provider — cada provider pode aparecer apenas uma vez, e entradas com o mesmo nome compartilham a mesma chave, endpoint e estado de saúde. Para adicionar um gateway compatível com OpenAI como entrada separada da OpenAI, use o preset OpenRouter apontado para ele: defina OPENROUTER_API_KEY com a chave do gateway e OPENROUTER_API_URL com a URL completa de chat completions do gateway, e liste OPENROUTER junto de OPENAI na cadeia.