WhatsApp

Status: produktionsbereit ü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 zur Installation des Plugins auf, wenn Sie es zum ersten Mal auswählen; 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-Laufzeitumgebung wird außerhalb des zentralen OpenClaw-npm-Pakets ausgeliefert, daher verbleiben ihre Laufzeitabhängigkeiten beim externen Plugin. Manuelle Installation:

openclaw plugins install clawhub:@openclaw/whatsapp

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

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 Wiederverbindungsschleife.
• Ein Watchdog überwacht zwei Signale unabhängig voneinander: die rohe WhatsApp-Web-Transportaktivität und die Aktivität der Anwendungsnachrichten. Eine ruhige, aber verbundene Sitzung wird nicht neu gestartet, nur weil kürzlich keine Nachricht eingegangen ist; eine Wiederverbindung wird nur erzwungen, wenn für ein festes internes Zeitfenster (nicht vom Benutzer konfigurierbar) keine Transport-Frames mehr eingehen oder Anwendungsnachrichten länger als das Vierfache des normalen Nachrichten-Timeouts ausbleiben. Direkt nach einer Wiederverbindung für eine kürzlich aktive Sitzung verwendet dieses erste Zeitfenster statt des vierfachen Fensters den kürzeren normalen Nachrichten-Timeout. OpenClaw kann automatisch auf Offline-Nachrichten antworten, die Baileys früh während dieser Wiederverbindung zustellt, begrenzt durch die Lebensdauer der Deduplizierung eingehender Nachrichten-IDs; beim ersten Start bleibt die kurze Schutzfrist gegen veraltete Verlaufsnachrichten bestehen.
• Ausgehende Sendungen erfordern einen aktiven WhatsApp-Listener für das Zielkonto; andernfalls schlagen sie sofort fehl.
• Gruppensendungen fügen native Erwähnungsmetadaten für @+<digits>- und @<digits>-Token (in Text und Medienbeschriftungen) hinzu, wenn das Token mit aktuellen Teilnehmermetadaten übereinstimmt, einschließlich LID-basierter Gruppen.
• Status- und Broadcast-Chats (@status, @broadcast) werden ignoriert.
• Direktchats verwenden DM-Sitzungsregeln (session.dmScope; der Standardwert main führt DMs in der Hauptsitzung des Agenten zusammen). Gruppensitzungen werden pro JID isoliert (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters 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, Varianten in Kleinschreibung). Bevorzugen Sie eine Proxy-Konfiguration auf Hostebene gegenüber kanalspezifischen Einstellungen.

Aktuellen Anfragenden mit MeowCaller anrufen (experimentell)

Das Plugin kann whatsapp_call in von WhatsApp stammenden Agentendurchläufen bereitstellen. Es verwendet MeowCaller, um den aktuell autorisierten Anfragenden über WhatsApp anzurufen und nach der Annahme eine OpenClaw-TTS-Nachricht abzuspielen. Das Tool besitzt keinen Parameter für die Zielnummer, sodass ein Prompt 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: ausschließlich ausgehende Einzel-Audioanrufe, keine beliebigen Zielnummern, keine gemeinsame Authentifizierung mit der Chatverbindung, keine Selbstanrufe im Modus mit persönlicher Nummer bzw. Selbst-Chat, 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 (das die Verbindungs-, Annahme-, Wiedergabe- und Beendigungsphasen von MeowCaller abdeckt).

Genehmigungsaufforderungen

WhatsApp kann Ausführungs- und Plugin-Genehmigungsaufforderungen 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 weitergeleitet wird. Der Sitzungsmodus stellt native Emoji-Genehmigungen nur für Genehmigungen bereit, die aus WhatsApp stammen. Der Zielmodus verwendet die gemeinsame Weiterleitungspipeline für explizite Ziele und erzeugt keine separate Auffächerung auf Genehmiger-DMs.

WhatsApp-Genehmigungsreaktionen erfordern explizite Genehmiger in allowFrom (oder "*"). defaultTo legt gewöhnliche standardmäßige Nachrichtenziele fest, keine Genehmigerliste. Manuelle /approve-Befehle durchlaufen vor der Genehmigungsauflösung weiterhin den normalen WhatsApp-Autorisierungspfad für Absender.

Reaktionen auf Fragen

Bei einer ask_user-Aufforderung mit einer einzelnen nicht geheimen Einfachauswahlfrage und einer bis vier Optionen zeigt WhatsApp 1️⃣ bis 4️⃣ neben den Optionsbezeichnungen an. Reagieren Sie auf die zugestellte Aufforderung mit der entsprechenden Zahl, um sie zu beantworten. OpenClaw ordnet die Zahl über den Gateway der kanonischen Option zu; veraltete oder doppelte Eingaben werden ignoriert. Aufforderungen mit mehreren Fragen, Mehrfachauswahl oder Freitext können weiterhin nur per Textantwort beantwortet werden. Die normalen WhatsApp-Zulassungsregeln für DMs/Gruppen autorisieren den reagierenden Absender.

Plugin-Hooks und Datenschutz

Eingehende WhatsApp-Nachrichten können persönliche Inhalte, Telefonnummern, Gruppenkennungen, Absendernamen und Felder zur Sitzungskorrelation enthalten. WhatsApp sendet eingehende message_received-Hook-Nutzdaten nicht an Plugins, sofern Sie dies nicht ausdrücklich aktivieren:

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

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

Zugriffskontrolle und Aktivierung

Konfigurierte ACP-Bindungen

WhatsApp unterstützt dauerhafte ACP-Bindungen über bindings[] auf oberster Ebene:

{  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 abgeglichen, Gruppen anhand von WhatsApp-Gruppen-JIDs. Gruppen-Positivlisten, Absenderrichtlinie und die Aktivierungsbedingung durch Erwähnung 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 vorhanden ist, werden Schutzmechanismen für Selbstchats aktiviert: Lesebestätigungen für Selbstchat-Durchläufe werden übersprungen, das automatische Auslösen durch Erwähnungs-JIDs, das Sie selbst benachrichtigen würde, wird ignoriert, und Antworten werden standardmäßig an [{identity.name}] (oder [openclaw]) gesendet, wenn responsePrefix für den Kanal oder das Konto nicht festgelegt ist.

Nachrichtennormalisierung und Kontext

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

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

Zustellung, Aufteilung und Medien

Antwortzitate

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 (unterdrückt, wenn "off"):

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

Hinweise: Wird unmittelbar nach Annahme der eingehenden Nachricht gesendet (vor der Antwort); wenn ackReaction ohne emoji vorhanden ist, verwendet WhatsApp das Identitäts-Emoji des zugewiesenen Agenten mit „👀“ als Fallback (ackReaction weglassen oder emoji: "" festlegen, um keine Bestätigung zu senden); Fehler werden protokolliert, blockieren jedoch nicht die Zustellung der Antwort; im Gruppenmodus mentions erfolgt eine Reaktion nur bei durch Erwähnung ausgelösten Durchläufen, während die Gruppenaktivierung always diese Prüfung umgeht; WhatsApp verwendet ausschließlich channels.whatsapp.ackReaction (das veraltete messages.ackReaction gilt hier nicht).

Lebenszyklus-Statusreaktionen

Legen Sie messages.statusReactions.enabled: true fest, damit WhatsApp während eines Durchlaufs die Bestätigungsreaktion ersetzt, anstatt ein statisches Empfangs-Emoji beizubehalten. Dabei werden Zustände wie „in Warteschlange“, „denkt nach“, „Werkzeugaktivität“, Compaction, „abgeschlossen“ und „Fehler“ durchlaufen:

{  messages: {    statusReactions: {      enabled: true,    },  },}

Hinweise: channels.whatsapp.ackReaction steuert weiterhin die Berechtigung für Direktnachrichten und Gruppen; der Warteschlangenzustand 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 und stellen die Bestätigung nach dem abschließenden Erfolgs- oder Fehlerzustand wieder her.

Mehrere Konten und Anmeldedaten

Tools, Aktionen und Konfigurationsänderungen

• Die Unterstützung für Agent-Tools umfasst die WhatsApp-Reaktionsaktion (react).
• Aktionsfreigaben: channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (vorhandene Aktionen verwenden standardmäßig true), channels.whatsapp.actions.calls (Standardwert false, siehe MeowCaller oben).
• Vom Kanal initiierte Konfigurationsänderungen sind standardmäßig aktiviert; deaktivieren Sie sie über channels.whatsapp.configWrites: false.

Fehlerbehebung

openclaw channels login --channel whatsappopenclaw channels status

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 Telegram-ähnliche System-Prompts für Gruppen und Direktchats über die Zuordnungen groups und direct.

Auflösung für Gruppennachrichten: Zunächst wird die effektive Zuordnung groups bestimmt — wenn das Konto überhaupt einen eigenen Schlüssel groups definiert, ersetzt dieser die Stammzuordnung groups vollständig (keine tiefe Zusammenführung). Anschließend erfolgt die Prompt-Suche in dieser einzelnen 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. Gruppen-Platzhalter-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 die Stammzuordnung groups für jedes Konto in einer Einrichtung mit mehreren Konten (selbst für Konten ohne eigene groups), damit ein Bot keine Gruppennachrichten für Gruppen empfängt, denen er nicht angehört. WhatsApp wendet diesen Schutz nicht an — die Stammzuordnungen groups/direct werden unabhängig von der Anzahl der Konten von jedem Konto ohne eigene Überschreibung übernommen. Definieren Sie in einer WhatsApp-Einrichtung mit mehreren Konten die vollständige Zuordnung ausdrücklich unter jedem Konto, wenn Sie kontospezifische Prompts wünschen.

Wichtiges Verhalten:

• channels.whatsapp.groups ist sowohl eine gruppenspezifische Konfigurationszuordnung als auch die Positivliste für Gruppen auf Chat-Ebene. Sowohl im Stamm- als auch im Kontogültigkeitsbereich bedeutet groups["*"], dass für diesen Gültigkeitsbereich „alle Gruppen zugelassen sind“.
• Fügen Sie den Platzhalter systemPrompt nur hinzu, wenn in diesem Gültigkeitsbereich bereits alle Gruppen zugelassen werden sollen. Damit nur eine festgelegte Gruppe von Gruppen-IDs zulässig bleibt, wiederholen Sie den Prompt für jeden ausdrücklich in der Positivliste aufgeführten Eintrag, anstatt groups["*"] zu verwenden.
• Gruppenzulassung und Absenderautorisierung sind separate Prüfungen. groups["*"] erweitert die Auswahl der Gruppen, die die Gruppenverarbeitung erreichen; dadurch werden nicht alle Absender in diesen Gruppen autorisiert — dies wird weiterhin durch groupPolicy/groupAllowFrom gesteuert.
• channels.whatsapp.direct hat für DMs keine entsprechende Nebenwirkung: direct["*"] stellt lediglich eine Standardkonfiguration bereit, nachdem eine DM bereits durch dmPolicy zusammen mit allowFrom oder Regeln des Kopplungsspeichers zugelassen wurde.

Beispiel:

{  channels: {    whatsapp: {      groups: {        // Nur verwenden, wenn im Stammgültigkeitsbereich alle Gruppen 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 groups, daher werden die groups des Stammbereichs            // 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 in diesem Konto alle Gruppen zugelassen werden sollen.            "*": { systemPrompt: "Standard-Prompt für Arbeitsgruppen." },          },          direct: {            // Dieses Konto definiert eine eigene direct-Zuordnung, daher werden die direct-Einträge            // des Stammbereichs vollständig ersetzt. Um einen Platzhalter beizubehalten, definieren Sie "*" auch hier ausdrücklich.            "+15551234567": { systemPrompt: "Prompt für einen bestimmten geschäftlichen Direktchat." },            "*": { systemPrompt: "Standard-Prompt für geschäftliche Direktchats." },          },        },      },    },  },}

Verweise zur Konfigurationsreferenz

Primäre Referenz: Konfigurationsreferenz – WhatsApp

Verwandte Themen

• Kopplung
• Gruppen
• Sicherheit
• Kanalrouting
• Multi-Agent-Routing
• Fehlerbehebung