​

Fallback 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. agents.defaults.model.fallbacks configurados, em ordem.
3. O modelo primário configurado ao final, quando a execução começou a partir de uma substituição.

1. Resolver o modelo de sessão ativo e a preferência de perfil de autenticação.
2. Montar a cadeia de candidatos de modelo.
3. Tentar o provedor atual com regras de rotação/cooldown de perfil de autenticação.
4. Se esse provedor for esgotado com um erro elegível para failover, passar para o próximo candidato de modelo.
5. Persistir a substituição de fallback selecionada antes do início da nova tentativa, 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, reverter 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çar um FallbackSummaryError com detalhes por tentativa e a expiração de cooldown mais próxima, quando conhecida.

• 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).
• O estado de runtime do roteamento de autenticação fica em ~/.openclaw/agents/<agentId>/agent/auth-state.json.
• A configuração auth.profiles / auth.order é somente metadados + roteamento (sem segredos).
• Arquivo OAuth legado somente 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 email está disponível.
• OAuth com email: provider:<email> (por exemplo, google-antigravity:user@gmail.com).

​

Ordem de rotação

1. Configuração explícita: auth.order[provider] (se definido).
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 final, ordenados pela expiração mais próxima.

​

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

• a sessão seja redefinida (/new / /reset)
• uma compactação seja concluída (a contagem de compactação aumenta)
• o perfil entre em cooldown/esteja 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 está restrito a um modelo diferente.
• Janelas de cobrança/desabilitação ainda bloqueiam o perfil inteiro entre modelos.

• 1 minuto
• 5 minutos
• 25 minutos
• 1 hora (limite máximo)

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

​

Desabilitações por cobrança

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

• O backoff de cobrança começa em 5 horas, dobra a cada falha de cobrança e tem limite máximo de 24 horas.
• Os 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 no 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 é sempre o primeiro.
• Fallbacks configurados explicitamente são deduplicados, mas não filtrados pela allowlist 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 provedores, 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 acrescenta 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 é acrescentado ao final para que a cadeia possa retornar ao padrão normal assim que os candidatos anteriores forem esgotados.

​

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 cobrança
• LiveSessionModelSwitchError, que é normalizado para um caminho de failover para que um modelo persistido obsoleto não crie um loop externo de nova tentativa
• outros erros não reconhecidos quando ainda restam candidatos

• abortos explícitos que não têm formato de timeout/failover
• erros de estouro de contexto que devem permanecer dentro da lógica de compactação/nova 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 final desconhecido quando não restam candidatos

​

Comportamento de pular cooldown vs sondagem

• Falhas persistentes de autenticação ignoram o provedor inteiro imediatamente.
• Desabilitações por cobrança geralmente são ignoradas, mas o candidato primário ainda pode ser sondado com limitação para que a recuperação seja possível sem reiniciar.
• O candidato primário pode ser sondado perto da expiração do cooldown, com uma limitação por provedor.
• Modelos irmãos de fallback no mesmo provedor podem ser tentados apesar do cooldown quando a falha parece transitória (rate_limit, overloaded ou desconhecida). Isso é especialmente relevante quando um limite de taxa tem escopo de modelo e um modelo irmão pode ainda se recuperar imediatamente.
• Sondagens transitórias durante cooldown são limitadas a uma 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 alterações explícitas de modelo iniciadas pelo usuário marcam uma troca ao vivo pendente. Isso inclui /model, session_status(model=...) e sessions.patch.
• Alterações de modelo iniciadas pelo sistema, como rotação de fallback, substituições de heartbeat ou compactação, nunca marcam por conta própria uma troca ao vivo pendente.
• Antes de uma nova tentativa de fallback começar, o executor de resposta persiste os campos de substituição de fallback selecionados na entrada da sessão.
• A reconciliação de sessão ao vivo prefere substituições persistidas da sessão em vez de campos obsoletos de modelo em runtime.
• Se a tentativa de fallback falhar, o executor reverte apenas os campos de substituição que ele gravou, e somente se eles ainda corresponderem àquele candidato com falha.

1. O primário falha.
2. Um candidato de fallback é escolhido em memória.
3. O armazenamento da sessão ainda indica o primário antigo.
4. A reconciliação da sessão ao vivo lê o estado desatualizado da sessão.
5. A nova tentativa volta para o 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 semelhantes de failover)
• 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 tentada de provedor/modelo
• se o bloqueio restante for um limite de taxa correspondente com escopo de modelo, o OpenClaw informa a última expiração 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