OpenClaw-Agenten debuggen: Was tun wenn der Agent nicht mehr antwortet
Der Moment, den jeder kennt
Es ist 9:00 Uhr. Der Morgenreport-Cron sollte um 8:45 Uhr laufen. Keine Telegram-Nachricht. Du schickst dem Agenten eine manuelle Nachricht. Nichts.
Das ist kein Sonderfall — das passiert jedem, der Agenten in Produktion betreibt. Der Unterschied zwischen einem erfahrenen und einem unerfahrenen Betreiber liegt darin, wie schnell man die Ursache findet.
Nach mehreren Monaten mit unserem 6-Agenten-Team haben wir eine Diagnostik-Checkliste entwickelt, die wir bei jedem Ausfall durchgehen. Dieser Post ist diese Checkliste — mit den exakten Befehlen.
---
Schritt 1: Gateway läuft überhaupt?
Das ist der häufigste Grund. Das Gateway ist der Herzschlag des Systems — ohne es: keine Kanalkommunikation, keine Cron-Jobs, keine Heartbeats.
```bash
openclaw gateway status
```
Erwartete Ausgabe bei laufendem Gateway:
```
Gateway: running (PID 12345)
Uptime: 2h 14m
Channels: telegram (connected), discord (connected)
```
Wenn "stopped" oder kein Prozess:
```bash
openclaw gateway start
# Oder bei systemd-Setup:
systemctl start openclaw
systemctl status openclaw
```
Wenn Gateway startet aber sofort wieder stoppt:
```bash
# Logs anschauen
journalctl -u openclaw -n 50 --no-pager
# Oder direkt:
openclaw gateway start --foreground 2>&1 | head -30
```
Häufige Fehler im Log:
---
Schritt 2: Kanalverbindung prüfen
Das Gateway läuft, aber der Agent antwortet nicht auf Nachrichten? Das könnte der Kanal sein.
```bash
openclaw channels list
```
Erwartete Ausgabe:
```
telegram connected last message: 5m ago
discord connected last message: 12m ago
```
Wenn "disconnected" oder "error":
```bash
# Kanal-Test schickt eine interne Test-Nachricht
openclaw channels test telegram
# Kanal neu verbinden
openclaw gateway restart
```
Häufige Kanal-Probleme:
*Telegram:* Bot-Token abgelaufen oder widerrufen. Lösung: neuen Token über @BotFather holen, in .env ersetzen, Gateway neu starten.
*Discord:* Bot wurde vom Server entfernt oder hat nicht mehr die nötigen Berechtigungen. Lösung: Bot-Einladungslink neu generieren und Bot wieder einladen.
*Alle Kanäle:* Nach einem Server-Neustart ohne systemd-Autostart läuft das Gateway nicht automatisch. Lösung: `systemctl enable openclaw` einrichten (siehe unser VPS-Setup-Post).
---
Schritt 3: API-Key noch gültig?
API-Keys laufen ab, werden rotiert, oder überschreiten ihr Spending-Limit. Das ist eine häufige stille Fehlerquelle — das Gateway läuft, die Kanäle sind verbunden, aber der LLM-Aufruf schlägt fehl.
```bash
# Direkter Test mit curl (ersetzt sk-ant-... mit deinem echten Key)
curl https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" -d '{"model":"claude-haiku-20240307","max_tokens":10,"messages":[{"role":"user","content":"ping"}]}'
```
Wenn 401 zurückkommt: Key ungültig oder abgelaufen. Neuen Key erstellen, in .env ersetzen, Gateway neu starten.
Wenn 429 zurückkommt: Rate-Limit oder Spending-Limit erreicht. Im Anthropic-Dashboard unter Usage Limits prüfen.
Wenn der Befehl `ANTHROPIC_API_KEY` leer zurückgibt:
```bash
echo $ANTHROPIC_API_KEY
# Wenn leer: .env wird nicht geladen
# .env manuell sourcen und prüfen
source ~/.openclaw/workspace/.env && echo $ANTHROPIC_API_KEY
```
Das Gateway muss mit der richtigen `EnvironmentFile`-Konfiguration starten (siehe unser systemd-Setup-Guide).
---
Schritt 4: Session-Status prüfen
Manchmal hängt eine Session — der Agent hat eine Anfrage bekommen, verarbeitet sie aber nie fertig. Das blockiert neue Nachrichten.
```bash
# Aktive Sessions anzeigen
openclaw sessions list
```
Wenn eine Session als "stuck" oder seit Stunden "running" angezeigt wird:
```bash
# Session-ID aus dem list-Output nehmen
openclaw sessions kill <session-id>
# Danach: Neue Nachricht schicken — sollte wieder funktionieren
```
In Docker-Setups:
```bash
# Container-Status prüfen
docker ps
# Wenn Container "Exited":
docker compose up -d agent-sam
# Logs des letzten Absturzes anschauen
docker logs agent-sam --tail=50
```
Wenn der Container immer wieder neu startet (restart loop):
```bash
docker logs agent-sam --tail=100 2>&1 | grep -i error
```
---
Schritt 5: Workspace-Dateien prüfen
Der Agent startet, aber verhält sich komisch — gibt falsche Antworten, ignoriert Kontext, scheint seinen eigenen Namen nicht zu kennen?
Das deutet auf Probleme mit den Workspace-Dateien hin.
```bash
# Wichtigste Dateien prüfen
ls -la ~/.openclaw/workspace/
cat ~/.openclaw/workspace/SOUL.md # Persönlichkeit/Verhalten
cat ~/.openclaw/workspace/MEMORY.md # Langzeitgedächtnis
```
Häufige Probleme:
*SOUL.md leer oder fehlt:* Der Agent hat keine Persönlichkeit und verhält sich wie ein roher Chatbot. Lösung: SOUL.md neu erstellen.
*MEMORY.md zu groß:* Wenn MEMORY.md über 3000 Wörter hat, füllt es das Kontext-Fenster und verdrängt wichtigere Informationen. Lösung: MEMORY.md aufräumen — alte, unwichtige Einträge entfernen.
*Korrupte Tages-Notizen:* Wenn eine memory/YYYY-MM-DD.md-Datei ungültigen Inhalt hat, kann das den Agenten beim Lesen verwirren.
```bash
# Tagesnotizen der letzten 3 Tage prüfen
ls -la ~/.openclaw/workspace/memory/ | tail -5
cat ~/.openclaw/workspace/memory/$(date +%Y-%m-%d).md
```
---
Schritt 6: Cron-Job-Status prüfen
Der Agent antwortet auf manuelle Nachrichten, aber automatische Tasks laufen nicht mehr?
```bash
# Alle Cron-Jobs und ihren Status anzeigen
openclaw cron list
# Logs eines spezifischen Jobs
openclaw cron logs <job-id>
```
Wenn ein Job als "disabled" angezeigt wird: Irrtümlich deaktiviert oder durch einen Fehler automatisch deaktiviert.
```bash
openclaw cron enable <job-id>
```
Wenn der Job "failed" zeigt:
```bash
# Letzten Fehler anschauen
openclaw cron logs <job-id> --limit 1
# Job manuell auslösen und Ausgabe beobachten
openclaw cron trigger <job-id>
```
Häufige Cron-Fehler:
*Timing-Problem:* Der Job läuft nicht zur erwarteten Zeit. Häufig eine Zeitzone-Verwechslung. OpenClaw läuft in UTC. Berlin-Zeit ist UTC+1 (Winter) bzw. UTC+2 (Sommer). Prüfe die Cron-Syntax.
*Prompt referenziert eine nicht-existierende Datei:* Wenn der Prompt `HEARTBEAT.md` lädt, diese aber nicht existiert, kann der Job fehlschlagen. Lösung: Datei erstellen (darf leer sein).
*Nach Gateway-Neustart vergessen zu aktivieren:* Cron-Jobs sind erst nach `openclaw gateway restart` aktiv.
---
Schritt 7: Disk-Space prüfen
Das wird am häufigsten übersehen. Wenn die Festplatte voll ist, kann der Agent keine neuen Log-Einträge oder Gedächtnisdateien schreiben — und verhält sich undefiniert.
```bash
df -h
```
Wenn `/` über 85% belegt:
```bash
# Was nimmt Platz weg?
du -sh ~/.openclaw/workspace/* | sort -h | tail -10
# Docker-Cleanup (entfernt unused images und volumes)
docker system prune -a
# Alte Tagesnotizen aufräumen (älter als 30 Tage)
find ~/.openclaw/workspace/memory/ -name "*.md" -mtime +30 -delete
# OpenClaw-Logs rotieren
journalctl --vacuum-size=500M
```
In unserem Setup läuft täglich ein Cron-Job, der Disk-Nutzung prüft und bei über 80% eine Telegram-Warnung schickt. Das hat uns mehrmals vor einem Ausfall bewahrt.
---
Schritt 8: Netzwerk und DNS
Seltener, aber vorkommend: Der Agent kann keine externen APIs erreichen. Das zeigt sich in Fehlern wie "connection refused" oder "timeout" in den Logs.
```bash
# Grundlegender Netzwerk-Test
curl -s https://api.anthropic.com/health || echo "Anthropic nicht erreichbar"
curl -s https://api.telegram.org/bot<TOKEN>/getMe | head -c 100
# DNS-Auflösung prüfen
nslookup api.anthropic.com
# In Docker-Containern: Host-DNS prüfen
docker exec agent-sam curl -s https://api.anthropic.com/health
```
Wenn der Container die API nicht erreicht aber der Host-Server schon:
```bash
# DNS in docker-compose.yml explizit setzen
# Unter dem betroffenen Service:
dns:
- 8.8.8.8
- 1.1.1.1
```
---
Die schnelle Diagnostik-Checkliste
Wenn du nicht weißt, wo du anfangen sollst, geh diese Liste in Reihenfolge durch:
```bash
# 1. Gateway-Status
openclaw gateway status
# 2. Kanäle
openclaw channels list
# 3. API-Key
curl https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" -d '{"model":"claude-haiku-20240307","max_tokens":10,"messages":[{"role":"user","content":"ping"}]}'
# 4. Sessions
openclaw sessions list
# 5. Docker (falls in Containern)
docker compose ps
# 6. Disk
df -h
# 7. Logs
journalctl -u openclaw -n 30 --no-pager
```
90% aller Ausfälle werden durch einen dieser sieben Befehle diagnostiziert.
---
Monitoring einrichten, damit man nie zu spät erfährt
Besser als debuggen: gar nicht erst in die Situation kommen.
Drei einfache Monitoring-Maßnahmen:
1. Uptime-Monitor (UptimeRobot, kostenlos): Richtet einen HTTP-Ping auf einen Endpunkt deines Servers ein. Bei Ausfall: E-Mail oder Telegram-Benachrichtigung.
2. Disk-Warning-Cron:
```
Zeitplan: 0 */4 * * * (alle 4 Stunden)
Prompt: Prüfe den Disk-Speicher mit 'df -h /'. Wenn über 80% belegt:
schicke eine Warnung per Telegram. Sonst: HEARTBEAT_OK.
```
3. Agent-Self-Check:
```
Zeitplan: */30 * * * * (alle 30 Minuten, der reguläre Heartbeat)
Im HEARTBEAT.md vermerken: "Falls heute kein Morgenreport gesendet wurde,
erwähne das im nächsten Check."
```
Das klingt simpel — und das ist es auch. Aber diese drei Maßnahmen haben bei uns mehrmals verhindert, dass ein stiller Ausfall erst Stunden später bemerkt wurde.
---
Fazit
Agenten-Ausfälle sind unvermeidlich. Der Unterschied liegt darin, wie schnell und systematisch man reagiert. Die Checkliste oben bringt dich in unter 10 Minuten zur Ursache.
Das vollständige Setup — inklusive Monitoring-Konfiguration, systemd-Service, Docker-Compose und den Workspace-Dateien für alle 6 Agenten — ist im OpenClaw Setup Playbook dokumentiert.
Komplett auf Deutsch verfügbar. 🇩🇪