Vollstaendige Anleitung zur OpenClaw WhatsApp-Integration

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