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. Genau deshalb ist dieser Schritt wichtiger, als er zunächst wirkt: Nicht einfach das nächste Modell irgendwo eintragen, sondern die vorhandene Konfiguration so aufräumen, dass dein Setup auch dann weiterarbeitet, wenn ein Provider hakt, ein Modell verschwindet oder ein Login ausläuft.

Die OpenClaw-Doku trennt dabei sauber zwischen Modellreferenzen, Provider-Authentifizierung, Standardmodell, Fallbacks und optionaler Allowlist. Wenn du diese Ebenen nicht vermischst, sparst du dir später viele der typischen Fehler, die erst unter Last oder mitten im Arbeitsalltag auffallen.

Wichtig vorweg: Modellreferenzen folgen dem Muster provider/model, also zum Beispiel openai/<modell-id> oder anthropic/<modell-id>. Welche Modell-IDs deine Installation aktuell wirklich kennt, prüfst du nicht über Blogposts oder Screenshots, sondern live mit openclaw models list und openclaw models status.

Voraussetzungen für diesen Schritt

Du brauchst:

• eine lauffähige OpenClaw-Installation aus Teil 2,
• Zugriff auf die OpenClaw-CLI,
• mindestens einen nutzbaren Modellanbieter oder ein lokales Modell-Setup,
• Zugangsdaten für Cloud-Provider wie OpenAI, Anthropic oder OpenRouter, sofern du diese nutzen willst,
• Grundkenntnisse im Umgang mit Shell-Kommandos und Umgebungsvariablen.

Prüfe zuerst, welche Konfigurationsdatei deine Installation tatsächlich verwendet:

openclaw config file

Bevor du etwas änderst, validierst du den aktuellen Zustand:

openclaw config validate

Und dann schaust du dir an, was OpenClaw im Moment wirklich als Default, Fallbacks und verfügbare Modelle auflöst:

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

Wenn OpenClaw im Nix-Modus läuft (OPENCLAW_NIX_MODE=1), sind schreibende openclaw config set-Befehle laut Config-Doku gesperrt. Dann änderst du nicht die laufende JSON-Datei, sondern die Nix-Quelle deiner Installation.

Wenn dort schon ein sinnvolles Primary Model steht und openclaw config validate sauber durchläuft, musst du nicht bei null anfangen. Dann geht es eher darum, Fallbacks, Allowlists und Secret-Handling sauber nachzuziehen.

Die drei Begriffe, die du nicht verwechseln solltest

Für ein stabiles Setup musst du drei Ebenen auseinanderhalten:

1. Auth/Profile: So authentifiziert sich OpenClaw bei einem Provider. Das richtest du typischerweise über openclaw onboard, openclaw configure oder openclaw models auth login ein.
2. Primary Model: Das Standardmodell unter agents.defaults.model.primary oder kompatibel unter agents.defaults.model.
3. Fallbacks: Eine geordnete Liste unter agents.defaults.model.fallbacks, die einspringt, wenn das primäre Modell nicht verfügbar ist.

Daneben gibt es agents.defaults.models. Das ist laut Doku keine Fallback-Liste, sondern eine Allowlist beziehungsweise ein Katalog sichtbarer oder erlaubter Modelle. Dort sind auch Einträge wie provider/* möglich, wenn du einen Provider grundsätzlich freigeben willst.

Welche Modelle deine Installation gerade kennt

Lass dir zuerst anzeigen, welche Modelle OpenClaw mit deiner aktuellen Provider-Konfiguration überhaupt sieht:

openclaw models list

Und ergänzend:

openclaw models status

models list zeigt dir, welche Modellreferenzen aktuell verfügbar sind. models status ist der bessere Kontrollpunkt, wenn du zusätzlich sehen willst, welches Default-Modell tatsächlich aufgelöst wird, welche Fallbacks aktiv sind und wie der Auth-Zustand der Provider aussieht.

Wenn ein Modell dort nicht auftaucht, solltest du es weder als Primary noch als Fallback eintragen. Modellnamen ändern sich schnell, Accounts sehen nicht immer dieselben Kataloge und manche Provider blenden Modelle regional oder tarifabhängig aus. Die Live-Ausgabe deiner Installation ist deshalb belastbarer als jede statische Liste.

Provider authentifizieren

Für ein komplett neues Setup ist das Onboarding der einfachste Einstieg:

openclaw onboard

Wenn Teil 2 gerade erst hinter dir liegt, ist dieser Schritt oft schon erledigt. Starte den Wizard dann nicht automatisch erneut, sondern prüfe zuerst die bestehende Konfiguration:

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

Für gezielte Änderungen ist die Konfigurations-CLI meist präziser als ein kompletter neuer Onboarding-Durchlauf. Wenn du bewusst nur den Modellbereich anfassen willst, ist auch das hier sinnvoll:

openclaw configure --section model

Alternativ kannst du Provider einzeln authentifizieren. Typische Provider-IDs sind laut OpenClaw-Doku etwa openai, anthropic oder openrouter:

openclaw models auth login --provider openai
openclaw models auth login --provider anthropic
openclaw models auth login --provider openrouter

Wichtig: Wenn du einen neuen Provider ergänzt oder einen bestehenden reauthentifizierst, ersetzt OpenClaw dein bestehendes Standardmodell nicht automatisch. Wenn du das Primary Model bewusst wechseln willst, setze es danach explizit oder nutze beim Login --set-default.

Beispiel:

openclaw models set openai/<modell-id>

Oder direkt beim Login:

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

Wenn die gewünschte Modellreferenz in openclaw models list nicht auftaucht, nimm keinen Namen auf Verdacht aus einem alten Tutorial. Arbeite immer mit der Live-Ausgabe deiner Installation.

Primary Model und Fallbacks sauber setzen

Laut Model-Konzepten wählt OpenClaw Modelle in dieser Reihenfolge aus:

1. agents.defaults.model.primary beziehungsweise agents.defaults.model,
2. agents.defaults.model.fallbacks in der angegebenen Reihenfolge,
3. Auth-Failover innerhalb desselben Providers, bevor zum nächsten Modell gewechselt wird.

Für die Praxis heißt das: Du brauchst keine lange Kette aus fünf halb passenden Modellen. Du brauchst eine Reihenfolge, die zu deinem Betrieb passt.

Ein typisches Setup besteht aus einem starken Standardmodell und ein bis zwei Fallbacks. Welche Modelle das konkret sind, hängt von Budget, Latenz und deinen vorhandenen Provider-Logins ab.

Beispiel mit einem Primary Model und einem Fallback:

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

Beispiel mit mehreren Fallbacks:

openclaw config set agents.defaults.model.primary "openai/<primary-modell>"
openclaw config set agents.defaults.model.fallbacks '["anthropic/<fallback-1>","openrouter/<fallback-2>"]' --strict-json
openclaw config validate

Wichtig: fallbacks ist immer eine Liste. Auch ein einzelnes Fallback musst du als JSON-Array setzen. Dieser Befehl ist also falsch:

openclaw config set agents.defaults.model.fallbacks "openai/<modell-id>"

Richtig ist:

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

Konzeptionell sieht die Konfiguration so aus:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/<primary-modell>",
        "fallbacks": [
          "anthropic/<fallback-1>",
          "openrouter/<fallback-2>"
        ]
      }
    }
  }
}

Bearbeite die Datei nur manuell, wenn du sicher bist, dass du mit openclaw config file die aktive Datei erwischt hast und openclaw config validate danach ohne Fehler durchläuft. Für normale Änderungen ist die openclaw config-CLI der sauberere Weg.

Optionale Modell-Allowlist setzen

Wenn du begrenzen willst, welche Modelle OpenClaw grundsätzlich verwenden oder anzeigen darf, nutzt du agents.defaults.models. Das ist vor allem in Teams oder in produktionsnahen Setups sinnvoll, in denen nicht jeder spontan jeden Provider oder jedes experimentelle Modell freischalten soll.

Beispiel:

openclaw config set agents.defaults.models '{"openai/*":{},"anthropic/*":{},"openrouter/*":{}}' --strict-json --merge
openclaw config validate

Der Unterschied ist entscheidend: agents.defaults.models regelt, was grundsätzlich erlaubt ist. agents.defaults.model.fallbacks regelt, in welcher Reihenfolge Alternativen ausprobiert werden.

API-Schlüssel und Secrets sauber behandeln

Für Modellanbieter brauchst du je nach Provider Browser-Login, OAuth oder API-Token. Der sichere Weg beginnt mit den vorgesehenen Auth-Flows von OpenClaw:

openclaw models auth login --provider openai
openclaw models auth login --provider anthropic
openclaw models auth login --provider openrouter

Wenn ein Provider stattdessen einen API-Token erwartet, prüfe danach immer direkt, ob OpenClaw das Setup auch wirklich sieht:

openclaw models status
openclaw models list
openclaw config validate

Wenn du unsicher bist, welche Felder deine Installation unterstützt, schau zuerst in die lokale Hilfe und ins Schema:

openclaw models auth login --help
openclaw config schema

Wichtig für alles, was später in Git landet: Tokens gehören nicht in Screenshots, Chatlogs oder versionierte Config-Dateien. Wenn du Secrets aus der Hauptkonfiguration herausziehen willst, lies dazu den separaten Guide Secrets und API-Keys sicher verwalten.

Lokale Modelle mit Ollama

OpenClaw dokumentiert Ollama als eigenen Provider. Das ist interessant, wenn du lokale Modelle testen willst oder bestimmte Daten bewusst nicht an einen Cloud-Provider senden möchtest.

Wenn du Qwen oder Gemma lokal ausprobieren willst, ist Ollama ein naheliegender Einstieg. Die ausführliche Schritt-für-Schritt-Anleitung steht im separaten Guide Lokale Modelle mit Ollama in OpenClaw. Dort geht es um Installation, Modell-Download, openclaw models scan, openclaw models list, openclaw models set und typische Fehlerquellen.

Als grobe Orientierung sieht der Pfad so aus:

ollama pull qwen2.5:7b
ollama pull gemma2:9b
ollama list
openclaw models scan
openclaw models list

Wenn OpenClaw die Modelle sieht, verwendest du Modellreferenzen im OpenClaw-Format, also etwa ollama/qwen2.5:7b oder ollama/gemma2:9b.

Praktisch wichtig:

• Läuft Ollama auf demselben Rechner wie OpenClaw, ist die Basis-URL typischerweise http://127.0.0.1:11434.
• Verwende bei Ollama die native Basis-URL ohne /v1.
• Prüfe mit ollama list und curl -s http://127.0.0.1:11434/api/tags, ob Ollama läuft und Modelle sichtbar sind.
• Rechne damit, dass lokale Modelle bei Tool-Calls, langen Kontexten oder größeren Repositories deutlich schwächer oder langsamer wirken können als starke Cloud-Modelle.

Eine Fallback-Strategie, die im Alltag Sinn ergibt

Eine robuste Reihenfolge ist wichtiger als eine lange Liste.

Ein brauchbares Muster sieht so aus:

1. Primary: dein zuverlässigstes Modell für anspruchsvolle Aufgaben,
2. Fallback 1: ein anderer starker Provider,
3. Fallback 2: ein günstiger Aggregator oder ein lokales Modell,
4. Allowlist: nur die Modelle freigeben, die du tatsächlich einsetzen willst.

Der wichtige Punkt steckt nicht in der Theorie, sondern im Störfall: Wenn dein Primäranbieter wackelt, willst du nicht erst dann herausfinden, dass dein Fallback nie sichtbar war, ein Login abgelaufen ist oder die Allowlist das Ersatzmodell blockiert.

Bei mehreren Auth-Profilen für denselben Provider greift laut OpenClaw-Dokumentation zuerst das Auth-Failover innerhalb dieses Providers. Erst danach wird das nächste Modell in der Fallback-Kette relevant.

Konfiguration testen, bevor du weiterziehst

Nach jeder Änderung:

openclaw config validate

Für maschinenlesbare Diagnose:

openclaw config validate --json

Prüfe danach mindestens diese vier Punkte:

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

Wenn du den Gateway als Dienst betreibst, starte ihn mit dem Mechanismus neu, den du in Teil 2 eingerichtet hast. Entscheidend ist danach nicht nur der Neustart selbst, sondern das Ergebnis: Die Konfiguration muss validieren, das Primary Model muss korrekt aufgelöst werden und die Fallback-Liste darf keine ungültigen Referenzen enthalten. Ein kurzer Kontrolllauf mit openclaw models status, openclaw models list und einer kleinen Testanfrage zeigt dir schnell, ob der Wechsel wirklich im Betrieb angekommen ist.

Typische Fehler

Problem	Ursache	Lösung
Fallback greift nicht wie erwartet	agents.defaults.models mit Fallback-Liste verwechselt	Fallbacks unter agents.defaults.model.fallbacks setzen
Neuer Provider ist authentifiziert, aber das Standardmodell bleibt gleich	OpenClaw ersetzt das Primary Model nicht automatisch	openclaw models set <provider/model> oder --set-default nutzen
Config lässt sich nicht schreiben	Nix-Modus aktiv	Nix-Konfiguration statt openclaw config set ändern
API-Key landet in Git	Secret direkt in Config eingetragen	Auth-Profile, Secret-Refs oder externe Secret-Datei verwenden
Modell-ID wird nicht gefunden	Modellname veraltet oder für dein Konto nicht sichtbar	openclaw models list, openclaw models status und Provider-Dashboard prüfen

Worauf es am Ende ankommt

Ein sauberes OpenClaw-Modell-Setup braucht keine riesige Provider-Matrix. Entscheidend ist, dass du zuerst den Ist-Zustand prüfst, danach bewusst ein Primary Model setzt, ein oder zwei sinnvolle Fallbacks ergänzst und jede Änderung validierst.

Die Kurzfassung:

• Modellreferenzen folgen dem Muster provider/model.
• Das Standardmodell liegt unter agents.defaults.model.primary oder kompatibel unter agents.defaults.model.
• Fallbacks gehören nach agents.defaults.model.fallbacks.
• agents.defaults.models ist eine Allowlist, keine Fallback-Reihenfolge.
• Secrets gehören nicht im Klartext in versionierte Dateien.
• Nach jeder Änderung: openclaw config validate.
• Für den Realitätscheck: openclaw models status und openclaw models list.

Wenn diese Punkte sitzen, ist Teil 3 erledigt. Dann geht es im nächsten Schritt nicht mehr um Modellwahl, sondern darum, wie OpenClaw mit externen Kanälen wie Telegram und WhatsApp spricht.