WhatsApp-Einrichtung

WhatsApp ist die beliebteste Messaging-App der Welt. Mit OpenClaw verbindest du sie so, dass dein KI-Assistent dort lebt, wo deine Gespräche ohnehin stattfinden. Keine zusätzliche App, keine neue Gewohnheit.

Der Kopplungsprozess funktioniert wie bei Bluetooth-Kopfhörern: Code scannen, verbinden, fertig. Aber im Gegensatz zu Bluetooth sind WhatsApp-Sessions nicht dauerhaft. Sie laufen ab, und wenn das passiert, scannst du erneut. Der ganze Vorgang dauert weniger als eine Minute, wenn man es einmal gemacht hat.

Was du brauchst

• Einen WhatsApp-Account auf deinem Handy
• Eine laufende und erreichbare OpenClaw-Instanz
• Zugriff auf das OpenClaw-Gateway (Web-UI oder CLI)
• Etwa 5 Minuten für die Ersteinrichtung

Wie die WhatsApp-Integration funktioniert

OpenClaw verbindet sich mit WhatsApp über dasselbe Protokoll wie WhatsApp Web. Dein Handy bleibt das Hauptgerät. OpenClaw erscheint als verknüpftes Gerät, ähnlich wie wenn du WhatsApp Web im Browser öffnest.

Als WhatsApp Web 2015 startete, war es ein einfacher Spiegel deiner Handy-Nachrichten. Das Protokoll hat sich seitdem deutlich weiterentwickelt und ist auf eine Multi-Device-Architektur umgestiegen, bei der verknüpfte Geräte eigene Verschlüsselungskeys besitzen und zeitweise unabhängig funktionieren können. OpenClaw profitiert von dieser Weiterentwicklung: Dein Agent kann weiter antworten, auch wenn dein Handy kurzzeitig keine Verbindung hat.

Diese Architektur bestimmt, was gut funktioniert und was nicht:

• Funktioniert gut: Nachrichten senden und empfangen, Mediendateien verarbeiten, Gesprächskontext über Sessions hinweg behalten
• Einschränkungen: Sessions laufen periodisch ab, einige WhatsApp-Funktionen (Status-Updates, Kanäle) sind nicht zugänglich, die Zustellung hängt davon ab, dass dein Handy kürzlich online war

Schritt 1: WhatsApp in OpenClaw aktivieren

Öffne deine OpenClaw-Konfiguration und füge WhatsApp als Kanal hinzu.

Über die Gateway-UI

1. Öffne das OpenClaw-Gateway-Webinterface (Standard: http://localhost:18789)
2. Navigiere zu Channels (Kanäle)
3. Finde WhatsApp in der Liste und klicke auf Enable (Aktivieren)
4. Das Gateway generiert einen QR-Code

Über die Konfigurationsdatei

Füge WhatsApp zu deiner Kanalkonfiguration hinzu:

channels:
  entries:
    - name: whatsapp
      type: whatsapp
      enabled: true

Starte das Gateway nach Konfigurationsänderungen neu: openclaw gateway restart

Schritt 2: Kopplung per QR-Code

Das ist der zentrale Schritt. OpenClaw generiert einen QR-Code, und du scannst ihn mit deinem Handy, um das Gerät zu verknüpfen.

Code scannen

1. Öffne WhatsApp auf deinem Handy
2. Gehe zu Einstellungen → Verknüpfte Geräte → Gerät verknüpfen
3. Richte deine Handykamera auf den QR-Code im OpenClaw-Gateway-UI
4. Warte auf die Bestätigungsnachricht

Verbindung prüfen

Nach dem Scannen sollte das Gateway-UI den WhatsApp-Kanal als "Verbunden" anzeigen. Sende eine Testnachricht an deine eigene Nummer (oder direkt an den Agenten), um zu bestätigen, dass Nachrichten in beide Richtungen fließen.

Wenn der QR-Code schon einige Minuten sichtbar ist, kann er abgelaufen sein. Klicke auf "QR aktualisieren", um einen neuen zu generieren und scanne erneut.

Schritt 3: Nachrichtenverarbeitung konfigurieren

Entscheide nach der Kopplung, wie dein Agent eingehende WhatsApp-Nachrichten behandelt.

DM vs. Gruppen-Nachrichten

• Direktnachrichten: Der Agent antwortet jedem, der deiner verknüpften WhatsApp-Nummer schreibt. Konfiguriere Allowlists, wenn du den Zugriff einschränken möchtest.
• Gruppen-Nachrichten: Der Agent kann so konfiguriert werden, dass er nur bei Erwähnung antwortet, oder auf alle Nachrichten in bestimmten Gruppen.

Medien und Anhänge

OpenClaw kann Bilder, Dokumente und Sprachnotizen empfangen und verarbeiten, die über WhatsApp gesendet werden. Bilder lösen das Bildanalyse-Tool aus, Dokumente durchlaufen die PDF-Pipeline, und Sprachnotizen werden transkribiert, wenn ein Speech-to-Text-Modell konfiguriert ist.

Schritt 4: Mit Session-Ablauf umgehen

Dieser Teil überrascht viele. WhatsApp-Sessions für verknüpfte Geräte sind nicht dauerhaft. Sie laufen aus verschiedenen Gründen ab:

• Die Session ist wegen Inaktivität abgelaufen
• WhatsApp hat sein Protokoll aktualisiert (passiert regelmäßig)
• Du hast das Gerät manuell über dein Handy abgemeldet
• Der OpenClaw-Server war über einen längeren Zeitraum offline

Wenn eine Session abläuft, reagiert der Agent nicht mehr auf WhatsApp-Nachrichten. OpenClaw protokolliert die Trennung und kann dich über einen anderen Kanal (wie Telegram oder Discord) benachrichtigen, dass ein Re-Pairing nötig ist.

Das Re-Pairing folgt demselben QR-Scan-Prozess wie die Ersteinrichtung. Gehe zum Gateway-UI, generiere einen neuen QR-Code und scanne ihn. Nach ein paar Zyklen wird das zur Routine.

Die japanische Kunst des Kintsugi repariert zerbrochene Keramik mit Gold und macht die Bruchlinien zum Teil der Schönheit des Objekts. WhatsApp-Session-Management funktioniert ähnlich: Die Unterbrechungen sind unvermeidbar, aber der Re-Pairing-Prozess ist schnell, und jede neue Verbindung ist nahtlos. Baue das Re-Pairing in deine Routine ein, und die Abläufe hören auf, ein Problem zu sein.

Schritt 5: Multi-Device-Überlegungen

WhatsApp erlaubt bis zu 4 verknüpfte Geräte pro Account. OpenClaw nutzt einen dieser Slots. Plane deine verknüpften Geräte entsprechend:

• Slot 1: WhatsApp Web (Browser)
• Slot 2: WhatsApp Desktop-App
• Slot 3: OpenClaw-Agent
• Slot 4: Reserviert / Frei

Wenn du bereits alle 4 Slots nutzt, musst du ein Gerät trennen, bevor du OpenClaw koppelst. Gehe auf deinem Handy zu Einstellungen → Verknüpfte Geräte, um verbundene Geräte zu verwalten.

Troubleshooting

QR-Code lässt sich nicht scannen

• Stelle sicher, dass der QR-Code frisch generiert ist (sie verfallen schnell)
• Prüfe, ob die Handykamera sauber ist
• Versuche, den QR-Code in einem anderen Browser zu generieren oder den Browsercache zu leeren

Agent antwortet nicht nach dem Pairing

• Prüfe die Gateway-Logs: openclaw gateway logs
• Stelle sicher, dass der Kanal im Gateway-UI als "Verbunden" angezeigt wird
• Sende eine Nachricht direkt an deine eigene WhatsApp-Nummer (nicht über eine Gruppe) zum Testen
• Prüfe, ob ein anderer Kanal Nachrichten desselben Kontakts abfängt

Session bricht häufig ab

• Stelle sicher, dass dein OpenClaw-Server eine stabile Internetverbindung hat (keine häufigen Neustarts oder Netzwerkunterbrechungen)
• Halte dein Handy mit dem Internet verbunden (verknüpfte Geräte benötigen, dass das Handy kürzlich online war)
• Prüfe, ob WhatsApp ein Protokoll-Update durchgeführt hat (siehe OpenClaw-Release-Notes für Patches)
• Richte einen sekundären Benachrichtigungskanal ein, damit du alarmiert wirst, wenn die Session abbricht

Nachrichten sind verzögert

• Prüfe die Netzwerklatenz und DNS-Auflösung deines Servers
• Stelle sicher, dass dein KI-Anbieter schnell antwortet (Provider-Statusseiten prüfen)
• Große Mediendateien brauchen länger zur Verarbeitung. Das ist erwartetes Verhalten, kein Bug

Sicherheitshinweise

• Zugriffskontrolle: Standardmäßig kann jeder mit deiner WhatsApp-Nummer deinem Agenten schreiben. Nutze Allowlists, um den Zugriff einzuschränken.
• Nachrichtenprivatsphäre: Nachrichten werden von deinem KI-Anbieter verarbeitet. Informiere dich über die Datenaufbewahrungsrichtlinien deines Anbieters.
• Geräteverknüpfung: Verknüpfe OpenClaw nur auf Infrastruktur, die du kontrollierst. Vermeide geteilte oder öffentliche Server.
• Gateway-Sicherheit: Halte dein Gateway hinter einer Firewall. Port 18789 niemals öffentlich ins Internet freigeben.

Für einen vollständigen Sicherheits-Check lies die Security Best Practices.

WhatsApp vs. andere Kanäle

Was du als Nächstes tun kannst

• Richte einen zweiten Benachrichtigungskanal ein (Telegram oder Discord), damit du informiert wirst, wenn die WhatsApp-Session abbricht
• Konfiguriere Allowlists, wenn du einschränken möchtest, wer deinem Agenten schreiben darf
• Installiere Skills, die gut mit Messaging funktionieren: Kalender, Erinnerungen, Websuche
• Lies den Session-Management-Guide, um zu verstehen, wie OpenClaw lange Gespräche handhabt