OpenClaw Tutorial Teil 3: Modelle konfigurieren

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

Nach Installation und Start aus Teil 2 fehlt dem OpenClaw-Agenten noch die Modellanbindung. OpenClaw unterscheidet dabei zwischen Modellreferenzen, Provider-Authentifizierung, Standardmodell, Fallbacks und optionalen Allowlists.¹²

Wichtig vorweg: Aktuelle OpenClaw-Modellreferenzen verwenden das Format provider/model, zum Beispiel openai/gpt-5.4. Das ältere oder aus anderen Tools bekannte Format provider:model ist für die hier gezeigte OpenClaw-Konfiguration nicht korrekt.²

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 verwenden willst,
• Grundkenntnisse im Umgang mit Shell-Kommandos und Umgebungsvariablen.

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

openclaw config file

Validiere außerdem den aktuellen Stand, bevor du Änderungen machst:

openclaw config validate

Wenn OpenClaw im Nix-Modus läuft (OPENCLAW_NIX_MODE=1), sind schreibende openclaw config set-Befehle laut Dokumentation gesperrt. Dann musst du die Nix-Quelle deiner Installation ändern statt direkt in openclaw.json zu schreiben.³

Die drei wichtigsten Begriffe

Für ein sauberes Modell-Setup musst du drei Dinge auseinanderhalten:

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

Daneben gibt es agents.defaults.models. Das ist keine Fallback-Liste, sondern eine Allowlist beziehungsweise ein Katalog sichtbarer oder erlaubter Modelle. Laut Dokumentation können dort auch Einträge wie provider/* genutzt werden, um einen Provider dynamisch sichtbar zu halten.²

Verfügbare Modelle prüfen

Lass dir zuerst anzeigen, welche Modelle deine Installation und deine Provider-Konfiguration kennen:

openclaw models list

Modellnamen ändern sich regelmäßig. Übernimm Modell-IDs deshalb nicht blind aus Blogposts. Nutze die Ausgabe von openclaw models list, die aktuelle OpenClaw-Dokumentation oder das jeweilige Provider-Dashboard.

Provider authentifizieren

Für das erste Setup ist das Onboarding der sicherste Einstieg:

openclaw onboard

Alternativ kannst du Provider einzeln authentifizieren. Die Provider-ID hängt von deiner Installation und den aktivierten Provider-Plugins ab; typische IDs sind beispielsweise openai, anthropic oder openrouter:

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

Wichtig: Das Hinzufügen oder erneute Authentifizieren eines Providers ersetzt laut OpenClaw-Dokumentation ein bereits gesetztes Primary Model nicht automatisch. Wenn du den Standard bewusst ändern willst, nutze entweder openclaw models set oder beim Login die Option --set-default.²

Beispiel:

openclaw models set openai/gpt-5.4

Oder direkt beim Login:

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

Wenn openai/gpt-5.4 in deiner Installation nicht verfügbar ist, verwende stattdessen eine Modellreferenz aus openclaw models list.

Primary Model und Fallbacks setzen

OpenClaw wählt Modelle dokumentiert 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 eines Providers, bevor zum nächsten Modell gewechselt wird.⁴

Ein praktisches Setup besteht aus einem starken Standardmodell und mindestens einem Fallback bei einem anderen Provider.

Beispiel mit CLI:

openclaw config set agents.defaults.model.primary "openai/gpt-5.4"
openclaw config set agents.defaults.model.fallbacks '["anthropic/claude-opus-4-6","openrouter/deepseek-v3.2"]' --strict-json
openclaw config validate

Passe die Modell-IDs an deine tatsächliche Umgebung an. Entscheidend ist das Format provider/model.

Die entsprechende Konfigurationsform sieht konzeptionell so aus:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-5.4",
        "fallbacks": [
          "anthropic/claude-opus-4-6",
          "openrouter/deepseek-v3.2"
        ]
      }
    }
  }
}

Bearbeite die Datei nur manuell, wenn du sicher bist, dass du die aktive Datei aus openclaw config file änderst und danach openclaw config validate ohne Fehler durchläuft.

Optionale Modell-Allowlist setzen

Wenn du begrenzen willst, welche Modelle OpenClaw verwenden oder anzeigen darf, nutze agents.defaults.models. Das ist besonders hilfreich in Team- oder Produktionsumgebungen.

Beispiel:

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

Merke: agents.defaults.models ist nicht dasselbe wie agents.defaults.model.fallbacks. Die Allowlist entscheidet, was grundsätzlich verfügbar sein soll; die Fallback-Liste entscheidet, in welcher Reihenfolge Alternativen ausprobiert werden.

API-Schlüssel und Secrets sicher verwalten

API-Schlüssel gehören nicht im Klartext in Git. Nutze nach Möglichkeit die Auth-Flows von OpenClaw (openclaw onboard oder openclaw models auth login) und die dokumentierte Secret-Verwaltung.⁵

OpenClaw unterstützt Referenzen auf Secrets beziehungsweise externe Quellen. Die CLI-Dokumentation zeigt dafür unter anderem das Muster --ref-provider, --ref-source und --ref-id.³ Ein dokumentiertes Beispiel für einen Token aus einer Umgebungsvariable sieht so aus:

openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN

Für Provider-Zugangsdaten solltest du nicht raten, welcher interne Config-Pfad gerade korrekt ist. Prüfe stattdessen die aktuelle Provider-Dokumentation, nutze openclaw models auth login oder inspiziere das Schema:

openclaw config schema

Für dateibasierte Secret-Provider zeigt die CLI-Dokumentation unter anderem dieses Muster:

openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json

Achte darauf, lokale Secret-Dateien in .gitignore aufzunehmen und Dateirechte restriktiv zu setzen.

Lokale Modelle mit Ollama

OpenClaw dokumentiert Ollama als eigenen Provider.⁶ Das ist sinnvoll, wenn du lokale Modelle verwenden willst oder bestimmte Daten nicht an Cloud-Provider senden möchtest.

Praktische Hinweise:

• Verwende nicht wörtlich http://host:11434; host ist nur ein Platzhalter. Trage die tatsächliche Adresse deines Ollama-Servers ein, zum Beispiel eine lokale oder interne Host-Adresse.
• Prüfe in der aktuellen Ollama-Provider-Dokumentation, welche Config-Schlüssel deine OpenClaw-Version erwartet.
• Plane realistisch: Lokale Modelle können bei Tool-Calls, langen Kontexten oder großen Repositories deutlich langsamer und schwächer sein als Premium-Cloud-Modelle.

Fallback-Strategie in der Praxis

Eine robuste Reihenfolge ist wichtiger als möglichst viele Modelle.

Bewährtes Muster:

1. Primary: bestes oder zuverlässigstes Modell für schwierige Aufgaben,
2. Fallback 1: anderer Premium-Provider,
3. Fallback 2: günstiger Aggregator oder lokaler Provider,
4. Allowlist: nur Modelle erlauben, die du wirklich einsetzen willst.

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

Nach jeder Änderung:

openclaw config validate

Für maschinenlesbare Diagnose:

openclaw config validate --json

Prüfe außerdem die gesetzte Modellkonfiguration:

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. Je nach Installation kann das ein systemd-Service, ein Container, ein Prozessmanager oder ein manuell gestarteter Prozess sein.

Typische Fehler

Problem	Ursache	Lösung
provider:model funktioniert nicht	Falsches Referenzformat	provider/model verwenden
Fallback greift nicht wie erwartet	agents.defaults.models mit Fallback-Liste verwechselt	Fallbacks unter agents.defaults.model.fallbacks setzen
Neuer Provider wird authentifiziert, aber Standardmodell bleibt gleich	OpenClaw ersetzt Primary Model nicht automatisch	openclaw models set <provider/model> verwenden
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 nicht für dein Konto verfügbar	openclaw models list und Provider-Dashboard prüfen

Zusammenfassung

Für ein sauberes OpenClaw-Modell-Setup brauchst du keine riesige Provider-Matrix. Richte zuerst einen Provider sauber ein, setze ein Primary Model, ergänze ein bis zwei Fallbacks und validiere die Konfiguration.

Die wichtigsten Regeln:

• Modellreferenzen haben das Format 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.

Footnotes

1. https://docs.openclaw.ai/concepts/models.md ↩ ↩² ↩³ ↩⁴

2. https://docs.openclaw.ai/concepts/model-providers.md ↩ ↩² ↩³ ↩⁴ ↩⁵

3. https://docs.openclaw.ai/cli/config.md ↩ ↩²

4. https://docs.openclaw.ai/concepts/model-failover ↩ ↩² ↩³

5. https://docs.openclaw.ai/gateway/secrets ↩

6. https://docs.openclaw.ai/providers/ollama ↩