WhatsApp

Status: produktionsreif über WhatsApp Web (Baileys). Der Gateway verwaltet die verknüpfte(n) Sitzung(en); es gibt keinen separaten Twilio-WhatsApp-Kanal.

Installation

openclaw onboard und openclaw channels add --channel whatsapp fordern Sie bei der ersten Auswahl zur Installation des Plugins auf; openclaw channels login --channel whatsapp bietet denselben Installationsablauf an, wenn das Plugin fehlt. Entwicklungs-Checkouts verwenden den lokalen Plugin-Pfad; stabile/Beta-Installationen installieren zuerst @openclaw/whatsapp aus ClawHub und greifen ersatzweise auf npm zurück. Die WhatsApp-Laufzeit wird außerhalb des zentralen OpenClaw-npm-Pakets ausgeliefert, sodass ihre Laufzeitabhängigkeiten beim externen Plugin verbleiben. Manuelle Installation:

openclaw plugins install clawhub:@openclaw/whatsapp

Verwenden Sie das reine npm-Paket (@openclaw/whatsapp) nur als Registry-Ausweichlösung; fixieren Sie eine exakte Version nur für eine reproduzierbare Installation.

Schnelleinrichtung

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

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-authopenclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsappopenclaw pairing approve whatsapp <CODE>

Bereitstellungsmuster

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

Laufzeitmodell

• Der Gateway verwaltet den WhatsApp-Socket und die Schleife für erneute Verbindungen.
• Ein Watchdog überwacht unabhängig voneinander zwei Signale: die rohe WhatsApp-Web-Transportaktivität und die Aktivität von Anwendungsnachrichten. Eine ruhige, aber verbundene Sitzung wird nicht allein deshalb neu gestartet, weil kürzlich keine Nachricht eingegangen ist; eine erneute Verbindung wird nur erzwungen, wenn für ein festes internes Zeitfenster (nicht benutzerkonfigurierbar) keine Transport-Frames mehr eingehen oder Anwendungsnachrichten länger als das Vierfache des normalen Nachrichten-Timeouts ausbleiben. Direkt nach einer erneuten Verbindung einer kürzlich aktiven Sitzung verwendet dieses erste Zeitfenster anstelle des vierfachen Zeitfensters den kürzeren normalen Nachrichten-Timeout. OpenClaw kann automatisch auf Offline-Nachrichten antworten, die Baileys während dieser erneuten Verbindung frühzeitig zustellt, begrenzt durch die Lebensdauer der Deduplizierung eingehender Nachrichten-IDs; beim ersten Start bleibt der kurze Schutz vor veraltetem Verlauf aktiv.
• Die Socket-Zeitvorgaben von Baileys werden explizit unter web.whatsapp.* festgelegt: keepAliveIntervalMs (Intervall für Anwendungs-Pings), connectTimeoutMs (Timeout für den Verbindungsaufbau), defaultQueryTimeoutMs (Wartezeiten für Baileys-Abfragen sowie OpenClaws Timeouts für ausgehendes Senden/Präsenz und eingehende Lesebestätigungen).
• Ausgehende Sendungen erfordern einen aktiven WhatsApp-Listener für das Zielkonto; andernfalls schlagen sie sofort fehl.
• Gruppensendungen fügen native Erwähnungsmetadaten für Tokens im Format @+<digits> und @<digits> hinzu (in Texten und Medienbeschriftungen), wenn das Token mit den aktuellen Teilnehmermetadaten übereinstimmt; dies gilt auch für LID-basierte Gruppen.
• Status- und Broadcast-Chats (@status, @broadcast) werden ignoriert.
• Direktchats verwenden die DM-Sitzungsregeln (session.dmScope; der Standardwert main fasst DMs in der Hauptsitzung des Agenten zusammen). Gruppensitzungen sind pro JID isoliert (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp-Kanäle/Newsletter können über ihre native @newsletter-JID explizite ausgehende Ziele sein und verwenden Kanal-Sitzungsmetadaten (agent:<agentId>:whatsapp:channel:<jid>) anstelle der DM-Semantik.
• Der WhatsApp-Web-Transport berücksichtigt die standardmäßigen Proxy-Umgebungsvariablen auf dem Gateway-Host (HTTPS_PROXY, HTTP_PROXY, NO_PROXY sowie Varianten in Kleinschreibung). Bevorzugen Sie die Proxy-Konfiguration auf Host-Ebene gegenüber kanalspezifischen Einstellungen.
• Wenn messages.removeAckAfterReply aktiviert ist, entfernt OpenClaw die Bestätigungsreaktion, sobald eine sichtbare Antwort zugestellt wurde.

Aktuell anfragende Person mit MeowCaller anrufen (experimentell)

Das Plugin kann whatsapp_call in von WhatsApp ausgehenden Agenteninteraktionen bereitstellen. Es verwendet MeowCaller, um einen WhatsApp-Sprachanruf an die aktuell autorisierte anfragende Person zu tätigen und nach der Annahme eine OpenClaw-TTS-Nachricht abzuspielen. Das Werkzeug besitzt keinen Parameter für die Zielnummer, sodass eine Eingabeaufforderung den Anruf nicht umleiten kann. Standardmäßig deaktiviert.

{"channels": {"whatsapp": {  "actions": {    "calls": true  }}}}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.gitcd meowcallergit checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3fmkdir -p "$HOME/.local/bin"go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"mkdir -p "$state_dir"chmod 700 "$state_dir"meowcaller pair --store "$state_dir/wa-voip.db"

Einschränkungen: nur ausgehende Eins-zu-eins-Audioanrufe, keine beliebigen Zielnummern, keine gemeinsame Authentifizierung mit der Chatverbindung, keine Selbstanrufe im Modus mit persönlicher Nummer/Selbstchat, synthetisiertes Audio auf 60 Sekunden begrenzt, keine Empfangsbestätigung für die Hörbarkeit auf dem Mobilgerät über den Abschluss von Annahme/Wiedergabe/Auflegen durch MeowCaller hinaus, und OpenClaw beendet den Begleitprozess nach einem begrenzten Zeitfenster von 115–175 Sekunden (einschließlich der Verbindungs-, Annahme-, Wiedergabe- und Beendigungsphasen von MeowCaller).

Genehmigungsaufforderungen

WhatsApp kann Genehmigungsaufforderungen für Ausführungen und Plugins als 👍/👎-Reaktionen darstellen, gesteuert durch die übergeordnete Konfiguration für die Weiterleitung von Genehmigungen:

{  approvals: {    exec: {      enabled: true,      mode: "session",    },    plugin: {      enabled: true,      mode: "targets",      targets: [{ channel: "whatsapp", to: "+15551234567" }],    },  },}

approvals.exec und approvals.plugin sind unabhängig voneinander; die Aktivierung von WhatsApp als Kanal verknüpft lediglich den Transport und sendet nichts, sofern die entsprechende Genehmigungsfamilie nicht aktiviert und dorthin geroutet wird. Der Sitzungsmodus stellt native Emoji-Genehmigungen nur für Genehmigungen zu, die aus WhatsApp stammen. Der Zielmodus verwendet die gemeinsame Weiterleitungspipeline für explizite Ziele und erzeugt keine separate Verteilung an die DMs der Genehmigenden.

Für WhatsApp-Genehmigungsreaktionen müssen Genehmigende explizit in allowFrom (oder "*") aufgeführt sein. defaultTo legt gewöhnliche Standardnachrichtenziele fest, keine Liste der Genehmigenden. Manuelle /approve-Befehle durchlaufen weiterhin den normalen WhatsApp-Pfad zur Absenderautorisierung, bevor die Genehmigung aufgelöst wird.

Plugin-Hooks und Datenschutz

Eingehende WhatsApp-Nachrichten können persönliche Inhalte, Telefonnummern, Gruppenkennungen, Absendernamen und Felder zur Sitzungskorrelation enthalten. WhatsApp überträgt Nutzdaten des eingehenden Hooks message_received nur dann an Plugins, wenn Sie dies ausdrücklich aktivieren:

{  channels: {    whatsapp: {      pluginHooks: {        messageReceived: true,      },    },  },}

Beschränken Sie die Aktivierung auf ein Konto unter channels.whatsapp.accounts.<id>.pluginHooks.messageReceived. Aktivieren Sie dies nur für Plugins, denen Sie eingehende WhatsApp-Inhalte und Kennungen anvertrauen.

Zugriffskontrolle und Aktivierung

Konfigurierte ACP-Bindungen

WhatsApp unterstützt persistente ACP-Bindungen über das übergeordnete Array bindings[]:

{  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "direct", id: "+15555550123" },      },    },    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "group", id: "120363424282127706@g.us" },      },    },  ],}

Direktchats werden anhand von E.164-Nummern zugeordnet; Gruppen anhand von WhatsApp-Gruppen-JIDs. Gruppenzulassungslisten, Absenderrichtlinie und Aktivierungsanforderungen für Erwähnungen werden ausgeführt, bevor OpenClaw sicherstellt, dass die gebundene ACP-Sitzung vorhanden ist. Eine übereinstimmende Bindung übernimmt die Route – Broadcast-Gruppen verteilen diesen Durchlauf nicht an gewöhnliche WhatsApp-Sitzungen.

Verhalten bei persönlicher Nummer und Selbstchat

Wenn die verknüpfte eigene Nummer auch in allowFrom enthalten ist, werden Schutzmaßnahmen für Selbstchats aktiviert: Lesebestätigungen werden bei Selbstchat-Durchläufen übersprungen, das automatische Auslösen durch Erwähnungs-JIDs, durch das Sie sich selbst benachrichtigen würden, wird ignoriert, und Antworten erhalten standardmäßig das Präfix [{identity.name}] (oder [openclaw]), wenn messages.responsePrefix nicht gesetzt ist.

Nachrichtennormalisierung und Kontext

[Antwort auf <sender> id:<stanzaId>]<zitierter Inhalt oder Medienplatzhalter>[/Antwort]

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

Zustellung, Aufteilung und Medien

Zitieren von Antworten

channels.whatsapp.replyToMode steuert das native Zitieren von Antworten (ausgehende Antworten zitieren sichtbar die eingehende Nachricht):

Kontospezifische Überschreibung: channels.whatsapp.accounts.<id>.replyToMode.

{ channels: { whatsapp: { replyToMode: "first" } } }

Reaktionsstufe

channels.whatsapp.reactionLevel steuert, wie umfassend der Agent Emoji-Reaktionen verwendet:

Kontospezifische Überschreibung: channels.whatsapp.accounts.<id>.reactionLevel.

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

Bestätigungsreaktionen

channels.whatsapp.ackReaction sendet beim Eingang sofort eine Reaktion, die durch reactionLevel eingeschränkt wird (bei "off" unterdrückt):

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

Hinweise: Wird unmittelbar gesendet, nachdem die eingehende Nachricht akzeptiert wurde (vor der Antwort); wenn ackReaction ohne emoji vorhanden ist, verwendet WhatsApp das Identitäts-Emoji des zuständigen Agenten und greift ersatzweise auf „👀“ zurück (ackReaction auslassen oder emoji: "" festlegen, um keine Bestätigung zu senden); Fehler werden protokolliert, blockieren die Zustellung der Antwort jedoch nicht; der Gruppenmodus mentions reagiert nur auf Durchläufe, die durch Erwähnungen ausgelöst wurden, während die Gruppenaktivierung always diese Prüfung umgeht; WhatsApp verwendet ausschließlich channels.whatsapp.ackReaction (das ältere messages.ackReaction gilt hier nicht).

Statusreaktionen während des Lebenszyklus

Setzen Sie messages.statusReactions.enabled: true, damit WhatsApp die Bestätigungsreaktion während eines Durchlaufs ersetzt, anstatt ein statisches Empfangs-Emoji beizubehalten, und dabei Status wie „in der Warteschlange“, „denkt nach“, „Werkzeugaktivität“, Compaction, „abgeschlossen“ und „Fehler“ durchläuft:

{  messages: {    statusReactions: {      enabled: true,      emojis: {        deploy: "🛫",        build: "🏗️",        concierge: "💁",      },    },  },}

Hinweise: channels.whatsapp.ackReaction steuert weiterhin die Zulässigkeit für Direktnachrichten und Gruppen; der Warteschlangenstatus verwendet dasselbe effektive Emoji wie einfache Bestätigungsreaktionen; WhatsApp verfügt pro Nachricht über einen Reaktionsplatz für den Bot, daher ersetzen Lebenszyklusaktualisierungen die aktuelle Reaktion direkt; messages.removeAckAfterReply: true entfernt die abschließende Statusreaktion nach der konfigurierten Haltezeit für Abschluss/Fehler; Kategorien für Werkzeug-Emojis umfassen tool, coding, web, deploy, build und concierge.

Mehrere Konten und Anmeldedaten

Tools, Aktionen und Konfigurationsschreibvorgänge

• Die Agent-Tool-Unterstützung umfasst die WhatsApp-Reaktionsaktion (react).
• Aktionsfreigaben: channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (vorhandene Aktionen haben standardmäßig den Wert true), channels.whatsapp.actions.calls (standardmäßig false, siehe MeowCaller weiter oben).
• Vom Kanal initiierte Konfigurationsschreibvorgänge sind standardmäßig aktiviert; deaktivieren Sie sie über channels.whatsapp.configWrites: false.

Fehlerbehebung

openclaw channels login --channel whatsappopenclaw channels status

{  web: {    whatsapp: {      keepAliveIntervalMs: 15000,      connectTimeoutMs: 60000,      defaultQueryTimeoutMs: 60000,    },  },}

openclaw channels status --probeopenclaw doctoropenclaw logs --followopenclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \  ~/.openclaw/credentials/whatsapp/<accountId>.bakopenclaw channels logout --channel whatsapp --account <accountId>openclaw channels login --channel whatsapp --account <accountId>

System-Prompts

WhatsApp unterstützt über die Zuordnungen groups und direct System-Prompts im Telegram-Stil für Gruppen und Direktchats.

Auflösung für Gruppennachrichten: Zuerst wird die wirksame groups-Zuordnung bestimmt — wenn das Konto einen eigenen groups-Schlüssel definiert, ersetzt dieser die groups-Zuordnung auf Stammebene vollständig (keine tiefe Zusammenführung). Die Prompt-Suche erfolgt anschließend in dieser einen resultierenden Zuordnung:

1. Gruppenspezifischer Prompt (groups["<groupId>"].systemPrompt): wird verwendet, wenn der Gruppeneintrag vorhanden und sein Schlüssel systemPrompt definiert ist. Eine leere Zeichenfolge ("") unterdrückt den Platzhalter und wendet keinen Prompt an.
2. Gruppenplatzhalter-Prompt (groups["*"].systemPrompt): wird verwendet, wenn der spezifische Gruppeneintrag fehlt oder ohne Schlüssel systemPrompt vorhanden ist.

Die Auflösung für Direktnachrichten folgt demselben Muster anhand der Zuordnung direct und direct["*"].

Unterschied zu Telegram: Telegram unterdrückt groups auf Stammebene für jedes Konto in einer Mehrkontoeinrichtung (selbst für Konten ohne eigenes groups), damit ein Bot keine Gruppennachrichten für Gruppen empfängt, denen er nicht angehört. WhatsApp wendet diesen Schutz nicht an — groups/direct auf Stammebene werden unabhängig von der Anzahl der Konten von jedem Konto ohne eigene Überschreibung übernommen. Definieren Sie in einer WhatsApp-Mehrkontoeinrichtung die vollständige Zuordnung ausdrücklich unter jedem Konto, wenn Sie kontospezifische Prompts wünschen.

Wichtige Verhaltensweisen:

• channels.whatsapp.groups dient sowohl als Konfigurationszuordnung pro Gruppe als auch als Positivliste für Gruppen auf Chat-Ebene. Sowohl auf Stamm- als auch auf Kontoebene bedeutet groups["*"], dass für diesen Geltungsbereich alle Gruppen zugelassen sind.
• Fügen Sie einen Platzhalter-systemPrompt nur hinzu, wenn für diesen Geltungsbereich ohnehin alle Gruppen zugelassen werden sollen. Wenn nur eine feste Gruppe von Gruppen-IDs zulässig bleiben soll, wiederholen Sie den Prompt für jeden ausdrücklich in die Positivliste aufgenommenen Eintrag, anstatt groups["*"] zu verwenden.
• Gruppenzulassung und Absenderautorisierung sind separate Prüfungen. groups["*"] erweitert die Menge der Gruppen, die von der Gruppenverarbeitung erfasst werden; dadurch wird nicht jeder Absender in diesen Gruppen autorisiert — dies wird weiterhin durch groupPolicy/groupAllowFrom gesteuert.
• channels.whatsapp.direct hat keine entsprechende Nebenwirkung für Direktnachrichten: direct["*"] stellt lediglich eine Standardkonfiguration bereit, nachdem eine Direktnachricht bereits durch dmPolicy zusammen mit allowFrom oder den Regeln des Kopplungsspeichers zugelassen wurde.

Beispiel:

{  channels: {    whatsapp: {      groups: {        // Nur verwenden, wenn alle Gruppen auf Stammebene zugelassen werden sollen.        // Gilt für alle Konten, die keine eigene groups-Zuordnung definieren.        "*": { systemPrompt: "Standard-Prompt für alle Gruppen." },      },      direct: {        // Gilt für alle Konten, die keine eigene direct-Zuordnung definieren.        "*": { systemPrompt: "Standard-Prompt für alle Direktchats." },      },      accounts: {        work: {          groups: {            // Dieses Konto definiert eigene Gruppen, daher werden die Gruppen auf            // Stammebene vollständig ersetzt. Um einen Platzhalter beizubehalten,            // definieren Sie "*" auch hier ausdrücklich.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Konzentrieren Sie sich auf das Projektmanagement.",            },            // Nur verwenden, wenn alle Gruppen in diesem Konto zugelassen werden sollen.            "*": { systemPrompt: "Standard-Prompt für Arbeitsgruppen." },          },          direct: {            // Dieses Konto definiert eine eigene direct-Zuordnung, daher werden die            // direct-Einträge auf Stammebene vollständig ersetzt. Um einen Platzhalter            // beizubehalten, definieren Sie "*" auch hier ausdrücklich.            "+15551234567": { systemPrompt: "Prompt für einen bestimmten Arbeits-Direktchat." },            "*": { systemPrompt: "Standard-Prompt für Arbeits-Direktchats." },          },        },      },    },  },}

Verweise zur Konfigurationsreferenz

Primäre Referenz: Konfigurationsreferenz – WhatsApp

Verwandte Themen

• Kopplung
• Gruppen
• Sicherheit
• Kanalweiterleitung
• Multi-Agent-Weiterleitung
• Fehlerbehebung