​

Conmutación por error de 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. Los agents.defaults.model.fallbacks configurados en orden.
3. El modelo principal configurado al final cuando la ejecución empezó 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 reglas de rotación y tiempo de enfriamiento del perfil de autenticación.
4. Si ese proveedor se agota con un error apto para conmutación por error, pasar al siguiente candidato de modelo.
5. Conservar la anulación de respaldo seleccionada antes de que comience el reintento para que otros lectores de sesión vean el mismo proveedor o 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 la expiración de tiempo de enfriamiento más próxima cuando se conozca.

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Almacenamiento de autenticación (claves + OAuth)

• Los secretos viven en ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (heredado: ~/.openclaw/agent/auth-profiles.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 (importado 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)

​

IDs de perfil

• Predeterminado: provider:default cuando no hay 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á configurado).
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 o deshabilitados se mueven al final, ordenados por la expiración más próxima.

​

Persistencia por sesión (favorable para caché)

• se reinicia la sesión (/new / /reset)
• se completa una compactación (se incrementa el recuento de compactación)
• el perfil está en enfriamiento o 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 UI/superficie de chat la admita).

​

Tiempos de enfriamiento

• OpenClaw registra cooldownModel para fallos por límite de tasa cuando se conoce el ID del modelo que falló.
• Aun así se puede probar un modelo hermano del mismo proveedor cuando el enfriamiento está limitado a un modelo diferente.
• Las ventanas de facturación o deshabilitación siguen bloqueando todo el perfil entre 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 empieza en 5 horas, se duplica por cada fallo de facturación y tiene un máximo de 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 deduplican, pero no se filtran por la lista de permitidos de modelos. Se tratan como intención explícita del operador.
• Si la ejecución actual ya está en un respaldo configurado de la misma familia de proveedor, OpenClaw sigue usando la cadena configurada completa.
• Si la ejecución actual está en un proveedor distinto del de la configuración y ese modelo actual no forma ya parte de la cadena de respaldos configurada, OpenClaw no añade respaldos configurados no relacionados de otro proveedor.
• Cuando la ejecución empezó desde una anulación, el modelo principal configurado se añade al final para que la cadena pueda volver al valor predeterminado normal una vez se agoten los candidatos anteriores.

​

Qué errores hacen avanzar el respaldo

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

• abortos explícitos que no tienen forma de tiempo de espera o conmutación por error
• 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

​

Omitir por enfriamiento frente a comportamiento de sondeo

• Los fallos persistentes de autenticación omiten todo el proveedor inmediatamente.
• Las deshabilitaciones por facturación normalmente se omiten, pero el candidato principal aún puede sondearse con limitación para que la recuperación sea posible sin reiniciar.
• El candidato principal puede sondearse cerca de la expiración del enfriamiento, con una limitación por proveedor.
• Los modelos hermanos 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 puede recuperarse de inmediato.
• Los sondeos transitorios en enfriamiento se limitan a uno por proveedor en cada ejecución de respaldo para que un solo proveedor no bloquee el respaldo entre proveedores.

​

Anulaciones de sesión y cambio de modelo en vivo

• Solo los cambios de modelo explícitos iniciados por el usuario marcan un cambio pendiente en vivo. Eso incluye /model, session_status(model=...) y sessions.patch.
• Los cambios de modelo impulsados por el sistema, como rotación de respaldo, anulaciones de heartbeat o compactación, nunca marcan por sí mismos un cambio pendiente en vivo.
• Antes de que empiece un reintento de respaldo, el ejecutor de respuestas conserva 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 persistidas de la sesión frente a campos obsoletos del modelo de 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 primario falla.
2. Se elige en memoria un candidato de respaldo.
3. El almacén de sesión aún indica el primario antiguo.
4. La reconciliación de sesión en vivo lee el estado obsoleto de la sesión.
5. El reintento vuelve al modelo antiguo antes de que comience el intento de respaldo.

​

Observabilidad y resúmenes de fallo

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

• se ignoran límites de tasa de otros modelos 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 la última expiración coincidente que todavía 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
• agents.defaults.imageModel routing