​

Respaldo entre modelos

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

​

Flujo de tiempo de ejecución

1. El modelo de sesión seleccionado actualmente.
2. agents.defaults.model.fallbacks configurados, en orden.
3. El modelo principal configurado al final cuando la ejecución comenzó desde una anulación.

1. Resolver el modelo de sesión activo y la preferencia de perfil de autenticación.
2. Construir la cadena de candidatos de modelo.
3. Probar el proveedor actual con las reglas de rotación/enfriamiento de perfiles de autenticación.
4. Si ese proveedor se agota con un error que amerita respaldo, pasar al siguiente candidato de modelo.
5. Persistir la anulación de respaldo seleccionada antes de que comience el reintento para que otros lectores de la sesión vean el mismo proveedor/modelo que el ejecutor está a punto de usar.
6. Si el candidato de respaldo falla, revertir solo los campos de anulación de sesión que pertenecen al respaldo cuando todavía coincidan con ese candidato fallido.
7. Si todos los candidatos fallan, lanzar un FallbackSummaryError con detalles por intento y el vencimiento de enfriamiento más próximo cuando se conozca.

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Almacenamiento de autenticación (claves + OAuth)

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

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

​

ID de perfiles

• Predeterminado: provider:default cuando no hay un correo electrónico disponible.
• OAuth con correo electrónico: provider:<email> (por ejemplo, google-antigravity:user@gmail.com).

​

Orden de rotación

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.

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

​

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

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

​

Por qué OAuth puede “parecer perdido”

• 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 interfaz/superficie de chat lo admita).

​

Enfriamientos

• OpenClaw registra cooldownModel para fallos de límite de tasa cuando se conoce el ID del modelo que falló.
• Un modelo hermano en el mismo proveedor todavía puede intentarse cuando el enfriamiento tiene alcance para un modelo diferente.
• Las ventanas de facturación/deshabilitación siguen bloqueando todo el perfil en todos los modelos.

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

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

​

Deshabilitaciones por facturación

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

• El retroceso por facturación comienza en 5 horas, se duplica por cada fallo de facturación y se limita a 24 horas.
• Los contadores de retroceso 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 respaldo de modelo.
• Los reintentos por sobrecarga usan 0 ms de retroceso de forma predeterminada.

​

Respaldo de modelo

​

Reglas de la cadena de candidatos

• El modelo solicitado siempre va primero.
• Los respaldos configurados explícitamente se desduplican, pero no se filtran por la lista de modelos permitidos. Se tratan como intención explícita del operador.
• Si la ejecución actual ya está en un respaldo configurado dentro de la misma familia de proveedor, OpenClaw sigue usando la cadena configurada completa.
• Si la ejecución actual está en un proveedor diferente al de la configuración y ese modelo actual no forma ya parte de la cadena de respaldo configurada, OpenClaw no agrega respaldos configurados no relacionados de otro proveedor.
• Cuando la ejecución comenzó desde una anulación, el principal configurado se agrega al final para que la cadena pueda volver al valor predeterminado normal una vez que se agoten los candidatos anteriores.

​

Qué errores hacen avanzar el respaldo

• fallos de autenticación
• límites de tasa y agotamiento del enfriamiento
• errores de sobrecarga/proveedor ocupado
• errores de tiempo de espera aptos para respaldo
• deshabilitaciones por facturación
• LiveSessionModelSwitchError, que se normaliza a una ruta de respaldo para que un modelo persistido obsoleto no cree un bucle de reintento externo
• otros errores no reconocidos cuando todavía quedan candidatos

• abortos explícitos que no tienen forma de tiempo de espera/respaldo
• errores de desbordamiento de contexto que deben permanecer dentro de la lógica de compactación/reintento (por ejemplo, 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 o ollama error: context length exceeded)
• un error desconocido final cuando ya no quedan candidatos

​

Comportamiento de omisión por enfriamiento frente a sondeo

• Los fallos persistentes de autenticación omiten inmediatamente todo el proveedor.
• Las deshabilitaciones por facturación normalmente se omiten, pero el candidato principal todavía puede sondearse con una limitación para que la recuperación sea posible sin reiniciar.
• El candidato principal puede sondearse cerca del vencimiento del enfriamiento, con una limitación por proveedor.
• Los modelos hermanos de respaldo del mismo proveedor pueden intentarse a pesar del enfriamiento cuando el fallo parece transitorio (rate_limit, overloaded o desconocido). Esto es especialmente relevante cuando un límite de tasa tiene alcance de modelo y un modelo hermano aún puede recuperarse de inmediato.
• Los sondeos transitorios durante el enfriamiento se limitan a uno por proveedor en cada ejecución de respaldo para que un solo proveedor no retrase el respaldo entre proveedores.

​

Anulaciones de sesión y 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 por heartbeat o la compactación, nunca marcan por sí solos un cambio en vivo pendiente.
• Antes de que comience un reintento de respaldo, el ejecutor de respuestas persiste los campos de anulación de respaldo seleccionados en la entrada de sesión.
• La reconciliación de sesión en vivo prefiere las anulaciones de sesión persistidas sobre los campos obsoletos del modelo en tiempo de ejecución.
• Si el intento de respaldo falla, el ejecutor revierte solo los campos de anulación que escribió, y solo si todavía coinciden con ese candidato fallido.

1. El principal falla.
2. El candidato de respaldo se elige en memoria.
3. El almacenamiento de la sesión todavía indica el principal anterior.
4. La reconciliación de sesión en vivo lee el estado obsoleto de la sesión.
5. El reintento vuelve al modelo anterior antes de que comience el intento de respaldo.

​

Observabilidad y resúmenes de fallos

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

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

​

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