Modell-CLI

Eine Modellreferenz (provider/model) wählt einen Provider und ein Modell aus, nicht die Low-Level-Agent-Runtime. Wenn keine Runtime-Richtlinie festgelegt ist oder auto verwendet wird, kann die Provider-eigene Routing-Richtlinie von OpenAI Codex nur für eine exakte offizielle HTTPS-Platform-Responses- oder ChatGPT-Responses-Route auswählen, bei der die Anfrage keine explizite Überschreibung enthält; das Präfix openai/* allein wählt niemals Codex aus. Completions-Adapter, benutzerdefinierte Endpunkte und explizit festgelegtes Anfrageverhalten verbleiben bei OpenClaw. Offizielle Klartext-HTTP-Endpunkte werden abgelehnt. Siehe Implizite Agent-Runtime von OpenAI.

Copilot-Abonnementreferenzen (github-copilot/*) können für das externe GitHub-Copilot-Agent-Runtime-Plugin aktiviert werden, dieser Pfad ist jedoch immer explizit (und wird niemals durch auto ausgewählt). Runtime-Überschreibungen gehören in die Provider-/Modellrichtlinie, nicht auf den gesamten Agenten oder die gesamte Sitzung. Die Runtime-Auswahl bestimmt nicht die Abrechnung: Anmeldedaten für OpenAI-API-Schlüssel und ChatGPT-/Codex-Abonnements bleiben getrennt. Siehe Agent-Runtimes und GitHub-Copilot-Agent-Runtime.

Auswahlreihenfolge

Zugehörige Oberflächen zur Modellkonfiguration:

• agents.defaults.models speichert Aliasse und modellspezifische Einstellungen. Das Hinzufügen eines Eintrags schränkt Modellüberschreibungen nicht ein.
• agents.defaults.modelPolicy.allow ist die optionale Positivliste für Überschreibungen. Verwenden Sie exakte Referenzen oder abschließende Präfix-Platzhalter wie provider/* und provider/namespace/*; lassen Sie sie weg oder setzen Sie [], um jedes Modell zuzulassen. Das agentenspezifische agents.entries.*.modelPolicy.allow ersetzt die Standardrichtlinie für diesen Agenten.
• agents.defaults.utilityModel ist ein optionales kostengünstigeres Modell für kurze interne Aufgaben wie generierte Sitzungstitel im Dashboard, unterstützte Kanal-Thread-/Thementitel und Fortschrittsbeschreibungen. Das agentenspezifische agents.entries.*.utilityModel überschreibt es. Wenn es nicht festgelegt ist, verwendet OpenClaw den deklarierten Standard des primären Providers für kleine Modelle, sofern vorhanden (OpenAI → gpt-5.6-luna, Anthropic → claude-haiku-4-5), andernfalls das primäre Modell des Agenten; setzen Sie es auf eine leere Zeichenfolge, um das Utility-Routing zu deaktivieren. Generierte Titel werden einmal mit dem primären Modell erneut versucht, wenn ein separates Utility-Modell fehlschlägt. Bei Dashboard-Titeln folgen die automatische Utility-Ableitung und der reguläre Fallback dem effektiven Sitzungs-Provider und Auth-Profil; ein explizites Utility-Modell behält seinen konfigurierten Provider und seine konfigurierte Authentifizierung bei. Ein leeres Utility-Modell überspringt nur die alternative Route über das kleine Modell, nicht die Generierung von Dashboard-Titeln. Utility-Aufgaben sind separate Modellaufrufe und können begrenzte Aufgabeninhalte an den ausgewählten Modell-Provider senden.
• agents.defaults.imageModel wird nur verwendet, wenn das primäre Modell keine Bilder akzeptieren kann.
• agents.defaults.pdfModel wird vom Werkzeug pdf verwendet. Wenn es nicht festgelegt ist, greift das Werkzeug auf imageModel und anschließend auf das aufgelöste Sitzungs-/Standardmodell zurück.
• agents.defaults.mediaModels.{image,music,video} dient als Grundlage für die gemeinsam genutzten Werkzeuge zur Mediengenerierung. Wenn es nicht festgelegt ist, leitet jedes Werkzeug einen durch Authentifizierung gestützten Provider-Standard ab: zuerst den aktuellen Standard-Provider, dann die übrigen registrierten Provider für diese Fähigkeit in der Reihenfolge ihrer Provider-IDs. Provider-übergreifender Fallback ist das fest vorgegebene Standardverhalten.
• Das agentenspezifische agents.entries.*.model (zusammen mit Bindungen) überschreibt agents.defaults.model – siehe Multi-Agent-Routing.

Vollständige Schlüsselreferenz, Standardwerte und JSON5-Beispiele: Konfigurationsreferenz.

Auswahlquelle und Fallback-Strenge

Dasselbe provider/model verhält sich je nach Herkunft unterschiedlich:

Weitere Auswahlregeln:

• Eine Änderung von agents.defaults.model.primary schreibt vorhandene Sitzungsfixierungen nicht um. Wenn der Status This session is pinned to X; config primary Y will apply to new/unpinned sessions. meldet, führen Sie /model default aus, um die Fixierung zu löschen.
• CLI-Auswahlmenüs für das Standardmodell und die Positivliste berücksichtigen models.mode: "replace", indem sie nur models.providers.*.models statt des vollständigen integrierten Katalogs auflisten.
• Die Modellauswahl der Control UI fragt beim Gateway dessen konfigurierte Modellansicht ab. Ein explizites modelPolicy.allow filtert sie einschließlich Einträgen mit abschließendem Präfix-Platzhalter; andernfalls zeigt sie konfigurierte Modelle sowie Provider mit verwendbarer Authentifizierung an. Der vollständige integrierte Katalog ist expliziten Suchansichten vorbehalten (models.list mit view: "all" oder openclaw models list --all).
• Benutzeroberflächen für das Provider-Inventar verwenden models.list mit view: "provider-config", um von der Quelle definierte models.providers.*.models-Zeilen anzuzeigen, ohne Positivlisten der Auswahl anzuwenden.

Vollständige Funktionsweise: Modell-Failover.

Kurze Modellrichtlinie

• Legen Sie als primäres Modell das leistungsfähigste verfügbare Modell der neuesten Generation fest.
• Verwenden Sie Fallbacks für kosten-/latenzsensitive Aufgaben und Chats mit geringeren Anforderungen.
• Vermeiden Sie für Agenten mit aktivierten Werkzeugen oder bei nicht vertrauenswürdigen Eingaben ältere bzw. schwächere Modellstufen.

Onboarding

openclaw onboard

Richtet Modell und Authentifizierung für gängige Provider ein, ohne die Konfiguration manuell zu bearbeiten, einschließlich OAuth für OpenAI-Codex-Abonnements und Anthropic (API-Schlüssel oder Wiederverwendung der Claude CLI).

Wenn kein primäres Modell konfiguriert ist, wählt eine neue Einrichtung mit OpenAI-API-Schlüssel openai/gpt-5.6; die reine Direct-API-ID wird in die Sol-Stufe aufgelöst. Eine neue Einrichtung mit ChatGPT-/Codex-OAuth wählt die exakte Katalogreferenz openai/gpt-5.6-sol. Eine erneute Authentifizierung behält ein vorhandenes explizites primäres Modell bei, einschließlich openai/gpt-5.5. Wenn GPT-5.6 für das Konto nicht verfügbar ist, wählen Sie openai/gpt-5.5 explizit aus; OpenClaw stuft es nicht stillschweigend herab.

„Modell ist nicht zulässig“ (und warum Antworten ausbleiben)

Wenn agents.defaults.modelPolicy.allow nicht leer ist, wird es zur Positivliste für /model, Sitzungsüberschreibungen und --model. Die Auswahl eines Modells außerhalb dieser Positivliste führt zur Rückkehr, bevor eine normale Antwort generiert wird. Ein agentenspezifisches agents.entries.*.modelPolicy.allow ersetzt die Standardrichtlinie für diesen Agenten.

Die Modellüberschreibung "provider/model" ist durch agents.defaults.modelPolicy.allow nicht zulässig.Fügen Sie "provider/model", "provider/*" oder ein enger gefasstes Präfix "provider/namespace/*" zu agents.defaults.modelPolicy.allow hinzu oder entfernen/leeren Sie die Liste, um jedes Modell zuzulassen.

Beheben Sie dies, indem Sie das Modell oder einen Provider-Platzhalter zum genannten Schlüssel modelPolicy.allow hinzufügen, diese Liste entfernen/leeren oder ein Modell aus /model list auswählen. Wenn der abgelehnte Befehl eine Runtime-Überschreibung wie /model openai/gpt-5.5 --runtime codex enthielt, korrigieren Sie zuerst die Positivliste und versuchen Sie anschließend denselben Befehl erneut.

Für lokale/GGUF-Modelle muss die Positivliste die vollständige Referenz mit Provider-Präfix enthalten, beispielsweise ollama/gemma4:26b oder lmstudio/Gemma4-26b-a4-it-gguf – prüfen Sie openclaw models list --provider <provider> auf die exakte Zeichenfolge. Reine Dateinamen oder Anzeigenamen reichen nicht aus, sobald die Positivliste aktiv ist.

Um Provider einzuschränken, ohne jedes Modell aufzulisten, verwenden Sie Einträge mit abschließendem Präfix-Platzhalter. Ein Provider-weiter Eintrag provider/* entspricht jedem Modell dieses Providers; ein enger gefasstes Präfix wie clawrouter/anthropic/* entspricht nur diesem Namespace:

{  agents: {    defaults: {      modelPolicy: {        allow: ["openai/*", "vllm/*"],      },    },  },}

/model, /models und Modellauswahlmenüs zeigen dann nur den ermittelten Katalog dieser Provider an, und neue Modelle können erscheinen, ohne die Positivliste zu bearbeiten. Kombinieren Sie exakte provider/model-Einträge mit provider/*-Einträgen, um ein bestimmtes Modell eines anderen Providers einzubeziehen.

Beispiel einer Positivliste mit Aliassen und modellspezifischen Einstellungen:

{  agents: {    defaults: {      model: { primary: "anthropic/claude-sonnet-4-6" },      modelPolicy: {        allow: ["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "anthropic/claude-opus-4-6": { alias: "Opus" },      },    },  },}

openclaw config set agents.defaults.modelPolicy.allow '["openai/gpt-5.4","anthropic/*"]' --strict-json

/model im Chat

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

• /model und /model list zeigen eine kompakte nummerierte Auswahl (Modellfamilie + verfügbare Provider); /model <#> wählt daraus aus. Auf Discord öffnet dies Dropdown-Menüs für Provider und Modell mit einem Submit-Schritt; auf Telegram gelten Auswahlen in der Auswahl nur für die Sitzung und überschreiben niemals den dauerhaften Standard des Agenten in openclaw.json. /models add ist veraltet und gibt eine Nachricht zurück, statt Modelle über den Chat zu registrieren.
• /model speichert die neue Sitzungsauswahl sofort. Wenn der Agent inaktiv ist, verwendet der nächste Lauf sie unmittelbar; wenn bereits ein Lauf aktiv ist, wird der Wechsel für den nächsten einwandfreien Wiederholungszeitpunkt vorgemerkt (oder einen späteren, falls bereits Tool-Aktivität oder Antwortausgabe begonnen hat).
• /model default löscht die Sitzungsauswahl, sodass sie wieder den konfigurierten Primärwert übernimmt.
• Eine vom Benutzer ausgewählte /model-Referenz gilt strikt für diese Sitzung: Wenn sie nicht mehr erreichbar ist, schlägt die Antwort sichtbar fehl, statt stillschweigend über agents.defaults.model.fallbacks auszuweichen. Konfigurierte Standardwerte und Primärmodelle von Cron-Aufträgen verwenden weiterhin Fallback-Ketten.
• /model status ist die Detailansicht: Authentifizierungskandidaten pro Provider sowie (falls konfiguriert) der Provider-Endpunkt baseUrl und der Modus api.
• Modellreferenzen werden durch Aufteilen am ersten / geparst; geben Sie provider/model ein. Wenn die Modell-ID selbst / enthält (im OpenRouter-Stil), fügen Sie das Provider-Präfix hinzu, z. B. /model openrouter/moonshotai/kimi-k2. Wenn Sie den Provider weglassen, versucht OpenClaw Folgendes: (1) Übereinstimmung mit einem Alias, (2) eindeutige Übereinstimmung mit einem konfigurierten Provider für genau diese Modell-ID ohne Präfix, (3) den konfigurierten Standard-Provider (veralteter Fallback) — und wenn dieser Provider das konfigurierte Standardmodell nicht mehr bereitstellt, stattdessen das erste konfigurierte Provider-/Modellpaar, damit kein veralteter Standardwert eines entfernten Providers angezeigt wird.
• Modellreferenzen werden in Kleinbuchstaben normalisiert; Provider-IDs müssen ansonsten exakt übereinstimmen. Verwenden Sie daher die vom Plugin angegebene ID.

Vollständiges Befehlsverhalten und Konfiguration: Slash-Befehle.

CLI

openclaw models statusopenclaw models listopenclaw models set <provider/model>openclaw models set-image <provider/model>openclaw models scanopenclaw models aliases list|add|removeopenclaw models fallbacks list|add|remove|clearopenclaw models image-fallbacks list|add|remove|clearopenclaw models auth list|add|login|paste-api-key|paste-token|setup-token|order

openclaw models ohne Unterbefehl ist eine Kurzform für models status, das auch den Ablaufzeitpunkt von OAuth für Profile im Authentifizierungsspeicher anzeigt (standardmäßig erfolgt innerhalb von 24h eine Warnung). Vollständige Flags, JSON-Strukturen und Unterbefehle für Authentifizierungsprofile: CLI-Referenz für Modelle.

Modellregistrierung (models.json)

Unter models.providers konfigurierte benutzerdefinierte Provider werden unter dem Agentenverzeichnis (standardmäßig ~/.openclaw/agents/<agentId>/agent/models.json) in models.json geschrieben. Kataloge von Provider-Plugins werden separat als generierte, Plugin-eigene Katalogfragmente gespeichert und automatisch geladen. Diese Datei wird standardmäßig mit der Konfiguration zusammengeführt; setzen Sie models.mode: "replace", um ausschließlich Ihre konfigurierten Provider zu verwenden.

Bei der dauerhaften Speicherung von Markierungen ist die Quelle maßgeblich: OpenClaw schreibt bei jeder Neugenerierung von models.json Markierungen aus dem aktiven Snapshot der Quellkonfiguration (vor der Auflösung), nicht aus aufgelösten Laufzeitwerten von Secrets — einschließlich befehlsgesteuerter Pfade wie openclaw agent.

Verwandte Themen

• Agentenlaufzeiten — OpenClaw, Codex und andere Laufzeiten für Agentenschleifen
• Konfigurationsreferenz — Konfigurationsschlüssel für Modelle
• Bilderzeugung — Konfiguration von Bildmodellen
• Modell-Failover — Fallback-Ketten
• Modell-Provider — Provider-Routing und Authentifizierung
• CLI-Referenz für Modelle — vollständige Referenz für Befehle und Flags
• Musikerzeugung — Konfiguration von Musikmodellen
• Videoerzeugung — Konfiguration von Videomodellen