Configura el failover de modelos en OpenClaw

¿Te ha pasado que tu flujo de trabajo se detiene porque una API key alcanzó su límite o un token de OAuth expiró inesperadamente? Gestionar estos errores manualmente es una pérdida de tiempo y rompe la experiencia de desarrollo.

OpenClaw maneja los fallos en dos etapas:

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

Este documento explica las reglas de ejecución y los datos que las sustentan.

Almacenamiento de autenticación (keys + OAuth)

OpenClaw utiliza auth profiles tanto para API keys como para tokens de OAuth.

• Los secretos residen en ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (legacy: ~/.openclaw/agent/auth-profiles.json).
• La configuración en auth.profiles / auth.order es solo metadatos y enrutamiento (no contiene secretos).
• Archivo OAuth legacy solo para importación: ~/.openclaw/credentials/oauth.json (se importa 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 proveedores)

IDs de perfil

Los inicios de sesión por OAuth crean perfiles distintos para que varias cuentas puedan coexistir.

• Default: provider:default cuando no hay un email disponible.
• OAuth con email: provider:<email> (por ejemplo google-antigravity:user@gmail.com).

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

Orden de rotación

Cuando un proveedor tiene múltiples perfiles, OpenClaw elige un orden siguiendo esta lógica:

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

Si no hay un orden explícito configurado, OpenClaw utiliza un orden round‑robin:

• Clave primaria: tipo de perfil (OAuth antes que API keys).
• Clave secundaria: usageStats.lastUsed (el más antiguo primero, dentro de cada tipo).
• Perfiles en cooldown o desactivados se mueven al final, ordenados por su expiración más cercana.

Persistencia de sesión (amigable con la caché)

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

• la sesión se reinicia (/new / /reset)
• se completa una compactación (el contador de compactación aumenta)
• el perfil entra en cooldown o se desactiva

La selección manual mediante /model …@<profileId> establece un ajuste del usuario para esa sesión y no se rota automáticamente hasta que comience una nueva sesión.

Los perfiles fijados automáticamente (seleccionados por el router de la sesión) se tratan como una preferencia: se intentan primero, pero OpenClaw puede rotar a otro perfil si encuentra límites de tasa (rate limits) o timeouts. Los perfiles fijados por el usuario permanecen bloqueados a 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 un perfil OAuth y un perfil de API key para el mismo proveedor, el sistema round‑robin puede alternar entre ellos en distintos mensajes a menos que se fijen. Para forzar un único perfil:

• Fíjalo con auth.order[provider] = ["provider:profileId"], o
• Usa un ajuste por sesión mediante /model … con un perfil específico (si tu interfaz de chat lo permite).

Tiempos de espera (Cooldowns)

Cuando un perfil falla por errores de autenticación, rate-limit (o un timeout que parece un rate-limit), OpenClaw lo marca en cooldown y pasa al siguiente perfil. Los errores de formato o peticiones inválidas (por ejemplo, fallos de validación de ID en llamadas a herramientas de Cloud Code Assist) se consideran aptos para 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 o failover.

Los cooldowns usan un backoff exponencial:

• 1 minuto
• 5 minutos
• 25 minutos
• 1 hora (límite máximo)

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

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

Desactivación por facturación

Los fallos de facturación o créditos (por ejemplo, “insufficient credits” o “credit balance too low”) se consideran aptos para failover, pero normalmente no son temporales. En lugar de un cooldown corto, OpenClaw marca el perfil como desactivado (con un backoff más largo) y rota al siguiente perfil o proveedor.

El estado se almacena en auth-profiles.json:

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

Valores por defecto:

• El backoff de facturación comienza en 5 horas, se duplica por cada fallo de facturación y llega a un máximo de 24 horas.
• Los contadores de backoff se reinician si el perfil no ha fallado durante 24 horas (configurable).
• Los reintentos por sobrecarga permiten 1 rotación de perfil del mismo proveedor antes del fallback de modelo.
• Los reintentos por sobrecarga usan un backoff de 0 ms por defecto.

Fallback de modelos

Si todos los perfiles de un proveedor fallan, OpenClaw se mueve al siguiente modelo en agents.defaults.model.fallbacks. Esto aplica a fallos de autenticación, rate limits y timeouts que agotaron la rotación de perfiles (otros errores no activan el fallback).

Los errores por sobrecarga y rate-limit se manejan de forma más agresiva que los cooldowns de facturación. Por defecto, OpenClaw permite un reintento de perfil de autenticación en el mismo proveedor y luego cambia al siguiente modelo configurado sin esperar. Puedes ajustar esto con auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs, y auth.cooldowns.rateLimitedProfileRotations.

Cuando una ejecución comienza con un override de modelo (vía hooks o CLI), los fallbacks terminan en agents.defaults.model.primary después de intentar cualquier fallback configurado.

Configuración relacionada

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

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

AI Setup Assistant

Siguientes pasos

• Configuración del Gateway
• Conceptos de OAuth
• Gestión de Modelos