Failover de modelo

OpenClaw lida com falhas em duas etapas:

1. Rotação de perfil de autenticação dentro do provedor atual.
2. Fallback de modelo para o próximo modelo em agents.defaults.model.fallbacks.

Este documento explica as regras em tempo de execução e os dados que dão suporte a elas.

# Fluxo em tempo de execução

Para uma execução normal de texto, o OpenClaw avalia candidatos nesta ordem:

Isso é intencionalmente mais restrito do que "salvar e restaurar a sessão inteira". O executor de resposta só persiste os campos de seleção de modelo que ele controla para fallback:

• providerOverride
• modelOverride
• modelOverrideSource
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

Isso impede que uma nova tentativa de fallback com falha sobrescreva mutações de sessão mais recentes e não relacionadas, como alterações manuais de /model ou atualizações de rotação de sessão que aconteceram enquanto a tentativa estava em execução.

# Política de origem de seleção

O OpenClaw separa o provedor/modelo selecionado do motivo pelo qual ele foi selecionado. Essa origem controla se a cadeia de fallback é permitida:

• Padrão configurado: agents.defaults.model.primary usa agents.defaults.model.fallbacks.
• Modelo primário do agente: agents.list[].model é estrito, a menos que esse objeto de modelo do agente inclua seus próprios fallbacks. Use fallbacks: [] para tornar o comportamento estrito explícito, ou forneça uma lista não vazia para habilitar fallback de modelo para esse agente.
• Substituição automática de fallback: um fallback em tempo de execução grava providerOverride, modelOverride e modelOverrideSource: "auto" antes de tentar novamente. Essa substituição automática pode continuar percorrendo a cadeia de fallback configurada e é limpa por /new, /reset e sessions.reset.
• Substituição de sessão pelo usuário: /model, o seletor de modelos, session_status(model=...) e sessions.patch gravam modelOverrideSource: "user". Essa é uma seleção exata da sessão. Se o provedor/modelo selecionado falhar antes de produzir uma resposta, o OpenClaw relata a falha em vez de responder a partir de um fallback configurado não relacionado.
• Substituição de sessão legada: entradas de sessão mais antigas podem ter modelOverride sem modelOverrideSource. O OpenClaw trata essas entradas como substituições de usuário para que uma seleção antiga explícita não seja silenciosamente convertida em comportamento de fallback.
• Modelo de payload de Cron: um payload.model / --model de tarefa cron é um modelo primário da tarefa, não uma substituição de sessão pelo usuário. Ele usa fallbacks configurados, a menos que a tarefa forneça payload.fallbacks; payload.fallbacks: [] torna a execução cron estrita.

# Armazenamento de autenticação (chaves + OAuth)

O OpenClaw usa perfis de autenticação tanto para chaves de API quanto para tokens OAuth.

• Segredos ficam em ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (legado: ~/.openclaw/agent/auth-profiles.json).
• O estado de roteamento de autenticação em tempo de execução fica em ~/.openclaw/agents/<agentId>/agent/auth-state.json.
• Configurações auth.profiles / auth.order são apenas metadados + roteamento (sem segredos).
• Arquivo OAuth legado somente para importação: ~/.openclaw/credentials/oauth.json (importado para auth-profiles.json no primeiro uso).

Mais detalhes: OAuth

Tipos de credencial:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl para alguns provedores)

# IDs de perfil

Logins OAuth criam perfis distintos para que várias contas possam coexistir.

• Padrão: provider:default quando nenhum e-mail está disponível.
• OAuth com e-mail: provider:<email> (por exemplo, google-antigravity:[email protected]).

Perfis ficam em ~/.openclaw/agents/<agentId>/agent/auth-profiles.json sob profiles.

# Ordem de rotação

Quando um provedor tem vários perfis, o OpenClaw escolhe uma ordem assim:

Se nenhuma ordem explícita estiver configurada, o OpenClaw usa uma ordem round-robin:

• Chave primária: tipo de perfil (OAuth antes de chaves de API).
• Chave secundária: usageStats.lastUsed (mais antigo primeiro, dentro de cada tipo).
• Perfis em cooldown/desabilitados são movidos para o fim, ordenados pela expiração mais próxima.

# Fixação de sessão (favorável a cache)

O OpenClaw fixa o perfil de autenticação escolhido por sessão para manter os caches do provedor aquecidos. Ele não rotaciona a cada solicitação. O perfil fixado é reutilizado até que:

• a sessão seja redefinida (/new / /reset)
• uma Compaction seja concluída (a contagem de compactação incrementa)
• o perfil esteja em cooldown/desabilitado

A seleção manual via /model …@<profileId> define uma substituição de usuário para essa sessão e não é rotacionada automaticamente até que uma nova sessão comece.

# Por que OAuth pode "parecer perdido"

Se você tiver tanto um perfil OAuth quanto um perfil de chave de API para o mesmo provedor, o round-robin pode alternar entre eles entre mensagens, a menos que estejam fixados. Para forçar um único perfil:

• Fixe com auth.order[provider] = ["provider:profileId"], ou
• Use uma substituição por sessão via /model … com uma substituição de perfil (quando houver suporte pela sua interface de UI/chat).

# Cooldowns

Quando um perfil falha devido a erros de autenticação/limite de taxa (ou um timeout que parece limitação de taxa), o OpenClaw o marca em cooldown e avança para o próximo perfil.

Cooldowns usam backoff exponencial:

• 1 minuto
• 5 minutos
• 25 minutos
• 1 hora (limite)

O estado é armazenado em auth-state.json sob usageStats:

{
  "usageStats": {
    "provider:profile": {
      "lastUsed": 1736160000000,
      "cooldownUntil": 1736160600000,
      "errorCount": 2
    }
  }
}

# Desabilitações por cobrança

Falhas de cobrança/crédito (por exemplo, "insufficient credits" / "credit balance too low") são tratadas como dignas de failover, mas geralmente não são transitórias. Em vez de um cooldown curto, o OpenClaw marca o perfil como desabilitado (com um backoff mais longo) e rotaciona para o próximo perfil/provedor.

O estado é armazenado em auth-state.json:

{
  "usageStats": {
    "provider:profile": {
      "disabledUntil": 1736178000000,
      "disabledReason": "billing"
    }
  }
}

Padrões:

• O backoff de cobrança começa em 5 horas, dobra por falha de cobrança e tem limite de 24 horas.
• Contadores de backoff são redefinidos se o perfil não falhar por 24 horas (configurável).
• Tentativas por sobrecarga permitem 1 rotação de perfil no mesmo provedor antes do fallback de modelo.
• Tentativas por sobrecarga usam backoff de 0 ms por padrão.

# Fallback de modelo

Se todos os perfis de um provedor falharem, o OpenClaw avança para o próximo modelo em agents.defaults.model.fallbacks. Isso se aplica a falhas de autenticação, limites de taxa e timeouts que esgotaram a rotação de perfis (outros erros não avançam o fallback). Erros de provedor que não expõem detalhes suficientes ainda são rotulados com precisão no estado de fallback: empty_response significa que o provedor não retornou nenhuma mensagem ou status utilizável, no_error_details significa que o provedor retornou explicitamente Unknown error (no error details in response), e unclassified significa que o OpenClaw preservou a prévia bruta, mas nenhum classificador correspondeu a ela ainda.

Erros de sobrecarga e limite de taxa são tratados de forma mais agressiva do que pausas por cobrança. Por padrão, o OpenClaw permite uma nova tentativa com o mesmo perfil de autenticação do provedor e, em seguida, muda para a próxima alternativa de modelo configurada sem esperar. Sinais de provedor ocupado, como ModelNotReadyException, entram nesse grupo de sobrecarga. Ajuste isso com auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs e auth.cooldowns.rateLimitedProfileRotations.

Quando uma execução começa a partir do primário padrão configurado, de um primário de tarefa Cron, de um primário de agente com alternativas explícitas ou de uma substituição de alternativa selecionada automaticamente, o OpenClaw pode percorrer a cadeia de alternativas configurada correspondente. Primários de agente sem alternativas explícitas e seleções explícitas do usuário (por exemplo, /model ollama/qwen3.5:27b, o seletor de modelo, sessions.patch ou substituições pontuais de provedor/modelo pela CLI) são estritos: se esse provedor/modelo estiver inacessível ou falhar antes de produzir uma resposta, o OpenClaw relata a falha em vez de responder a partir de uma alternativa não relacionada.

# Regras da cadeia de candidatos

O OpenClaw cria a lista de candidatos a partir do provider/model solicitado no momento mais as alternativas configuradas.

# Quais erros avançam para a alternativa

# Comportamento de pular pausa vs sondagem

Quando todos os perfis de autenticação de um provedor já estão em pausa, o OpenClaw não pula automaticamente esse provedor para sempre. Ele toma uma decisão por candidato:

# Substituições de sessão e troca de modelo ao vivo

Alterações de modelo da sessão são estado compartilhado. O executor ativo, o comando /model, atualizações de Compaction/sessão e a reconciliação de sessão ao vivo leem ou escrevem partes da mesma entrada de sessão.

Isso significa que novas tentativas com alternativas precisam ser coordenadas com a troca de modelo ao vivo:

• Somente alterações de modelo acionadas explicitamente pelo usuário marcam uma troca ao vivo pendente. Isso inclui /model, session_status(model=...) e sessions.patch.
• Alterações de modelo acionadas pelo sistema, como rotação de alternativa, substituições de Heartbeat ou Compaction, nunca marcam uma troca ao vivo pendente por conta própria.
• Substituições de modelo acionadas pelo usuário são tratadas como seleções exatas para a política de alternativas, então um provedor selecionado inacessível aparece como falha em vez de ser mascarado por agents.defaults.model.fallbacks.
• Antes de uma nova tentativa com alternativa começar, o executor de respostas persiste os campos da substituição de alternativa selecionada na entrada de sessão.
• Substituições automáticas de alternativa permanecem selecionadas nos turnos seguintes para que o OpenClaw não sonde um primário sabidamente problemático a cada mensagem. /new, /reset e sessions.reset limpam substituições de origem automática e retornam a sessão ao padrão configurado.
• /status mostra o modelo selecionado e, quando o estado da alternativa difere, o modelo de alternativa ativo e o motivo.
• A reconciliação de sessão ao vivo prefere substituições de sessão persistidas em vez de campos de modelo de runtime obsoletos.
• Se um erro de troca ao vivo apontar para um candidato posterior na cadeia de alternativas ativa, o OpenClaw salta diretamente para esse modelo selecionado em vez de percorrer candidatos não relacionados primeiro.
• Se a tentativa de alternativa falhar, o executor reverte apenas os campos de substituição que escreveu, e somente se eles ainda corresponderem a esse candidato com falha.

Isso evita a corrida clássica:

A substituição de alternativa persistida fecha essa janela, e a reversão restrita mantém intactas alterações manuais ou de runtime mais recentes na sessão.

# Observabilidade e resumos de falhas

runWithModelFallback(...) registra detalhes por tentativa que alimentam logs e mensagens de pausa voltadas ao usuário:

• provedor/modelo tentado
• motivo (rate_limit, overloaded, billing, auth, model_not_found e motivos semelhantes de failover)
• status/código opcional
• resumo de erro legível por humanos

Logs estruturados model_fallback_decision também incluem campos planos fallbackStep* quando um candidato falha, é pulado ou uma alternativa posterior tem sucesso. Esses campos tornam explícita a transição tentada (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome) para que exportadores de logs e diagnósticos possam reconstruir a falha primária mesmo quando a alternativa terminal também falha.

Quando todos os candidatos falham, o OpenClaw lança FallbackSummaryError. O executor externo de respostas pode usar isso para criar uma mensagem mais específica, como "todos os modelos estão temporariamente com limite de taxa", e incluir o vencimento de pausa mais próximo quando ele for conhecido.

Esse resumo de pausa reconhece modelos:

• limites de taxa com escopo de modelo não relacionados são ignorados para a cadeia de provedor/modelo tentada
• se o bloqueio restante for um limite de taxa com escopo de modelo correspondente, o OpenClaw relata o último vencimento correspondente que ainda bloqueia esse modelo

# Configuração relacionada

Consulte Configuração do Gateway para:

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• roteamento de agents.defaults.imageModel

Consulte Modelos para uma visão geral mais ampla da seleção de modelos e alternativas.