Models CLI

Siehe /concepts/model-failover für Auth-Profil-Rotation, Cooldowns und wie das mit Fallbacks zusammenspielt. Schneller Provider-Überblick mit Beispielen: /concepts/model-providers.

So funktioniert die Modellauswahl

OpenClaw wählt Modelle in dieser Reihenfolge:

  1. Primary-Modell (agents.defaults.model.primary oder agents.defaults.model).
  2. Fallbacks in agents.defaults.model.fallbacks (der Reihe nach).
  3. Provider Auth Failover passiert innerhalb eines Providers, bevor zum nächsten Modell gewechselt wird.

Verwandte Einstellungen:

  • agents.defaults.models ist die Allowlist/der Katalog der Modelle, die OpenClaw nutzen kann (plus Aliase).
  • agents.defaults.imageModel wird nur verwendet, wenn das Primary-Modell keine Bilder verarbeiten kann.
  • Pro-Agent-Defaults können agents.defaults.model über agents.list[].model plus Bindings überschreiben (siehe /concepts/multi-agent).

Schnelle Modellempfehlungen (aus Erfahrung)

  • GLM: etwas besser für Coding/Tool Calling.
  • MiniMax: besser für Texte und Vibes.

Setup-Wizard (empfohlen)

Wenn du die Config nicht manuell bearbeiten willst, starte den Onboarding-Wizard:

openclaw onboard

Er kann Modell + Auth für gängige Provider einrichten, darunter OpenAI Code (Codex) Subscription (OAuth) und Anthropic (API-Key empfohlen; claude setup-token wird auch unterstützt).

Config-Keys (Überblick)

  • 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 (Custom Provider werden in models.json geschrieben)

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

Beispiele zur Provider-Konfiguration (inkl. OpenCode Zen) findest du unter /gateway/configuration.

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

Wenn agents.defaults.models gesetzt ist, wird es zur Allowlist für /model und Session-Overrides. Wenn du ein Modell auswählst, das nicht in dieser Allowlist ist, gibt OpenClaw zurück:

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

Das passiert bevor eine normale Antwort generiert wird, sodass es wirken kann, als hätte OpenClaw “nicht geantwortet”. Die Lösung ist:

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

Beispiel Allowlist-Config:

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

Modelle im Chat wechseln (/model)

Du kannst Modelle für die aktuelle Session 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 + verfügbare Provider).
  • /model <#> wählt aus diesem Picker aus.
  • /model status zeigt die Detailansicht (Auth-Kandidaten und, wenn konfiguriert, Provider-Endpoint baseUrl + api-Modus).
  • Model-Refs werden am ersten / geteilt. Nutze provider/model beim Eingeben von /model <ref>.
  • Wenn die Model-ID selbst / enthält (OpenRouter-Style), musst du das Provider-Präfix angeben (Beispiel: /model openrouter/moonshotai/kimi-k2).
  • Wenn du den Provider weglässt, behandelt OpenClaw die Eingabe als Alias oder als Modell für den Default-Provider (funktioniert nur, wenn kein / in der Model-ID ist).

Vollständiges Command-Verhalten/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 Subcommand) ist eine Abkürzung für models status.

models list

Zeigt standardmäßig konfigurierte Modelle. Nützliche Flags:

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

models status

Zeigt das aufgelöste Primary-Modell, Fallbacks, Image-Modell und einen Auth-Überblick der konfigurierten Provider. Außerdem wird der OAuth-Ablaufstatus für Profile im Auth-Store angezeigt (warnt standardmäßig innerhalb von 24h). --plain gibt nur das aufgelöste Primary-Modell aus.

OAuth-Status wird immer angezeigt (und in --json-Output eingeschlossen). Wenn ein konfigurierter Provider keine Credentials hat, zeigt models status einen Missing auth-Abschnitt.

JSON enthält auth.oauth (Warn-Fenster + Profile) und auth.providers (effektive Auth pro Provider).

Nutze --check für Automatisierung (Exit 1 bei fehlend/abgelaufen, 2 bei bald ablaufend).

Bevorzugte Anthropic-Auth ist der Claude Code CLI setup-token (überall ausführbar; bei Bedarf auf dem Gateway-Host einfügen):

claude setup-token
openclaw models status

Scanning (OpenRouter Free Models)

openclaw models scan untersucht OpenRouters Free-Model-Katalog und kann optional Modelle auf Tool- und Image-Support prüfen.

Wichtige Flags:

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

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

Scan-Ergebnisse werden sortiert nach:

  1. Image-Support
  2. Tool-Latenz
  3. Context-Größe
  4. Parameter-Anzahl

Input

  • OpenRouter /models-Liste (Filter :free)
  • Erfordert OpenRouter API-Key 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 auswählen. Im nicht-interaktiven Modus übergib --yes, um Defaults zu akzeptieren.

Models Registry (models.json)

Custom Provider in models.providers werden in models.json im Agent-Verzeichnis geschrieben (Standard: ~/.openclaw/agents/<agentId>/models.json). Diese Datei wird standardmäßig gemergt, es sei denn models.mode ist auf replace gesetzt.