OpenClaw Tutorial Teil 3: Modelle konfigurieren

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

Im zweiten Teil haben wir OpenClaw installiert und den Gateway gestartet. Jetzt geht es darum, KI‑Modelle an OpenClaw anzubinden – denn ohne Modelle kann dein Agent keine Antworten generieren.

OpenClaw unterstützt viele Anbieter: OpenAI, Anthropic, OpenRouter, Google Gemini, DeepSeek und sogar lokale LLMs via Ollama. In diesem Teil lernst du, wie du API‑Keys sicher verwaltest, Provider konfigurierst und Fallbacks sinnvoll einrichtest.

Voraussetzungen

✅ Laufender OpenClaw Gateway (siehe Teil 2)
✅ API‑Keys für die gewünschten Anbieter (z. B. OpenAI, Anthropic, OpenRouter)
✅ Grundlegendes Verständnis von API‑Keys und Umgebungsvariablen

Ziel dieses Teils: Du sollst am Ende (a) mindestens einen Provider sauber angebunden haben, (b) ein Fallback definiert haben und (c) deine Keys nicht versehentlich im Klartext in irgendein Repo committen.

Konfigurationsdatei verstehen

OpenClaw verwendet eine Konfigurationsdatei (typischerweise ~/.openclaw/config.yaml oder ~/.openclaw/openclaw.json). Dort definierst du:

Provider (welche Modelle nutzt du?)
Modelle pro Provider (z. B. gpt-5.4, claude-3.7-sonnet, deepseek-v3.2)
Falls ein Provider nicht verfügbar ist, wird auf einen Backup‑Provider gewechselt.

Beispiel: Minimal‑Config

providers:
  openai:
    enabled: true
    apiKey: "{{secrets.openai.apiKey}}"
    models:
      - gpt-5.4
      - gpt-5-mini
  anthropic:
    enabled: true
    apiKey: "{{secrets.anthropic.apiKey}}"
    models:
      - claude-3.7-sonnet
  openrouter:
    enabled: true
    apiKey: "{{secrets.openrouter.apiKey}}"
    models:
      - deepseek-v3.2
      - gemini-3.1-flash

defaults:
  model: "openai:gpt-5.4"
  fallback:
    - "anthropic:claude-3.7-sonnet"
    - "openrouter:deepseek-v3.2"

💡 Tipp: Nutze {{secrets.<name>}} statt Klartext – der Secret‑Wert liegt außerhalb der versionierten Config.

API‑Keys sicher speichern

Variante A: Umgebungsvariablen (einfach)

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-..."
export OPENROUTER_API_KEY="sk-..."

Dann in der Config:

apiKey: "{{env.OPENAI_API_KEY}}"

Variante B: Secrets/SecretRef (empfohlen)

Wenn du nicht nur „irgendwie einen Key“ setzen willst, sondern sauber und sicher arbeiten möchtest, nutze SecretRefs. Damit stehen Secrets nicht als Klartext in der Konfig.

Wichtig zu wissen (vereinfacht):

Secrets werden beim Start/Reload in einen Runtime‑Snapshot geladen.
Wenn ein aktiver SecretRef nicht aufgelöst werden kann, kann OpenClaw beim Start/Reload fail-fast.

Einfacher Einstieg: Für Hobby‑Setups reicht häufig eine lokale Datei (z. B. ~/.openclaw/secrets.json) + Referenzen in der Config.

apiKey: "{{secrets.openai.apiKey}}"

Wichtig: Secrets-Dateien nie ins Git‑Repo committen.

Wo liegen die Keys praktisch?

Je nach Setup landen Provider-Credentials entweder als env‑Var, als SecretRef oder in OpenClaws Auth‑Profilen (Profile/Rotation). Wenn du onboarding nutzt, erstellt OpenClaw typischerweise entsprechende Profile pro Provider, sodass später auch Rotation/Fallbacks sauber funktionieren.

Provider im Detail

OpenAI

Modelle: GPT‑5.4, GPT‑5‑Mini, GPT‑5‑Nano
Vorteil: Hohe Qualität, viele Features (Funktionen, Vision)
Nachteil: Teurer als viele Alternativen

Anthropic

Modelle: Claude 3.7 Sonnet, Claude 4.6
Vorteil: Sehr gute Sprachqualität, gutes Context‑Handling
Nachteil: Weniger Features als OpenAI, etwas teurer

OpenRouter

Modelle: DeepSeek V3.2, Gemini 3.1 Flash, GLM‑Flash, Qwen, etc.
Vorteil: Preisgünstig, viele Modelle auf einer Plattform
Nachteil: Qualität schwankt je nach Modell

Provider-Vergleich (praktische Entscheidungshilfe)

Preise ändern sich schnell – für die Praxis ist diese Frage oft wichtiger:

Willst du maximale Qualität (und akzeptierst höhere Kosten)? → OpenAI/Anthropic als Primary.
Willst du günstig viel ausprobieren (Research, Entwürfe, Vorarbeit)? → OpenRouter/DeepSeek als Fallback.
Willst du ohne API-Key starten (oder offline/privat)? → lokale Modelle mit Ollama.

Tipp: Viele Setups funktionieren am besten als „teuer als Primary, günstig als Fallback“.

Fallbacks definieren (damit dein Agent immer antwortet)

OpenClaw kann bei Problemen in zwei Stufen ausweichen:

Auth‑Profile rotieren (wenn du mehrere Keys/Logins pro Provider hast)
Model‑Fallbacks nutzen (nächstes Modell/Provider)

Danach definierst du, welches Modell standardmäßig genutzt wird und worauf gewechselt wird, wenn ein Anbieter nicht verfügbar ist:

defaults:
  model: "openai:gpt-5.4"
  fallback:
    - "anthropic:claude-3.7-sonnet"
    - "openrouter:deepseek-v3.2"

Dies sorgt dafür, dass dein Agent immer antworten kann – auch wenn ein Anbieter kurzzeitig nicht erreichbar ist.

Lokale Modelle (Ollama) – kurzer Überblick

Wenn du lokal (ohne Cloud‑API‑Key) Modelle laufen lassen willst, ist Ollama der Standard‑Weg.

Wichtig (wenn Ollama auf einem anderen Rechner läuft): Nutze nicht die OpenAI‑kompatible /v1‑URL (http://host:11434/v1), sondern die native Ollama‑API (baseUrl: "http://host:11434"). Das reduziert Ärger bei Tool‑Calls.

Du kannst Ollama am einfachsten über openclaw onboard hinzufügen (Provider auswählen). Details stehen in den Docs unter /providers/ollama.

Testen

Nachdem du die Config aktualisiert hast, starte den Gateway neu:

openclaw gateway restart

Dann testest du, ob die Modelle korrekt geladen wurden:

openclaw status

Wenn der Status sauber antwortet und du keine Auth-/Provider-Fehler siehst, ist die Konfiguration im Kern erfolgreich. Du kannst auch einen einfachen Prompt testen:

openclaw ask "Was ist 2+2?"

Erweiterter Test mit Modell-Auswahl

OpenClaw erlaubt auch, ein bestimmtes Modell für eine Anfrage zu wählen:

openclaw ask --model openai:gpt-5.4 "Erkläre KI‑Agenten in drei Sätzen."
openclaw ask --model openrouter:deepseek-v3.2 "Schreibe einen kurzen Python‑Code, der eine Liste sortiert."

Falls ein Modell nicht verfügbar ist, wird automatisch auf den nächsten Fallback gewechselt.

Logs prüfen

Wenn etwas nicht funktioniert, schau in die Gateway‑Logs:

openclaw gateway logs --follow

Oder prüfe die Konfiguration auf Syntaxfehler:

openclaw config validate

Best Practices

Secret‑Rotation: Rotiere API‑Keys regelmäßig (alle 3–6 Monate) und aktualisiere sie in deiner Secrets‑Datei.
Modell‑Monitoring: Beobachte die Nutzungskosten über die Dashboards der Anbieter (OpenAI, Anthropic, OpenRouter).
Fallback‑Hierarchie: Platziere das teuerste, qualitativ hochwertigste Modell als Standard, gefolgt von günstigeren Alternativen.
Production/Team-Setups: Sobald mehr als eine Person dran hängt, lohnt sich ein sauberer Secrets‑Workflow (SecretRef/Provider) statt „Key in env und fertig“.
Konfiguration versionieren: Speichere deine OpenClaw‑Config (ohne Secrets) in Git, um Änderungen nachvollziehen zu können.

Troubleshooting

“API key invalid”: Prüfe, ob der API‑Key korrekt ist und nicht abgelaufen.
“Model not found”: Prüfe, ob das Modell beim Provider verfügbar ist.
“Rate limit exceeded”: Warte kurz oder wechsle zu einem anderen Modell/Provider.

Quellen & weiterführende Links

Dieser Artikel ist Teil der Serie „OpenClaw installieren & einrichten“. Der nächste Teil erscheint in Kürze. Wenn du Fragen oder Anregungen hast, schreib mir gerne auf Mastodon oder per E‑Mail.