​

Failover de modelo

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.

​

Fluxo de runtime

1. O modelo de sessão atualmente selecionado.
2. Os agents.defaults.model.fallbacks configurados, em ordem.
3. O modelo primário configurado no final, quando a execução começou a partir de uma substituição.

1. Resolve o modelo de sessão ativo e a preferência de perfil de autenticação.
2. Constrói a cadeia de candidatos de modelo.
3. Tenta o provedor atual com regras de rotação/cooldown de perfil de autenticação.
4. Se esse provedor se esgotar com um erro elegível para failover, passa para o próximo candidato de modelo.
5. Persiste a substituição de fallback selecionada antes de a nova tentativa começar, para que outros leitores da sessão vejam o mesmo provedor/modelo que o executor está prestes a usar.
6. Se o candidato de fallback falhar, reverte apenas os campos de substituição da sessão pertencentes ao fallback quando eles ainda corresponderem àquele candidato com falha.
7. Se todos os candidatos falharem, lança um FallbackSummaryError com detalhes por tentativa e o vencimento de cooldown mais próximo, quando conhecido.

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Armazenamento de autenticação (chaves + OAuth)

• Os segredos ficam em ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (legado: ~/.openclaw/agent/auth-profiles.json).
• A configuração auth.profiles / auth.order é apenas metadados + roteamento (sem segredos).
• Arquivo OAuth legado apenas para importação: ~/.openclaw/credentials/oauth.json (importado para auth-profiles.json no primeiro uso).

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

​

IDs de perfil

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

​

Ordem de rotação

1. Configuração explícita: auth.order[provider] (se definida).
2. Perfis configurados: auth.profiles filtrados por provedor.
3. Perfis armazenados: entradas em auth-profiles.json para o provedor.

• 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 pelo vencimento mais próximo.

​

Persistência por sessão (favorável a cache)

• a sessão seja redefinida (/new / /reset)
• uma compactação seja concluída (o contador de compactação é incrementado)
• o perfil entre em cooldown/seja desabilitado

​

Por que o OAuth pode “parecer perdido”

• Fixe com auth.order[provider] = ["provider:profileId"], ou
• Use uma substituição por sessão via /model … com uma substituição de perfil (quando compatível com sua UI/superfície de chat).

​

Cooldowns

• O OpenClaw registra cooldownModel para falhas de limite de taxa quando o id do modelo com falha é conhecido.
• Um modelo irmão no mesmo provedor ainda pode ser tentado quando o cooldown tiver escopo de um modelo diferente.
• Janelas de faturamento/desabilitação ainda bloqueiam o perfil inteiro em todos os modelos.

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

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

​

Desabilitações por faturamento

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

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

​

Fallback de modelo

​

Regras da cadeia de candidatos

• O modelo solicitado vem sempre primeiro.
• Fallbacks configurados explicitamente são deduplicados, mas não filtrados pela lista de permissões de modelos. Eles são tratados como intenção explícita do operador.
• Se a execução atual já estiver em um fallback configurado na mesma família de provedor, o OpenClaw continua usando a cadeia configurada completa.
• Se a execução atual estiver em um provedor diferente do da configuração e esse modelo atual ainda não fizer parte da cadeia de fallback configurada, o OpenClaw não anexa fallbacks configurados e não relacionados de outro provedor.
• Quando a execução começou a partir de uma substituição, o primário configurado é anexado ao final para que a cadeia possa voltar ao padrão normal depois que os candidatos anteriores se esgotarem.

​

Quais erros avançam o fallback

• falhas de autenticação
• limites de taxa e esgotamento de cooldown
• erros de sobrecarga/provedor ocupado
• erros de failover com formato de timeout
• desabilitações por faturamento
• LiveSessionModelSwitchError, que é normalizado para um caminho de failover para que um modelo persistido obsoleto não crie um loop de nova tentativa externo
• outros erros não reconhecidos quando ainda houver candidatos restantes

• abortos explícitos que não tenham formato de timeout/failover
• erros de estouro de contexto que devem permanecer dentro da lógica de compactação/tentativa (por exemplo request_too_large, INVALID_ARGUMENT: input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, The input is too long for the model ou ollama error: context length exceeded)
• um erro desconhecido final quando não restarem candidatos

​

Comportamento de ignorar cooldown vs testar

• Falhas persistentes de autenticação ignoram o provedor inteiro imediatamente.
• Desabilitações por faturamento normalmente são ignoradas, mas o candidato primário ainda pode ser testado com throttling para permitir recuperação sem reiniciar.
• O candidato primário pode ser testado perto do vencimento do cooldown, com throttling por provedor.
• Irmãos de fallback no mesmo provedor podem ser tentados apesar do cooldown quando a falha parecer transitória (rate_limit, overloaded ou desconhecida). Isso é especialmente relevante quando um limite de taxa tem escopo por modelo e um modelo irmão pode ainda se recuperar imediatamente.
• Testes transitórios de cooldown ficam limitados a um por provedor por execução de fallback, para que um único provedor não atrase o fallback entre provedores.

​

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

• Apenas mudanças explícitas de modelo acionadas pelo usuário marcam uma troca ao vivo pendente. Isso inclui /model, session_status(model=...) e sessions.patch.
• Mudanças de modelo conduzidas pelo sistema, como rotação de fallback, substituições de heartbeat ou compactação, nunca marcam por si só uma troca ao vivo pendente.
• Antes que uma nova tentativa de fallback comece, o executor de resposta persiste os campos de substituição do fallback selecionado na entrada da sessão.
• A reconciliação de sessão ao vivo prefere substituições persistidas da sessão a campos de modelo obsoletos do runtime.
• Se a tentativa de fallback falhar, o executor reverte apenas os campos de substituição que escreveu, e somente se eles ainda corresponderem àquele candidato com falha.

1. O primário falha.
2. O candidato de fallback é escolhido na memória.
3. O armazenamento da sessão ainda indica o primário antigo.
4. A reconciliação de sessão ao vivo lê o estado obsoleto da sessão.
5. A nova tentativa volta ao modelo antigo antes que a tentativa de fallback comece.

​

Observabilidade e resumos de falha

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

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

​

Configuração relacionada

• 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