openclaw doctor: So hältst du dein Multi-Agenten-Setup gesund
Das Problem mit wachsenden Agent-Setups
Ein einzelner KI-Agent ist einfach zu managen. Aber sobald du mehrere Agenten betreibst, wächst auch die Angriffsfläche für schleichende Probleme:
Diese Probleme sind nicht laut. Kein Absturz, kein roter Fehler. Der Agent ist einfach... weniger zuverlässig als vorher.
Hier kommt `openclaw doctor` ins Spiel.
---
Was macht openclaw doctor?
Der `doctor`-Befehl ist eine kombinierte Diagnose, Reparatur und Migrations-Pipeline für dein OpenClaw-Setup. Er prüft systematisch:
Einfach ausführen:
```bash
openclaw doctor
```
Die Ausgabe ist farbcodiert: grün (OK), gelb (Warnung), rot (kritisches Problem).
---
Die drei wichtigsten Flags
1. `--fix` — Automatische Reparatur
Das ist der nützlichste Flag im Alltag. `openclaw doctor --fix` repariert gefundene Probleme automatisch:
```bash
openclaw doctor --fix
```
Was wird automatisch repariert?
Sicherheitsnetz: Vor jeder Reparatur erstellt `--fix` automatisch ein Backup von `~/.openclaw/openclaw.json`. Du kannst also jederzeit zurückrollen.
Wann verwenden? Nach OpenClaw-Updates, nach Konfigurationsänderungen, wenn der Agent sich komisch verhält.
2. `--deep` — Tiefenscan
```bash
openclaw doctor --deep
```
Prüft zusätzlich System-Services (z. B. ob der Gateway als systemd-Service korrekt konfiguriert ist) und führt Live-Probes für jeden Kanal durch.
Bei unserer 6-Agenten-Installation: `--deep` dauert etwa 45 Sekunden, ist aber die zuverlässigste Methode, um Probleme zu finden, bevor sie zum echten Ausfall werden.
3. `--non-interactive` — Für Automatisierung
```bash
openclaw doctor --fix --non-interactive
```
Überspringt alle Bestätigungsdialoge und wendet nur sichere Reparaturen an. Genau was du in einem Cron-Job willst.
---
openclaw status vs. openclaw health vs. openclaw doctor
Diese drei Befehle werden oft verwechselt. Hier der Unterschied:
| Befehl | Wofür | Wann nutzen |
|--------|-------|-------------|
| `openclaw status` | Snapshot des aktuellen Zustands | Schneller Check: "Läuft alles?" |
| `openclaw health --json` | Detaillierter Health-Report als JSON | Monitoring, Alerting, Dashboards |
| `openclaw doctor` | Diagnose + optionale Reparatur | Nach Updates, bei Problemen |
Für schnelles Triage:
```bash
# Kurzer Status-Check
openclaw status
# Mehr Details + Kanalprüfung
openclaw status --deep
# Als JSON für Weiterverarbeitung
openclaw health --json | jq '.channels'
```
---
Wie wir doctor in unserem 6-Agenten-Setup einsetzen
Bei uns laufen 6 Agenten auf einem Hetzner-Server, jeder in seinem eigenen Docker-Container. Ein Agent, der still scheitert, kostet Zeit — weil wir ihn oft erst Stunden später bemerken.
Unsere Lösung: `openclaw doctor` läuft automatisch als OpenClaw-Cron-Job, jeden Morgen um 06:30 Uhr.
Das Cron-Setup sieht ungefähr so aus:
```json
{
"schedule": { "kind": "cron", "expr": "30 6 * * *", "tz": "Europe/Berlin" },
"payload": {
"kind": "agentTurn",
"message": "Run 'openclaw doctor --fix --non-interactive' on all agent containers and report any issues found. If any agent has a critical problem, alert via Telegram immediately."
},
"sessionTarget": "isolated"
}
```
Was passiert: Jeden Morgen um 6:30 Berliner Zeit prüft Sam alle 6 Agenten-Container. Wenn ein Problem gefunden wird, kommt eine Telegram-Nachricht: "Peter-Container: Skill 'coding-agent' kann nicht gefunden werden — bitte prüfen."
So wissen wir vor dem ersten Arbeitstag, ob alles läuft.
---
Gateway-Token-Regenerierung
Ein häufiges Problem nach Neuinstallationen oder Container-Migrationen: Der Gateway-Token ist nicht konfiguriert oder ungültig.
```bash
openclaw doctor --generate-gateway-token
```
Dieser Flag erzwingt die Generierung eines neuen Gateway-Tokens. Danach muss der Gateway neu gestartet werden:
```bash
openclaw gateway restart
```
---
Sicherheits-Check mit doctor
`openclaw doctor` prüft auch grundlegende Sicherheitsaspekte — zum Beispiel ob der Gateway auf einem LAN-Interface bindet, das nicht nach außen exponiert sein sollte. Für einen dedizierten Sicherheits-Audit gibt es zusätzlich:
```bash
openclaw security audit --deep
```
Das ist besonders wichtig, wenn du einen neuen Kanal (z. B. WhatsApp) hinzufügst oder den Server verschoben hast.
---
Wenn doctor selbst nicht mehr hilft
In seltenen Fällen ist das Setup so beschädigt, dass doctor nicht mehr weiterkommt. Dann hilft `--force`:
```bash
openclaw doctor --fix --force
```
Vorsicht: `--force` überschreibt auch benutzerdefinierte Supervisor-Konfigurationen. Nur verwenden, wenn du sicher bist, dass die Service-Konfiguration tatsächlich kaputt ist — und vorher manuell ein Backup anlegen.
---
Unsere Maintenance-Routine
Für Referenz — das machen wir jeden Monat:
1. Täglich (automatisch): `openclaw doctor --fix --non-interactive` per Cron
2. Wöchentlich (manuell): `openclaw doctor --deep` — tiefe Prüfung inkl. System-Services
3. Nach jedem Update: `openclaw doctor --fix` — migriert veraltete Konfiguration
4. Vor größeren Änderungen: Manuelles Backup von `~/.openclaw/` zusätzlich zum automatischen doctor-Backup
Mit dieser Routine ist unser 6-Agenten-System seit Monaten stabil gelaufen — ohne manuelle Notfalleingriffe.
---
Das Fazit
`openclaw doctor` ist kein "Fix-Button für Abstürze". Es ist Prävention. Regelmäßig ausgeführt — am besten automatisch — hält es dein Setup sauber, migriert Konfigurationen nach Updates und warnt, bevor aus einem kleinen Problem ein großes wird.
Wie wir die vollständige Maintenance-Routine für alle 6 Agenten aufgebaut haben — inklusive Cron-Konfiguration, Alerting und Container-Restart-Policies — ist im OpenClaw Setup Playbook dokumentiert.
Komplett auf Deutsch verfügbar. 🇩🇪