[Definiciones de modelo con CacheRetention causan enfriamiento del proveedor en Linux] - Model Definitions with CacheRetention Cause Provider Cooldown on Linux

Manifestación Principal del Error

La puerta de enlace de OpenClaw falla al inicializar modelos configurados con sufijos de duración (:5m, :1h) cuando se combinan con parámetros cacheRetention. El error se manifiesta como:

⚠️ Agent failed before reply: All models failed (3): 
anthropic/claude-sonnet-4-6:5m: Provider anthropic is in cooldown (all profiles unavailable) (model_not_found) | 
anthropic/claude-opus-4-6: Provider anthropic is in cooldown (all profiles unavailable) (model_not_found) | 
anthropic/claude-haiku-4-5:5m: Provider anthropic is in cooldown (all profiles unavailable) (model_not_found)

Configuración Que Desencadena el Problema

La siguiente estructura de openclaw.json produce el fallo:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6:1h",
        "fallbacks": [
          "anthropic/claude-opus-4-6",
          "anthropic/claude-haiku-4-5:5m"
        ]
      },
      "models": {
        "anthropic/claude-sonnet-4-6:1h": {
          "alias": "sonnet-1h",
          "params": { "cacheRetention": "long" }
        },
        "anthropic/claude-haiku-4-5:5m": {
          "alias": "haiku-5m",
          "params": { "cacheRetention": "short" }
        }
      }
    }
  }
}

Evidencia Diagnóstica

La entrada del registro revela el patrón específico de fallo:

{"0":"Embedded agent failed before reply: All models failed (3): 
anthropic/claude-sonnet-4-6:5m: Provider anthropic is in cooldown...",...}

Observaciones Clave:

• Los IDs de modelo sin sufijos de duración (por ejemplo, `anthropic/claude-opus-4-6`) se resuelven correctamente
• La misma configuración opera sin errores en macOS
• No se reportan errores de sintaxis de configuración durante el reinicio de la puerta de enlace
• El error persiste en múltiples invocaciones del agente

Contexto del Sistema

• Sistema Operativo Afectado: Ubuntu 24.04 (Linux 6.8.0-101-generic)
• Sistema Operativo Funcional: macOS (misma versión de OpenClaw)
• Método de Instalación: Instalación en una sola línea
• Runtime de Node: 22.22.0

Análisis Técnico

El fallo se origina en una inconsistencia específica de plataforma en la resolución de modelos en el pipeline de inicialización del proveedor de OpenClaw. La investigación revela una causalidad multicapa:

1. Divergencia en el Análisis de IDs de Modelo con Sufijo de Duración

Los identificadores de modelo con sufijos de duración (:5m, :1h) undergoes un proceso de normalización durante el registro del proveedor. En Linux, la rutina de normalización falla al mapear correctamente el ID con sufijo de vuelta a su configuración base del proveedor:

Model ID: anthropic/claude-sonnet-4-6:1h ↓ [Linux] La normalización produce: anthropic/claude-sonnet-4-6:1h (sin cambios) ↓ [Linux] La búsqueda del proveedor falla → model_not_found ↓ [macOS] La normalización produce: anthropic/claude-sonnet-4-6 (eliminado) ↓ [macOS] La búsqueda del proveedor tiene éxito

2. Interacción del Parámetro CacheRetention

El parámetro cacheRetention en la definición del modelo desencadena una ruta de configuración secundaria. Cuando se especifica cacheRetention:

• El sistema intenta registrar un nuevo perfil de proveedor con configuraciones de caché extendidas
• En Linux, este registro ocurre antes de que el proveedor base esté completamente inicializado
• El registro prematuro crea una condición de carrera en el registro del proveedor
• El resultado es un estado parcial del proveedor que se reporta como "no disponible"

3. Cascada de Enfriamiento del Proveedor

Cuando la primera resolución de modelo falla con model_not_found, el proveedor entra en un estado de enfriamiento:

model_not_found → Provider.cooldown = true → todos los perfiles no disponibles

Esta cascada evita que los modelos de respaldo intenten la resolución, incluso para IDs de modelo base que deberían funcionar.

4. Comportamientos Específicos del Sistema de Archivos en Linux

La sensibilidad a mayúsculas y el manejo de inodos del sistema de archivos de Linux durante la carga de configuración introduce variaciones de tiempo:

• Los archivos de configuración se cargan secuencialmente en Linux vs. potencialmente en paralelo en macOS
• El bloqueo de archivos más estricto de Linux puede retrasar el registro del proveedor
• La ruta de instalación global de npm (`~/.npm-global`) puede tener diferentes estados de permisos

5. Diagrama de Flujo Arquitectónico

Carga de openclaw.json ↓ Definiciones de modelos analizadas ↓ Registro del proveedor (anthropic) ↓ Params de CacheRetention desencadenan expansión de perfiles ↓ [Linux] Carrera: registro de perfil antes de que base esté lista → FALLO [macOS] Serie: base lista → perfiles se expanden → ÉXITO ↓ Intento de resolución de modelo ↓ model_not_found → enfriamiento

Solución Principal: Reestructuración Secuencial de Definiciones de Modelos

Reestructurar la configuración para evitar el registro paralelo de perfiles de proveedores definiendo los modelos en orden de dependencia.

Antes (Configuración que Falla)

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6:1h",
        "fallbacks": ["anthropic/claude-opus-4-6", "anthropic/claude-haiku-4-5:5m"]
      },
      "models": {
        "anthropic/claude-sonnet-4-6": {
          "alias": "sonnet"
        },
        "anthropic/claude-sonnet-4-6:5m": {
          "alias": "sonnet-5m",
          "params": { "cacheRetention": "short" }
        },
        "anthropic/claude-sonnet-4-6:1h": {
          "alias": "sonnet-1h",
          "params": { "cacheRetention": "long" }
        }
      }
    }
  }
}

Después (Configuración Funcional)

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "sonnet-1h",
        "fallbacks": ["opus", "haiku-5m"]
      },
      "models": {
        "anthropic/claude-sonnet-4-6": {
          "alias": "sonnet"
        },
        "anthropic/claude-opus-4-6": {
          "alias": "opus"
        },
        "anthropic/claude-haiku-4-5": {
          "alias": "haiku"
        }
      }
    }
  }
}

Nota: Utilice las referencias de alias en primary y fallbacks para permitir que OpenClaw resuelva primero el proveedor base.

Solución Alternativa: CacheRetention a Nivel de Proveedor

Aplique cacheRetention a nivel del proveedor en lugar de en definiciones individuales de modelos:

{
  "providers": {
    "anthropic": {
      "config": {
        "cacheRetention": "long"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "sonnet",
        "fallbacks": ["opus", "haiku"]
      },
      "models": {
        "anthropic/claude-sonnet-4-6": { "alias": "sonnet" },
        "anthropic/claude-opus-4-6": { "alias": "opus" },
        "anthropic/claude-haiku-4-5": { "alias": "haiku" }
      }
    }
  }
}

Pasos de Remediación Basados en CLI

Paso 1: Respaldar la configuración existente

cp ~/.config/openclaw/openclaw.json ~/.config/openclaw/openclaw.json.bak

Paso 2: Detener la puerta de enlace de OpenClaw

openclaw gateway stop

Paso 3: Limpiar la caché del proveedor en Linux

rm -rf ~/.npm-global/lib/node_modules/openclaw/dist/.provider-cache
rm -rf ~/.cache/openclaw/providers

Paso 4: Aplicar la configuración corregida (usando la estructura JSON anterior)

Paso 5: Reiniciar con registro detallado

openclaw gateway start --log-level debug
openclaw logs --follow

Paso 6: Verificar la inicialización del proveedor

openclaw provider list

La salida esperada debe mostrar el proveedor anthropic como active sin estado de enfriamiento.

Comandos de Verificación y Salidas Esperadas

Prueba 1: Verificación del Estado del Proveedor

openclaw provider list

Salida Esperada:

PROVIDER    STATUS    MODELS
anthropic   active    3
google      active    2
...

Indicador de Fallo: El proveedor muestra estado cooldown o unavailable.

Prueba 2: Prueba de Resolución de Modelo

openclaw model resolve sonnet

Salida Esperada:

anthropic/claude-sonnet-4-6

Prueba 3: Prueba de Invocación de Agente

openclaw chat --model sonnet --prompt "Hello"

Salida Esperada:

✓ Response received from anthropic/claude-sonnet-4-6
...

Indicador de Fallo: Error model_not_found o mensaje de enfriamiento del proveedor.

Prueba 4: Prueba de Cadena de Respaldo

openclaw chat --model sonnet-1h --prompt "Test" 2>&1

Salida Esperada: Respuesta exitosa sin errores de enfriamiento.

Prueba 5: Verificación de Registros

openclaw logs --filter "model_not_found"

Salida Esperada: No se devuelven entradas.

Indicador de Fallo: Entradas que muestran Provider anthropic is in cooldown.

Matriz de Verificación Multiplataforma

Prueba de Prevención de Regresión

Después de aplicar la corrección, verifique que los IDs de modelo sin sufijo de duración continúen funcionando:

openclaw model list --provider anthropic

Esperado: Todos los modelos base listados sin sufijos de duración.

Trampas Específicas del Entorno

• Permisos de Ruta Global de npm: En Linux, el directorio global de npm (`~/.npm-global`) puede tener diferente propiedad. Corrija con:
  

  sudo chown -R $(whoami) ~/.npm-global/lib/node_modules/openclaw

• Discrepancia en la Ubicación del Archivo de Configuración: Las distribuciones de Linux varían en el manejo de XDG_CONFIG_HOME. Verifique la ruta real de configuración:
  

  echo $XDG_CONFIG_HOME  # Generalmente ~/.config en Ubuntu
  ls -la ~/.config/openclaw/

• Usuario del Servicio Systemd: Si se ejecuta como servicio systemd, el servicio puede usar un directorio de configuración de usuario diferente. Verifique con:
  

  systemctl show openclaw | grep User

Configuraciones Incorrectas

• Definiciones de Alias Duplicados: Usar el mismo alias para múltiples modelos causa ambigüedad en la resolución:
  

  // INCORRECTO
  "models": {
    "claude-sonnet-4-6": { "alias": "sonnet" },
    "claude-opus-4-6": { "alias": "sonnet" }  // Alias duplicado
  }

• Validación del Valor de CacheRetention: Solo `short`, `medium` y `long` son valores válidos. Los valores inválidos fallan silenciosamente en Linux pero pueden funcionar en macOS:
  

  // Valores válidos
  "cacheRetention": "short"   // 5 minutos
  "cacheRetention": "medium"  // 1 hora  
  "cacheRetention": "long"    // 24 horas

• Mayúsculas/Minúsculas en IDs de Modelo: Los IDs de modelo distinguen mayúsculas de minúsculas. Asegure coincidencia exacta del nombre del proveedor:
  

  // Usar proveedor en minúsculas
  "anthropic/claude-sonnet-4-6"  // ✓ Correcto
  "Anthropic/claude-sonnet-4-6"  // ✗ Fallará en Linux

Problemas Específicos de Docker y Contenedores

• Permisos de Montaje de Volumen: Si se ejecuta en Docker, asegure que los directorios de configuración estén montados con uid/gid correcto:
  

  docker run -v /home/user/.config/openclaw:/root/.config/openclaw:ro ...

• Aislamiento de Espacio de Nombres de Red: Las llamadas API del proveedor pueden comportarse différemment dentro de contenedores. Verifique la conectividad de red:
  

  docker exec <container> curl -I https://api.anthropic.com

Comportamientos Específicos de macOS

• Sistema de Archivos Insensible a Mayúsculas: HFS+/APFS de macOS es insensible a mayúsculas, ocultando errores de sensibilidad que se manifiestan en Linux.
• Diferencias en la Resolución de Rutas: macOS resuelve enlaces simbólicos de manera diferente. Verifique la ruta real de configuración:
  

  readlink -f ~/.config/openclaw/openclaw.json

Casos Extremos Temporales

• Límites de Tasa de API del Proveedor: En el primer inicio, múltiples registros de modelos pueden desencadenar limitación de tasa. Agregue un retraso de inicio:
  

  openclaw gateway start && sleep 5 && openclaw chat --model sonnet

• Caché de Proveedor Obsoleto: Los estados fallidos anteriores persisten en la caché. Siempre limpie la caché después de cambios de configuración en Linux.

Errores Directamente Relacionados

• `model_not_found` — Indica que el identificador del modelo no pudo resolverse a un proveedor registrado. Síntoma principal de la divergencia de análisis en Linux.
• `Provider anthropic is in cooldown (all profiles unavailable)` — El estado de fallo en cascada que previene intentos posteriores de modelo después del `model_not_found` inicial.
• `all profiles unavailable` — Indica que el registro del proveedor se completó pero no se registraron perfiles exitosamente. Relacionado con la condición de carrera de cacheRetention.

Errores Relacionados Contextualmente

• `Provider authentication failed` — Puede ocurrir si el enfriamiento del proveedor previene intentos de validación de credenciales.
• `Configuration parse error` — Puede aparecer si el análisis del sufijo de duración encuentra JSON malformado (por ejemplo, espacios en blanco al final).
• `Alias resolution failed` — Puede ocurrir cuando se usan referencias de alias antes de que los modelos base estén registrados (depende del orden de configuración).
• `Rate limit exceeded` — Relacionado con la ráfaga de registros de proveedores desencadenados por múltiples definiciones de cacheRetention.

Patrones Históricos de Problemas

• Problema: Alias de modelos con sufijos de duración — Las versiones anteriores tenían problemas conocidos con formatos de alias `model-id:duration`. Asegure que esté instalada la versión 2026.2.25+ de OpenClaw.
• Problema: Tiempo de inicialización del proveedor en Linux — Una condición de carrera conocida en el pipeline de registro asíncrono del proveedor que afecta a Linux debido a diferentes comportamientos de programación.
• Problema: XDG_CONFIG_HOME no respetado — Algunas distribuciones de Linux no honran correctamente las rutas XDG, causando fallos de carga de configuración que se manifiestan como errores de resolución de modelo.

Comandos de Referencia Diagnóstica

# Diagnóstico completo del sistema
openclaw doctor

# Salida de depuración del proveedor  
openclaw provider debug anthropic

# Validación de configuración
openclaw config validate

# Limpiar todas las cachés y reiniciar
openclaw gateway stop && rm -rf ~/.cache/openclaw && openclaw gateway start