Conmutación por error del modelo

OpenClaw gestiona los errores en dos etapas:

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

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

# Flujo de runtime

Para una ejecución de texto normal, OpenClaw evalúa los candidatos en este orden:

Esto es intencionalmente más limitado que "guardar y restaurar toda la sesión". El ejecutor de respuestas solo persiste los campos de selección de modelo que le pertenecen para el respaldo:

• providerOverride
• modelOverride
• modelOverrideSource
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

Eso evita que un reintento de respaldo fallido sobrescriba mutaciones de sesión más nuevas y no relacionadas, como cambios manuales de /model o actualizaciones de rotación de sesión que ocurrieron mientras el intento estaba en ejecución.

# Política de origen de selección

OpenClaw separa el proveedor/modelo seleccionado del motivo por el que fue seleccionado. Ese origen controla si la cadena de respaldo está permitida:

• Valor predeterminado configurado: agents.defaults.model.primary usa agents.defaults.model.fallbacks.
• Modelo principal del agente: agents.list[].model es estricto a menos que ese objeto de modelo de agente incluya sus propios fallbacks. Usa fallbacks: [] para hacer explícito el comportamiento estricto, o proporciona una lista no vacía para habilitar el respaldo de modelo en ese agente.
• Anulación automática de respaldo: un respaldo de runtime escribe providerOverride, modelOverride y modelOverrideSource: "auto" antes de reintentar. Esa anulación automática puede seguir recorriendo la cadena de respaldo configurada y se borra con /new, /reset y sessions.reset.
• Anulación de sesión del usuario: /model, el selector de modelo, session_status(model=...) y sessions.patch escriben modelOverrideSource: "user". Esa es una selección exacta de sesión. Si el proveedor/modelo seleccionado falla antes de producir una respuesta, OpenClaw informa el fallo en lugar de responder desde un respaldo configurado no relacionado.
• Anulación de sesión heredada: las entradas de sesión antiguas pueden tener modelOverride sin modelOverrideSource. OpenClaw las trata como anulaciones de usuario para que una selección antigua explícita no se convierta silenciosamente en comportamiento de respaldo.
• Modelo de carga útil de Cron: un trabajo cron payload.model / --model es un modelo principal de trabajo, no una anulación de sesión del usuario. Usa los respaldos configurados a menos que el trabajo proporcione payload.fallbacks; payload.fallbacks: [] hace que la ejecución cron sea estricta.

# Almacenamiento de autenticación (claves + OAuth)

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

• Los secretos viven en ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (heredado: ~/.openclaw/agent/auth-profiles.json).
• El estado de enrutamiento de autenticación de runtime vive en ~/.openclaw/agents/<agentId>/agent/auth-state.json.
• La configuración auth.profiles / auth.order es solo metadatos + enrutamiento (sin secretos).
• Archivo OAuth heredado solo para importación: ~/.openclaw/credentials/oauth.json (se importa a auth-profiles.json en el primer uso).

Más detalles: OAuth

Tipos de credenciales:

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

# ID de perfiles

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

• Predeterminado: provider:default cuando no hay correo electrónico disponible.
• OAuth con correo electrónico: provider:<email> (por ejemplo google-antigravity:[email protected]).

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

# Orden de rotación

Cuando un proveedor tiene varios perfiles, OpenClaw elige un orden así:

Si no se configura un orden explícito, OpenClaw usa un orden round-robin:

• Clave principal: tipo de perfil (OAuth antes que claves de API).
• Clave secundaria: usageStats.lastUsed (los más antiguos primero, dentro de cada tipo).
• Los perfiles en enfriamiento/deshabilitados se mueven al final, ordenados por vencimiento más cercano.

# Fijación de sesión (compatible con caché)

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

• se restablece la sesión (/new / /reset)
• se completa una compactación (aumenta el recuento de compactación)
• el perfil está en enfriamiento/deshabilitado

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

# Por qué OAuth puede "parecer perdido"

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

• Fíjalo con auth.order[provider] = ["provider:profileId"], o
• Usa una anulación por sesión mediante /model … con una anulación de perfil (cuando tu superficie de UI/chat lo admita).

# Enfriamientos

Cuando un perfil falla por errores de autenticación/límite de tasa (o un tiempo de espera que parece un límite de tasa), OpenClaw lo marca en enfriamiento y pasa al siguiente perfil.

Los enfriamientos usan retroceso exponencial:

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

El estado se almacena en auth-state.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 aptos para conmutación por error, pero normalmente no son transitorios. En lugar de un enfriamiento corto, OpenClaw marca el perfil como deshabilitado (con un retroceso más largo) y rota al siguiente perfil/proveedor.

El estado se almacena en auth-state.json:

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

Valores predeterminados:

• El retroceso de facturación empieza en 5 horas, se duplica por cada fallo de facturación y tiene un tope de 24 horas.
• Los contadores de retroceso se restablecen si el perfil no ha fallado durante 24 horas (configurable).
• Los reintentos por sobrecarga permiten 1 rotación de perfil en el mismo proveedor antes del respaldo de modelo.
• Los reintentos por sobrecarga usan 0 ms de retroceso de forma predeterminada.

# Respaldo de modelo

Si todos los perfiles de un proveedor fallan, OpenClaw pasa al siguiente modelo en agents.defaults.model.fallbacks. Esto se aplica a fallos de autenticación, límites de tasa y tiempos de espera que agotaron la rotación de perfiles (otros errores no hacen avanzar el respaldo). Los errores de proveedor que no exponen suficiente detalle siguen etiquetándose con precisión en el estado de respaldo: empty_response significa que el proveedor no devolvió ningún mensaje o estado utilizable, no_error_details significa que el proveedor devolvió explícitamente Unknown error (no error details in response), y unclassified significa que OpenClaw conservó la vista previa sin procesar, pero ningún clasificador coincidió aún.

Los errores de sobrecarga y límite de tasa se gestionan de forma más agresiva que los periodos de espera de facturación. De forma predeterminada, OpenClaw permite un reintento de perfil de autenticación del mismo proveedor y luego cambia al siguiente respaldo de modelo configurado sin esperar. Las señales de proveedor ocupado, como ModelNotReadyException, entran en esa categoría de sobrecarga. Ajusta esto con auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs y auth.cooldowns.rateLimitedProfileRotations.

Cuando una ejecución comienza desde el principal predeterminado configurado, el principal de un trabajo cron, el principal de un agente con respaldos explícitos o una anulación de respaldo seleccionada automáticamente, OpenClaw puede recorrer la cadena de respaldos configurada correspondiente. Los principales de agente sin respaldos explícitos y las selecciones explícitas del usuario (por ejemplo, /model ollama/qwen3.5:27b, el selector de modelo, sessions.patch o anulaciones puntuales de proveedor/modelo de la CLI) son estrictos: si ese proveedor/modelo no está disponible o falla antes de producir una respuesta, OpenClaw informa del fallo en lugar de responder desde un respaldo no relacionado.

# Reglas de la cadena candidata

OpenClaw construye la lista de candidatos a partir del provider/model solicitado actualmente más los respaldos configurados.

# Qué errores hacen avanzar el respaldo

# Omisión de periodo de espera frente a comportamiento de sondeo

Cuando todos los perfiles de autenticación de un proveedor ya están en periodo de espera, OpenClaw no omite automáticamente ese proveedor para siempre. Toma una decisión por candidato:

# Anulaciones de sesión y cambio de modelo en vivo

Los cambios de modelo de sesión son estado compartido. El ejecutor activo, el comando /model, las actualizaciones de compaction/sesión y la reconciliación de sesión en vivo leen o escriben partes de la misma entrada de sesión.

Eso significa que los reintentos de respaldo tienen que coordinarse con el cambio de modelo en vivo:

• Solo los cambios de modelo explícitos impulsados por el usuario marcan un cambio en vivo pendiente. Eso incluye /model, session_status(model=...) y sessions.patch.
• Los cambios de modelo impulsados por el sistema, como la rotación de respaldo, las anulaciones de Heartbeat o compaction, nunca marcan por sí solos un cambio en vivo pendiente.
• Las anulaciones de modelo impulsadas por el usuario se tratan como selecciones exactas para la política de respaldo, por lo que un proveedor seleccionado que no esté disponible se muestra como fallo en lugar de quedar oculto por agents.defaults.model.fallbacks.
• Antes de que empiece un reintento de respaldo, el ejecutor de respuestas persiste los campos de anulación de respaldo seleccionados en la entrada de sesión.
• Las anulaciones de respaldo automáticas permanecen seleccionadas en turnos posteriores para que OpenClaw no sondee un principal conocido como defectuoso en cada mensaje. /new, /reset y sessions.reset borran las anulaciones de origen automático y devuelven la sesión al valor predeterminado configurado.
• /status muestra el modelo seleccionado y, cuando el estado de respaldo difiere, el modelo de respaldo activo y el motivo.
• La reconciliación de sesión en vivo prefiere las anulaciones de sesión persistidas frente a campos de modelo de ejecución obsoletos.
• Si un error de cambio en vivo apunta a un candidato posterior en la cadena de respaldos activa, OpenClaw salta directamente a ese modelo seleccionado en lugar de recorrer primero candidatos no relacionados.
• Si el intento de respaldo falla, el ejecutor revierte solo los campos de anulación que escribió, y solo si aún coinciden con ese candidato fallido.

Esto evita la carrera clásica:

La anulación de respaldo persistida cierra esa ventana, y la reversión acotada mantiene intactos los cambios de sesión manuales o de ejecución más recientes.

# Observabilidad y resúmenes de fallos

runWithModelFallback(...) registra detalles por intento que alimentan los registros y los mensajes de periodos de espera visibles para el usuario:

• proveedor/modelo intentado
• motivo (rate_limit, overloaded, billing, auth, model_not_found y motivos de conmutación por error similares)
• estado/código opcional
• resumen de error legible para humanos

Los registros estructurados model_fallback_decision también incluyen campos planos fallbackStep* cuando un candidato falla, se omite o un respaldo posterior tiene éxito. Estos campos hacen explícita la transición intentada (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome) para que los exportadores de registros y diagnósticos puedan reconstruir el fallo principal incluso cuando el respaldo terminal también falla.

Cuando todos los candidatos fallan, OpenClaw lanza FallbackSummaryError. El ejecutor de respuestas externo puede usarlo para crear un mensaje más específico, como "todos los modelos están limitados temporalmente por tasa", e incluir la expiración de periodo de espera más próxima cuando se conozca.

Ese resumen de periodo de espera tiene en cuenta el modelo:

• se ignoran los límites de tasa con alcance de modelo no relacionados para la cadena de proveedor/modelo intentada
• si el bloqueo restante es un límite de tasa con alcance de modelo coincidente, OpenClaw informa de la última expiración coincidente que todavía bloquea ese modelo

# Configuración relacionada

Consulta Configuración de 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 una visión general más amplia de la selección de modelos y los respaldos.