WhatsApp (Web-Kanal)

Status: produktionsreif über WhatsApp Web (Baileys). Das Gateway besitzt verknüpfte Sitzung(en).

Installation (bei Bedarf)

Onboarding (openclaw onboard) und openclaw channels add --channel whatsapp fordern beim ersten Auswählen von WhatsApp zur Installation des WhatsApp-Plugins auf.
openclaw channels login --channel whatsapp bietet den Installationsablauf ebenfalls an, wenn das Plugin noch nicht vorhanden ist.
Dev-Kanal + Git-Checkout: standardmäßig der lokale Plugin-Pfad.
Stable/Beta: standardmäßig das npm-Paket @openclaw/whatsapp.

Die manuelle Installation bleibt verfügbar:

openclaw plugins install @openclaw/whatsapp

Kopplung

Die Standard-DM-Richtlinie ist Kopplung für unbekannte Absender.

Fehlerbehebung für Kanäle

Kanalübergreifende Diagnose- und Reparaturleitfäden.

Gateway-Konfiguration

Vollständige Kanal-Konfigurationsmuster und Beispiele.

Schnelleinrichtung

WhatsApp-Zugriffsrichtlinie konfigurieren

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

WhatsApp verknüpfen (QR)

openclaw channels login --channel whatsapp

Für ein bestimmtes Konto:

openclaw channels login --channel whatsapp --account work

Gateway starten

openclaw gateway

Erste Kopplungsanfrage genehmigen (bei Verwendung des Kopplungsmodus)

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Kopplungsanfragen laufen nach 1 Stunde ab. Ausstehende Anfragen sind auf 3 pro Kanal begrenzt.

OpenClaw empfiehlt, WhatsApp möglichst mit einer separaten Nummer zu betreiben. (Die Kanalmetadaten und der Einrichtungsablauf sind für dieses Setup optimiert, aber Setups mit persönlicher Nummer werden ebenfalls unterstützt.)

Bereitstellungsmuster

Dedizierte Nummer (empfohlen)

Dies ist der sauberste Betriebsmodus:

separate WhatsApp-Identität für OpenClaw
klarere DM-Allowlists und Routing-Grenzen
geringere Wahrscheinlichkeit von Verwirrung durch Selbst-Chats

Minimales Richtlinienmuster:

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

Fallback mit persönlicher Nummer

Das Onboarding unterstützt den Modus mit persönlicher Nummer und schreibt eine selbstchatfreundliche Basis:

dmPolicy: "allowlist"
allowFrom enthält Ihre persönliche Nummer
selfChatMode: true

Zur Laufzeit orientieren sich die Schutzmechanismen für Selbst-Chats an der verknüpften eigenen Nummer und allowFrom.

Kanalumfang nur für WhatsApp Web

Der Messaging-Plattform-Kanal basiert in der aktuellen Kanalarchitektur von OpenClaw auf WhatsApp Web (Baileys).Es gibt keinen separaten Twilio-WhatsApp-Messaging-Kanal in der integrierten Chat-Kanal-Registry.

Laufzeitmodell

Das Gateway besitzt den WhatsApp-Socket und die Wiederverbindungsschleife.
Ausgehendes Senden erfordert einen aktiven WhatsApp-Listener für das Zielkonto.
Status- und Broadcast-Chats werden ignoriert (@status, @broadcast).
Direktchats verwenden DM-Sitzungsregeln (session.dmScope; der Standard main führt DMs in die Hauptsitzung des Agent zusammen).
Gruppensitzungen sind isoliert (agent:<agentId>:whatsapp:group:<jid>).

Zugriffskontrolle und Aktivierung

DM-Richtlinie
Gruppenrichtlinie + Allowlists
Erwähnungen + /activation

channels.whatsapp.dmPolicy steuert den Zugriff auf Direktchats:

pairing (Standard)
allowlist
open (erfordert, dass allowFrom "*" enthält)
disabled

allowFrom akzeptiert Nummern im E.164-Stil (intern normalisiert).Multi-Account-Überschreibung: channels.whatsapp.accounts.<id>.dmPolicy (und allowFrom) haben für dieses Konto Vorrang vor kanalweiten Standards.Details zum Laufzeitverhalten:

Kopplungen werden im kanalbezogenen Allow-Store persistiert und mit konfiguriertem allowFrom zusammengeführt
wenn keine Allowlist konfiguriert ist, ist die verknüpfte eigene Nummer standardmäßig erlaubt
ausgehende fromMe-DMs werden nie automatisch gekoppelt

Der Gruppenzugriff hat zwei Ebenen:

Allowlist für Gruppenmitgliedschaft (channels.whatsapp.groups)
- wenn groups ausgelassen wird, kommen alle Gruppen infrage
- wenn groups vorhanden ist, wirkt es als Gruppen-Allowlist ("*" erlaubt)
Richtlinie für Gruppensender (channels.whatsapp.groupPolicy + groupAllowFrom)
- open: Sender-Allowlist wird umgangen
- allowlist: Sender muss groupAllowFrom entsprechen (oder *)
- disabled: blockiert alle eingehenden Gruppennachrichten

Fallback für die Sender-Allowlist:

wenn groupAllowFrom nicht gesetzt ist, greift die Laufzeit auf allowFrom zurück, falls verfügbar
Sender-Allowlists werden vor der Aktivierung durch Erwähnung/Antwort ausgewertet

Hinweis: Wenn überhaupt kein channels.whatsapp-Block vorhanden ist, ist der Laufzeit-Fallback für die Gruppenrichtlinie allowlist (mit einer Warnung im Log), selbst wenn channels.defaults.groupPolicy gesetzt ist.

Gruppenantworten erfordern standardmäßig eine Erwähnung.Die Erwähnungserkennung umfasst:

explizite WhatsApp-Erwähnungen der Bot-Identität
konfigurierte Regex-Muster für Erwähnungen (agents.list[].groupChat.mentionPatterns, Fallback messages.groupChat.mentionPatterns)
implizite Antwort-an-Bot-Erkennung (Antwortabsender entspricht der Bot-Identität)

Sicherheitshinweis:

Zitieren/Antworten erfüllt nur das Mention-Gating; es erteilt keine Senderautorisierung
bei groupPolicy: "allowlist" bleiben nicht allowlistete Absender blockiert, selbst wenn sie auf die Nachricht eines allowlisteten Benutzers antworten

Sitzungsbezogener Aktivierungsbefehl:

/activation mention
/activation always

activation aktualisiert den Sitzungszustand (nicht die globale Konfiguration). Es ist eigentümergeschützt.

Persönliche Nummer und Selbst-Chat-Verhalten

Wenn die verknüpfte eigene Nummer auch in allowFrom vorhanden ist, werden Schutzmechanismen für WhatsApp-Selbst-Chats aktiviert:

Lesebestätigungen für Selbst-Chat-Durchläufe überspringen
Auto-Trigger-Verhalten für Erwähnungs-JIDs ignorieren, das Sie sonst selbst anpingen würde
wenn messages.responsePrefix nicht gesetzt ist, verwenden Antworten in Selbst-Chats standardmäßig [{identity.name}] oder [openclaw]

Nachrichtennormalisierung und Kontext

Eingehender Envelope + Antwortkontext

Eingehende WhatsApp-Nachrichten werden in den gemeinsamen eingehenden Envelope verpackt.Wenn eine zitierte Antwort vorhanden ist, wird Kontext in dieser Form angehängt:

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

Metadatenfelder für Antworten werden ebenfalls befüllt, wenn verfügbar (ReplyToId, ReplyToBody, ReplyToSender, Sender-JID/E.164).

Medienplatzhalter und Extraktion von Standort/Kontakt

Eingehende Nachrichten nur mit Medien werden mit Platzhaltern wie diesen normalisiert:

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

Standort- und Kontakt-Nutzlasten werden vor dem Routing in textuellen Kontext normalisiert.

Einfügung ausstehender Gruppenhistorie

Für Gruppen können unverarbeitete Nachrichten gepuffert und als Kontext eingefügt werden, wenn der Bot schließlich ausgelöst wird.

Standardlimit: 50
Konfiguration: channels.whatsapp.historyLimit
Fallback: messages.groupChat.historyLimit
0 deaktiviert

Einfügungsmarkierungen:

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

Lesebestätigungen

Lesebestätigungen sind standardmäßig für akzeptierte eingehende WhatsApp-Nachrichten aktiviert.Global deaktivieren:

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

Überschreibung pro Konto:

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

Durchläufe in Selbst-Chats überspringen Lesebestätigungen auch dann, wenn sie global aktiviert sind.

Zustellung, Chunking und Medien

Text-Chunking

Standard-Chunk-Limit: channels.whatsapp.textChunkLimit = 4000
channels.whatsapp.chunkMode = "length" | "newline"
der Modus newline bevorzugt Absatzgrenzen (Leerzeilen) und greift dann auf längensicheres Chunking zurück

Verhalten ausgehender Medien

unterstützt Nutzlasten für Bild, Video, Audio (PTT-Sprachnachricht) und Dokument
audio/ogg wird für die Kompatibilität mit Sprachnachrichten zu audio/ogg; codecs=opus umgeschrieben
animierte GIF-Wiedergabe wird über gifPlayback: true bei Video-Sendungen unterstützt
Bildunterschriften werden beim Senden von Antwortnutzlasten mit mehreren Medien auf das erste Medienelement angewendet
Medienquelle kann HTTP(S), file:// oder lokale Pfade sein

Größenlimits für Medien und Fallback-Verhalten

Speicherlimit für eingehende Medien: channels.whatsapp.mediaMaxMb (Standard 50)
Sendelimit für ausgehende Medien: channels.whatsapp.mediaMaxMb (Standard 50)
Überschreibungen pro Konto verwenden channels.whatsapp.accounts.<accountId>.mediaMaxMb
Bilder werden automatisch optimiert (Größenänderung/Qualitätsdurchlauf), um die Limits einzuhalten
bei Fehlern beim Mediensenden sendet der Fallback für das erste Element eine Textwarnung, anstatt die Antwort stillschweigend zu verwerfen

Reaktionsstufe

channels.whatsapp.reactionLevel steuert, wie breit der Agent Emoji-Reaktionen auf WhatsApp verwendet:

Stufe	Bestätigungsreaktionen	Vom Agent initiierte Reaktionen	Beschreibung
`"off"`	Nein	Nein	Überhaupt keine Reaktionen
`"ack"`	Ja	Nein	Nur Bestätigungsreaktionen (Empfang vor Antwort)
`"minimal"`	Ja	Ja (zurückhaltend)	Bestätigung + Agent-Reaktionen mit zurückhaltender Anleitung
`"extensive"`	Ja	Ja (empfohlen)	Bestätigung + Agent-Reaktionen mit empfohlener Anleitung

Standard: "minimal". Überschreibungen pro Konto verwenden channels.whatsapp.accounts.<id>.reactionLevel.

{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

Bestätigungsreaktionen

WhatsApp unterstützt sofortige Bestätigungsreaktionen beim eingehenden Empfang über channels.whatsapp.ackReaction. Bestätigungsreaktionen werden durch reactionLevel gesteuert — sie werden unterdrückt, wenn reactionLevel "off" ist.

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

Verhaltenshinweise:

werden sofort gesendet, nachdem eingehende Nachrichten akzeptiert wurden (vor der Antwort)
Fehler werden protokolliert, blockieren aber die normale Antwortzustellung nicht
im Gruppenmodus mentions wird bei durch Erwähnung ausgelösten Durchläufen reagiert; die Gruppenaktivierung always wirkt dabei als Umgehung dieser Prüfung
WhatsApp verwendet channels.whatsapp.ackReaction (das veraltete messages.ackReaction wird hier nicht verwendet)

Multi-Account und Anmeldedaten

Kontoauswahl und Standards

Konto-IDs stammen aus channels.whatsapp.accounts
Standard-Kontoauswahl: default, wenn vorhanden, sonst die erste konfigurierte Konto-ID (sortiert)
Konto-IDs werden intern für die Suche normalisiert

Pfade für Anmeldedaten und Legacy-Kompatibilität

aktueller Auth-Pfad: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
Sicherungsdatei: creds.json.bak
veraltete Standard-Authentifizierung unter ~/.openclaw/credentials/ wird für Standardkonto-Abläufe weiterhin erkannt/migriert

Abmeldeverhalten

openclaw channels logout --channel whatsapp [--account <id>] löscht den WhatsApp-Authentifizierungszustand für dieses Konto.In veralteten Auth-Verzeichnissen bleibt oauth.json erhalten, während Baileys-Auth-Dateien entfernt werden.

Tools, Aktionen und Konfigurationsschreibvorgänge

Die Agent-Tool-Unterstützung umfasst die WhatsApp-Reaktionsaktion (react).
Aktions-Gates:
- channels.whatsapp.actions.reactions
- channels.whatsapp.actions.polls
Kanalinitiierte Konfigurationsschreibvorgänge sind standardmäßig aktiviert (deaktivieren über channels.whatsapp.configWrites=false).

Fehlerbehebung

Nicht verknüpft (QR erforderlich)

Symptom: Der Kanalstatus meldet nicht verknüpft.Korrektur:

openclaw channels login --channel whatsapp
openclaw channels status

Verknüpft, aber getrennt / Wiederverbindungsschleife

Symptom: Verknüpftes Konto mit wiederholten Verbindungsabbrüchen oder Wiederverbindungsversuchen.Korrektur:

openclaw doctor
openclaw logs --follow

Falls nötig, mit channels login erneut verknüpfen.

Kein aktiver Listener beim Senden

Ausgehende Sendungen schlagen sofort fehl, wenn für das Zielkonto kein aktiver Gateway-Listener vorhanden ist.Stellen Sie sicher, dass das Gateway läuft und das Konto verknüpft ist.

Gruppennachrichten werden unerwartet ignoriert

In dieser Reihenfolge prüfen:

groupPolicy
groupAllowFrom / allowFrom
Allowlist-Einträge in groups
Mention-Gating (requireMention + Erwähnungsmuster)
doppelte Schlüssel in openclaw.json (JSON5): spätere Einträge überschreiben frühere, daher pro Scope nur ein groupPolicy

Warnung zur Bun-Laufzeit

Die Gateway-Laufzeit für WhatsApp sollte Node verwenden. Bun ist als inkompatibel für einen stabilen Gateway-Betrieb von WhatsApp/Telegram gekennzeichnet.

Hinweise zur Konfigurationsreferenz

Primäre Referenz:

Konfigurationsreferenz - WhatsApp

Signalstarke WhatsApp-Felder:

Zugriff: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
Zustellung: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
Multi-Account: accounts.<id>.enabled, accounts.<id>.authDir, Überschreibungen auf Kontoebene
Betrieb: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
Sitzungsverhalten: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

Overview

Messaging platforms

Configuration

WhatsApp

WhatsApp (Web-Kanal)

Installation (bei Bedarf)

Kopplung

Fehlerbehebung für Kanäle

Gateway-Konfiguration

Schnelleinrichtung

Bereitstellungsmuster

Laufzeitmodell

Zugriffskontrolle und Aktivierung

Persönliche Nummer und Selbst-Chat-Verhalten

Nachrichtennormalisierung und Kontext

Zustellung, Chunking und Medien

Reaktionsstufe

Bestätigungsreaktionen

Multi-Account und Anmeldedaten

Tools, Aktionen und Konfigurationsschreibvorgänge

Fehlerbehebung

Hinweise zur Konfigurationsreferenz

Verwandt

Overview

Messaging platforms

Configuration

​WhatsApp (Web-Kanal)

​Installation (bei Bedarf)

Kopplung

Fehlerbehebung für Kanäle

Gateway-Konfiguration

​Schnelleinrichtung

​Bereitstellungsmuster

​Laufzeitmodell

​Zugriffskontrolle und Aktivierung

​Persönliche Nummer und Selbst-Chat-Verhalten

​Nachrichtennormalisierung und Kontext

​Zustellung, Chunking und Medien

​Reaktionsstufe

​Bestätigungsreaktionen

​Multi-Account und Anmeldedaten

​Tools, Aktionen und Konfigurationsschreibvorgänge

​Fehlerbehebung

​Hinweise zur Konfigurationsreferenz

​Verwandt

WhatsApp (Web-Kanal)

Installation (bei Bedarf)

Schnelleinrichtung

Bereitstellungsmuster

Laufzeitmodell

Zugriffskontrolle und Aktivierung

Persönliche Nummer und Selbst-Chat-Verhalten

Nachrichtennormalisierung und Kontext

Zustellung, Chunking und Medien

Reaktionsstufe

Bestätigungsreaktionen

Multi-Account und Anmeldedaten

Tools, Aktionen und Konfigurationsschreibvorgänge

Fehlerbehebung

Hinweise zur Konfigurationsreferenz

Verwandt