OpenClaw Konfigurations-Guide: Lies das und du kapiert's besser als 90% der Leute!

1. Überblick: Wo liegt die Datei & wie wird sie geladen?

1.1 Wo versteckt sich die Config?

Die openclaw.json liegt standardmäßig tief vergraben in deinem Home-Verzeichnis:

• Linux/Mac: ~/.openclaw/openclaw.json
• Windows: C:\Users\DEIN_NAME\.openclaw\openclaw.json

💡 Tipp: Du kannst den Pfad auch über die Umgebungsvariable OPENCLAW_CONFIG_PATH selbst bestimmen. Willst du noch stealthier sein? Nur zu!

1.2 Die Ladereihenfolge (Wer hat Vorfahrt?)

OpenClaw lädt Configs nach einem strikten Prioritätsprinzip. Stell dir vor wie bei einem Konzert: Wer früher da ist, bekommt den besten Platz.

1. Prozess-Umgebungsvariablen (Der Boss – höchste Priorität)
2. .env Datei im aktuellen Ordner
3. Globale .env Datei (~/.openclaw/.env)
4. Der env-Block in der openclaw.json
5. Login Shell Imports (Der Notnagel)

1.3 Was tun nach der Änderung?

Vergiss Hot-Reload. Das gibt's hier nicht. Nach jeder Änderung musst du das Gateway neu starten:

openclaw gateway restart

💡 Tipp: Mach vorher immer ein Backup. Frag mich nicht, woher ich das weiß... 😅

2. Die große Struktur: 14 Module im Check

Die openclaw.json besteht aus 14 Hauptmodulen. Klingt viel, ist aber halb so wild:

3. Deep Dive: Die wichtigsten Module erklärt

3.1 agents – Der Chef im Ring

Hier definierst du, wie dein KI-Assistent arbeitet. Welches Modell? Wie viele parallele Anfragen?

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/qwen3.5-plus",
        "fallbacks": ["bailian/qwen3-max"]
      },
      "maxConcurrent": 4,
      "workspace": "C:\\\\Users\\\\xxx\\\\.openclaw\\\\workspace"
    }
  }
}

• primary: Das Hauptmodell (der Stammspieler).
• fallbacks: Die Reservebank, falls das Hauptmodell streikt.
• maxConcurrent: Nicht zu gierig sein! Sonst wirst du vom API-Anbieter geblockt.

3.2 auth – Der Türsteher

Hier verwaltest du deine Zugangsdaten. Aber bitte keine Klartext-Passwörter hier rein!

3.3 gateway – Das Kommandozentrum

Das Gateway steuert Ports und wer Zugriff hat.

• bind: loopback (nur lokal, sicher), tailnet (Tailscale), oder all (gefährlich!).
• port: Standard ist 18789. Ändere es nur, wenn du es dir merken kannst.
• mode: local für Solo-Arbeit, remote für Teams.

3.4 models – Dein KI-Waffenarsenal

Hier trägst ein, welche Modelle du nutzen willst (Bailian, MiniMax, etc.).

"models": {
  "providers": {
    "bailian": {
      "api": "openai-completions",
      "apiKey": "${DASHSCOPE_API_KEY}", 
      "baseUrl": "https://..."
    }
  }
}

💡 Achte darauf, dass baseUrl und apiKey stimmen. Die KI kann nicht Gedanken lesen!

3.5 channels – Die Kommunikationszentrale

Verbinde WhatsApp, Telegram, Discord oder Feishu. Jeder Kanal braucht seine eigenen Credentials.

3.6 plugins – Der Erweiterungs-Store

Plugins installieren und aktivieren. Wichtig: Nach der Installation oder Änderung in der Config muss das Gateway neu gestartet werden!

openclaw plugins install @clawdbot/voice-call
openclaw gateway restart

3.7 hooks – Die Automatisierungs-Maschine

Reagiere auf Events. Zum Beispiel: Logs speichern, Session-Memory aktivieren.

3.8 skills – Der Skill-Tree

Hier aktivierst du spezielle Fähigkeiten (wie Websuche via Tavily). Manche Skills brauchen eigene API Keys.

4. Häufige Szenarien: Was man oft ändert

4.1 Modell-Provider wechseln

Von Bailian zu MiniMax? Einfach im agents.defaults.model den Namen ändern. Aber stell sicher, dass das neue Modell auch unter models.providers konfiguriert ist!

4.2 Neuen Kanal hinzufügen

Telegram einrichten? Füge den Block unter channels.telegram hinzu und pack deinen Bot-Token rein. Nicht vergessen: Restart!

4.3 API Keys sicher verwalten

Der richtige Weg:

1. Key in ~/.openclaw/.env schreiben: DASHSCOPE_API_KEY=sk-...
2. In der JSON referenzieren: "apiKey": "${DASHSCOPE_API_KEY}"

4.4 Plugins an/aus schalten

Fauler Modus: Nutze CLI Befehle (openclaw plugins disable voice-call). Oder setze einfach "enabled": false in der Config.

5. Fehlerbehebung: Wenn nichts funktioniert

5.1 Syntax-Fehler

Symptom: Gateway startet nicht.
Grund: Fehlendes Komma, falsche Anführungszeichen oder ein Kommentar (JSON kann keine Kommentare!).
Lösung: Nutze einen JSON-Validator (z.B. in VS Code).

5.2 "Ich habe geändert, aber nichts passiert"

90% der Fälle:

• Du hast die falsche Datei bearbeitet (checke OPENCLAW_CONFIG_PATH).
• Du hast das Gateway nicht komplett neu gestartet.
• Die Einrückung stimmt nicht.

Schau ins Log: tail -f ~/.openclaw/gateway.log. Das Log lügt nicht!

5.3 Umwelt-Variablen-Konflikt

Wenn eine Umgebungsvariable bereits existiert, ignoriert OpenClaw den Wert in der Config. Lösche die Variable im Terminal, wenn du die Config nutzen willst.

6. Best Practices: Mach es richtig

• Backup-Strategie: Bevor du editierst: cp openclaw.json openclaw.json.backup.datum. Das ist dein Rettungsfloß.
• Test-Prozess: Validieren -> Neustarten -> Logs checken -> Funktion testen. Keine Schritte überspringen!
• Sicherheit: Minimal-Prinzip. Aktiviere nur, was du brauchst. Remote-Zugriff nur mit Token und am besten über Tailscale.

7. Fazit

Die openclaw.json sieht zwar komplex aus, aber wenn du die Module und die Reihenfolge verstehst, hast du die Macht. Denk an die drei goldenen Regeln:

1. Sensible Daten in die .env.
2. Immer Gateway neustarten nach Änderungen.
3. Erst Backup machen, dann rumexperimentieren.

Viel Erfolg beim Tuning deiner KI! 🚀