OpenClaw Tutorial Teil 3: Modelle konfigurieren

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

Nach der erfolgreichen Installation und dem Start des Gateways im zweiten Teil fehlt dem OpenClaw-Agenten noch das Wichtigste: die Anbindung an KI-Modelle. Damit der Agent Antworten generieren und Werkzeuge nutzen kann, unterstützt OpenClaw nativ eine breite Palette an Providern – von OpenAI und Anthropic über Aggregatoren wie OpenRouter bis hin zu lokalen Modellen via Ollama. Dieser Teil zeigt, wie Sie API-Schlüssel sicher verwalten, Provider konfigurieren und eine robuste Ausfallsicherheit einrichten.

Voraussetzungen für diesen Schritt

• Ein laufender OpenClaw Gateway.
• Aktive API-Schlüssel für die gewünschten KI-Anbieter.
• Grundkenntnisse im Umgang mit Umgebungsvariablen.

Ein sauberes Setup stellt sicher, dass mindestens ein Provider angebunden ist, ein Fallback greift und sensible Schlüssel nicht im Klartext in der Versionskontrolle landen.

Provider und Modelle konfigurieren

OpenClaw steuert die Modellanbindung zentral über eine Konfigurationsdatei im JSON5-Format, die standardmäßig unter ~/.openclaw/openclaw.json liegt. Hier definieren Sie aktive Provider, die gewünschten Modelle (wie gpt-5.4 oder claude-3.7-sonnet) und die Fallback-Routinen.

Minimal-Setup

{
  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"],
  },
}

Der Einsatz von Platzhaltern wie {{secrets.<name>}} verhindert, dass sensible API-Schlüssel im Klartext in der Konfiguration stehen.

API-Schlüssel sicher verwalten

Es gibt zwei bewährte Methoden, um Zugangsdaten an OpenClaw zu übergeben, ohne die Sicherheit zu gefährden.

Umgebungsvariablen

Für einfache Setups oder Container-Umgebungen lassen sich die Schlüssel direkt als Umgebungsvariablen exportieren:

export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"

In der Konfiguration wird anschließend über {{env.OPENAI_API_KEY}} darauf referenziert.

Secrets und Referenzen

Für den produktiven Einsatz empfiehlt sich die Nutzung von Secret-Referenzen. Dabei werden die Schlüssel in einer separaten, lokalen Datei (etwa ~/.openclaw/secrets.json) abgelegt, die strikt von der Versionskontrolle ausgeschlossen wird. OpenClaw lädt diese Secrets beim Start in einen geschützten Laufzeit-Snapshot. Kann eine aktive Referenz nicht aufgelöst werden, greift ein Fail-Fast-Mechanismus und der Startvorgang bricht ab.

Wer das integrierte Onboarding (openclaw onboard) nutzt, profitiert von automatisch angelegten Auth-Profilen pro Provider. Das erleichtert später die Schlüsselrotation und das Management von Ausweichlösungen.

Provider-Strategien im Vergleich

Die Wahl des passenden Providers hängt stark vom Einsatzzweck ab.

Premium-Modelle: Anbieter wie OpenAI und Anthropic liefern mit Modellen wie GPT-5.4 oder Claude 3.7 Sonnet die höchste Qualität bei komplexen Tool-Calls und multimodalen Aufgaben (Vision). Diese Leistung geht mit höheren Kosten einher, weshalb sie sich primär für anspruchsvolle Kernaufgaben eignen.

Aggregatoren: Plattformen wie OpenRouter bündeln zahlreiche Modelle (darunter DeepSeek V3.2, Gemini 3.1 Flash oder Qwen) unter einer API. Das ist oft kostengünstiger und eignet sich hervorragend für Recherchen, Entwürfe oder als Ausweichlösung.

Lokale Modelle: Für datenschutzkritische Anwendungen oder den Betrieb ohne Cloud-Kosten bieten sich lokale Modelle via Ollama an. Laut der offiziellen OpenClaw-Dokumentation sollte bei einem extern gehosteten Ollama-Server zwingend die native API (baseUrl: "http://host:11434") und nicht der OpenAI-kompatible Endpunkt genutzt werden, um Abbrüche bei Tool-Calls zu vermeiden.

Ausfallsicherheit durch Fallbacks

Damit der Agent bei API-Ausfällen oder Rate-Limits nicht blockiert, nutzt OpenClaw ein zweistufiges Fallback-System. Zunächst rotiert das System die Auth-Profile, falls mehrere Schlüssel für denselben Provider hinterlegt sind. Schlägt das fehl, greift der Modell-Fallback.

In der Konfiguration wird dazu ein Standardmodell definiert und eine Liste von Alternativen angegeben:

{
  defaults: {
    model: "openai:gpt-5.4",
    fallback: ["anthropic:claude-3.7-sonnet", "openrouter:deepseek-v3.2"],
  },
}

Eine bewährte Strategie in der Praxis: Ein leistungsstarkes Modell als Standard setzen und kostengünstigere Alternativen als Fallback definieren.

Konfiguration testen

Nach Anpassungen an der openclaw.json muss der Gateway neu gestartet werden:

openclaw gateway restart

Der Befehl openclaw status zeigt an, ob die Modelle korrekt geladen wurden. Treten keine Fehler auf, lässt sich die Anbindung direkt prüfen:

openclaw ask "Was ist 2+2?"

Um die Fallback-Kette oder spezifische Provider zu testen, kann ein Modell auch gezielt angesprochen werden:

openclaw ask --model openrouter:deepseek-v3.2 "Schreibe eine kurze Python-Funktion."

Sollte es zu Fehlern kommen (etwa durch ungültige API-Schlüssel), hilft ein Blick in die Live-Logs (openclaw gateway logs --follow) oder eine Syntax-Prüfung der Konfigurationsdatei (openclaw config validate).

Best Practices für den Betrieb

Für einen stabilen und sicheren Betrieb sollten API-Schlüssel regelmäßig rotiert und die Nutzungskosten über die Dashboards der jeweiligen Anbieter überwacht werden. Sobald mehrere Personen an einem Projekt arbeiten, ist eine saubere Trennung unerlässlich: Die eigentliche openclaw.json wird versioniert in Git abgelegt, während alle Zugangsdaten strikt in lokalen, ignorierten Secret-Dateien verbleiben.