OpenClaw Modelle konfigurieren: Fallbacks & CLI-Setup

Kennst du das? Du hast gerade deinen Workflow perfektioniert, und plötzlich ist die API deines Lieblingsmodells nicht erreichbar oder du läufst in ein Rate-Limit. Das Jonglieren mit verschiedenen Providern, API-Keys und Fallbacks kann echt nervig sein, besonders wenn du eigentlich nur produktiv arbeiten willst.

Hier kommt das Models CLI von OpenClaw ins Spiel. Es hilft dir dabei, deine Modelle zentral zu verwalten, damit du dich nicht ständig mit Konfigurationsdateien herumschlagen musst. Schau dir an, wie du die volle Kontrolle über deine KI-Infrastruktur behältst.

Weitere Informationen findest du unter /concepts/model-failover für Auth-Profil-Rotation, Cooldowns und das Zusammenspiel mit Fallbacks. Eine schnelle Provider-Übersicht mit Beispielen gibt es hier: /concepts/model-providers.

Wie die Modellauswahl funktioniert

OpenClaw wählt Modelle in dieser Reihenfolge aus:

1. Primary Modell (agents.defaults.model.primary oder agents.defaults.model).
2. Fallbacks in agents.defaults.model.fallbacks (der Reihe nach).
3. Provider auth failover findet innerhalb eines Providers statt, bevor zum nächsten Modell gewechselt wird.

Verwandte Themen:

• agents.defaults.models ist die Allowlist/der Katalog der Modelle, die OpenClaw nutzen kann (plus Aliase).
• agents.defaults.imageModel wird nur dann verwendet, wenn das primäre Modell keine Bilder verarbeiten kann.
• agents.defaults.imageGenerationModel wird von der gemeinsamen Image-Generation-Capability genutzt. Wenn dieser Wert fehlt, kann image_generate trotzdem einen Provider-Standard aus kompatiblen Image-Generation-Plugins ableiten. Wenn du ein spezifisches Modell setzt, konfiguriere auch die entsprechende Auth/API-Key für diesen Provider.
• Per-Agent-Defaults können agents.defaults.model via agents.list[].model plus Bindings überschreiben (siehe /concepts/multi-agent).

Schnelle Modell-Policy

• Setze dein primäres Modell auf das stärkste Modell der neuesten Generation, das dir zur Verfügung steht.
• Nutze Fallbacks für kosten- oder latenzsensitive Aufgaben und weniger wichtige Chats.
• Vermeide ältere oder schwächere Modell-Tiers für Agenten mit Tool-Nutzung oder bei unsicheren Inputs.

Onboarding (empfohlen)

Wenn du die Konfiguration nicht manuell bearbeiten möchtest, starte das Onboarding:

openclaw onboard

Es kann Modelle und Auth für gängige Provider einrichten, einschließlich OpenAI Code (Codex) subscription (OAuth) und Anthropic (API-Key oder claude setup-token).

Konfigurations-Keys (Übersicht)

• agents.defaults.model.primary und agents.defaults.model.fallbacks
• agents.defaults.imageModel.primary und agents.defaults.imageModel.fallbacks
• agents.defaults.imageGenerationModel.primary und agents.defaults.imageGenerationModel.fallbacks
• agents.defaults.models (Allowlist + Aliase + Provider-Parameter)
• models.providers (benutzerdefinierte Provider, die in die models.json geschrieben werden)

Modell-Referenzen werden auf Kleinschreibung normalisiert. Provider-Aliase wie z.ai/* werden zu zai/* normalisiert.

Beispiele für Provider-Konfigurationen (einschließlich OpenCode) findest du unter /providers/opencode.

”Model is not allowed” (und warum Antworten stoppen)

Wenn agents.defaults.models gesetzt ist, fungiert es als Allowlist für /model und für Session-Overrides. Wenn ein Nutzer ein Modell wählt, das nicht in dieser Allowlist steht, gibt OpenClaw folgendes zurück:

Model "provider/model" is not allowed. Use /model to list available models.

Das passiert, bevor eine normale Antwort generiert wird, weshalb es so wirken kann, als ob die Nachricht “nicht beantwortet” wurde. Die Lösung ist:

• Füge das Modell zu agents.defaults.models hinzu, oder
• Leere die Allowlist (entferne agents.defaults.models), oder
• Wähle ein Modell aus /model list.

Beispiel für eine Allowlist-Konfiguration:

{
  agent: {
    model: { primary: "anthropic/claude-sonnet-4-6" },
    models: {
      "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
      "anthropic/claude-opus-4-6": { alias: "Opus" },
    },
  },
}

Modelle im Chat wechseln (/model)

Du kannst Modelle für die aktuelle Session wechseln, ohne neu zu starten:

/model
/model list
/model 3
/model openai/gpt-5.2
/model status

Hinweise:

• /model (und /model list) ist eine kompakte, nummerierte Auswahl (Modell-Familie + verfügbare Provider).
• Auf Discord öffnen /model und /models eine interaktive Auswahl mit Dropdowns für Provider und Modelle sowie einem Submit-Button.
• /model <#> wählt einen Eintrag aus dieser Liste aus.
• /model aktualisiert die Session-Auswahl sofort. Wenn der Agent im Leerlauf ist, nutzt der nächste Run direkt das neue Modell. Wenn der Agent beschäftigt ist, wird der laufende Prozess beendet und wartende Aufgaben nutzen danach das neue Modell.
• /model status zeigt die Detailansicht (Auth-Kandidaten und, falls konfiguriert, Provider-Endpoint baseUrl + api Modus).
• Modell-Referenzen werden am ersten / getrennt. Nutze provider/model, wenn du /model <ref> tippst.
• Wenn die Modell-ID selbst ein / enthält (wie bei OpenRouter), musst du das Provider-Präfix inkludieren (Beispiel: /model openrouter/moonshotai/kimi-k2).
• Wenn du den Provider weglässt, behandelt OpenClaw den Input als Alias oder als Modell für den Standard-Provider (funktioniert nur, wenn kein / in der Modell-ID enthalten ist).

Details zum Befehlsverhalten: Slash commands.

CLI-Befehle

openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>

openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

openclaw models image-fallbacks list
openclaw models image-fallbacks add <provider/model>
openclaw models image-fallbacks remove <provider/model>
openclaw models image-fallbacks clear

openclaw models (ohne Subcommand) ist ein Shortcut für models status.

models list

Zeigt standardmäßig konfigurierte Modelle an. Nützliche Flags:

• --all: der gesamte Katalog
• --local: nur lokale Provider
• --provider <name>: nach Provider filtern
• --plain: ein Modell pro Zeile
• --json: maschinenlesbare Ausgabe

models status

Zeigt das aufgelöste primäre Modell, Fallbacks, das Image-Modell und eine Auth-Übersicht der konfigurierten Provider. Es zeigt auch den OAuth-Ablaufstatus für Profile im Auth-Store an (Warnung standardmäßig innerhalb von 24h). --plain gibt nur das aufgelöste primäre Modell aus. Der OAuth-Status wird immer angezeigt (und ist in der --json Ausgabe enthalten). Wenn ein konfigurierter Provider keine Credentials hat, gibt models status eine Sektion Missing auth aus. JSON enthält auth.oauth (Warnzeitraum + Profile) und auth.providers (effektive Auth pro Provider). Nutze --check für Automatisierungen (Exit-Code 1 bei fehlenden/abgelaufenen Daten, 2 wenn sie bald ablaufen).

Die Wahl der Auth hängt vom Provider/Account ab. Für dauerhaft laufende Gateway-Hosts sind API-Keys meist am zuverlässigsten; Subscription-Token-Flows werden ebenfalls unterstützt.

Beispiel (Anthropic setup-token):

claude setup-token
openclaw models status

Scanning (Kostenlose OpenRouter-Modelle)

openclaw models scan prüft den Katalog der kostenlosen Modelle von OpenRouter und kann optional Modelle auf Tool- und Image-Support testen.

Wichtige Flags:

• --no-probe: überspringt Live-Tests (nur Metadaten)
• --min-params <b>: minimale Parametergröße (in Milliarden)
• --max-age-days <days>: überspringt ältere Modelle
• --provider <name>: Filter nach Provider-Präfix
• --max-candidates <n>: Größe der Fallback-Liste
• --set-default: setzt agents.defaults.model.primary auf die erste Wahl
• --set-image: setzt agents.defaults.imageModel.primary auf die erste Wahl für Bilder

Das Testen (Probing) erfordert einen OpenRouter API-Key (aus Auth-Profilen oder OPENROUTER_API_KEY). Ohne Key nutze --no-probe, um nur Kandidaten aufzulisten.

Scan-Ergebnisse werden nach diesen Kriterien sortiert:

1. Image-Support
2. Tool-Latenz
3. Context-Größe
4. Parameter-Anzahl

Input:

• OpenRouter /models Liste (Filter :free)
• Erfordert OpenRouter API-Key aus Auth-Profilen oder OPENROUTER_API_KEY (siehe /environment)
• Optionale Filter: --max-age-days, --min-params, --provider, --max-candidates
• Probe-Optionen: --timeout, --concurrency

In einem TTY kannst du Fallbacks interaktiv auswählen. Im nicht-interaktiven Modus nutze --yes, um Standards zu akzeptieren.

Modell-Registry (models.json)

Benutzerdefinierte Provider in models.providers werden in die models.json im Agent-Verzeichnis geschrieben (Standard: ~/.openclaw/agents/<agentId>/agent/models.json). Diese Datei wird standardmäßig zusammengeführt (merged), außer models.mode ist auf replace gesetzt.

Rangfolge im Merge-Modus bei übereinstimmenden Provider-IDs:

• Eine bereits vorhandene, nicht leere baseUrl in der models.json des Agenten gewinnt.
• Ein nicht leerer apiKey in der models.json des Agenten gewinnt nur, wenn dieser Provider im aktuellen Konfigurations-/Auth-Profil-Kontext nicht über SecretRef verwaltet wird.
• API-Key-Werte von SecretRef-verwalteten Providern werden aus den Quell-Markern aktualisiert (ENV_VAR_NAME für Env-Refs, secretref-managed für File/Exec-Refs), anstatt aufgelöste Secrets dauerhaft zu speichern.
• Header-Werte von SecretRef-verwalteten Providern werden aus den Quell-Markern aktualisiert (secretref-env:ENV_VAR_NAME für Env-Refs, secretref-managed für File/Exec-Refs).
• Leere oder fehlende apiKey/baseUrl Werte des Agenten fallen auf die models.providers der Konfiguration zurück.
• Andere Provider-Felder werden aus der Konfiguration und normalisierten Katalogdaten aktualisiert.

Die Marker-Persistenz ist quell-autoritativ: OpenClaw schreibt Marker aus dem aktiven Quell-Konfigurations-Snapshot (vor der Auflösung), nicht aus den aufgelösten Runtime-Secret-Werten. Dies gilt immer, wenn OpenClaw die models.json neu generiert, auch bei Befehlen wie openclaw agent.

Nächste Schritte

• Model Providers — Provider-Routing und Auth
• Model Failover — Fallback-Ketten
• Image Generation — Konfiguration von Bild-Modellen
• Configuration Reference — Modell-Konfigurations-Keys

Du hast noch Fragen zur Einrichtung? Der AI Setup Assistant hilft dir gerne weiter!