Modelle-CLI

Modellreferenzen wählen einen Provider und ein Modell aus. Normalerweise wählen sie nicht die Low-Level-Agent-Laufzeit aus. OpenAI-Agent-Referenzen sind die wichtigste Ausnahme: openai/gpt-5.5 läuft beim offiziellen OpenAI-Provider standardmäßig über die Codex-App-Server-Laufzeit. Subscription-Copilot-Referenzen (github-copilot/*) können zusätzlich für das externe GitHub-Copilot-Agent-Laufzeit-Plugin aktiviert werden – dieser Pfad bleibt explizit (kein auto-Fallback). Explizite Laufzeitüberschreibungen gehören in die Provider-/Modellrichtlinie, nicht auf den gesamten Agent oder die gesamte Sitzung. Im Codex-Laufzeitmodus impliziert die Referenz openai/gpt-* keine Abrechnung über API-Schlüssel; die Authentifizierung kann über ein Codex-Konto oder ein openai-OAuth-Profil erfolgen. Siehe Agent-Laufzeiten und GitHub-Copilot-Agent-Laufzeit.

So funktioniert die Modellauswahl

OpenClaw wählt Modelle in dieser Reihenfolge aus:

Auswahlquelle und Fallback-Verhalten

Dasselbe provider/model kann je nach Herkunft unterschiedliche Dinge bedeuten:

• Konfigurierte Standards (agents.defaults.model.primary und agent-spezifische Primärmodelle) sind der normale Ausgangspunkt und verwenden agents.defaults.model.fallbacks.
• Automatische Fallback-Auswahlen sind temporärer Wiederherstellungszustand. Sie werden mit modelOverrideSource: "auto" gespeichert, damit spätere Durchläufe die Fallback-Kette weiter verwenden können, ohne jedes Mal ein bekannt defektes Primärmodell zu prüfen; OpenClaw prüft das ursprüngliche Primärmodell regelmäßig erneut, löscht die automatische Auswahl, wenn es sich erholt, und kündigt Fallback-/Wiederherstellungsübergänge einmal pro Zustandsänderung an.
• Benutzersitzungsauswahlen sind exakt. /model, die Modellauswahl, session_status(model=...) und sessions.patch speichern modelOverrideSource: "user"; wenn dieser ausgewählte Provider/dieses ausgewählte Modell nicht erreichbar ist, schlägt OpenClaw sichtbar fehl, statt auf ein anderes konfiguriertes Modell zurückzufallen.
• Das Ändern von agents.defaults.model.primary schreibt bestehende Sitzungsauswahlen nicht um. Wenn der Status This session is pinned to X; config primary Y will apply to new/unpinned sessions. meldet, löschen Sie die aktuelle Sitzungsauswahl mit /model default, damit sie wieder das konfigurierte Primärmodell erbt.
• Cron --model / Payload model ist ein Primärmodell pro Job. Es verwendet weiterhin konfigurierte Fallbacks, sofern der Job keine expliziten Payload-fallbacks bereitstellt (verwenden Sie fallbacks: [] für einen strikten Cron-Lauf).
• CLI-Standardmodell- und Allowlist-Auswahlen respektieren models.mode: "replace", indem sie explizite models.providers.*.models auflisten, statt den vollständigen eingebauten Katalog zu laden.
• Die Control-UI-Modellauswahl fragt beim Gateway die konfigurierte Modellansicht ab: agents.defaults.models, falls vorhanden, einschließlich providerweiter provider/*-Einträge, andernfalls explizite models.providers.*.models plus Provider mit verwendbarer Authentifizierung. Der vollständige eingebaute Katalog ist expliziten Browsing-Ansichten vorbehalten, etwa models.list mit view: "all" oder openclaw models list --all.

Kurze Modellrichtlinie

• Legen Sie Ihr Primärmodell auf das stärkste Modell der neuesten Generation fest, das Ihnen zur Verfügung steht.
• Verwenden Sie Fallbacks für kosten-/latenzempfindliche Aufgaben und Chats mit geringeren Anforderungen.
• Vermeiden Sie bei Tool-fähigen Agenten oder nicht vertrauenswürdigen Eingaben ältere/schwächere Modellstufen.

Onboarding (empfohlen)

Wenn Sie die Konfiguration nicht manuell bearbeiten möchten, führen Sie Onboarding aus:

openclaw onboard

Es kann Modell + Authentifizierung für gängige Provider einrichten, einschließlich OpenAI Code (Codex)-Abonnement (OAuth) und Anthropic (API-Schlüssel oder Claude CLI).

Konfigurationsschlüssel (Überblick)

• agents.defaults.model.primary und agents.defaults.model.fallbacks
• agents.defaults.imageModel.primary und agents.defaults.imageModel.fallbacks
• agents.defaults.pdfModel.primary und agents.defaults.pdfModel.fallbacks
• agents.defaults.imageGenerationModel.primary und agents.defaults.imageGenerationModel.fallbacks
• agents.defaults.videoGenerationModel.primary und agents.defaults.videoGenerationModel.fallbacks
• agents.defaults.models (Allowlist + Aliase + Provider-Parameter + dynamische Provider-Einträge provider/*)
• models.providers (benutzerdefinierte Provider, die in models.json geschrieben werden)

Sichere Allowlist-Bearbeitungen

Verwenden Sie additive Schreibvorgänge, wenn Sie agents.defaults.models manuell aktualisieren:

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge

„Modell ist nicht erlaubt“ (und warum Antworten stoppen)

Wenn agents.defaults.models gesetzt ist, wird es zur Allowlist für /model und für Sitzungsüberschreibungen. Wenn ein Benutzer ein Modell auswählt, das nicht in dieser Allowlist enthalten ist, gibt OpenClaw zurück:

Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

Wenn der abgelehnte Befehl eine Laufzeitüberschreibung wie /model openai/gpt-5.5 --runtime codex enthielt, beheben Sie zuerst die Allowlist und wiederholen Sie dann denselben Befehl /model ... --runtime .... Für native Codex-Ausführung ist das ausgewählte Modell weiterhin openai/gpt-5.5; die Laufzeit codex wählt das Harness aus und verwendet Codex-Authentifizierung separat.

Speichern Sie für lokale/GGUF-Modelle die vollständige, providerpräfixierte Referenz in der Allowlist, zum Beispiel ollama/gemma4:26b, lmstudio/Gemma4-26b-a4-it-gguf oder das exakte Provider/Modell, das von openclaw models list --provider <provider> angezeigt wird. Bloße lokale Dateinamen oder Anzeigenamen reichen nicht aus, wenn die Allowlist aktiv ist.

Wenn Sie Provider begrenzen möchten, ohne jedes Modell manuell aufzulisten, fügen Sie provider/*-Einträge zu agents.defaults.models hinzu:

{  agents: {    defaults: {      models: {        "openai/*": {},        "vllm/*": {},      },    },  },}

Mit dieser Richtlinie zeigen /model, /models und Modellauswahlen den erkannten Katalog nur für diese Provider an. Neue Modelle der ausgewählten Provider können erscheinen, ohne die Allowlist zu bearbeiten. Exakte provider/model-Einträge können mit provider/*-Einträgen gemischt werden, wenn Sie ein bestimmtes Modell eines anderen Providers benötigen.

Beispielkonfiguration für die Allowlist:

{  agents: {    defaults: {      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)

Sie können Modelle für die aktuelle Sitzung wechseln, ohne neu zu starten:

/model/model list/model 3/model openai/gpt-5.4/model default/model status

Vollständiges Befehlsverhalten/Konfiguration: Slash-Befehle.

CLI-Befehle

openclaw models listopenclaw models statusopenclaw models set <provider/model>openclaw models set-image <provider/model> openclaw models aliases listopenclaw models aliases add <alias> <provider/model>openclaw models aliases remove <alias> openclaw models fallbacks listopenclaw models fallbacks add <provider/model>openclaw models fallbacks remove <provider/model>openclaw models fallbacks clear openclaw models image-fallbacks listopenclaw models image-fallbacks add <provider/model>openclaw models image-fallbacks remove <provider/model>openclaw models image-fallbacks clear

openclaw models (ohne Unterbefehl) ist eine Abkürzung für models status.

models list

Zeigt standardmäßig konfigurierte/auth-verfügbare Modelle. Nützliche Flags:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> Nach Provider-ID filtern, zum Beispiel moonshot. Anzeigebezeichnungen aus interaktiven Auswahldialogen werden nicht akzeptiert.

models status

Zeigt das aufgelöste Primärmodell, Fallbacks, Bildmodell und eine Auth-Übersicht der konfigurierten Provider. Außerdem wird der OAuth-Ablaufstatus für Profile angezeigt, die im Auth-Speicher gefunden wurden (standardmäßig Warnung innerhalb von 24 h). --plain gibt nur das aufgelöste Primärmodell aus.

Beispiel (Claude CLI):

claude auth loginopenclaw models status

Scanning (kostenlose OpenRouter-Modelle)

openclaw models scan prüft den kostenlosen Modellkatalog von OpenRouter und kann optional Modelle auf Tool- und Bildunterstützung prüfen.

Scan-Ergebnisse werden bewertet nach:

1. Bildunterstützung
2. Tool-Latenz
3. Kontextgröße
4. Parameteranzahl

Eingabe:

• OpenRouter-/models-Liste (Filter :free)
• Live-Prüfungen erfordern einen OpenRouter-API-Schlüssel aus Auth-Profilen oder OPENROUTER_API_KEY (siehe Umgebungsvariablen)
• Optionale Filter: --max-age-days, --min-params, --provider, --max-candidates
• Anforderungs-/Prüfsteuerung: --timeout, --concurrency

Wenn Live-Prüfungen in einem TTY laufen, können Sie Fallbacks interaktiv auswählen. Im nicht interaktiven Modus übergeben Sie --yes, um Standardwerte zu akzeptieren. Ergebnisse nur mit Metadaten dienen der Information; --set-default und --set-image erfordern Live-Prüfungen, damit OpenClaw kein unbrauchbares OpenRouter-Modell ohne Schlüssel konfiguriert.

Modellregistrierung (models.json)

Benutzerdefinierte Provider in models.providers werden in models.json im Agent-Verzeichnis geschrieben (Standard ~/.openclaw/agents/<agentId>/agent/models.json). Provider-Plugin-Kataloge werden als generierte, Plugin-eigene Katalog-Shards im Plugin-Status des Agents gespeichert und automatisch geladen. Diese Datei wird standardmäßig zusammengeführt, sofern models.mode nicht auf replace gesetzt ist.

Verwandte Themen

• Agent-Runtimes — OpenClaw, Codex und andere Agent-Loop-Runtimes
• Konfigurationsreferenz — Modellkonfigurationsschlüssel
• Bildgenerierung — Bildmodellkonfiguration
• Modell-Failover — Fallback-Ketten
• Modell-Provider — Provider-Routing und Auth
• Musikgenerierung — Musikmodellkonfiguration
• Videogenerierung — Videomodellkonfiguration