WhatsApp

Status: produktionsbereit über WhatsApp Web (Baileys). Gateway verwaltet verknüpfte Sitzung(en).

Installation (bei Bedarf)

• Onboarding (openclaw onboard) und openclaw channels add --channel whatsapp fragen bei der ersten Auswahl nach der Installation des WhatsApp-Plugins.
• openclaw channels login --channel whatsapp bietet den Installationsablauf ebenfalls an, wenn das Plugin noch nicht vorhanden ist.
• Dev-Channel + Git-Checkout: verwendet standardmäßig den lokalen Plugin-Pfad.
• Stable/Beta: installiert zuerst das offizielle @openclaw/whatsapp-Plugin aus ClawHub, mit npm als Fallback.
• Die WhatsApp-Laufzeit wird außerhalb des zentralen OpenClaw-npm-Pakets verteilt, damit WhatsApp-spezifische Laufzeitabhängigkeiten beim externen Plugin bleiben.

Die manuelle Installation bleibt verfügbar:

openclaw plugins install clawhub:@openclaw/whatsapp

Verwenden Sie das reine npm-Paket (@openclaw/whatsapp) nur, wenn Sie den Registry- Fallback benötigen. Pinnen Sie eine exakte Version nur, wenn Sie eine reproduzierbare Installation benötigen.

Schnelle Einrichtung

{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>

Aktuellen Anfragenden mit MeowCaller anrufen (experimentell)

Das WhatsApp-Plugin kann whatsapp_call in Agent-Turns offenlegen, die aus WhatsApp stammen. Das Tool verwendet MeowCaller, um einen WhatsApp-Sprachanruf an den aktuell autorisierten Anfragenden zu starten, und spielt nach Annahme eine OpenClaw-TTS-Nachricht ab. Das Tool akzeptiert keine Zielnummer, daher kann ein Prompt den Anruf nicht an Dritte umleiten. Diese experimentelle Fähigkeit ist 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"

Aktuelle Grenzen:

• nur ausgehende 1:1-Audioanrufe
• keine beliebigen Zielnummern
• keine gemeinsame Authentifizierung mit der Chat-Verbindung
• keine Selbstanrufe im Modus mit persönlicher Nummer/Selbst-Chat
• synthetisiertes Audio ist auf 60 Sekunden begrenzt
• keine Empfangsbestätigung zur Hörbarkeit auf dem Handgerät über MeowCallers Abschluss von Annahme/Wiedergabe/Auflegen hinaus
• OpenClaw stoppt den Begleitprozess nach einem begrenzten Fenster von 115-175 Sekunden, einschließlich MeowCallers Verbindungs-, Annahme-, Wiedergabe- und Beendigungsphasen

Bereitstellungsmuster

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

Laufzeitmodell

• Gateway verwaltet den WhatsApp-Socket und die Reconnect-Schleife.
• Der Reconnect-Watchdog verwendet WhatsApp-Web-Transportaktivität, nicht nur eingehendes App-Nachrichtenvolumen, sodass eine stille Linked-Device-Sitzung nicht allein deshalb neu gestartet wird, weil kürzlich niemand eine Nachricht gesendet hat. Eine längere Obergrenze für Anwendungspausen erzwingt weiterhin einen Reconnect, wenn weiter Transport-Frames eintreffen, aber innerhalb des Watchdog-Fensters keine Anwendungsnachrichten verarbeitet werden; nach einem vorübergehenden Reconnect für eine kürzlich aktive Sitzung verwendet diese Prüfung auf Anwendungspausen für das erste Wiederherstellungsfenster das normale Nachrichten-Timeout.
• Baileys-Socket-Timings sind explizit unter web.whatsapp.*: keepAliveIntervalMs steuert WhatsApp-Web-Anwendungs-Pings, connectTimeoutMs steuert das Timeout des öffnenden Handshakes, und defaultQueryTimeoutMs steuert Baileys-Abfragewartezeiten plus die lokalen OpenClaw-Grenzen für ausgehendes Senden/Präsenz und eingehende Lesebestätigungsoperationen.
• Ausgehende Sendungen erfordern einen aktiven WhatsApp-Listener für das Zielkonto.
• Gruppensendungen hängen native Erwähnungsmetadaten für @+<digits>- und @<digits>-Tokens in Text und Medienbeschriftungen an, wenn das Token aktuellen WhatsApp-Teilnehmermetadaten entspricht, einschließlich LID-gestützter Gruppen.
• Status- und Broadcast-Chats werden ignoriert (@status, @broadcast).
• Der Reconnect-Watchdog folgt WhatsApp-Web-Transportaktivität, nicht nur eingehendem App-Nachrichtenvolumen: stille Linked-Device-Sitzungen bleiben aktiv, solange Transport-Frames weiterlaufen, aber ein Transportstillstand erzwingt einen Reconnect deutlich vor dem späteren Remote-Disconnect-Pfad.
• Direktchats verwenden DM-Sitzungsregeln (session.dmScope; Standard main führt DMs in der Hauptsitzung des Agent zusammen).
• Gruppensitzungen sind isoliert (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters können explizite ausgehende Ziele mit ihrer nativen @newsletter-JID sein. Ausgehende Newsletter-Sendungen verwenden Channel-Sitzungsmetadaten (agent:<agentId>:whatsapp:channel:<jid>) statt DM-Sitzungssemantik.
• Der WhatsApp-Web-Transport berücksichtigt standardmäßige Proxy-Umgebungsvariablen auf dem Gateway-Host (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / Varianten in Kleinbuchstaben). Bevorzugen Sie hostweite Proxy-Konfiguration gegenüber Channel-spezifischen WhatsApp-Proxy-Einstellungen.
• Wenn messages.removeAckAfterReply aktiviert ist, entfernt OpenClaw die WhatsApp-Ack-Reaktion, nachdem eine sichtbare Antwort zugestellt wurde.

Genehmigungs-Prompts

WhatsApp kann Exec- und Plugin-Genehmigungs-Prompts mit 👍-/👎-Reaktionen rendern. Die Zustellung wird durch die Top-Level-Konfiguration für Genehmigungsweiterleitung gesteuert:

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

approvals.exec und approvals.plugin sind unabhängig. WhatsApp als Channel zu aktivieren verknüpft nur den Transport; es sendet keine Genehmigungs-Prompts, sofern die passende Genehmigungsfamilie nicht aktiviert ist und an WhatsApp routet. Der Sitzungsmodus liefert native Emoji-Genehmigungen nur für Genehmigungen, die aus WhatsApp stammen. Der Zielmodus verwendet die gemeinsame Weiterleitungs-Pipeline für explizite WhatsApp- Ziele und erstellt keinen separaten Fanout für Genehmiger-DMs.

WhatsApp-Genehmigungsreaktionen erfordern explizite WhatsApp-Genehmiger aus allowFrom oder "*". defaultTo steuert gewöhnliche Standardnachrichtenziele; es ist kein Genehmiger für Genehmigungen. Manuelle /approve-Befehle durchlaufen weiterhin den normalen WhatsApp-Absenderautorisierungspfad, bevor die Genehmigung aufgelöst wird.

Plugin-Hooks und Datenschutz

WhatsApp-Eingangsnachrichten können persönliche Nachrichteninhalte, Telefonnummern, Gruppenkennungen, Absendernamen und Felder zur Sitzungs-Korrelation enthalten. Aus diesem Grund sendet WhatsApp eingehende message_received-Hook-Payloads nicht an Plugins, es sei denn, Sie aktivieren dies ausdrücklich:

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

Sie können die Aktivierung auf ein Konto beschränken:

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

Aktivieren Sie dies nur für Plugins, denen Sie den Empfang eingehender WhatsApp-Nachrichteninhalte und Kennungen anvertrauen.

Zugriffskontrolle und Aktivierung

Konfigurierte ACP-Bindings

WhatsApp unterstützt persistente ACP-Bindings mit bindings[]-Einträgen 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" },      },    },  ],}

• Direkte Chats stimmen mit E.164-Nummern wie +15555550123 überein.
• Gruppen stimmen mit WhatsApp-Gruppen-JIDs wie 120363424282127706@g.us überein.
• Gruppen-Zulassungslisten, Absenderregel und Erwähnungs- oder Aktivierungs-Gating werden ausgeführt, bevor OpenClaw sicherstellt, dass die konfigurierte ACP-Sitzung existiert.
• Ein übereinstimmendes konfiguriertes ACP-Binding besitzt die Route. WhatsApp-Broadcast-Gruppen verteilen diesen Durchlauf nicht an gewöhnliche WhatsApp-Sitzungen.

Verhalten für persönliche Nummern und Selbst-Chats

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

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

Nachrichtennormalisierung und Kontext

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

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

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

Zustellung, Aufteilung und Medien

Antwortzitate

WhatsApp unterstützt natives Zitieren von Antworten, bei dem ausgehende Antworten die eingehende Nachricht sichtbar zitieren. Steuern Sie dies mit channels.whatsapp.replyToMode.

Standard ist "off". Überschreibungen pro Konto verwenden channels.whatsapp.accounts.<id>.replyToMode.

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

Reaktionsstufe

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

Standard: "minimal".

Überschreibungen pro Konto verwenden channels.whatsapp.accounts.<id>.reactionLevel.

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

Bestätigungsreaktionen

WhatsApp unterstützt unmittelbare Ack-Reaktionen beim eingehenden Empfang über channels.whatsapp.ackReaction. Ack-Reaktionen werden durch reactionLevel gesteuert — sie werden unterdrückt, wenn reactionLevel "off" ist.

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

Verhaltenshinweise:

• wird sofort gesendet, nachdem eingehend akzeptiert wurde (vor der Antwort)
• wenn ackReaction ohne emoji vorhanden ist, verwendet WhatsApp das Identitäts-Emoji des gerouteten Agenten, mit Fallback auf "👀"; lassen Sie ackReaction weg oder setzen Sie emoji: "", um keine Bestätigungsreaktion zu senden
• Fehler werden protokolliert, blockieren aber nicht die normale Antwortzustellung
• Gruppenmodus mentions reagiert bei durch Erwähnungen ausgelösten Turns; Gruppenaktivierung always dient als Umgehung für diese Prüfung
• WhatsApp verwendet channels.whatsapp.ackReaction (das ältere messages.ackReaction wird hier nicht verwendet)

Lifecycle-Statusreaktionen

Setzen Sie messages.statusReactions.enabled: true, damit WhatsApp während eines Turns die Bestätigungsreaktion ersetzt, anstatt ein statisches Empfangs-Emoji stehen zu lassen. Wenn aktiviert, verwendet OpenClaw denselben Reaktionsslot der eingehenden Nachricht für Lifecycle-Zustände wie in die Warteschlange gestellt, denkend, Tool-Aktivität, Compaction, erledigt und Fehler.

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

Verhaltenshinweise:

• channels.whatsapp.ackReaction steuert weiterhin, ob Statusreaktionen für Direktnachrichten und Gruppen zulässig sind.
• Die Statusreaktion für die Warteschlange verwendet dasselbe effektive Bestätigungs-Emoji wie einfache Bestätigungsreaktionen.
• WhatsApp hat einen Bot-Reaktionsslot pro Nachricht, daher ersetzen Lifecycle-Aktualisierungen die aktuelle Reaktion direkt.
• messages.removeAckAfterReply: true entfernt die finale Statusreaktion nach der konfigurierten Haltezeit für erledigt/Fehler.
• Tool-Emoji-Kategorien umfassen tool, coding, web, deploy, build und concierge.

Mehrere Konten und Zugangsdaten

Tools, Aktionen und Konfigurationsschreibvorgänge

• Agent-Tool-Unterstützung umfasst die WhatsApp-Reaktionsaktion (react).
• Aktions-Gates:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Vom Kanal initiierte Konfigurationsschreibvorgänge sind standardmäßig aktiviert (deaktivieren ü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 Telegram-artige System-Prompts für Gruppen und Direktchats über die Maps groups und direct.

Auflösungshierarchie für Gruppennachrichten:

Die effektive groups-Map wird zuerst bestimmt: Wenn das Konto eigene groups definiert, ersetzt sie die Root-groups-Map vollständig (kein Deep Merge). Die Prompt-Suche läuft dann auf der resultierenden einzelnen Map:

1. Gruppenspezifischer System-Prompt (groups["<groupId>"].systemPrompt): wird verwendet, wenn der spezifische Gruppeneintrag in der Map vorhanden ist und sein Schlüssel systemPrompt definiert ist. Wenn systemPrompt ein leerer String ("") ist, wird der Wildcard unterdrückt und kein System-Prompt angewendet.
2. Gruppen-Wildcard-System-Prompt (groups["*"].systemPrompt): wird verwendet, wenn der spezifische Gruppeneintrag in der Map vollständig fehlt oder wenn er vorhanden ist, aber keinen Schlüssel systemPrompt definiert.

Auflösungshierarchie für Direktnachrichten:

Die effektive direct-Map wird zuerst bestimmt: Wenn das Konto eigene direct definiert, ersetzt sie die Root-direct-Map vollständig (kein Deep Merge). Die Prompt-Suche läuft dann auf der resultierenden einzelnen Map:

1. Direktspezifischer System-Prompt (direct["<peerId>"].systemPrompt): wird verwendet, wenn der spezifische Peer-Eintrag in der Map vorhanden ist und sein Schlüssel systemPrompt definiert ist. Wenn systemPrompt ein leerer String ("") ist, wird der Wildcard unterdrückt und kein System-Prompt angewendet.
2. Direkt-Wildcard-System-Prompt (direct["*"].systemPrompt): wird verwendet, wenn der spezifische Peer-Eintrag in der Map vollständig fehlt oder wenn er vorhanden ist, aber keinen Schlüssel systemPrompt definiert.

Unterschied zum Telegram-Verhalten bei mehreren Konten: In Telegram wird Root-groups für alle Konten in einer Mehrkonten-Einrichtung absichtlich unterdrückt, auch für Konten, die keine eigenen groups definieren, um zu verhindern, dass ein Bot Gruppennachrichten für Gruppen empfängt, denen er nicht angehört. WhatsApp wendet diese Schutzmaßnahme nicht an: Root-groups und Root-direct werden immer von Konten geerbt, die keinen Override auf Kontoebene definieren, unabhängig davon, wie viele Konten konfiguriert sind. Wenn Sie in einer WhatsApp-Mehrkonten-Einrichtung gruppen- oder direktchatspezifische Prompts pro Konto möchten, definieren Sie die vollständige Map explizit unter jedem Konto, statt sich auf Root-Standardwerte zu verlassen.

Wichtiges Verhalten:

• channels.whatsapp.groups ist sowohl eine Konfigurations-Map pro Gruppe als auch die Allowlist auf Chat-Ebene für Gruppen. Auf Root- oder Konto-Scope bedeutet groups["*"]: „Alle Gruppen sind zugelassen“ für diesen Scope.
• Fügen Sie einen Wildcard-Gruppen-systemPrompt nur hinzu, wenn dieser Scope bereits alle Gruppen zulassen soll. Wenn weiterhin nur eine feste Menge von Gruppen-IDs zulässig sein soll, verwenden Sie groups["*"] nicht als Prompt-Standard. Wiederholen Sie den Prompt stattdessen für jeden explizit in der Allowlist enthaltenen Gruppeneintrag.
• Gruppenzulassung und Senderautorisierung sind getrennte Prüfungen. groups["*"] erweitert die Menge der Gruppen, die die Gruppenverarbeitung erreichen können, autorisiert aber nicht von sich aus jeden Sender in diesen Gruppen. Senderzugriff wird weiterhin separat durch channels.whatsapp.groupPolicy und channels.whatsapp.groupAllowFrom gesteuert.
• channels.whatsapp.direct hat nicht denselben Nebeneffekt für DMs. direct["*"] stellt nur eine Standardkonfiguration für Direktchats bereit, nachdem ein DM bereits durch dmPolicy plus allowFrom oder Pairing-Store-Regeln zugelassen wurde.

Beispiel:

{  channels: {    whatsapp: {      groups: {        // Use only if all groups should be admitted at the root scope.        // Applies to all accounts that do not define their own groups map.        "*": { systemPrompt: "Default prompt for all groups." },      },      direct: {        // Applies to all accounts that do not define their own direct map.        "*": { systemPrompt: "Default prompt for all direct chats." },      },      accounts: {        work: {          groups: {            // This account defines its own groups, so root groups are fully            // replaced. To keep a wildcard, define "*" explicitly here too.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Focus on project management.",            },            // Use only if all groups should be admitted in this account.            "*": { systemPrompt: "Default prompt for work groups." },          },          direct: {            // This account defines its own direct map, so root direct entries are            // fully replaced. To keep a wildcard, define "*" explicitly here too.            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },            "*": { systemPrompt: "Default prompt for work direct chats." },          },        },      },    },  },}

Verweise zur Konfigurationsreferenz

Primäre Referenz:

• Konfigurationsreferenz - WhatsApp

Wichtige 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.*, web.whatsapp.*
• Sitzungsverhalten: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• Prompts: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

Verwandte Themen

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