Conmutación por Error de Modelo

OpenClaw maneja fallos en dos fases:

1. Rotación de perfiles de autenticación dentro del proveedor actual.

2. ''Conmutación de modelo'' al siguiente modelo en ''agents.defaults.model.fallbacks''.

Este documento explica las reglas de runtime y los datos que las soportan.

OpenClaw usa perfiles de autenticación para claves API y tokens OAuth.

- Los secretos viven en ''~/.openclaw/agents/<agentId>/agent/auth-profiles.json'' (legado: ''~/.openclaw/agent/auth-profiles.json'').

- La configuración ''auth.profiles'' / ''auth.order'' es ''metadatos + enrutamiento'' (sin secretos).

- Importación legada solo OAuth: ''~/.openclaw/credentials/oauth.json'' (importado a ''auth-profiles.json'' en primer uso).

Más detalles: ''/concepts/oauth''

Tipos de credenciales:

- ''type: "api_key"'' → ''{ provider, key }''

- ''type: "oauth"'' → ''{ provider, access, refresh, expires, email? }'' (para algunos proveedores, + ''projectId''/''enterpriseUrl'')

Los logins OAuth crean perfiles distintos para que múltiples cuentas puedan coexistir.

- Predeterminado: ''provider:default'' (cuando no hay email disponible).

- OAuth con email: ''provider:<email>'' (ej., ''google-antigravity:[email protected]'').

Los perfiles viven bajo ''profiles'' en ''~/.openclaw/agents/<agentId>/agent/auth-profiles.json''.

Cuando un proveedor tiene múltiples perfiles, OpenClaw selecciona en este orden:

1. ''Configuración explícita'': ''auth.order[provider]'' (si está establecido).

2. ''Perfiles configurados'': ''auth.profiles'' filtrados por proveedor.

3. ''Perfiles almacenados'': entradas en el ''auth-profiles.json'' del proveedor.

Si no hay orden explícito configurado, OpenClaw usa un orden round-robin:

- Clave primaria: tipo de perfil (OAuth antes que clave API).

- ''Clave secundaria:'' ''usageStats.lastUsed'' (más antiguo primero dentro de cada tipo).

- Perfiles en cooldown/deshabilitados se mueven al final, ordenados por expiración más temprana.

#

OpenClaw fija el perfil de autenticación seleccionado por sesión para mantener calientes los cachés del proveedor.

No rota por solicitud. El perfil fijado se reutiliza hasta:

- Reinicio de sesión (''/new'' / ''/reset'')

- Compaction completa (contador de compaction incrementa)

- Perfil está en estado cooldown/deshabilitado

Selección manual via ''/model …@<profileId>'' establece un ''override de usuario'' para esa sesión

y no rota automáticamente hasta que una nueva sesión inicia.

Perfiles auto-fijados (elegidos por el router de sesión) son tratados como preferencias:

Se intentan primero, pero OpenClaw puede rotar a otro perfil en límite de tasa/timeout.

Perfiles fijados por usuario permanecen bloqueados a ese perfil; si falla y la conmutación de modelo

completa, OpenClaw se mueve al siguiente modelo en lugar de cambiar perfiles.

Si tienes perfiles OAuth y de clave API para el mismo proveedor, la rotación puede cambiar entre ellos a través de mensajes a menos que esté fijado. Para forzar un solo perfil:

- Fija con ''auth.order[provider] = ["provider:profileId"]'', o

- Usa override por sesión y override de perfil via ''/model …'' (cuando tu interfaz UI/chat lo soporta).

Cuando un perfil falla debido a errores de auth/límite de tasa (o parece un timeout

como límites de tasa), OpenClaw lo marca para cooldown y se mueve al siguiente perfil.

Errores de formato/solicitud inválida (ej., validaciones de ID de llamada de herramienta Cloud Code Assist)

son tratados como dignos de conmutación y usan el mismo cooldown.

Los cooldowns usan backoff exponencial:

- 1 minuto

- 5 minutos

- 25 minutos

- 1 hora (limitado)

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

Fallos de facturación/crédito (ej., "crédito insuficiente"/"balance de crédito muy bajo") son tratados como dignos de conmutación, pero usualmente no son transitorios. En lugar de un cooldown corto, OpenClaw marca el perfil como deshabilitado (con un backoff más largo) y rota al siguiente perfil/proveedor.

El estado se almacena en ''auth-profiles.json'':

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

Predeterminados:

- El backoff de facturación inicia en 5 horas, se duplica en cada fallo de facturación, limitado a 24 horas.

- Si un perfil no falla dentro de 24 horas, el contador de backoff se reinicia (configurable).

Si todos los perfiles de un proveedor fallan, OpenClaw se mueve al siguiente modelo en

''agents.defaults.model.fallbacks''. Esto aplica a fallos de auth, límites de tasa, y

timeouts que agotan la rotación de perfiles (otros errores no avanzan conmutaciones).

Cuando una ejecución inicia con un override de modelo (hook o CLI), las conmutaciones todavía intentan

''agents.defaults.model.primary'' después de cualquier conmutación configurada.

Ver ''Configuración de Gateway'' para:

- ''auth.profiles'' / ''auth.order''

- ''auth.cooldowns.billingBackoffHours'' / ''auth.cooldowns.billingBackoffHoursByProvider''

- ''auth.cooldowns.billingMaxHours'' / ''auth.cooldowns.failureWindowHours''

- ''agents.defaults.model.primary'' / ''agents.defaults.model.fallbacks''

ReferenceConceptsModelFailoverPage.step09.p6

ReferenceConceptsModelFailoverPage.step09.p7