Vollstaendige Anleitung zur OpenClaw WhatsApp-Integration

Ueberblick

Die WhatsApp-Integration ermoeglicht es Ihnen, direkt ueber WhatsApp mit Ihrem OpenClaw KI-Assistenten zu chatten. OpenClaw verwendet WhatsApp Web via Baileys -- das Gateway verwaltet die Sitzung(en) und die gesamte Kommunikation. Sie verknuepfen Ihr WhatsApp-Konto aehnlich wie WhatsApp Web in einem Browser.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Folgendes vorhanden ist:

• OpenClaw installiert und das Gateway laeuft
• Ein WhatsApp-Konto mit einer echten Mobilfunknummer (VoIP- und virtuelle Nummern werden von WhatsApp in der Regel blockiert)
• Node.js Runtime (Bun wird nicht empfohlen -- WhatsApp/Baileys ist unter Bun unzuverlaessig)

Eine Telefonnummer beschaffen

WhatsApp benoetigt eine echte Mobilfunknummer zur Verifizierung. Es werden zwei Modi unterstuetzt:

Dedizierte Nummer (Empfohlen)

Verwenden Sie eine separate Telefonnummer fuer OpenClaw. Dies bietet die beste Nutzererfahrung mit sauberem Routing und ohne Self-Chat-Eigenheiten. Das ideale Setup ist ein Ersatz-/altes Android-Telefon + eSIM -- lassen Sie es am WLAN und Strom, und verknuepfen Sie es per QR-Code.

Tipps zur Nummernbeschaffung:

• Lokale eSIM von Ihrem Mobilfunkanbieter (am zuverlaessigsten)
• Prepaid-SIM -- guenstig, muss nur eine Verifizierungs-SMS empfangen
• Vermeiden: TextNow, Google Voice, die meisten "kostenlose SMS"-Dienste -- WhatsApp blockiert diese aggressiv

Die Nummer muss nur eine einzige Verifizierungs-SMS empfangen. Danach bleiben WhatsApp Web-Sitzungen ueber creds.json bestehen.

Tipp: Sie koennen WhatsApp Business auf demselben Geraet mit einer anderen Nummer verwenden. Ideal, um Ihr persoenliches WhatsApp getrennt zu halten -- installieren Sie WhatsApp Business und registrieren Sie die OpenClaw-Nummer dort.

Persoenliche Nummer (Ausweichloesung)

Schnelle Ausweichloesung: Betreiben Sie OpenClaw mit Ihrer eigenen Nummer. Schreiben Sie sich selbst (WhatsApp "Nachricht an mich") zum Testen, damit Sie keine Kontakte zuspammen. In diesem Fall muessen Sie den Self-Chat-Modus aktivieren.

Schritt 1: WhatsApp konfigurieren

Bearbeiten Sie Ihre ~/.openclaw/openclaw.json.

Konfiguration fuer dedizierte Nummer

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

Ersetzen Sie +15551234567 durch die Telefonnummer(n), die mit dem Assistenten chatten duerfen (E.164-Format).

Konfiguration fuer persoenliche Nummer (Self-Chat-Modus)

{
  "whatsapp": {
    "selfChatMode": true,
    "dmPolicy": "allowlist",
    "allowFrom": ["+15551234567"]
  }
}

Im Self-Chat-Modus geben Sie die Telefonnummer ein, von der Sie Nachrichten senden (der Eigentuemer/Absender), nicht die Assistenten-Nummer. Self-Chat-Antworten verwenden standardmaessig [{identity.name}] als Praefix (oder [openclaw] falls nicht gesetzt). Sie koennen dies ueber messages.responsePrefix anpassen oder auf "" setzen, um es zu entfernen.

Schritt 2: Ihr WhatsApp-Konto verknuepfen

Fuehren Sie den Login-Befehl aus:

openclaw channels login

Dies zeigt einen QR-Code in Ihrem Terminal an. Auf Ihrem Telefon:

1. Oeffnen Sie WhatsApp
2. Gehen Sie zu Einstellungen > Verknuepfte Geraete
3. Tippen Sie auf Geraet verknuepfen
4. Scannen Sie den QR-Code, der in Ihrem Terminal angezeigt wird

Fuer Multi-Account-Setups geben Sie das Konto an:

openclaw channels login --account <accountId>

Das Standardkonto (wenn --account weggelassen wird) ist default, falls vorhanden, andernfalls die erste konfigurierte Konto-ID (sortiert).

Schritt 3: Das Gateway starten

Starten Sie das OpenClaw-Gateway, um Nachrichten zu empfangen. Das Gateway verwaltet den Baileys-Socket und die Posteingangsschleife -- CLI und macOS-App kommunizieren mit dem Gateway, ohne Baileys direkt zu nutzen.

Wichtig: Ein aktiver Listener ist fuer ausgehende Nachrichten erforderlich; andernfalls schlagen Sendeversuche sofort fehl.

DM-Zugriffskontrolle

OpenClaw bietet drei DM-Richtlinien-Modi ueber channels.whatsapp.dmPolicy:

Pairing-Modus (Standard)

Unbekannte Absender erhalten einen zeitlich begrenzten Pairing-Code. Ihre Nachricht wird nicht verarbeitet, bis sie genehmigt wurde.

# Eine Pairing-Anfrage genehmigen
openclaw pairing approve whatsapp <code>

# Ausstehende Pairing-Anfragen auflisten
openclaw pairing list whatsapp

Pairing-Codes laufen nach 1 Stunde ab, und ausstehende Anfragen sind auf 3 pro Kanal begrenzt.

Allowlist-Modus

Nur Telefonnummern, die in channels.whatsapp.allowFrom aufgefuehrt sind, koennen Chats initiieren.

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567", "+15559876543"],
    },
  },
}

Offener Modus

Erfordert, dass channels.whatsapp.allowFrom den Wert "*" enthaelt.

Hinweis: Ihre verknuepfte WhatsApp-Nummer wird implizit als vertrauenswuerdig eingestuft -- Eigene Nachrichten umgehen die Pruefungen von dmPolicy und allowFrom.

Lesebestaetigungen

Standardmaessig markiert das Gateway eingehende WhatsApp-Nachrichten als gelesen (blaue Haekchen), sobald sie akzeptiert wurden.

Global deaktivieren:

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

Pro Konto deaktivieren:

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

Im Self-Chat-Modus werden Lesebestaetigungen immer uebersprungen.

Gruppenchat-Unterstuetzung

Gruppen werden dedizierten Sitzungen zugeordnet. Konfigurieren Sie das Gruppenverhalten mit:

• Gruppenrichtlinie: channels.whatsapp.groupPolicy -- open, disabled oder allowlist (Standard: allowlist)
• Aktivierungsmodi:
  • mention (Standard): erfordert @Erwaehnung oder Regex-Treffer
  • always: loest immer eine Antwort aus

Aktivierungsmodus umschalten mit einem Nur-Eigentuemer-Befehl (muss eine eigenstaendige Nachricht sein):

/activation mention
/activation always

Der Eigentuemer wird durch channels.whatsapp.allowFrom bestimmt (oder Ihre eigene E.164-Nummer, falls nicht gesetzt).

Gruppen-Verlaufskontext

Letzte unverarbeitete Nachrichten (Standard 50) werden automatisch als Kontext eingefuegt:

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

Jede Nachricht enthaelt ein Absender-Suffix: [from: Name (+E164)].

Gruppen-Metadaten (Betreff + Teilnehmer) werden 5 Minuten lang zwischengespeichert.

Bestaetigungs-Reaktionen

WhatsApp kann automatisch Emoji-Reaktionen auf eingehende Nachrichten beim Empfang senden und so sofortiges Feedback geben, bevor der Bot eine Antwort generiert.

{
  "whatsapp": {
    "ackReaction": {
      "emoji": "👀",
      "direct": true,
      "group": "mentions"
    }
  }
}

Optionen:

• emoji: Emoji, mit dem reagiert wird (z.B. "👀", "✅"). Leer oder weggelassen deaktiviert die Funktion.
• direct (Standard: true): Reaktionen in DM-Chats senden.
• group (Standard: "mentions"):
  • "always": Auf alle Gruppennachrichten reagieren
  • "mentions": Nur reagieren, wenn der Bot @erwaehnt wird
  • "never": Nie in Gruppen reagieren

Pro-Konto-Ueberschreibung:

{
  "whatsapp": {
    "accounts": {
      "work": {
        "ackReaction": {
          "emoji": "✅",
          "direct": false,
          "group": "always"
        }
      }
    }
  }
}

Reaktionen werden sofort beim Empfang gesendet, vor Tipp-Indikatoren oder Bot-Antworten. Fehler werden protokolliert, verhindern aber nicht, dass der Bot antwortet.

Nachrichtenverarbeitung

Eingehende Nachrichten

• Nachrichten kommen ueber Baileys messages.upsert-Events
• Status-/Broadcast-Chats werden ignoriert
• Direktchats verwenden das E.164-Format; Gruppen verwenden die Gruppen-JID
• Zitierter Antwortkontext wird immer angehaengt, um Gespraechskontext zu liefern
• Reine Mediennachrichten verwenden Platzhalter: <media:image|video|audio|document|sticker>

Ausgehende Nachrichten

• Text wird standardmaessig in 4.000 Zeichen aufgeteilt (konfigurierbar ueber channels.whatsapp.textChunkLimit)
• Optionale Zeilenumbruch-Aufteilung: Setzen Sie channels.whatsapp.chunkMode="newline", um vor der Laengenaufteilung an Absatzgrenzen zu teilen
• Unterstuetzte Medientypen: Bild, Video, Audio, Dokument
• Audio wird als Sprachnachricht (PTT) gesendet. Beste Ergebnisse mit OGG/Opus-Format
• Bildunterschrift nur beim ersten Medienelement
• Animierte GIFs: WhatsApp erwartet MP4 mit gifPlayback: true fuer Inline-Schleifen

Medienlimits

• Eingehende Medien-Speichergrenze: 50 MB (konfigurierbar ueber channels.whatsapp.mediaMaxMb)
• Ausgehende Mediengrenze: 5 MB pro Element (konfigurierbar ueber agents.defaults.mediaMaxMb)
• Bilder werden automatisch zu JPEG optimiert, wenn unter dem Limit (Groessenanpassung + Qualitaetsstufen)
• Uebergrosse Medien fuehren zu einem Fehler; die Medienantwort faellt auf eine Textwarnung zurueck

Anmeldedaten & Speicher

• Anmeldedaten gespeichert unter: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Automatische Sicherung unter creds.json.bak (wird bei Beschaedigung wiederhergestellt)
• Abmelden: openclaw channels logout (oder --account <id>) loescht den WhatsApp-Authentifizierungsstatus, behaelt aber die gemeinsame oauth.json

Multi-Account-Unterstuetzung

Mehrere WhatsApp-Konten koennen in einem einzigen Gateway-Prozess laufen. Verwenden Sie Konto-Bezeichner in der Konfiguration:

{
  channels: {
    whatsapp: {
      accounts: {
        personal: { /* Pro-Konto-Einstellungen */ },
        work: { /* Pro-Konto-Einstellungen */ },
      },
    },
  },
}

Pro-Konto-Einstellungen unterstuetzen Ueberschreibungen fuer sendReadReceipts, ackReaction, mediaMaxMb, historyLimit und mehr.

Warum nicht Twilio / WhatsApp Business API?

Fruehe OpenClaw-Builds unterstuetzten Twilios WhatsApp Business-Integration, aber diese wurde entfernt, weil:

• WhatsApp Business-Nummern schlecht zu einem persoenlichen Assistenten passen
• Meta ein 24-Stunden-Antwortfenster erzwingt -- wenn Sie in den letzten 24 Stunden nicht geantwortet haben, kann die Business-Nummer keine neuen Nachrichten initiieren
• Hohes Nachrichtenaufkommen oder "gespraechiger" Gebrauch aggressives Blocking ausloest, da Business-Konten nicht fuer persoenliche Assistenten-Nutzung konzipiert sind
• Ergebnis: unzuverlaessige Zustellung und haeufige Sperren

Konfigurations-Kurzreferenz

| Config Key | Beschreibung | |---|---| | channels.whatsapp.dmPolicy | DM-Richtlinie: pairing / allowlist / open / disabled | | channels.whatsapp.selfChatMode | Fuer persoenliche Nummern-Einrichtung aktivieren | | channels.whatsapp.allowFrom | DM-Allowlist (E.164-Telefonnummern) | | channels.whatsapp.sendReadReceipts | Automatische Lesebestaetigungen (Standard: true) | | channels.whatsapp.ackReaction | Automatische Reaktion bei Nachrichtenempfang | | channels.whatsapp.groupPolicy | Gruppenrichtlinie: open / disabled / allowlist | | channels.whatsapp.textChunkLimit | Ausgehende Text-Aufteilungsgroesse (Standard: 4000) | | channels.whatsapp.mediaMaxMb | Eingehende Mediengrenze (Standard: 50 MB) | | channels.whatsapp.configWrites | Konfigurationsaenderungen ueber /config-Befehl erlauben | | agents.defaults.mediaMaxMb | Ausgehende Mediengrenze (Standard: 5 MB) |

Fehlerbehebung

Nicht verknuepft / QR-Login erforderlich

Symptom: channels status zeigt linked: false oder warnt "Not linked".

Loesung: Fuehren Sie openclaw channels login auf dem Gateway-Host aus und scannen Sie den QR-Code (WhatsApp > Einstellungen > Verknuepfte Geraete).

Verknuepft aber getrennt / Reconnect-Schleife

Symptom: channels status zeigt running, disconnected oder warnt "Linked but disconnected".

Loesung: Fuehren Sie openclaw doctor aus oder starten Sie das Gateway neu. Falls das Problem bestehen bleibt, verknuepfen Sie erneut ueber openclaw channels login und pruefen Sie openclaw logs --follow.

Bun-Runtime-Probleme

Bun wird nicht empfohlen. WhatsApp (Baileys) und Telegram sind unter Bun unzuverlaessig. Betreiben Sie das Gateway mit Node.js.

Reconnect-Verhalten

Das Gateway verwendet eine Backoff-Richtlinie (web.reconnect) mit konfigurierbaren Werten fuer initialMs, maxMs, factor, jitter und maxAttempts. Wenn die maximale Anzahl an Versuchen erreicht ist, wird die Web-Ueberwachung gestoppt (eingeschraenkter Modus). Ein abgemeldeter Socket stoppt und erfordert eine erneute Verknuepfung.

Naechste Schritte

• Telegram Integrationsanleitung
• Discord Integrationsanleitung
• Offizielle WhatsApp-Dokumentation