Model-Failover in OpenClaw: Fallback-Modelle einrichten und gezielt prüfen

Die Fallback-Liste ist gepflegt, das Hauptmodell fällt aus – und trotzdem steht im Chat nur eine Fehlermeldung. Oft ist das kein Konfigurationsfehler. Wer das Modell einer Sitzung mit /model festlegt, macht diese Auswahl in OpenClaw strikt, und die globale Fallback-Kette bleibt außen vor.

OpenClaw verbindet Chats und Automationen mit Modellen verschiedener Anbieter. Welches Modell einspringt, wenn eines ausfällt, hängt davon ab, woher die Modellauswahl stammt. Dieses Tutorial erklärt die Regeln und führt durch einen kontrollierten Test mit einem absichtlich gesperrten Zugang. Vorausgesetzt wird eine laufende Installation mit Zugängen zu mindestens zwei Modellanbietern. Die Grundeinrichtung beschreibt Teil 3 der Tutorial-Reihe zur Modellkonfiguration.

Was vor einem Modellwechsel passiert

Laut der OpenClaw-Dokumentation zum Modell-Failover arbeitet die Laufzeit Fehler in zwei Stufen ab. Zuerst rotiert sie innerhalb des aktuellen Anbieters durch die vorhandenen Auth-Profile, also die hinterlegten API-Schlüssel oder OAuth-Zugänge. Erst wenn dieser Anbieter erschöpft ist, wechselt sie zum nächsten Modell der Fallback-Kette.

Davor steht noch ein Wiederholungsversuch mit demselben Modell. Bei Rate-Limits sind das bis zu zehn Versuche pro zusammenhängendem Ausfall, die Control UI zeigt dann „Retrying… n/10“. Der Lauf setzt dabei das bestehende Transkript fort, Teilausgaben bleiben erhalten, und der Agent soll unterbrochene Aktionen prüfen, bevor er sie wiederholt.

Ein Fallback gilt nur für den aktuellen Turn. Der nächste beginnt wieder beim ausgewählten Primary. /status und die Übergangshinweise unterscheiden laut Dokumentation zwischen dem ausgewählten Modell und dem, das tatsächlich geantwortet hat.

Nicht jeder Fehler löst einen Wechsel aus. Ausweichfähig sind unter anderem Authentifizierungsfehler, Rate-Limits, überlastete Anbieter, Timeouts, Abrechnungssperren und model_not_found. Format- und Request-Fehler gelten dagegen meist als endgültig, weil derselbe Payload beim nächsten Modell genauso scheitern würde. Ein ausdrücklicher Abbruch beendet die Kette ebenfalls.

Welche Auswahl ausweichen darf

Entscheidend ist die Herkunft der Auswahl. Der konfigurierte Standard besteht aus agents.defaults.model.primary und agents.defaults.model.fallbacks. Er darf die Kette durchlaufen, ebenso Cron-Job-Primaries und Agenten mit ausdrücklicher Fallback-Liste.

{
  agents: {
    defaults: {
      model: {
        primary: "provider-a/model-a",
        fallbacks: ["provider-b/model-b"],
      },
    },
  },
}

Die Modellreferenzen sind Platzhalter. Ersetze sie durch zwei Modelle, die deine Installation kennt und für die gültige Zugangsdaten hinterlegt sind.

Ausdrückliche Benutzerauswahlen sind strikt: /model provider/modell, der Model Picker, sessions.patch und einmalige Provider- oder Modell-Overrides in der CLI. Scheitert das gewählte Modell, bevor es antwortet, meldet OpenClaw den Fehler, statt mit einem fremden Fallback zu antworten. Zurück zur Standardauswahl geht es mit „Default“ im Picker oder mit /model default.

Fallbacks bei einzelnen Agenten

Hier liegt die häufigste Falle. Laut Konfigurationsreferenz und Failover-Dokumentation gelten für agents.entries.<agent-id>.model vier Fälle:

• Fehlt model ganz, erbt der Agent Primary und Fallbacks des Standards.
• Ein Objekt nur mit fallbacks erbt das Primary und nutzt die eigene Kette.
• Ein eigenes primary ohne fallbacks macht den Agenten strikt, die geerbte Liste entfällt.
• fallbacks: [] schaltet das Ausweichen ausdrücklich ab.

Der dritte Fall überrascht. Wer einem Agenten nur ein anderes Hauptmodell zuweist, verliert damit stillschweigend jede Ausweichroute, auch wenn global eine Kette gepflegt ist. Soll ein Agent ein eigenes Primary und trotzdem Fallbacks haben, gehören beide Felder zusammen:

{
  agents: {
    entries: {
      "research-agent": {
        model: {
          primary: "provider-c/model-c",
          fallbacks: ["provider-b/model-b"],
        },
      },
    },
  },
}

Eine solche Liste ersetzt die globale vollständig. Angehängt wird nichts.

ACP-Harness und native Aufrufe

Agenten mit runtime.type: "acp" wählen über ihr Primary das Modell eines externen Harness, also eines separaten Agentenprogramms, das OpenClaw ansteuert. Native OpenClaw-Aufrufe desselben Agenten erben laut Failover-Dokumentation Primary und Fallbacks aus agents.defaults.model. Eine eigene model.fallbacks-Liste ersetzt diese, [] schaltet sie ab. Harness-spezifische Modellnamen sollten deshalb nicht in der nativen Fallback-Liste landen, und jeder native Kandidat braucht in OpenClaw hinterlegte Zugangsdaten.

Cron-Jobs: Primary mit Kette

Ein per --model gesetztes Modell eines Automations-Jobs ist ein Job-Primary, kein Benutzer-Pin. Laut Failover-Dokumentation nutzt es die konfigurierten Fallbacks, solange der Job keine eigene Liste mitbringt. Die Automations-Dokumentation nennt dafür --fallbacks mit einer kommagetrennten Modellliste. --fallbacks "" erzwingt einen strikten Lauf. Hat ein Job --model, aber weder eine eigene noch eine konfigurierte Liste, läuft er ebenfalls ohne Ausweichen.

Die Bedienung des Schedulers beschreibt Teil 7 zu Cron-Jobs, Heartbeats und Automationen.

Voraussetzungen für den Test

Du brauchst zwei native Modelle verschiedener Anbieter, damit der absichtlich ausgelöste Zugangsfehler beim Primary nicht auch das Fallback trifft. Für das Primary eignet sich nur ein eigens angelegtes Test-Credential, das sich beim Anbieter deaktivieren lässt. Notiere vorher den Namen des Auth-Profils und den Speicherort dahinter, etwa eine SecretRef oder eine Umgebungsvariable. Wie man solche Quellen sauber verwaltet, steht in OpenClaw SecretRef richtig einsetzen.

Der Test ist nur eindeutig, wenn genau ein Profil auf das Primary zugreifen kann. Sonst rotiert OpenClaw zum nächsten Profil desselben Anbieters, und der Modell-Fallback wird nie ausgelöst. Nutze dafür eine isolierte Testinstallation oder ein eigenes Testkonto, statt vorhandene Profile zu löschen.

Außerdem nötig: Zugriff auf ~/.openclaw/openclaw.json, ein verbundener Owner-Chat für /restart und /status sowie die Berechtigung, Agenten und Automationen anzulegen.

Konfiguration sichern und Testagenten anlegen

Sichere zuerst die gesamte Datei:

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.failover-test-backup

Die Sicherung kann vertrauliche Konfiguration enthalten. Bewahre sie mit denselben Dateirechten wie das Original auf.

Trage dann in openclaw.json das Standardpaar aus dem obigen Beispiel ein und ergänze drei Testagenten. Vorhandene Einträge unter agents.entries bleiben stehen:

{
  agents: {
    entries: {
      "primary-probe": {
        model: {
          primary: "provider-a/model-a",
          fallbacks: [],
        },
      },
      "fallback-probe": {
        model: {
          primary: "provider-b/model-b",
          fallbacks: [],
        },
      },
      "chain-probe": {
        model: {
          fallbacks: ["provider-b/model-b"],
        },
      },
    },
  },
}

primary-probe und fallback-probe sind strikte Gegenproben: Keiner der beiden kann einen Fehler durch ein anderes Modell verdecken. chain-probe erbt das globale Primary und bringt eine eigene Kette mit genau einem Ersatzkandidaten mit.

Aktiviere die Konfiguration mit /restart im Owner-Chat und kontrolliere sie:

openclaw config get agents.defaults.model

Die Ausgabe muss provider-a/model-a als Primary und genau provider-b/model-b als Fallback enthalten. Sende danach /model default und prüfe mit /status, dass die Sitzung auf keinem konkreten Modell festgepinnt ist.

Beide Modelle vorab prüfen

Solange beide Credentials gültig sind, laufen die Gegenproben:

openclaw agent --agent primary-probe --message "Antworte nur mit PRIMARY_REACHABLE"
openclaw agent --agent fallback-probe --message "Antworte nur mit FALLBACK_REACHABLE"

Beide müssen erfolgreich enden. Scheitert schon hier einer, liegt das Problem bei Modellreferenz oder Credential – erst beheben, dann weitertesten.

Das Primary-Credential sperren

Deaktiviere beim Anbieter ausschließlich das notierte Primary-Test-Credential. Fallback und andere Profile bleiben unangetastet. Lässt dein Anbieter nur einen Widerruf zu, plane gleich ein Ersatz-Credential ein, das du nach dem Test am selben Speicherort hinterlegst. Geheime Werte gehören weder in den Chat noch in Testausgaben.

Nach /restart laufen beide Gegenproben erneut:

openclaw agent --agent primary-probe --message "Antworte nur mit PRIMARY_MUST_FAIL"
openclaw agent --agent fallback-probe --message "Antworte nur mit FALLBACK_STILL_REACHABLE"

primary-probe muss jetzt mit einem Authentifizierungs- oder Anbieterfehler enden. Antwortet er trotzdem, erreicht noch ein anderes Profil das Primary. fallback-probe muss weiterhin funktionieren. Wiederholungsversuche können das Scheitern des Primary verzögern, am Ergebnis ändern sie nichts.

Erst wenn beide Bedingungen erfüllt sind, ist der eigentliche Test aussagekräftig.

Die Default-Kette auslösen

Stelle im Testchat die Standardauswahl her und sende einen eindeutigen Prompt:

/model default
Antworte nur mit DEFAULT_CHAIN_OK

Der Turn sollte erfolgreich enden. /status nennt danach das ausgewählte Primary und das Modell, das geantwortet hat, getrennt. In den Logs liefert ein model_fallback_decision-Eintrag mit fallbackStepFromModel, fallbackStepToModel und dem Fehlergrund des Primary den zweiten Beleg. Zusammen mit den Gegenproben bleibt kein Zweifel, welcher Kandidat eingesprungen ist.

Endet der Turn mit dem Primary-Fehler, prüfe die globale Liste, die Fehlerklasse und einen möglichen Sitzungspin.

Den strikten Sitzungspin prüfen

Lass die Sperre bestehen und wähle das gestörte Modell ausdrücklich:

/model provider-a/model-a
Antworte nur mit DEFAULT_CHAIN_OK

Jetzt muss ein sichtbarer Fehler kommen. Das funktionierende Fallback darf diesen Turn nicht übernehmen. Nach /model default gelingt derselbe Prompt wieder – damit sind Pin und Default-Policy sauber voneinander abgegrenzt.

Die Agentenkette prüfen

openclaw agent --agent chain-probe --message "Antworte nur mit AGENT_CHAIN_OK"
openclaw agent --agent primary-probe --message "Antworte nur mit AGENT_STRICT_MUST_FAIL"

chain-probe erbt das gesperrte Primary, weicht auf das Fallback aus und endet erfolgreich. primary-probe scheitert weiterhin, weil fallbacks: [] jedes Ausweichen unterbindet.

Die Falle aus dem Agentenabschnitt lässt sich direkt nachstellen. Ersetze bei chain-probe die fallbacks-Zeile durch primary: "provider-a/model-a", starte neu und wiederhole den Aufruf. Er scheitert, obwohl global eine Kette existiert.

Cron-Primary prüfen

Lege zwei isolierte Agent-Turn-Jobs mit dem gesperrten Primary an. Der erste nutzt die globale Kette, der zweite ist mit --fallbacks "" ausdrücklich strikt:

openclaw cron add \
  --name "failover-test-chain" \
  --every 1h \
  --session isolated \
  --message "Antworte nur mit CRON_CHAIN_OK" \
  --model "provider-a/model-a"

openclaw cron add \
  --name "failover-test-strict" \
  --every 1h \
  --session isolated \
  --message "Antworte nur mit CRON_STRICT_MUST_FAIL" \
  --model "provider-a/model-a" \
  --fallbacks ""

openclaw cron list --all --json

Lies die beiden Job-IDs aus der Liste ab, starte die Jobs manuell und sieh dir die Läufe an:

openclaw cron run <JOB_ID>
openclaw cron runs --id <JOB_ID> --limit 5

Der Ketten-Job muss erfolgreich enden, der strikte Job mit dem Auth-Fehler des Primary. Endet auch der Ketten-Job mit einem Fehler, kommen ein fehlendes Fallback-Credential, eine nicht ausweichfähige Fehlerklasse oder eine abweichende Auswahlquelle infrage.

Credential und Konfiguration wiederherstellen

Reaktiviere zuerst genau das gesperrte Primary-Credential oder hinterlege das Ersatz-Credential am notierten Speicherort. Sende /restart und prüfe strikt:

openclaw agent --agent primary-probe --message "Antworte nur mit PRIMARY_RESTORED"

Scheitert dieser Aufruf direkt nach der Reaktivierung, ist das nicht zwingend ein neues Problem. Laut Failover-Dokumentation landen Profile nach Auth-Fehlern in einer Abkühlphase von 30 Sekunden, einer Minute und ab dem dritten Fehler fünf Minuten. Dauerhaft wirkende Auth-Fehler wie widerrufene Schlüssel sperren ein Profil zunächst für zehn Minuten. Wer diese Fenster abwartet, bevor er weitersucht, spart sich eine Fehlersuche an der falschen Stelle.

Funktioniert das Primary wieder, entferne beide Testjobs, stelle die Konfiguration wieder her und starte neu:

openclaw cron rm <JOB_ID>
cp ~/.openclaw/openclaw.json.failover-test-backup ~/.openclaw/openclaw.json
openclaw config get agents.defaults.model

Nach /restart zeigt /status, ob ein Testpin zurückgeblieben ist. Die Sicherungsdatei kann weg, sobald Primary, Fallbacks, Agenten und reguläre Cron-Jobs wieder dem Ausgangszustand entsprechen.

Wenn der Test anders endet

Bleibt primary-probe nach dem Sperren erfolgreich, greift noch ein anderes Auth-Profil auf das Primary zu, oder die Sperre traf die falsche Credential-Quelle. Ein kontrollierter Failover-Test ist so nicht möglich.

Scheitert fallback-probe, prüfe dessen Credential und Modellreferenz. Scheitert nur die normale Chatsitzung, ist vermutlich ein /model-Pin aktiv. Weicht ein Agent nicht aus, obwohl global eine Kette existiert, hat er wahrscheinlich ein eigenes primary ohne fallbacks.

Dauert ein Fehler auffällig lange, laufen meist noch Wiederholungen oder eine Profilrotation. Eine erfolgreiche Rotation innerhalb desselben Anbieters ist noch kein Modell-Fallback.

Fazit

Ob OpenClaw ausweicht, entscheidet weniger die gepflegte Liste als die Herkunft der Modellauswahl. Standard, Cron-Primaries und Agenten mit eigener Liste dürfen ausweichen, Benutzer-Pins und Agenten mit einem eigenen Primary ohne Fallbacks nicht. Daraus folgt eine Mindestregel: Wer einem Agenten ein eigenes Hauptmodell gibt, schreibt dessen Fallbacks gleich mit dazu.

Für den Test gilt dasselbe Prinzip wie im Betrieb. Ein separates Credential, strikte Gegenproben auf beiden Seiten und ein Blick auf die Abkühlphasen nach der Wiederherstellung machen aus einem Bauchgefühl einen belastbaren Befund.