Modelle-CLI

Modellreferenzen wählen einen Provider und ein Modell aus. Sie wählen normalerweise nicht die Low-Level-Agent-Laufzeit aus. Beispielsweise kann openai/gpt-5.5 je nach agents.defaults.agentRuntime.id über den normalen OpenAI-Provider-Pfad oder über die Codex-App-Server-Laufzeit ausgeführt werden. Im Codex-Laufzeitmodus bedeutet die Referenz openai/gpt-* keine Abrechnung über API-Schlüssel; die Authentifizierung kann aus einem Codex-Konto oder einem openai-codex-Auth-Profil stammen. Siehe Agent-Laufzeiten.

# 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 ein temporärer Wiederherstellungszustand. Sie werden mit modelOverrideSource: "auto" gespeichert, damit spätere Turns die Fallback-Kette weiter verwenden können, ohne zuerst ein bekanntermaßen fehlerhaftes primäres Modell zu prüfen.
• Benutzersitzungsauswahlen sind exakt. /model, der Modellauswähler, session_status(model=...) und sessions.patch speichern modelOverrideSource: "user"; wenn dieser ausgewählte Provider/dieses Modell nicht erreichbar ist, schlägt OpenClaw sichtbar fehl, statt auf ein anderes konfiguriertes Modell durchzufallen.
• Cron --model / Payload model ist ein primäres Modell 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-Auswähler respektieren models.mode: "replace", indem sie explizite models.providers.*.models auflisten, anstatt den vollständigen integrierten Katalog zu laden.
• Der Modellauswähler in der Control UI fragt beim Gateway die konfigurierte Modellansicht ab: agents.defaults.models, sofern vorhanden, andernfalls explizite models.providers.*.models plus Provider mit nutzbarer Authentifizierung. Der vollständige integrierte Katalog ist expliziten Browse-Ansichten wie models.list mit view: "all" oder openclaw models list --all vorbehalten.

# Schnelle Modellrichtlinie

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

# Onboarding (empfohlen)

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

openclaw onboard

Es kann Modell + Auth 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)
• 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 festgelegt 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 steht, gibt OpenClaw Folgendes 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, korrigieren Sie zuerst die Allowlist und versuchen Sie dann denselben Befehl /model ... --runtime ... erneut. Für native Codex-Ausführung bleibt das ausgewählte Modell openai/gpt-5.5; die codex-Laufzeit wählt das Harness aus und verwendet Codex-Auth separat.

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

Beispiel-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)

Sie können Modelle für die aktuelle Sitzung ohne Neustart wechseln:

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

Vollständiges Befehlsverhalten/Konfiguration: Slash-Befehle.

# 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 Unterbefehl) ist eine Abkürzung für models status.

# models list

Zeigt standardmäßig konfigurierte bzw. mit verfügbarer Authentifizierung nutzbare Modelle an. Nützliche Flags:

--allboolean

Vollständiger Katalog. Enthält gebündelte, Provider-eigene statische Katalogzeilen, bevor die Authentifizierung konfiguriert ist, damit reine Erkennungsansichten Modelle anzeigen können, die erst verfügbar sind, wenn Sie passende Provider-Anmeldedaten hinzufügen.

--localboolean

Nur lokale Provider.

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

--plainboolean

Ein Modell pro Zeile.

--jsonboolean

Maschinenlesbare Ausgabe.

# models status

Zeigt das aufgelöste primäre Modell, Fallbacks, Bildmodell und eine Authentifizierungsübersicht der konfigurierten Provider an. Außerdem wird der Ablaufstatus von OAuth für Profile angezeigt, die im Auth-Store gefunden wurden (warnt standardmäßig innerhalb von 24 Stunden). --plain gibt nur das aufgelöste primäre Modell aus.

Beispiel (Claude CLI):

claude auth login
openclaw models status

# Scannen (kostenlose OpenRouter-Modelle)

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

--no-probeboolean

Live-Prüfungen überspringen (nur Metadaten).

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

agents.defaults.model.primary auf die erste Auswahl setzen.

--set-imageboolean

agents.defaults.imageModel.primary auf die erste Bildauswahl setzen.

Scan-Ergebnisse werden nach folgenden Kriterien sortiert:

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
• Anfrage-/Prüfsteuerung: --timeout, --concurrency

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

# Modellregistrierung (models.json)

Benutzerdefinierte Provider in models.providers werden in models.json im Agent-Verzeichnis 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-Laufzeiten — PI, Codex und andere Agent-Loop-Laufzeiten
• Konfigurationsreferenz — Modellkonfigurationsschlüssel
• Bildgenerierung — Bildmodellkonfiguration
• Modell-Failover — Fallback-Ketten
• Modell-Provider — Provider-Routing und Authentifizierung
• Musikgenerierung — Musikmodellkonfiguration
• Videogenerierung — Videomodellkonfiguration