Modelle-CLI

Modell-Refs wählen einen Provider und ein Modell aus. Sie wählen normalerweise nicht die Low-Level-Agent-Runtime aus. OpenAI-Agent-Refs sind die wichtigste Ausnahme: openai/gpt-5.5 wird beim offiziellen OpenAI-Provider standardmäßig über die Codex-App-Server-Runtime ausgeführt. Explizite Runtime-Überschreibungen gehören in die Provider-/Modellrichtlinie, nicht auf den gesamten Agent oder die gesamte Sitzung. Im Codex-Runtime-Modus bedeutet die Ref openai/gpt-* keine API-Key-Abrechnung; die Authentifizierung kann von einem Codex-Konto oder einem Auth-Profil openai-codex stammen. Siehe Agent-Runtimes.

So funktioniert die Modellauswahl

OpenClaw wählt Modelle in dieser Reihenfolge aus:

Auswahlquelle und Fallback-Verhalten

Dasselbe provider/model kann je nach Herkunft Unterschiedliches bedeuten:

• Konfigurierte Standards (agents.defaults.model.primary und Agent-spezifische primäre Modelle) 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 Turns die Fallback-Kette weiter verwenden können, ohne zuerst ein bekannt fehlerhaftes primäres Modell zu testen.
• Benutzersitzungs-Auswahlen sind exakt. /model, der Modell-Picker, session_status(model=...) und sessions.patch speichern modelOverrideSource: "user"; wenn dieser ausgewählte Provider/dieses Modell nicht erreichbar ist, schlägt OpenClaw sichtbar fehl, anstatt zu einem anderen konfigurierten Modell durchzufallen.
• Cron --model / Payload model ist ein primäres Modell pro Job. Es verwendet weiterhin konfigurierte Fallbacks, es sei denn, der Job liefert explizite Payload-fallbacks (verwenden Sie fallbacks: [] für einen strikten Cron-Lauf).
• CLI-Standardmodell- und Allowlist-Picker respektieren models.mode: "replace", indem sie explizite models.providers.*.models auflisten, statt den vollständigen integrierten Katalog zu laden.
• Der Modell-Picker der Control UI fragt beim Gateway dessen konfigurierte Modellansicht ab: agents.defaults.models, wenn vorhanden, einschließlich providerweiter provider/*-Einträge, andernfalls explizite models.providers.*.models plus Provider mit nutzbarer Authentifizierung. Der vollständige integrierte Katalog ist expliziten Browse-Ansichten vorbehalten, etwa models.list mit view: "all" oder openclaw models list --all.

Kurze Modellrichtlinie

• Setzen Sie Ihr primäres Modell auf das stärkste Modell der neuesten Generation, das Ihnen zur Verfügung steht.
• Verwenden Sie Fallbacks für kosten-/latenzsensible Aufgaben und Chat mit niedrigerem Risiko.
• Vermeiden Sie bei Tool-fähigen Agents oder nicht vertrauenswürdigen Eingaben ältere/schwächere Modellstufen.

Onboarding (empfohlen)

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

openclaw onboard

Es kann Modell + Authentifizierung für gängige Provider einrichten, einschließlich OpenAI Code (Codex) subscription (OAuth) und Anthropic (API-Key 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 von Hand 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 Runtime-Überschreibung wie /model openai/gpt-5.5 --runtime codex enthielt, korrigieren Sie zuerst die Allowlist und versuchen Sie danach denselben Befehl /model ... --runtime ... erneut. Für native Codex-Ausführung bleibt das ausgewählte Modell openai/gpt-5.5; die Runtime codex wählt das Harness aus und verwendet Codex-Authentifizierung separat.

Speichern Sie für lokale/GGUF-Modelle die vollständige providerpräfixierte Ref 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-codex/*": {},        "vllm/*": {},      },    },  },}

Mit dieser Richtlinie zeigen /model, /models und Modell-Picker 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.

Beispiel-Allowlist-Konfiguration:

{  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 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 Kurzform für models status.

models list

Zeigt standardmäßig konfigurierte bzw. per Auth verfügbare Modelle an. 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äre Modell, Fallbacks, das Bildmodell und eine Auth-Übersicht der konfigurierten Provider an. Außerdem wird der OAuth-Ablaufstatus für Profile angezeigt, die im Auth-Speicher gefunden wurden (standardmäßig Warnung innerhalb von 24 Stunden). --plain gibt nur das aufgelöste primäre Modell aus.

Beispiel (Claude CLI):

claude auth loginopenclaw models status

Scannen (kostenlose OpenRouter-Modelle)

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

Scan-Ergebnisse werden nach folgenden Kriterien eingestuft:

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

Eingabe:

• OpenRouter-Liste /models (Filter :free)
• Live-Probes 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
• Anfrage-/Probe-Steuerung: --timeout, --concurrency

Wenn Live-Probes in einem TTY ausgeführt werden, können Sie Fallbacks interaktiv auswählen. Im nicht interaktiven Modus übergeben Sie --yes, um Standards zu akzeptieren. Ergebnisse ohne Live-Probes dienen nur zur Information; --set-default und --set-image erfordern Live-Probes, damit OpenClaw kein unbrauchbares schlüsselloses OpenRouter-Modell konfiguriert.

Modellregistrierung (models.json)

Benutzerdefinierte Provider in models.providers werden unter dem Agent-Verzeichnis in models.json geschrieben (Standard ~/.openclaw/agents/<agentId>/agent/models.json). Diese Datei wird standardmäßig zusammengeführt, sofern models.mode nicht auf replace gesetzt ist.

Verwandte Themen

• Agent-Runtimes — PI, 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