WhatsApp Integration mit OpenClaw

Es ist oft mühsam, Messaging-Dienste in bestehende Workflows zu integrieren, ohne sich mit komplexen offiziellen APIs oder hohen Kosten herumzuschlagen. Wenn du versuchst, automatisierte Antworten oder Gateways für WhatsApp zu bauen, landest du schnell bei komplizierten Setups, die schwer zu warten sind.

OpenClaw löst das über WhatsApp Web (Baileys). Damit kannst du dein Konto direkt verknüpfen und Nachrichten über ein Gateway verarbeiten, ohne den Umweg über teure Drittanbieter zu gehen.

Voraussetzungen

• OpenClaw CLI
• WhatsApp Account (OpenClaw empfiehlt eine separate Nummer)
• Zugriff auf die Gateway-Konfiguration

Schnellstart

In 5 Minuten ist dein WhatsApp-Channel einsatzbereit. Folge diesen Schritten für den minimalen Pfad:

1. WhatsApp Access Policy konfigurieren Definiere in deiner Konfiguration, wie mit DMs und Gruppen umgegangen werden soll:

   {
     channels: {
       whatsapp: {
         dmPolicy: "pairing",
         allowFrom: ["+15551234567"],
         groupPolicy: "allowlist",
         groupAllowFrom: ["+15551234567"],
       },
     },
   }

2. WhatsApp verknüpfen (QR) Nutze die CLI, um den QR-Code für den Login zu generieren:

   openclaw channels login --channel whatsapp

   Für einen spezifischen Account:

   openclaw channels login --channel whatsapp --account work

3. Gateway starten Bringe das Gateway online, um den WhatsApp Socket zu aktivieren:

   openclaw gateway

4. Erste Pairing-Anfrage bestätigen Falls du den pairing Modus nutzt, musst du Anfragen manuell freigeben:

   openclaw pairing list whatsapp
   openclaw pairing approve whatsapp <CODE>

Deployment Patterns

Ich empfehle, WhatsApp auf einer separaten Nummer zu betreiben. Das sorgt für eine saubere Trennung der Identitäten und vermeidet Verwirrung bei Self-Chats. Hier sind die zwei gängigen Wege:

• Dedizierte Nummer (Empfohlen): Dies bietet klare Routing-Grenzen und eine eigene Identität für OpenClaw. Nutze hierfür eine minimale Policy mit dmPolicy: "allowlist".
• Persönliche Nummer: Der Onboarding-Flow unterstützt dies und schreibt automatisch eine Konfiguration mit selfChatMode: true. So werden Schutzmechanismen für Self-Chats aktiviert.

Der Channel basiert aktuell rein auf WhatsApp Web (Baileys). Eine separate Twilio-Integration ist im integrierten Chat-Channel-Registry nicht vorgesehen.

Fehlerbehebung

• Pairing-Anfrage abgelaufen: Pairing-Anfragen sind nur 1 Stunde lang gültig. Danach musst du eine neue Anfrage initiieren.
• Anfrage-Limit erreicht: Es können maximal 3 ausstehende Pairing-Anfragen pro Channel existieren.
• Fehlende Nachrichten: Das System ignoriert Status-Updates (@status) und Broadcast-Chats (@broadcast) automatisch.
• Sende-Probleme: Outbound-Nachrichten erfordern, dass ein aktiver WhatsApp-Listener für den Ziel-Account im Gateway läuft.

Bei weiteren Fragen zum Setup hilft dir der AI Setup Assistant direkt weiter.

Nächste Schritte

• Pairing Dokumentation
• Channel Troubleshooting
• Gateway Konfiguration
• Deployment Patterns

Du kennst das Problem: Dein Bot ist online, aber plötzlich schreibt ihm jeder oder er fängt an, in Gruppen zu antworten, in denen er eigentlich ruhig sein sollte. Den Zugriff sauber zu verwalten, ohne legitime Nutzer auszusperren, ist oft zeitfressend.

Hier erfährst du, wie du die Kontrolle über DMs und Gruppen behältst und sicherstellst, dass dein Bot nur dann reagiert, wenn er wirklich gefragt ist.

Voraussetzungen

• Zugriff auf die Konfigurationsdatei deines Bots
• Die channels.whatsapp Konfigurations-Blöcke
• Optional: Definierte mentionPatterns in der agents.list oder unter messages.groupChat

Schnellstart

In weniger als 5 Minuten legst du fest, wer deinem Bot schreiben darf. Die zentrale Stelle dafür ist channels.whatsapp.dmPolicy.

channels:
  whatsapp:
    dmPolicy: pairing # Standardwert
    allowFrom:
      - "+49123456789"

DM Policy Optionen

Die dmPolicy steuert den Zugriff auf Direct Chats:

• pairing: Das Standardverhalten.
• allowlist: Nur Nummern, die explizit in allowFrom stehen, haben Zugriff.
• open: Jeder kann den Bot anschreiben (erfordert allowFrom: ["*"]).
• disabled: Deaktiviert alle Direct Chats.

Wichtig: E.164-Nummern in allowFrom werden intern normalisiert. Wenn du keine Allowlist konfigurierst, ist deine eigene verknüpfte Nummer standardmäßig erlaubt. Ausgehende fromMe DMs führen niemals zu einem automatischen Pairing.

Gruppen-Zugriff steuern

Der Zugriff in Gruppen erfolgt über zwei Layer:

1. Group Membership Allowlist (channels.whatsapp.groups): Wenn dieser Block fehlt, sind alle Gruppen erlaubt. Ist er vorhanden, fungiert er als Allowlist (nutze * für alle Gruppen).
2. Sender Policy: Über channels.whatsapp.groupPolicy und groupAllowFrom legst du fest, wer innerhalb der Gruppe den Bot triggern darf.
   • open: Die Sender-Allowlist wird ignoriert.
   • allowlist: Der Sender muss in groupAllowFrom (oder *) stehen.
   • disabled: Blockiert alle eingehenden Nachrichten aus Gruppen.

Falls groupAllowFrom nicht gesetzt ist, nutzt das System automatisch allowFrom als Fallback. Wenn gar kein channels.whatsapp Block existiert, ist die Group-Policy effektiv auf open gestellt.

Mentions und der /activation Befehl

In Gruppen reagiert der Bot standardmäßig nur, wenn er erwähnt wird. Die Mention-Erkennung umfasst:

• Explizite WhatsApp-Mentions deiner Bot-Identität.
• Konfigurierte mentionPatterns (Regex) in agents.list[].groupChat.mentionPatterns oder als Fallback in messages.groupChat.mentionPatterns.
• Implizite Erkennung von Antworten (wenn ein Nutzer direkt auf eine Nachricht des Bots antwortet).

Mit dem Befehl /activation kannst du das Verhalten für die aktuelle Session ändern. Dieser Befehl ist für Owner reserviert:

• /activation mention
• /activation always

Beachte, dass /activation nur den Session-Status aktualisiert und nicht die globale Konfiguration ändert.

Personal-number und self-chat behavior

Wenn du deine eigene Nummer in allowFrom einträgst, werden spezielle Schutzmaßnahmen für den Self-Chat aktiv:

• Lesebestätigungen (read receipts) werden für Self-Chat-Interaktionen übersprungen.
• Die Mention-JID-Erkennung wird ignoriert, damit du dich nicht versehentlich selbst triggerst.
• Falls messages.responsePrefix nicht gesetzt ist, nutzen Self-Chat-Antworten standardmäßig [{identity.name}] oder [openclaw].

Fehlerbehebung

• Bot antwortet nicht in DMs: Prüfe, ob dmPolicy auf disabled steht oder ob deine Nummer in der allowFrom Liste fehlt.
• Bot reagiert in Gruppen nicht auf jede Nachricht: Das ist das Standardverhalten. Nutze den Befehl /activation always, um die Mention-Pflicht für die aktuelle Session aufzuheben.
• Regex für Mentions greift nicht: Überprüfe die mentionPatterns in deiner Konfiguration. Der Fallback liegt bei messages.groupChat.mentionPatterns.
• Eigene Nachrichten triggern den Bot nicht: Das ist ein gewolltes Verhalten im Self-Chat, um Feedback-Loops zu verhindern.

Hast du Fragen zur Einrichtung? Nutze den AI Setup Assistant.

Nächste Schritte

• Messaging Configuration
• Identity Setup
• Agent Configuration

Kennst du das Problem? Du versuchst einen Bot zu bauen, aber jede eingehende Nachricht sieht anders aus. Mal ist es ein Bild, mal ein Standort und mal eine Antwort auf eine Nachricht von vor drei Tagen. Ohne eine einheitliche Struktur verbringst du mehr Zeit mit dem Parsen von Daten als mit der eigentlichen Logik.

Wenn die Datenformate deiner Messaging-Kanäle ständig variieren, wird der Code schnell unübersichtlich. Du brauchst ein System, das die Nachrichten normalisiert, damit dein Bot immer weiß, worauf er sich bezieht – egal ob Text, Media oder Gruppen-Chat-Historie.

Voraussetzungen

• Einen aktiven WhatsApp Channel
• Zugriff auf deine Konfigurationsdateien (für History- und Read-Receipt-Einstellungen)

Schnellstart

In weniger als 5 Minuten hast du die Kontrolle über deine eingehenden Nachrichten. Das System verpackt jede WhatsApp-Nachricht in einen standardisierten Inbound Envelope.

Eingehende Nachrichten werden so normalisiert, dass du dich nicht um die speziellen WhatsApp-Datenstrukturen kümmern musst. Wenn ein Nutzer auf eine Nachricht antwortet, wird der Kontext automatisch in diesem Format angehängt:

[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]

Zusätzlich werden Metadaten-Felder wie ReplyToId, ReplyToBody, ReplyToSender und die JID/E.164 des Absenders befüllt, sofern sie verfügbar sind.

Media Placeholders und Datenextraktion

Bilder oder Dokumente ohne Text sind oft schwer zu verarbeiten. Das System ersetzt reine Media-Nachrichten durch eindeutige Placeholder. So sieht dein Bot sofort, was geschickt wurde:

• <media:image>
• <media:video>
• <media:audio>
• <media:document>
• <media:sticker>

Standortdaten und Kontakt-Payloads werden ebenfalls in einen Text-Kontext umgewandelt, bevor sie an deinen Bot weitergeleitet werden. Das spart dir das manuelle Extrahieren aus komplexen JSON-Objekten.

Gruppen-Historie nutzen

In Gruppen kann es passieren, dass Nachrichten ungelesen bleiben, bis der Bot getriggert wird. Du kannst diese Nachrichten puffern und als Kontext injizieren lassen.

Standardmäßig liegt das Limit bei 50 Nachrichten. Du kannst das in deiner Config anpassen:

• Config-Pfad: channels.whatsapp.historyLimit
• Fallback: messages.groupChat.historyLimit
• Deaktivieren: Setze den Wert auf 0

Um den Überblick zu behalten, werden Marker in den Text eingefügt:

• [Chat messages since your last reply - for context]
• [Current message - respond to this]

Read Receipts konfigurieren

Standardmäßig sendet das System Read Receipts für akzeptierte WhatsApp-Nachrichten. Wenn du das nicht möchtest, kannst du es global oder pro Account deaktivieren.

Global deaktivieren:

{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}

Override für einzelne Accounts:

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  }
}

Fehlerbehebung

Read Receipts werden nicht gesendet

Überprüfe, ob es sich um einen “Self-Chat” handelt (Nachrichten an dich selbst). Hier werden Read Receipts automatisch übersprungen, auch wenn sie global aktiviert sind.

Fehlender Kontext in Gruppen

Wenn keine Historie angezeigt wird, prüfe, ob channels.whatsapp.historyLimit versehentlich auf 0 gesetzt wurde. Stelle sicher, dass der Bot die entsprechenden Berechtigungen hat, um Nachrichten in der Gruppe zu lesen.

Hast du Fragen zur Einrichtung? Nutze unseren AI Setup Assistant.

Nächste Schritte

• WhatsApp Channel Setup
• Handling Media Attachments
• Webhooks und Callbacks
• Configuration Reference

Es ist frustrierend, wenn automatisierte WhatsApp-Nachrichten einfach abgeschnitten werden oder Media-Uploads ohne klare Fehlermeldung im Nichts verschwinden. Wenn du Bots baust, die zuverlässig mit Usern kommunizieren sollen, musst du das Chunking und die Media-Limits präzise kontrollieren, um eine gute User Experience sicherzustellen.

Hier erfährst du, wie du den Nachrichtenfluss steuerst und sicherstellst, dass deine Inhalte korrekt ankommen.

Voraussetzungen

• Zugriff auf die Konfiguration unter channels.whatsapp
• Installierte Openclaw CLI für das Account-Management
• Bestehende WhatsApp-Account-Anbindung

Schnellstart

In nur 5 Minuten optimierst du deine Delivery-Einstellungen. Füge die ackReaction zu deiner Konfiguration hinzu, um Usern sofortiges Feedback zu geben, sobald eine Nachricht eingeht:

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // options: always | mentions | never
      },
    },
  },
}

Diese Reaktion wird sofort gesendet, nachdem die Nachricht akzeptiert wurde, noch bevor der Agent eine Antwort generiert.

Text Chunking

WhatsApp hat Limits für die Nachrichtenlänge. Du kannst steuern, wie lange Texte aufgeteilt werden:

• Default Limit: channels.whatsapp.textChunkLimit = 4000
• Chunk Mode: Wähle zwischen length oder newline.
• Der newline Modus bevorzugt Absätze (Leerzeilen) für die Trennung. Wenn das nicht möglich ist, wird auf das zeichenbasierte Chunking zurückgegriffen.

Outbound Media Verhalten

Das Gateway unterstützt verschiedene Media-Typen und optimiert diese für die Plattform:

• Unterstützte Typen: Image, Video, Audio (PTT Voice-Note) und Dokumente.
• Audio-Optimierung: audio/ogg wird automatisch in audio/ogg; codecs=opus umgeschrieben, um die Kompatibilität mit Voice-Notes zu garantieren.
• GIFs: Animierte GIFs werden unterstützt, wenn du gifPlayback: true beim Senden von Videos setzt.
• Captions: Bei Multi-Media Payloads wird die Caption automatisch auf das erste Element angewendet.
• Quellen: Du kannst HTTP(S), file:// oder lokale Pfade als Media-Quelle nutzen.

Media Limits und Fallbacks

Um Fehler beim Versand zu vermeiden, gelten spezifische Limits und automatische Optimierungen:

• Inbound Limit: Eingehende Medien werden bis maximal channels.whatsapp.mediaMaxMb (Standard: 50) gespeichert.
• Outbound Limit: Für Auto-Replies liegt das Limit bei agents.defaults.mediaMaxMb (Standard: 5MB).
• Optimierung: Bilder werden automatisch in Größe und Qualität angepasst, um in diese Limits zu passen.
• Fallback: Schlägt ein Media-Versand fehl, wird eine Text-Warnung gesendet, anstatt die Antwort lautlos zu verwerfen.

Multi-Account und Credentials

Wenn du mehrere Accounts verwaltest, ist die Struktur der Credentials entscheidend:

• Account-Auswahl: Die IDs werden aus channels.whatsapp.accounts gezogen. Standardmäßig wird der Account default genutzt, ansonsten der erste konfigurierte Account (sortiert).
• Pfad: Credentials liegen unter ~/.openclaw/credentials/whatsapp/<accountId>/creds.json.
• Legacy Support: Alte Pfade in ~/.openclaw/credentials/ werden weiterhin für Default-Account-Flows erkannt und migriert.

Logout

Um die Authentifizierung für einen Account aufzuheben, nutzt du die CLI:

openclaw channels logout --channel whatsapp [--account <id>]

Dabei werden Baileys-Auth-Dateien gelöscht, während oauth.json in Legacy-Verzeichnissen erhalten bleibt.

Tools und Config Writes

Deine Agenten können direkt mit WhatsApp interagieren:

• Tools: Das Tool-Set enthält die react Action für WhatsApp.
• Action Gates: Du kannst Funktionen über channels.whatsapp.actions.reactions und channels.whatsapp.actions.polls steuern.
• Config Writes: Vom Channel initiierte Konfigurationsänderungen sind standardmäßig aktiv (deaktivierbar über channels.whatsapp.configWrites=false).

Fehlerbehebung

• Reaktions-Fehler: Wenn ackReaction fehlschlägt, wird dies geloggt. Der Fehler blockiert jedoch nicht die Zustellung der eigentlichen Antwort.
• Gruppen-Reaktionen: Wenn du im Modus mentions keine Reaktionen erhältst, prüfe, ob der Agent korrekt erwähnt wurde. Nutze den Modus always, um diese Prüfung zu umgehen.

Hast du Fragen zur Einrichtung? Nutze den AI Setup Assistant.

Nächste Schritte

• WhatsApp Account Setup
• Agent Tool Configuration
• Handling Inbound Events
• CLI Command Reference

Kennst du das? Du hast alles eingerichtet, aber die Nachrichten gehen einfach nicht raus oder die Verbindung bricht ständig ab. Debugging von Gateways kann nervig sein, besonders wenn man im Dunkeln tappt und nicht weiß, ob es am Token, der Runtime oder der Konfiguration liegt.

Hier erfährst du, wie du die häufigsten Probleme schnell identifizierst und behebst, damit dein Setup stabil bleibt.

Voraussetzungen

Bevor du startest, stelle sicher, dass du folgende Dinge bereit hast (wie in der Dokumentation beschrieben):

• Die installierte CLI (openclaw)
• Node.js als Runtime (vermeide Bun für WhatsApp/Telegram)
• Zugriff auf deine Konfigurationsdateien

Schnellstart

Wenn es schnell gehen muss, ist dies der 5-Minuten-Pfad, um den Status zu prüfen:

1. Führe openclaw channels status aus, um den aktuellen Verbindungsstatus zu sehen.
2. Falls der Account nicht verknüpft ist, nutze openclaw channels login --channel whatsapp.
3. Überprüfe die Live-Logs mit openclaw logs --follow, um Fehler in Echtzeit zu sehen.

Fehlerbehebung

Hier sind die Lösungen für die Probleme, die in der Praxis am häufigsten auftreten.

Nicht verknüpft (QR erforderlich)

Symptom: Die Channel-Statusberichte melden “not linked”.

Fix: Du musst dich neu authentifizieren. Nutze diese Befehle in deiner CLI:

openclaw channels login --channel whatsapp
openclaw channels status

Verknüpft, aber getrennt / Reconnect-Schleife

Symptom: Dein Account wird als verknüpft angezeigt, verliert aber ständig die Verbindung oder versucht sich dauerhaft neu zu verbinden.

Fix: Nutze das integrierte Diagnose-Tool und schau dir die Logs an:

openclaw doctor
openclaw logs --follow

Falls das Problem bestehen bleibt, verknüpfe den Account mit channels login neu.

Kein aktiver Listener beim Senden

Symptom: Outbound-Senden schlägt sofort fehl, wenn kein aktiver Gateway-Listener für den Zielaccount existiert.

Fix: Stelle sicher, dass das Gateway tatsächlich läuft und der spezifische Account korrekt verknüpft ist. Ohne aktiven Listener können keine Nachrichten geroutet werden.

Gruppennachrichten werden unerwartet ignoriert

Falls Nachrichten in Gruppen nicht verarbeitet werden, solltest du deine Konfiguration in dieser Reihenfolge prüfen:

• groupPolicy
• groupAllowFrom / allowFrom
• groups Allowlist-Einträge
• Mention-Gating (requireMention + Mention-Patterns)

Bun Runtime Warnung

Wichtig: Nutze für das WhatsApp Gateway Node.js. Bun ist als inkompatibel für einen stabilen Betrieb des WhatsApp- oder Telegram-Gateways markiert.

Configuration reference pointers

Wenn du tiefere Anpassungen vornehmen willst, findest du hier die wichtigsten Referenzpunkte:

Hauptreferenz:

• Configuration reference - WhatsApp

Wichtige WhatsApp-Felder:

• Access: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• Delivery: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction
• Multi-Account: accounts.<id>.enabled, accounts.<id>.authDir, Account-Level Overrides
• Operations: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
• Session-Verhalten: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

Du hast noch Fragen oder ein spezifisches Problem? Nutze den AI Setup Assistant für schnelle Hilfe.

Nächste Schritte

• Pairing
• Channel routing
• Troubleshooting