​

Models CLI

​

So funktioniert die Modellauswahl

1. Primärmodell (agents.defaults.model.primary oder agents.defaults.model).
2. Fallbacks in agents.defaults.model.fallbacks (in Reihenfolge).
3. Provider-Auth-Failover findet innerhalb eines Providers statt, bevor zum nächsten Modell gewechselt wird.

• agents.defaults.models ist die Allowlist/der Katalog der Modelle, die OpenClaw verwenden kann (plus Aliasse).
• agents.defaults.imageModel wird nur dann verwendet, wenn das Primärmodell keine Bilder akzeptieren kann.
• agents.defaults.pdfModel wird vom Tool pdf verwendet. Wenn es fehlt, greift das Tool auf agents.defaults.imageModel und dann auf das aufgelöste Sitzungs-/Standardmodell zurück.
• agents.defaults.imageGenerationModel wird von der gemeinsamen Bildgenerierungsfunktion verwendet. Wenn es fehlt, kann image_generate weiterhin einen Auth-gestützten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider und dann die übrigen registrierten Bildgenerierungs-Provider in der Reihenfolge der Provider-IDs. Wenn Sie einen bestimmten Provider/ein bestimmtes Modell festlegen, konfigurieren Sie auch die Auth/den API-Schlüssel dieses Providers.
• agents.defaults.videoGenerationModel wird von der gemeinsamen Videogenerierungsfunktion verwendet. Anders als bei der Bildgenerierung wird heute kein Provider-Standard abgeleitet. Setzen Sie ein explizites provider/model wie qwen/wan2.6-t2v und konfigurieren Sie auch die Auth/den API-Schlüssel dieses Providers.
• Standards pro Agent können agents.defaults.model über agents.list[].model plus Bindings überschreiben (siehe /concepts/multi-agent).

​

Schnelle Modellrichtlinie

• Setzen Sie Ihr Primärmodell auf das stärkste Modell der neuesten Generation, das Ihnen zur Verfügung steht.
• Verwenden Sie Fallbacks für kosten-/latenzsensitive Aufgaben und Chat mit geringerer Tragweite.
• Vermeiden Sie bei Agenten mit aktivierten Tools oder nicht vertrauenswürdigen Eingaben ältere/schwächere Modellstufen.

​

Onboarding (empfohlen)

openclaw onboard

​

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 + Aliasse + Provider-Parameter)
• models.providers (benutzerdefinierte Provider, die in models.json geschrieben werden)

​

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

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

• Das Modell zu agents.defaults.models hinzuzufügen, oder
• Die Allowlist zu leeren (agents.defaults.models entfernen), oder
• Ein Modell aus /model list auszuwählen.

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

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

• /model (und /model list) ist ein kompakter nummerierter Picker (Modellfamilie + verfügbare Provider).
• Auf Discord öffnen /model und /models einen interaktiven Picker mit Dropdowns für Provider und Modell sowie einem Submit-Schritt.
• /model <#> wählt aus diesem Picker aus.
• /model speichert die neue Sitzungsauswahl sofort.
• Wenn der Agent untätig ist, verwendet die nächste Ausführung das neue Modell sofort.
• Wenn bereits eine Ausführung aktiv ist, markiert OpenClaw einen Live-Wechsel als ausstehend und startet erst an einem sauberen Wiederholungspunkt mit dem neuen Modell neu.
• Wenn Tool-Aktivität oder Antwortausgabe bereits begonnen haben, kann der ausstehende Wechsel bis zu einer späteren Wiederholungsmöglichkeit oder bis zum nächsten Benutzer-Turn in der Warteschlange bleiben.
• /model status ist die detaillierte Ansicht (Auth-Kandidaten und, wenn konfiguriert, Provider-Endpunkt baseUrl + api-Modus).
• Modellreferenzen werden durch Aufteilen am ersten / geparst. Verwenden Sie provider/model, wenn Sie /model <ref> eingeben.
• Wenn die Modell-ID selbst / enthält (OpenRouter-Stil), müssen Sie das Provider-Präfix angeben (Beispiel: /model openrouter/moonshotai/kimi-k2).
• Wenn Sie den Provider weglassen, löst OpenClaw die Eingabe in dieser Reihenfolge auf:
  1. Alias-Treffer
  2. eindeutiger Treffer eines konfigurierten Providers für genau diese Modell-ID ohne Präfix
  3. veralteter Fallback auf den konfigurierten Standard-Provider Wenn dieser Provider das konfigurierte Standardmodell nicht mehr bereitstellt, fällt OpenClaw stattdessen auf das erste konfigurierte Provider-/Modellpaar zurück, um keinen veralteten entfernten Provider-Standard anzuzeigen.

​

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

​

models list

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

​

models status

claude auth login
openclaw models status

​

Scanning (kostenlose OpenRouter-Modelle)

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

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

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

​

Modell-Registry (models.json)

• Bereits vorhandene nichtleere baseUrl in der models.json des Agenten gewinnt.
• Nichtleerer apiKey in der models.json des Agenten gewinnt nur dann, wenn dieser Provider im aktuellen Konfigurations-/Auth-Profilkontext nicht über SecretRef verwaltet wird.
• SecretRef-verwaltete apiKey-Werte von Providern werden aus Quellmarkierungen (ENV_VAR_NAME für Env-Referenzen, secretref-managed für Datei-/Exec-Referenzen) aktualisiert, statt aufgelöste Secrets zu persistieren.
• SecretRef-verwaltete Header-Werte von Providern werden aus Quellmarkierungen aktualisiert (secretref-env:ENV_VAR_NAME für Env-Referenzen, secretref-managed für Datei-/Exec-Referenzen).
• Leere oder fehlende apiKey/baseUrl des Agenten fallen auf models.providers in der Konfiguration zurück.
• Andere Provider-Felder werden aus der Konfiguration und normalisierten Katalogdaten aktualisiert.

​

Verwandt

• Model Providers — Provider-Routing und Auth
• Model Failover — Fallback-Ketten
• Image Generation — Konfiguration von Bildmodellen
• Configuration Reference — Modell-Konfigurationsschlüssel