Models CLI

Siehe /concepts/model-failover fuer Auth-Profil-Rotation, Cooldowns und wie das mit Fallbacks zusammenspielt. Schneller Provider-Ueberblick mit Beispielen: /concepts/model-providers.

Wie die Modellauswahl funktioniert

OpenClaw waehlt Modelle in dieser Reihenfolge:

  1. Primaeres 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 naechsten Modell gewechselt wird.

Verwandt:

  • agents.defaults.models ist die Allowlist/der Katalog der Modelle, die OpenClaw nutzen kann (plus Aliase).
  • agents.defaults.imageModel wird nur genutzt, wenn das primaere Modell keine Bilder akzeptieren kann.
  • Pro-Agent-Defaults koennen agents.defaults.model ueber agents.list[].model plus Bindings ueberschreiben (siehe /concepts/multi-agent).

Schnelle Modell-Policy

  • Setze dein primaeres Modell auf das staerkste verfuegbare Modell der aktuellen Generation.
  • Nutze Fallbacks fuer kosten-/latenz-sensitive Aufgaben und weniger kritische Chats.
  • Fuer toolfaehige Agenten oder nicht vertrauenswuerdige Eingaben vermeide aeltere/schwaechere Modell-Stufen.

Setup-Assistent (empfohlen)

Wenn du die Config nicht von Hand bearbeiten willst, starte den Onboarding-Assistenten:

openclaw onboard

Er kann Modell und Auth fuer gaengige Provider einrichten, darunter OpenAI Code (Codex) Subscription (OAuth) und Anthropic (API-Schluessel oder claude setup-token).

Config-Schluessel (Ueberblick)

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

Model-Refs werden auf Kleinbuchstaben normalisiert. Provider-Aliase wie z.ai/* werden zu zai/* normalisiert.

Provider-Konfigurationsbeispiele (einschliesslich OpenCode) findest du in /gateway/configuration.

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

Wenn agents.defaults.models gesetzt ist, wird es zur Allowlist fuer /model und fuer Sitzungs-Overrides. Wenn ein Nutzer ein Modell auswaehlt, das nicht in der Allowlist steht, gibt OpenClaw zurueck:

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

Das passiert vor der normalen Antwortgenerierung, sodass die Nachricht sich anfuehlen kann, als haette sie “nicht geantwortet”. Die Loesung ist entweder:

  • Das Modell zu agents.defaults.models hinzufuegen, oder
  • Die Allowlist leeren (entferne agents.defaults.models), oder
  • Ein Modell aus /model list waehlen.

Beispiel-Allowlist-Config:

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

Modelle im Chat wechseln (/model)

Du kannst Modelle fuer die aktuelle Sitzung wechseln, ohne neu zu starten:

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

Hinweise:

  • /model (und /model list) ist ein kompakter, nummerierter Picker (Modellfamilie + verfuegbare Provider).
  • Auf Discord oeffnen /model und /models einen interaktiven Picker mit Provider- und Modell-Dropdowns plus Submit-Schritt.
  • /model <#> waehlt aus diesem Picker.
  • /model status ist die ausfuehrliche Ansicht (Auth-Kandidaten und, wenn konfiguriert, Provider-Endpunkt baseUrl + api-Modus).
  • Model-Refs werden durch Aufteilen am ersten / geparst. Verwende provider/model beim Eingeben von /model <ref>.
  • Wenn die Modell-ID selbst / enthaelt (OpenRouter-Stil), musst du den Provider-Praefix angeben (Beispiel: /model openrouter/moonshotai/kimi-k2).
  • Wenn du den Provider weglaeest, behandelt OpenClaw die Eingabe als Alias oder als Modell fuer den Standard-Provider (funktioniert nur, wenn kein / in der Modell-ID steht).

Vollstaendiges Befehlsverhalten/-config: 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 Abkuerzung fuer models status.

models list

Zeigt standardmaessig konfigurierte Modelle. Nuetzliche Flags:

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

models status

Zeigt das aufgeloeste primaere Modell, Fallbacks, Bildmodell und einen Auth-Ueberblick der konfigurierten Provider. Zeigt auch den OAuth-Ablauf-Status fuer Profile im Auth-Store an (warnt standardmaessig innerhalb von 24h). --plain gibt nur das aufgeloeste primaere Modell aus. OAuth-Status wird immer angezeigt (und in --json-Ausgabe einbezogen). Wenn ein konfigurierter Provider keine Zugangsdaten hat, gibt models status einen Missing auth-Abschnitt aus. JSON enthaelt auth.oauth (Warnfenster + Profile) und auth.providers (effektive Auth pro Provider). Verwende --check fuer Automatisierung (Exit 1 bei fehlend/abgelaufen, 2 bei bald ablaufend).

Die Auth-Wahl haengt vom Provider/Account ab. Fuer Always-on-Gateway-Hosts sind API-Schluessel normalerweise am berechenbarsten; Subscription-Token-Flows werden ebenfalls unterstuetzt.

Beispiel (Anthropic Setup-Token):

claude setup-token
openclaw models status

Scanning (OpenRouter kostenlose Modelle)

openclaw models scan inspiziert OpenRouters kostenlosen Modellkatalog und kann optional Modelle auf Tool- und Bild-Unterstuetzung pruefen.

Wichtige Flags:

  • --no-probe: Live-Pruefungen ueberspringen (nur Metadaten)
  • --min-params <b>: minimale Parametergroesse (Milliarden)
  • --max-age-days <tage>: aeltere Modelle ueberspringen
  • --provider <name>: Provider-Praefix-Filter
  • --max-candidates <n>: Fallback-Listengroesse
  • --set-default: setzt agents.defaults.model.primary auf die erste Auswahl
  • --set-image: setzt agents.defaults.imageModel.primary auf die erste Bild-Auswahl

Probing erfordert einen OpenRouter-API-Schluessel (aus Auth-Profilen oder OPENROUTER_API_KEY). Ohne Schluessel verwende --no-probe, um nur Kandidaten aufzulisten.

Scan-Ergebnisse werden gerankt nach:

  1. Bild-Unterstuetzung
  2. Tool-Latenz
  3. Kontextgroesse
  4. Parameteranzahl

Eingabe

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

Im TTY-Modus kannst du Fallbacks interaktiv auswaehlen. Im nicht-interaktiven Modus verwende --yes, um Standards zu akzeptieren.

Models-Registry (models.json)

Benutzerdefinierte Provider in models.providers werden in models.json unter dem Agent-Verzeichnis geschrieben (Standard ~/.openclaw/agents/<agentId>/agent/models.json). Diese Datei wird standardmaessig gemergt, es sei denn, models.mode ist auf replace gesetzt.

Merge-Modus-Vorrang fuer uebereinstimmende Provider-IDs:

  • Nicht-leere baseUrl, die bereits in der Agent-models.json vorhanden ist, gewinnt.
  • Nicht-leere apiKey in der Agent-models.json gewinnt nur, wenn dieser Provider nicht SecretRef-verwaltet im aktuellen Config/Auth-Profil-Kontext ist.
  • SecretRef-verwaltete Provider-apiKey-Werte werden aus Quell-Markern aktualisiert (ENV_VAR_NAME fuer Env-Refs, secretref-managed fuer Datei-/Exec-Refs), statt aufgeloeste Secrets zu persistieren.
  • SecretRef-verwaltete Provider-Header-Werte werden aus Quell-Markern aktualisiert (secretref-env:ENV_VAR_NAME fuer Env-Refs, secretref-managed fuer Datei-/Exec-Refs).
  • Leere oder fehlende Agent-apiKey/baseUrl fallen auf Config-models.providers zurueck.
  • Andere Provider-Felder werden aus Config und normalisierten Katalogdaten aktualisiert.

Marker-Persistenz ist quell-autoritativ: OpenClaw schreibt Marker aus dem aktiven Quell-Config-Snapshot (vor Aufloesung), nicht aus aufgeloesten Runtime-Secret-Werten. Das gilt immer, wenn OpenClaw models.json regeneriert, einschliesslich befehlsgesteuerter Pfade wie openclaw agent.

arrow_back
Zurück
Models
Weiter
Model Providers
arrow_forward