Failover de modelos

OpenClaw maneja los fallos en dos etapas:

1. Rotación de perfiles de autenticación dentro del provider actual.
2. Fallback de modelo al siguiente modelo en agents.defaults.model.fallbacks.

Este documento explica las reglas del runtime y los datos que las respaldan.

Almacenamiento de autenticación (claves + OAuth)

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

• Los secretos residen en ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (legado: ~/.openclaw/agent/auth-profiles.json).
• Los valores de configuración auth.profiles / auth.order son solo metadatos + enrutamiento (sin secretos).
• Archivo OAuth heredado de solo importación: ~/.openclaw/credentials/oauth.json (importado a auth-profiles.json en el primer uso).

Más detalles: /concepts/oauth

Tipos de credenciales:

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

IDs de perfil

Los inicios de sesión OAuth crean perfiles distintos para que múltiples cuentas puedan coexistir.

• Por defecto: provider:default cuando no hay email disponible.
• OAuth con email: provider:<email> (por ejemplo google-antigravity:[email protected]).

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

Orden de rotación

Cuando un provider tiene múltiples perfiles, OpenClaw elige un orden así:

1. Configuración explícita: auth.order[provider] (si está configurado).
2. Perfiles configurados: auth.profiles filtrados por provider.
3. Perfiles almacenados: entradas en auth-profiles.json para el provider.

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

• Clave primaria: tipo de perfil (OAuth antes que claves API).
• Clave secundaria: usageStats.lastUsed (más antiguo primero, dentro de cada tipo).
• Los perfiles en cooldown/deshabilitados se mueven al final, ordenados por la expiración más cercana.

Afinidad de sesión (amigable con caché)

OpenClaw fija el perfil de autenticación elegido por sesión para mantener calientes las cachés del provider. No rota en cada solicitud. El perfil fijado se reutiliza hasta que:

• la sesión se resetea (/new / /reset)
• se completa una compactación (el conteo de compactaciones incrementa)
• el perfil está en cooldown/deshabilitado

La selección manual vía /model …@<profileId> establece una sobrescritura de usuario para esa sesión y no se auto-rota hasta que comience una nueva sesión.

Los perfiles auto-fijados (seleccionados por el enrutador de sesión) se tratan como una preferencia: se prueban primero, pero OpenClaw puede rotar a otro perfil por límites de tasa/timeouts. Los perfiles fijados por el usuario permanecen bloqueados en ese perfil; si falla y hay fallbacks de modelo configurados, OpenClaw pasa al siguiente modelo en lugar de cambiar de perfil.

Por qué OAuth puede “parecer perdido”

Si tienes tanto un perfil OAuth como un perfil de clave API para el mismo provider, el round-robin puede alternar entre ellos entre mensajes a menos que estén fijados. Para forzar un solo perfil:

• Fija con auth.order[provider] = ["provider:profileId"], o
• Usa una sobrescritura por sesión vía /model … con una sobrescritura de perfil (cuando lo soporte tu UI/superficie de chat).

Cooldowns

Cuando un perfil falla por errores de autenticación/límite de tasa (o un timeout que parece un límite de tasa), OpenClaw lo marca en cooldown y pasa al siguiente perfil. Los errores de formato/solicitud inválida (por ejemplo, fallos de validación de ID de llamada a herramienta de Cloud Code Assist) se tratan como dignos de failover y usan los mismos cooldowns. Los errores de stop-reason compatibles con OpenAI como Unhandled stop reason: error, stop reason: error y reason: error se clasifican como señales de timeout/failover.

Los cooldowns usan backoff exponencial:

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

El estado se almacena en auth-profiles.json bajo usageStats:

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

Deshabilitaciones por facturación

Los fallos de facturación/crédito (por ejemplo “insufficient credits” / “credit balance too low”) se tratan como dignos de failover, pero normalmente 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/provider.

El estado se almacena en auth-profiles.json:

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

Valores por defecto:

• El backoff por facturación comienza en 5 horas, se duplica por cada fallo de facturación y tiene un tope de 24 horas.
• Los contadores de backoff se resetean si el perfil no ha fallado durante 24 horas (configurable).

Fallback de modelo

Si todos los perfiles de un provider fallan, OpenClaw pasa al siguiente modelo en agents.defaults.model.fallbacks. Esto aplica a fallos de autenticación, límites de tasa y timeouts que agotaron la rotación de perfiles (otros errores no avanzan el fallback).

Cuando una ejecución comienza con una sobrescritura de modelo (hooks o CLI), los fallbacks aún terminan en agents.defaults.model.primary después de probar cualquier fallback configurado.

Configuración relacionada

Consulta Configuración del 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
• Enrutamiento de agents.defaults.imageModel

Consulta Modelos para la visión general más amplia de selección de modelos y fallback.