Modelldefinitionen mit CacheRetention verursachen Provider-Cooldown unter Linux - Model Definitions with CacheRetention Cause Provider Cooldown on Linux

Primäre Fehleräußerung

Das OpenClaw-Gateway kann Modelle, die mit Dauersuffixen (:5m, :1h) konfiguriert sind, nicht initialisieren, wenn sie mit cacheRetention-Parametern kombiniert werden. Der Fehler äußert sich wie folgt:

⚠️ 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)

Konfiguration, die das Problem auslöst

Die folgende openclaw.json-Struktur verursacht den Fehler:

{
  "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" }
        }
      }
    }
  }
}

Diagnostische Hinweise

Der Logeintrag zeigt das spezifische Fehlermuster:

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

Wichtige Beobachtungen:

• Model-IDs ohne Dauersuffix (z.B. `anthropic/claude-opus-4-6`) werden korrekt aufgelöst
• Die gleiche Konfiguration funktioniert fehlerfrei auf macOS
• Keine Konfigurationssyntaxfehler werden beim Gateway-Neustart gemeldet
• Der Fehler bleibt über mehrere Agent-Aufrufe hinweg bestehen

Systemkontext

• Betroffenes Betriebssystem: Ubuntu 24.04 (Linux 6.8.0-101-generic)
• Funktionierendes Betriebssystem: macOS (gleiche OpenClaw-Version)
• Installationsmethode: One-Liner-Installation
• Node-Laufzeit: 22.22.0

Technische Analyse

Der Fehler stammt aus einer plattformspezifischen Inkonsistenz bei der Model-Auflösung in OpenClaws Provider-Initialisierungspipeline. Die Untersuchung zeigt eine mehrschichtige Verursachung:

1. Abweichung bei der Parsing von Model-IDs mit Dauersuffix

Model-Identifikatoren mit Dauersuffixen (:5m, :1h) durchlaufen während der Provider-Registrierung einen Normalisierungsprozess. Unter Linux scheitert die Normalisierungsroutine daran, die suffixed ID korrekt auf ihre Basis-Provider-Konfiguration abzubilden:

Model ID: anthropic/claude-sonnet-4-6:1h ↓ [Linux] Normalisierung erzeugt: anthropic/claude-sonnet-4-6:1h (unverändert) ↓ [Linux] Provider-Lookup schlägt fehl → model_not_found ↓ [macOS] Normalisierung erzeugt: anthropic/claude-sonnet-4-6 (entfernt) ↓ [macOS] Provider-Lookup erfolgreich

2. CacheRetention-Parameter-Interaktion

Der cacheRetention-Parameter in der Model-Definition löst einen sekundären Konfigurationspfad aus. Wenn cacheRetention angegeben ist:

• Das System versucht, ein neues Provider-Profil mit erweiterten Cache-Einstellungen zu registrieren
• Unter Linux erfolgt diese Registrierung, bevor der Basis-Provider vollständig initialisiert ist
• Die vorzeitige Registrierung erzeugt einen Race-Condition im Provider-Registry
• Das Ergebnis ist ein partieller Provider-Status, der als „nicht verfügbar" gemeldet wird

3. Provider-Cooldown-Kaskade

Wenn die erste Model-Auflösung mit model_not_found fehlschlägt, tritt der Provider in einen Cooldown-Status ein:

model_not_found → Provider.cooldown = true → alle Profile nicht verfügbar

Diese Kaskade verhindert, dass Fallback-Modelle einen Auflösungsversuch unternehmen, selbst für Basis-Model-IDs, die funktionieren sollten.

4. Plattformspezifische Dateisystem-Verhaltensweisen

Die Groß-/Kleinschreibungsempfindlichkeit des Linux-Dateisystems und die Inode-Behandlung beim Laden der Konfiguration führen zu zeitlichen Abweichungen:

• Konfigurationsdateien werden unter Linux sequenziell geladen, im Gegensatz zu potenziell parallel auf macOS
• Linux' strengere Dateisperrung kann die Provider-Registrierung verzögern
• Der npm-Global-Installationspfad (`~/.npm-global`) kann unterschiedliche Berechtigungszustände haben

5. Architektonischer Ablaufplan

openclaw.json laden ↓ Model-Definitionen geparst ↓ Provider-Registrierung (anthropic) ↓ CacheRetention-Parameter lösen Profile-Erweiterung aus ↓ [Linux] Race: Profilregistrierung vor Basis bereit → FEHLER [macOS] Seriell: Basis bereit → Profile erweitern → ERFOLG ↓ Model-Auflösungsversuch ↓ model_not_found → cooldown

Primäre Lösung: Sequenzielle Model-Definition-Umstrukturierung

Restrukturieren Sie die Konfiguration, um parallele Provider-Profilregistrierung zu vermeiden, indem Sie Modelle in Abhängigkeitsreihenfolge definieren.

Vorher (Fehlerhafte Konfiguration)

{
  "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" }
        }
      }
    }
  }
}

Nachher (Funktionierende Konfiguration)

{
  "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"
        }
      }
    }
  }
}

Hinweis: Verwenden Sie die alias-Referenzen in primary und fallbacks, damit OpenClaw den Basis-Provider zuerst auflöst.

Alternative Lösung: Provider-Bereichsbezogener CacheRetention

Wenden Sie cacheRetention auf Provider-Ebene anstelle einzelner Model-Definitionen an:

{
  "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" }
      }
    }
  }
}

CLI-basierte Behebungsschritte

Schritt 1: Bestehende Konfiguration sichern

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

Schritt 2: OpenClaw-Gateway stoppen

openclaw gateway stop

Schritt 3: Provider-Cache auf Linux leeren

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

Schritt 4: Korrigierte Konfiguration anwenden (mit der JSON-Struktur oben)

Schritt 5: Mit ausführlichem Logging neu starten

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

Schritt 6: Provider-Initialisierung überprüfen

openclaw provider list

Die erwartete Ausgabe sollte zeigen, dass der anthropic-Provider als active ohne Cooldown-Status angezeigt wird.

Verifizierungsbefehle und erwartete Ausgaben

Test 1: Provider-Statusprüfung

openclaw provider list

Erwartete Ausgabe:

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

Fehlerindikator: Provider zeigt cooldown- oder unavailable-Status.

Test 2: Model-Auflösungs-Test

openclaw model resolve sonnet

Erwartete Ausgabe:

anthropic/claude-sonnet-4-6

Test 3: Agent-Aufruf-Test

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

Erwartete Ausgabe:

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

Fehlerindikator: model_not_found-Fehler oder Provider-Cooldown-Meldung.

Test 4: Fallback-Ketten-Test

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

Erwartete Ausgabe: Erfolgreiche Antwort ohne Cooldown-Fehler.

Test 5: Log-Verifizierung

openclaw logs --filter "model_not_found"

Erwartete Ausgabe: Keine zurückgegebenen Einträge.

Fehlerindikator: Einträge, die Provider anthropic is in cooldown zeigen.

Plattformübergreifende Verifizierungsmatrix

Regression-Verhinderungs-Test

Nach dem Anwenden des Fixes verifizieren Sie, dass einfache Model-IDs weiterhin funktionieren:

openclaw model list --provider anthropic

Erwartet: Alle Basismodelle ohne Dauersuffixe aufgelistet.

Umgebungsspezifische Fallen

• npm-Global-Pfad-Berechtigungen: Unter Linux kann das npm-Global-Verzeichnis (`~/.npm-global`) unterschiedliches Eigentum haben. Beheben Sie mit:
  

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

• Konfigurationsdatei-Standort-Abweichung: Linux-Distributionen variieren in der XDG_CONFIG_HOME-Behandlung. Überprüfen Sie den tatsächlichen Konfigurationspfad:
  

  echo $XDG_CONFIG_HOME  # Üblicherweise ~/.config auf Ubuntu
  ls -la ~/.config/openclaw/

• Systemd-Dienstbenutzer: Bei Ausführung als Systemd-Dienst kann der Dienst ein anderes Benutzerkonfigurationsverzeichnis verwenden. Überprüfen Sie mit:
  

  systemctl show openclaw | grep User

Konfigurationsfehlkonfigurationen

• Doppelte Alias-Definitionen: Die Verwendung desselben Alias für mehrere Modelle verursacht Auflösungsmehrdeutigkeit:
  

  // FALSCH
  "models": {
    "claude-sonnet-4-6": { "alias": "sonnet" },
    "claude-opus-4-6": { "alias": "sonnet" }  // Doppelter Alias
  }

• CacheRetention-Wertvalidierung: Nur `short`, `medium` und `long` sind gültige Werte. Ungültige Werte scheitern unter Linux stillschweigend, können aber auf macOS funktionieren:
  

  // Gültige Werte
  "cacheRetention": "short"   // 5 Minuten
  "cacheRetention": "medium"  // 1 Stunde  
  "cacheRetention": "long"    // 24 Stunden

• Model-ID-Groß-/Kleinschreibung: Model-IDs sind groß-/kleinschreibungsempfindlich. Stellen Sie exakte Provider-Namensübereinstimmung sicher:
  

  // Kleinbuchstaben-Provider verwenden
  "anthropic/claude-sonnet-4-6"  // ✓ Korrekt
  "Anthropic/claude-sonnet-4-6"  // ✗ Schlägt unter Linux fehl

Docker- und Container-spezifische Probleme

• Volume-Mount-Berechtigungen: Bei Ausführung in Docker stellen Sie sicher, dass Konfigurationsverzeichnisse mit korrekter uid/gid gemountet werden:
  

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

• Netzwerk-Namespace-Isolation: Provider-API-Aufrufe können sich innerhalb von Containern unterschiedlich verhalten. Überprüfen Sie die Netzwerkverbindung:
  

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

macOS-spezifische Verhaltensweisen

• Groß-/Kleinschreibungsunempfindliches Dateisystem: macOS HFS+/APFS ist groß-/kleinschreibungsunempfindlich und verbirgt Groß-/Kleinschreibungsprobleme, die auf Linux auftreten.
• Pfadauflösungsunterschiede: macOS löst Symlinks unterschiedlich auf. Überprüfen Sie den tatsächlichen Konfigurationspfad:
  

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

Zeitliche Randfälle

• Provider-API-Ratenbegrenzungen: Beim ersten Start können mehrere Model-Registrierungen Ratenbegrenzung auslösen. Fügen Sie eine Startverzögerung hinzu:
  

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

• Veralteter Provider-Cache: Vorherige fehlgeschlagene Zustände bleiben im Cache. Leeren Sie immer den Cache nach Konfigurationsänderungen unter Linux.

Direkt zugehörige Fehler

• `model_not_found` — Zeigt an, dass die Model-ID nicht zu einem registrierten Provider aufgelöst werden konnte. Primäres Symptom der Linux-Parsing-Abweichung.
• `Provider anthropic is in cooldown (all profiles unavailable)` — Der kaskadierende Fehlerzustand, der nach dem anfänglichen `model_not_found` nachfolgende Model-Versuche verhindert.
• `all profiles unavailable` — Zeigt an, dass die Provider-Registrierung abgeschlossen wurde, aber keine Profile erfolgreich registriert wurden. Bezogen auf die cacheRetention-Race-Condition.

Kontextbezogen zugehörige Fehler

• `Provider authentication failed` — Kann auftreten, wenn der Provider-Cooldown Authentifizierungsversuche verhindert.
• `Configuration parse error` — Kann erscheinen, wenn das Dauersuffix-Parsing auf fehlerhaftes JSON stößt (z.B. nachgestellte Leerzeichen).
• `Alias resolution failed` — Kann auftreten, wenn Alias-Referenzen verwendet werden, bevor Basismodelle registriert wurden (abhängig von der Konfigurationsreihenfolge).
• `Rate limit exceeded` — Bezogen auf den Burst von Provider-Registrierungen, ausgelöst durch mehrere cacheRetention-Definitionen.

Historische Problemmuster

• Problem: Model-Aliase mit Dauersuffixen — Ältere Versionen hatten bekannte Probleme mit `model-id:duration`-Alias-Formaten. Stellen Sie sicher, dass OpenClaw Version 2026.2.25+ installiert ist.
• Problem: Linux-Provider-Initialisierungs-Timing — Eine bekannte Race-Condition in der asynchronen Provider-Registrierungs-Pipeline, die Linux aufgrund unterschiedlicher Scheduling-Verhaltensweisen betrifft.
• Problem: XDG_CONFIG_HOME nicht respektiert — Einige Linux-Distributionen honorieren XDG-Pfade nicht korrekt, was zu Konfigurationsladefehlern führt, die sich als Model-Auflösungsfehler manifestieren.

Diagnostische Referenzbefehle

# Vollständige Systemdiagnose
openclaw doctor

# Provider-Debug-Ausgabe  
openclaw provider debug anthropic

# Konfigurationsvalidierung
openclaw config validate

# Alle Caches leeren und neu starten
openclaw gateway stop && rm -rf ~/.cache/openclaw && openclaw gateway start