OpenClaw WhatsApp-Anbindung – vollständiger Leitfaden: Von der Konfiguration bis zur Praxis

Mit WhatsApp direkt mit der KI chatten – Ihr meistgenutztes Messenger-Tool ruft den Assistenten ab, ohne zwischen Apps zu wechseln. Die WhatsApp-Anbindung ist etwas aufwendiger als bei Telegram, aber mit dem richtigen Verständnis ist die Einrichtung in 5–10 Minuten erledigt.

Günstiger Einstieg: ArkClaw macht KI-Agenten wirklich zugänglich

OpenClaw (der „Hummer“) ist beliebt, aber die Konfiguration schreckt ab? ByteDance Volcano Engine bietet mit ArkClaw eine Ein-Klick-Lösung: 24/7 online, Browser steuern, Skripte ausführen, Kalender verwalten – ohne Server- und Token-Gefrickel.

Der Preis ist der Hammer: 9,9 Yuan/Monat, mit Einladungscode ZLKUK54M (hier registrieren) nur 8,9 Yuan. Als Entwickler lohnt sich Coding Plan Pro – ArkClaw quasi gratis.

Warum KI auf WhatsApp anbinden?

Bevor Sie loslegen, fragen Sie sich vielleicht: Warum nicht einfach Telegram oder die Web-Oberfläche?

Jede Plattform hat ihre Stärken. Für mich spricht Folgendes für WhatsApp:

• Gewohnheit: WhatsApp ist mein meistgenutzter Messenger – Familie und Freunde sind dort
• Nahtlose Integration: Keine separate KI-App nötig, Fragen direkt im Chat stellen
• Linked Devices: WhatsApps Multi-Geräte-Funktion ist ausgereift und stabil
• Kontrollierbare Privatsphäre: Daten auf dem eigenen Server, ohne Drittanbieter

Telegram hat ebenfalls Vorteile – offenere API, reicheres Bot-Ökosystem. Die Wahl hängt von Ihrem Anwendungsfall ab.

Vorbereitung: Umgebung prüfen

Vor der Anbindung sollten diese Voraussetzungen erfüllt sein:

Pflichtvoraussetzungen

1. OpenClaw installiert und lauffähig – Falls noch nicht geschehen, siehe die Installationsanleitung
2. WhatsApp-Konto auf dem Handy – Hauptkonto zum QR-Scan erforderlich
3. Gateway läuft – openclaw gateway muss gestartet sein
4. Stabile Netzwerkverbindung – Für den QR-Scan und die Kopplung

Technischer Hinweis

Ein Detail: Mit der Bun-Runtime können bei WhatsApp- oder Telegram-Verbindungen Kompatibilitätsprobleme auftreten. Offiziell wird Node.js für das Gateway empfohlen – stabiler im Betrieb.

Umgebung prüfen:

# Node.js-Version prüfen
node --version

# Gateway-Lauf prüfen
ps aux | grep openclaw

Drei Anbindungsmethoden

OpenClaw bietet drei Wege zur WhatsApp-Verbindung – nach Empfehlung sortiert.

Methode 1: onboard-Assistent (am einfachsten)

Der unkomplizierteste Weg – ideal für die Erstkonfiguration.

Falls die Ersteinrichtung noch aussteht:

openclaw onboard --install-daemon

Im Assistenten werden die Messaging-Kanäle abgefragt. WhatsApp wählen, dann:

1. Im Terminal erscheint ein QR-Code
2. WhatsApp auf dem Handy öffnen → „Einstellungen“ → „Verknüpfte Geräte“
3. „Gerät verknüpfen“ tippen und QR-Code scannen
4. Nach erfolgreichem Scan meldet das Terminal die abgeschlossene Verbindung

Der Vorgang dauert 1–2 Minuten. Beim ersten Scan war ich etwas nervös – ging aber auf Anhieb durch.

Methode 2: channels login-Befehl

Wenn onboard bereits abgeschlossen ist und Sie nur WhatsApp hinzufügen möchten:

openclaw channels login

Ablauf:

1. QR-Code im Terminal (oder in der Web-Oberfläche)
2. Mit WhatsApp scannen
3. Verbindung steht, Nachrichten werden empfangen

Schnell und direkt – ohne vollständigen Konfigurationsflow.

Methode 3: Web-Oberfläche (am flexibelsten)

Für feinere Kontrolle über die Einstellungen.

OpenClaw Control Panel öffnen (Standard: http://localhost:18789), dann:

Schritt 1: Konfigurationsseite

Navigieren Sie zu Settings → Config, oben rechts RAW klicken – Raw-Editor.

Schritt 2: WhatsApp-Konfiguration

Im Abschnitt channels WhatsApp ergänzen:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+8613800138000"],
      "groupPolicy": "allowlist",
      "mediaMaxMb": 50,
      "debounceMs": 0
    }
  }
}

Bedeutung der Optionen:

• dmPolicy: Privatchat-Strategie – allowlist erlaubt nur Whitelist-Nummern
• allowFrom: Whitelist mit eigener Nummer (internationales Format mit Ländercode)
• groupPolicy: Gruppenstrategie – allowlist ist sicherer
• mediaMaxMb: Maximale Mediengröße in MB
• debounceMs: Debounce-Verzögerung in Millisekunden, üblicherweise 0

Schritt 3: Speichern und scannen

Oben rechts Update klicken, dann auf der Channels-Seite den QR-Code mit WhatsApp scannen.

Konfiguration im Detail

Die genannten Optionen im Überblick.

Berechtigungen: Wer darf der KI schreiben?

dmPolicy und groupPolicy sind zentrale Sicherheitseinstellungen.

dmPolicy (Privatchat) – drei Optionen:

• allowlist: Nur Whitelist-Nummern (empfohlen)
• denylist: Alle außer Blacklist
• open: Jeder (nicht empfohlen, außer Sie wissen genau, was Sie tun)

Ich nutze allowlist – nur eigene und Familiennummern. Die KI kann Systembefehle ausführen (wenn Skills aktiv sind); fremde Nummern sollten keinen Zugriff haben.

allowFrom – Telefonnummernformat

Internationales Format mit Ländercode:

"allowFrom": [
  "+8613800138000",    // China
  "+14155552671",      // USA
  "+447700900000"      // UK
]

Pluszeichen + und Ländercode nicht vergessen – sonst wird die Nummer nicht erkannt.

groupPolicy (Gruppen)

Für KI in WhatsApp-Gruppen Gruppenstrategie setzen. Vorsicht: Gruppenfreigabe nur in vertrauenswürdigen, kleinen Gruppen.

Beispiel:

"groupPolicy": "allowlist",
"allowFrom": ["Gruppen-ID"]

Gruppen-ID steht in den Logs, oder vorübergehend open setzen, eine Nachricht senden und die ID aus dem Log übernehmen.

Message-Routing: Wie die KI Nachrichten verarbeitet

OpenClaw leitet WhatsApp-Nachrichten automatisch an das KI-Modell weiter:

1. Sie senden eine WhatsApp-Nachricht
2. OpenClaw Gateway empfängt sie
3. Prüfung, ob der Absender auf der Whitelist steht
4. Bei Erfolg Weiterleitung an das KI-Modell
5. KI erzeugt die Antwort
6. Antwort geht zurück nach WhatsApp

Typisch 1–2 Sekunden – abhängig von der Modell-Latenz.

Medienverarbeitung

mediaMaxMb begrenzt die empfangbare Dateigröße. Standard 50 MB reicht meist.

Unterstützte Medientypen:

• Bilder (JPG, PNG usw.)
• Audiodateien
• Dokumente (PDF, TXT usw.)

Mit Vision-Fähigkeit (z. B. GPT-4V) kann die KI Bildinhalte auswerten.

QR-Code-Scan im Detail

Unabhängig von der Methode folgt am Ende der QR-Scan – mit ein paar Details.

Auf dem Handy

1. WhatsApp öffnen
2. Oben rechts „Mehr“ (drei Punkte)
3. „Verknüpfte Geräte“ (oder „Linked Devices“)
4. „Gerät verknüpfen“ (oder „Link a Device“)
5. Ggf. Fingerabdruck oder PIN
6. Kamera auf den QR-Code am Computer richten

Am Computer

• Gültigkeit: QR-Codes laufen nach 1–2 Minuten ab – bei Fehlschlag neu generieren
• Lesbarkeit: QR-Code scharf darstellen, Terminal-Schrift nicht zu klein
• Netzwerk: Beim Scan müssen Handy und Computer online sein

Beim ersten Versuch war der QR-Code im Terminal zu klein und unscharf – nach Vergrößern des Fensters klappte es sofort.

Erfolgszeichen

Nach erfolgreichem Scan:

• Handy: OpenClaw erscheint unter „Verknüpfte Geräte“
• Terminal: Meldung wie „WhatsApp connected“
• Web-Oberfläche: WhatsApp auf der Channels-Seite grün (verbunden)

Test und Verifizierung

Direkt nach der Verbindung testen.

Erste Nachricht

Sich selbst eine WhatsApp-Nachricht senden, z. B.:

Hallo, hörst du mich?

Bei korrekter Konfiguration antwortet die KI innerhalb weniger Sekunden.

Verschiedene Nachrichtentypen

• Text: der KI eine Frage stellen
• Bild: Bild senden und Beschreibung anfordern (Vision-Modell nötig)
• Dokument: PDF oder TXT
• Sprache: ggf. Sprache-zu-Text testen

Logs prüfen

Bei Problemen helfen die Logs:

# OpenClaw-Logs anzeigen
openclaw gateway --port 18789

Dort: empfangene Nachrichten, Verarbeitung, Fehlermeldungen.

Häufige Probleme und Lösungen

Software einrichten – Fehler sind normal. Meine Erfahrungen:

Problem 1: Keine Reaktion nach QR-Scan

Mögliche Ursachen:

• QR-Code abgelaufen
• Netzwerkprobleme
• Veraltete WhatsApp-Version

Lösung:

1. QR-Code aktualisieren und erneut scannen
2. Netzwerk von Handy und Computer prüfen
3. WhatsApp auf die neueste Version aktualisieren

Problem 2: Verbindung fehlgeschlagen, status=515

Häufiger Fehler, in der offiziellen Doku dokumentiert.

Vollständige Fehlermeldung:

WhatsApp login failed: status=515 Unknown Stream Errored (restart required)

Lösung:

1. Settings → Config
2. Oben rechts Update (auch ohne Änderungen)
3. Channels-Seite – Verbindungsstatus prüfen
4. Falls nötig Gateway neu starten

# Gateway neu starten
pkill -f openclaw
openclaw gateway --port 18789

Problem 3: Nachricht gesendet, KI antwortet nicht

Mögliche Ursachen:

• Absender nicht auf der Whitelist
• KI-Modell falsch konfiguriert
• API-Schlüssel ungültig

Schritte:

1. Nummernformat prüfen (international)
2. Logs – wurde die Nachricht empfangen?
3. KI in der Web-Oberfläche testen
4. API-Schlüssel validieren

Problem 4: Berechtigung verweigert

Symptom: „Permission denied“ oder keine Antwort

Lösung:

• Nummer in allowFrom?
• Format inkl. Ländercode?
• Bei Gruppen: groupPolicy prüfen

Problem 5: Medien können nicht gesendet werden

Mögliche Ursachen:

• Datei größer als mediaMaxMb
• Format nicht unterstützt
• Upload-Netzwerkfehler

Lösung:

• mediaMaxMb erhöhen
• Datei komprimieren
• Netzwerk prüfen

Problem 6: Nach Gateway-Neustart getrennt

Symptom: Nach PC- oder Gateway-Neustart WhatsApp offline

Lösung:

1. Normalerweise automatische Wiederverbindung
2. Sonst openclaw channels login erneut
3. QR-Code neu scannen
4. Daemon-Start prüfen

Fortgeschrittene Tipps

Nach den Grundlagen – optionale Feineinstellungen.

Multi-Geräte-Verwaltung

WhatsApp erlaubt mehrere verknüpfte Geräte. Mehrere OpenClaw-Installationen können parallel verbunden sein – Nachrichten synchronisieren sich.

Hinweis: Pro WhatsApp-Konto nur eine OpenClaw-Verbindung. Mehrere Rechner erfordern unterschiedliche WhatsApp-Konten.

Eigene Antwortstrategie

debounceMs steuert Message-Debounce:

"debounceMs": 1000

Bei mehreren schnellen Nachrichten wartet die KI 1 Sekunde und verarbeitet gebündelt – weniger API-Aufrufe.

Nachrichtenfilter

Bestimmte Nachrichtentypen ignorieren – in den Skills Filterregeln setzen, z. B. nur auf Nachrichten reagieren, die mit „AI“ beginnen.

Performance-Optimierung

Bei hohem Nachrichtenaufkommen:

• mediaMaxMb reduzieren, Bandbreite sparen
• debounceMs anpassen, API-Last senken
• Schnelleres KI-Modell wählen

Sicherheitsempfehlungen

Nach der WhatsApp-Anbindung diese Punkte beachten:

1. Whitelist strikt führen

Nur vertrauenswürdige Nummern in allowFrom. Diese Nummern können über die KI Systembefehle auslösen (wenn Skills aktiv) – hohe Berechtigung.

2. Verknüpfte Geräte regelmäßig prüfen

Unter WhatsApp „Verknüpfte Geräte“ prüfen, welche Geräte online sind. Unbekannte sofort entfernen.

3. Sensible Aktionen bestätigen

Für Löschen, Konfigurationsänderungen usw. in Skills eine Zweitbestätigung einbauen.

4. Nicht an öffentlichen Geräten verbinden

In Internetcafés, Bibliotheken usw. keinen QR-Scan – Geräte können überwacht werden.

5. OpenClaw aktuell halten

Regelmäßig aktualisieren für Sicherheitspatches:

npm update -g openclaw
# oder
pnpm update -g openclaw

Fazit

Damit sollte WhatsApp an OpenClaw angebunden sein. Kurzüberblick:

WhatsApp vs. Telegram – was wählen?

WhatsApp, wenn:

• WhatsApp Ihr Haupt-Messenger ist
• Familie und Freunde die KI nutzen sollen
• Stabilität von Linked Devices wichtig ist

Telegram, wenn:

• Sie offenere API-Fähigkeiten brauchen
• Bot-Ökosystem wichtig ist
• Kanäle und erweiterte Gruppenfunktionen nötig sind

Beide parallel ist möglich – OpenClaw unterstützt Multi-Channel; je nach Situation die passende Plattform wählen.

Nächste Schritte

Nach erfolgreicher Verbindung:

• OpenClaw-Skills erkunden, der KI mehr Fähigkeiten geben
• Bilder und Dokumente senden, Multimodalität testen
• Eigene Antwortlogik anpassen
• Bei Interesse eigene Skill-Plugins entwickeln

Abschließend: WhatsApp ist praktisch, aber Sicherheit zählt. Whitelist vorsichtig verwalten – keine KI-Berechtigung für unvertrauenswürdige Kontakte.

Viel Erfolg – bei Fragen Doku oder Community nutzen!

---