OpenClaw Tutorial Teil 3: Modelle konfigurieren

📚 Serie: OpenClaw installieren & einrichten — Teil 3 von 8
← Teil 2: Installation | Teil 4: Telegram & WhatsApp verbinden →

Nach Teil 2 läuft OpenClaw bereits mit einem Modell aus dem Onboarding. In diesem Teil prüfst du diese Konfiguration, ergänzt bei Bedarf einen weiteren Provider und richtest eine nachvollziehbare Fallback-Reihenfolge ein.

OpenClaw trennt Provider-Authentifizierung, primäres Modell, Fallbacks und den Modellkatalog für manuelle Wechsel. Modellreferenzen haben das Format provider/model. Verwende nur Referenzen, die deine Installation selbst ausgibt, statt Modellnamen aus älteren Screenshots oder Tutorials zu übernehmen.

Voraussetzungen

Du brauchst eine lauffähige OpenClaw-Installation aus Teil 2, Zugriff auf die OpenClaw-CLI und mindestens einen eingerichteten Modellanbieter. Für einen zusätzlichen Cloud-Provider benötigst du dessen Zugangsdaten. Der interaktive Konfigurationsassistent setzt außerdem ein Terminal voraus.

openclaw configure benötigt laut CLI-Dokumentation ein interaktives Terminal. In einem nicht interaktiven Job verwendest du stattdessen die Unterbefehle von openclaw config.

1. Aktive Konfiguration und Ausgangszustand prüfen

Zeige den Pfad der aktiven Konfiguration an:

openclaw config file

Validiere anschließend den unveränderten Ausgangszustand:

openclaw config validate

Bei einer gültigen Konfiguration endet der Befehl erfolgreich. Meldet er bereits jetzt einen Fehler, behebe diesen vor den Modelländerungen. So kannst du spätere Fehler eindeutig einer Änderung zuordnen.

Prüfe danach die Modellkonfiguration:

openclaw models status
openclaw models list
openclaw config get agents.defaults.model --json
openclaw config get agents.defaults.models --json

openclaw models list zeigt den konfigurierten Modellkatalog. openclaw models status zeigt das aufgelöste Primary Model, die Fallbacks und den Auth-Zustand.

Unter agents.defaults.model liegen Primary Model und Fallback-Liste. Das Objekt agents.defaults.models ist der konfigurierte Modellkatalog und die Allowlist. Seine Einträge können außerdem Aliasse und per-Modell-Einstellungen enthalten.

Speichere die beiden JSON-Ausgaben von config get, bevor du Werte änderst. Notiere auch, wenn einer der Pfade noch nicht existiert. Diese Information brauchst du für einen vollständigen Rollback.

Wenn OPENCLAW_NIX_MODE=1 aktiv ist, verweigert OpenClaw schreibende config-Operationen. Ändere in diesem Fall die Nix-Quelle deiner Installation und nutze die hier gezeigten Lese- und Prüfkommandos zur Kontrolle.

2. Modellkonfiguration richtig einordnen

Ein Auth-Profil stellt die Zugangsdaten für einen Provider bereit. Das Standardmodell steht unter agents.defaults.model.primary. Die geordnete Liste unter agents.defaults.model.fallbacks enthält die Ausweichmodelle.

agents.defaults.models erfüllt eine andere Aufgabe. Das Objekt ist der Modellkatalog und die Allowlist der aktuellen Runtime. Seine Schlüssel sind vollständige Referenzen wie provider/model.

Ist das Objekt gesetzt, steuern diese Einträge, welche Modelle unter anderem in /model und im Model-Picker angeboten werden. In den zugehörigen Objekten lassen sich zusätzlich Aliasse und per-Modell-Einstellungen speichern.

Ein Eintrag in agents.defaults.models wird nicht automatisch zum Fallback. Dafür ist weiterhin agents.defaults.model.fallbacks zuständig. Ein Primary Model oder Fallback sollte zusätzlich im Modellkatalog stehen, wenn es für manuelle Wechsel angeboten werden soll.

3. Modellreferenzen ermitteln

Zeige den konfigurierten Katalog an:

openclaw models list

Den vollständigen bekannten Katalog liefert:

openclaw models list --all

Für einen bestimmten Provider kannst du die Ausgabe filtern:

openclaw models list --provider <provider-id>

Übernimm eine vollständige Referenz aus der Ausgabe, etwa provider/modell-id. Der Katalog bestätigt den Namen der Modellroute. Er bestätigt nicht, dass die Zugangsdaten funktionieren oder eine Anfrage erfolgreich verarbeitet wird. Diese Prüfungen folgen separat.

4. Provider ergänzen oder neu authentifizieren

Für gezielte Änderungen am Modellbereich kannst du den Konfigurationsassistenten öffnen:

openclaw configure --section model

Das erneute Einrichten oder Authentifizieren eines Providers ersetzt ein vorhandenes Primary Model nicht automatisch. Ein zusätzlicher Provider übernimmt daher nicht ungefragt den bisherigen Standard.

Alternativ bietet OpenClaw einen interaktiven Auth-Helfer:

openclaw models auth add

Provider-Plugins können eigene Login-Verfahren bereitstellen. Prüfe die installierten Plugins und starte danach nur einen von deiner Installation unterstützten Auth-Flow:

openclaw plugins list
openclaw models auth login --provider <provider-id>

Für OpenAI ist dieser Aufruf konkret dokumentiert:

openclaw models auth login --provider openai

Soll das vom Provider empfohlene Modell bewusst zum Standard werden, kannst du beim OpenAI-Login den dokumentierten Schalter ergänzen:

openclaw models auth login --provider openai --set-default

Ohne diese Auswahl bleibt das vorhandene Primary Model erhalten.

Prüfe nach dem Login erneut:

openclaw models status
openclaw models list --provider <provider-id>

models status sollte für den Provider keinen fehlenden oder unbrauchbaren Credential-Status melden. Die gefilterte Katalogausgabe muss die Modellreferenz enthalten, die du später verwenden möchtest.

5. Primary Model setzen

Wähle eine exakte Referenz aus openclaw models list und setze sie als Standardmodell:

openclaw models set <provider>/<primary-modell>

Alternativ kannst du den Config-Pfad direkt setzen:

openclaw config set agents.defaults.model.primary "<provider>/<primary-modell>"

Kontrolliere den gespeicherten Wert und die Struktur der Konfiguration:

openclaw config get agents.defaults.model.primary
openclaw config validate

Die Config-Ausgabe muss die gewählte Referenz enthalten. Die Validierung muss erfolgreich enden. Ob die Route praktisch funktioniert, prüfst du in Schritt 10.

6. Fallbacks in sinnvoller Reihenfolge ergänzen

OpenClaw versucht das Primary Model. Danach folgen die Einträge aus agents.defaults.model.fallbacks in ihrer gespeicherten Reihenfolge.

Gibt es mehrere Auth-Profile für denselben Provider, findet deren Auth-Failover innerhalb des Providers statt. Erst danach wechselt OpenClaw zum nächsten Fallback-Modell.

Nimm für Fallbacks nur Referenzen, die du zuvor mit openclaw models list geprüft hast. Ein einzelnes Fallback setzt du als JSON-Array:

openclaw config set agents.defaults.model.fallbacks '["<provider>/<fallback-modell>"]' --strict-json
openclaw config validate

Mehrere Fallbacks werden in der gewünschten Reihenfolge eingetragen:

openclaw config set agents.defaults.model.fallbacks '["<provider-a>/<fallback-1>","<provider-b>/<fallback-2>"]' --strict-json
openclaw config validate

Ein einzelner String ist an diesem Pfad falsch, weil das Runtime-Schema ein Array verlangt.

Du kannst die Liste auch mit der Models-CLI verwalten:

openclaw models fallbacks list
openclaw models fallbacks add <provider>/<fallback-modell>
openclaw models fallbacks remove <provider>/<fallback-modell>

Kontrolliere anschließend die gespeicherte und die aufgelöste Reihenfolge:

openclaw config get agents.defaults.model.fallbacks --json
openclaw models status

7. Allowlist für Picker und /model festlegen

Das Runtime-Schema beschreibt agents.defaults.models als Modellkatalog und Allowlist. Verwende vollständige Modellreferenzen als Schlüssel, damit klar bleibt, welche Modelle für manuelle Wechsel angeboten werden.

Prüfe die vorhandenen Einträge:

openclaw config get agents.defaults.models --json

Ergänze danach ein Modell, ohne vorhandene Einträge zu ersetzen:

openclaw config set agents.defaults.models '{"<provider>/<modell-id>":{}}' --strict-json --merge
openclaw config validate

Wiederhole den Merge-Aufruf für weitere Modelle. Das leere Objekt hält den Eintrag in der Allowlist. Bei Bedarf kann es später Alias- oder Modellparameter aufnehmen.

Prüfe das Ergebnis:

openclaw config get agents.defaults.models --json
openclaw models list

Die JSON-Ausgabe muss den neuen Schlüssel enthalten. Das Modell sollte anschließend im konfigurierten Katalog erscheinen. Dieser Katalogeintrag sagt noch nichts über die Gültigkeit der Zugangsdaten aus.

8. Zugangsdaten und Secrets prüfen

Nutze die vorgesehenen Auth-Flows, statt API-Schlüssel direkt in die Hauptkonfiguration zu schreiben. Zugangsdaten gehören weder in Git noch in Screenshots oder Chatlogs.

OpenClaw kann gespeicherte Auth-Profile auflisten, ohne Token, API-Key oder OAuth-Secret auszugeben:

openclaw models auth list

Für einen einzelnen Provider filterst du die Ausgabe:

openclaw models auth list --provider <provider-id>

Wenn du SecretRefs oder externe Secret-Quellen einrichten möchtest, führt der Praxisartikel OpenClaw SecretRef richtig einsetzen durch die Einrichtung.

Das Schema deiner installierten Version kannst du lokal ausgeben:

openclaw config schema

9. Lokale Modelle mit Ollama

OpenClaw führt Ollama als eigenen Provider. Konkrete Modellnamen und Provider-Einstellungen hängen von der installierten OpenClaw- und Ollama-Version ab. Verwende deshalb die aktuelle Provider-Dokumentation und die lokale CLI-Ausgabe.

Nach der Einrichtung prüfst du den erkannten Katalog mit:

openclaw models scan
openclaw models list --provider ollama
openclaw models status

models scan liefert Erkennungsinformationen. Übernimm anschließend ausschließlich eine Modellreferenz, die openclaw models list --provider ollama tatsächlich ausgibt.

Die vollständige Einrichtung behandelt der Guide OpenClaw mit Ollama: lokale Modelle einrichten, Limits prüfen, Stalls vermeiden.

10. Konfiguration und Modellroute testen

Die Schema-Validierung prüft die Struktur der Konfiguration:

openclaw config validate

Eine maschinenlesbare Ausgabe erhältst du mit:

openclaw config validate --json

Eine erfolgreiche Validierung bestätigt weder einen gültigen API-Schlüssel noch eine erreichbare Modellroute. Prüfe deshalb anschließend den aufgelösten Status:

openclaw models status

Wenn du die Zugangsdaten aktiv gegen den Provider testen möchtest, unterstützt die installierte CLI einen Live-Probe:

openclaw models status --probe

Der Probe kann eine Provider-Anfrage auslösen und damit Netzwerkzugriff, Kontingent oder geringe Kosten verursachen. Begrenze ihn bei Bedarf auf den betroffenen Provider:

openclaw models status --probe --probe-provider <provider-id>

Sende danach über deinen eingerichteten OpenClaw-Zugang eine kurze, unkritische Testanfrage. openclaw config validate muss eine gültige Konfiguration melden. openclaw models status muss das gewünschte Primary Model und die erwarteten Fallbacks zeigen.

Der Auth-Status oder Live-Probe darf keine unbrauchbaren Zugangsdaten melden. Die Testanfrage muss außerdem eine Antwort über die eingerichtete Modellroute liefern.

Wenn OpenClaw als Dienst läuft und deine Installationsart nach einer Änderung einen Neustart verlangt, verwende denselben Dienstmechanismus wie in Teil 2. Prüfe danach Status und Testanfrage erneut.

Änderungen zurücknehmen

Stellt sich nach der Änderung ein Problem heraus, setze die zuvor gesicherten Werte wieder ein. Das frühere Primary Model stellst du so wieder her:

openclaw config set agents.defaults.model.primary "<vorheriges-primary-modell>"

Fallbacks setzt du auf das zuvor gesicherte JSON-Array zurück:

openclaw config set agents.defaults.model.fallbacks '<vorheriges-json-array>' --strict-json

Den früheren Modellkatalog und seine Allowlist stellst du mit dem gesicherten JSON-Objekt wieder her:

openclaw config set agents.defaults.models '<vorheriges-json-objekt>' --strict-json

Existierte ein Feld vor der Änderung nicht, entferne genau dieses Feld wieder. Beispiele:

openclaw config unset agents.defaults.model.primary
openclaw config unset agents.defaults.model.fallbacks
openclaw config unset agents.defaults.models

Führe nur die passenden unset-Befehle aus. Validiere danach die zurückgesetzte Konfiguration und kontrolliere die aufgelöste Modellroute:

openclaw config validate
openclaw models status

Typische Fehler

Modelle und Provider

Problem	Wahrscheinliche Ursache	Prüfung und Lösung
Modellreferenz wird nicht gefunden	Name ist veraltet oder nicht im lokalen Katalog	Exakte Referenz mit openclaw models list oder openclaw models list --all ermitteln
Provider-Login ist nicht verfügbar	Das benötigte Provider-Plugin fehlt oder bietet keinen solchen Auth-Flow	openclaw plugins list prüfen und nur einen angebotenen Login verwenden
Provider ist eingerichtet, aber das Standardmodell bleibt unverändert	Authentifizierung ersetzt das Primary Model nicht automatisch	openclaw models set <provider/model> verwenden
Modell erscheint nicht im Picker	Es fehlt in der Allowlist unter agents.defaults.models	Exakte Referenz per --merge ergänzen und den Katalog erneut ausgeben

Konfiguration und Betrieb

Problem	Wahrscheinliche Ursache	Prüfung und Lösung
Fallbacks validieren nicht	Statt eines Arrays wurde ein String gespeichert	agents.defaults.model.fallbacks als JSON-Array mit --strict-json setzen
Status zeigt unbrauchbare Credentials	Auth-Profil fehlt, ist abgelaufen oder kann nicht aufgelöst werden	Auth-Liste, Status und bei Bedarf Live-Probe prüfen
Config lässt sich nicht schreiben	Nix-Modus ist aktiv	Nix-Quelle ändern und schreibende openclaw config-Befehle vermeiden
Validierung ist erfolgreich, Anfragen scheitern aber	Provider oder Zugangsdaten funktionieren praktisch nicht	Status, gezielten Live-Probe und eine Testanfrage ausführen
Fallback greift anders als erwartet	Auth-Failover läuft vor dem Modell-Fallback	Auth-Profile und Fallback-Reihenfolge getrennt prüfen

Kernpunkte

Das Primary Model liegt unter agents.defaults.model.primary. Die geordnete Fallback-Liste liegt unter agents.defaults.model.fallbacks. Modellkatalog und Allowlist werden unter agents.defaults.models gepflegt.

openclaw models list liefert Modellreferenzen, aber keinen Laufzeitnachweis. openclaw config validate prüft das Schema. openclaw models status zeigt die aufgelösten Routen und den Auth-Zustand. Ein optionaler Live-Probe sowie eine kurze Testanfrage prüfen die praktische Erreichbarkeit.

Sichere die vorhandenen Config-Werte vor jeder Änderung. So kannst du gesetzte Werte wiederherstellen oder neu angelegte Felder mit openclaw config unset entfernen.

Im nächsten Teil verbindest du OpenClaw mit externen Kanälen wie Telegram und WhatsApp.