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 fordern zur Installation des WhatsApp-Plugin auf, wenn Sie es zum ersten Mal auswählen.
• openclaw channels login --channel whatsapp bietet ebenfalls den Installationsablauf an, wenn das Plugin noch nicht vorhanden ist.
• Dev-Kanal + Git-Checkout: verwendet standardmäßig den lokalen Plugin-Pfad.
• Stable/Beta: verwendet das npm-Paket @openclaw/whatsapp auf dem aktuellen offiziellen Release-Tag.

Die manuelle Installation bleibt verfügbar:

openclaw plugins install @openclaw/whatsapp

Verwenden Sie das reine Paket, um dem aktuellen offiziellen Release-Tag zu folgen. Pinnen Sie eine exakte Version nur, wenn Sie eine reproduzierbare Installation benötigen.

Unter Windows benötigt das WhatsApp-Plugin während der npm-Installation Git in PATH, weil eine seiner Baileys/libsignal-Abhängigkeiten von einer Git-URL abgerufen wird. Installieren Sie Git for Windows, starten Sie dann die Shell neu und führen Sie die Installation erneut aus:

winget install --id Git.Git -e

Portable Git funktioniert ebenfalls, wenn dessen bin-Verzeichnis in PATH liegt.

# 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-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

# Bereitstellungsmuster

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

# Laufzeitmodell

• Gateway verwaltet den WhatsApp-Socket und die Wiederverbindungsschleife.
• Der Wiederverbindungs-Watchdog verwendet WhatsApp-Web-Transportaktivität, nicht nur eingehendes App-Nachrichtenvolumen, sodass eine ruhige verknüpfte Gerätesitzung nicht allein deshalb neu gestartet wird, weil kürzlich niemand eine Nachricht gesendet hat. Eine längere Grenze für Anwendungsschweigen erzwingt weiterhin eine Wiederverbindung, wenn weiterhin Transport-Frames eintreffen, aber im Watchdog-Fenster keine Anwendungsnachrichten verarbeitet werden; nach einer vorübergehenden Wiederverbindung für eine kürzlich aktive Sitzung verwendet diese Prüfung auf Anwendungsschweigen für das erste Wiederherstellungsfenster das normale Nachrichten-Timeout.
• Baileys-Socket-Zeitwerte sind unter web.whatsapp.* explizit: keepAliveIntervalMs steuert WhatsApp-Web-Anwendungspings, connectTimeoutMs steuert das Timeout des öffnenden Handshakes, und defaultQueryTimeoutMs steuert Baileys-Abfrage-Timeouts.
• 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 mit aktuellen WhatsApp-Teilnehmermetadaten übereinstimmt, einschließlich LID-gestützter Gruppen.
• Status- und Broadcast-Chats werden ignoriert (@status, @broadcast).
• Der Wiederverbindungs-Watchdog folgt der WhatsApp-Web-Transportaktivität, nicht nur eingehendem App-Nachrichtenvolumen: ruhige verknüpfte Gerätesitzungen bleiben aktiv, während Transport-Frames weiterlaufen, aber ein Transport-Stillstand erzwingt eine Wiederverbindung deutlich vor dem späteren Remote-Disconnect-Pfad.
• Direkt-Chats verwenden DM-Sitzungsregeln (session.dmScope; Standard main führt DMs in der Hauptsitzung des Agenten 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 beachtet Standard-Proxy-Umgebungsvariablen auf dem Gateway-Host (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / Varianten in Kleinschreibung). Bevorzugen Sie Proxy-Konfiguration auf Host-Ebene gegenüber Channel-spezifischen WhatsApp-Proxy-Einstellungen.
• Wenn messages.removeAckAfterReply aktiviert ist, entfernt OpenClaw die WhatsApp-Ack-Reaktion, nachdem eine sichtbare Antwort zugestellt wurde.

# Plugin-Hooks und Datenschutz

Eingehende WhatsApp-Nachrichten können persönliche Nachrichteninhalte, Telefonnummern, Gruppenkennungen, Absendernamen und Sitzungs-Korrelationsfelder enthalten. Aus diesem Grund sendet WhatsApp eingehende message_received-Hook-Payloads nicht an Plugins, sofern Sie sich nicht ausdrücklich dafür entscheiden:

{
  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

# Verhalten bei persönlicher Nummer und Selbst-Chat

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

• Lesebestätigungen für Selbst-Chat-Durchläufe überspringen
• Mention-JID-Auto-Trigger-Verhalten ignorieren, das sonst Sie 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, Chunking und Medien

# Antwortzitate

WhatsApp unterstützt native Antwortzitate, bei denen ausgehende Antworten die eingehende Nachricht sichtbar zitieren. Steuern Sie dies mit channels.whatsapp.replyToMode.

Standardwert ist "off". Kontospezifische Überschreibungen verwenden channels.whatsapp.accounts.<id>.replyToMode.

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

# Reaktionsstufe

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

Standardwert: "minimal".

Kontospezifische Überschreibungen verwenden channels.whatsapp.accounts.<id>.reactionLevel.

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

# Bestätigungsreaktionen

WhatsApp unterstützt sofortige Bestätigungsreaktionen beim Eingang ü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:

• wird sofort gesendet, nachdem die eingehende Nachricht akzeptiert wurde (vor der Antwort)
• Fehler werden protokolliert, blockieren aber nicht die normale Antwortzustellung
• der Gruppenmodus mentions reagiert bei durch Erwähnungen ausgelösten Runden; die Gruppenaktivierung always dient als Umgehung für diese Prüfung
• WhatsApp verwendet channels.whatsapp.ackReaction (das Legacy-messages.ackReaction wird hier nicht verwendet)

# Mehrere Konten und Anmeldedaten

# Tools, Aktionen und Konfigurationsschreibvorgänge

• Die Agenten-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

openclaw channels login --channel whatsapp
openclaw channels status

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

openclaw doctor
openclaw logs --follow

# System-Prompts

WhatsApp unterstützt System-Prompts im Telegram-Stil für Gruppen und direkte Chats über die Maps groups und direct.

Auflösungshierarchie für Gruppennachrichten:

Zuerst wird die effektive groups-Map bestimmt: Wenn das Konto eine eigene groups definiert, ersetzt sie die Root-groups-Map vollständig (keine tiefe Zusammenführung). Die Prompt-Suche läuft anschließend auf der daraus 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 eine leere Zeichenfolge ("") ist, wird der Platzhalter unterdrückt und kein System-Prompt angewendet.
2. Gruppen-Platzhalter-System-Prompt (groups["*"].systemPrompt): wird verwendet, wenn der spezifische Gruppeneintrag in der Map gar nicht vorhanden ist oder wenn er vorhanden ist, aber keinen Schlüssel systemPrompt definiert.

Auflösungshierarchie für direkte Nachrichten:

Zuerst wird die effektive direct-Map bestimmt: Wenn das Konto eine eigene direct definiert, ersetzt sie die Root-direct-Map vollständig (keine tiefe Zusammenführung). Die Prompt-Suche läuft anschließend auf der daraus 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 eine leere Zeichenkette ("") ist, wird der Platzhalter unterdrückt und kein System-Prompt angewendet.
2. Direkter Platzhalter-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 mit mehreren Konten: In Telegram wird groups auf Root-Ebene in einer Multi-Konto-Konfiguration absichtlich für alle Konten 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: groups und direct auf Root-Ebene werden immer von Konten geerbt, die keinen Override auf Kontoebene definieren, unabhängig davon, wie viele Konten konfiguriert sind. Wenn Sie in einer WhatsApp-Konfiguration mit mehreren Konten Gruppen- oder Direkt-Prompts pro Konto möchten, definieren Sie die vollständige Map explizit unter jedem Konto, statt sich auf Defaults auf Root-Ebene zu verlassen.

Wichtiges Verhalten:

• channels.whatsapp.groups ist sowohl eine Konfigurations-Map pro Gruppe als auch die Allowlist für Gruppen auf Chat-Ebene. Im Root- oder Kontobereich bedeutet groups["*"], dass „alle Gruppen zugelassen werden“.
• Fügen Sie einen Platzhalter-Gruppen-systemPrompt nur hinzu, wenn Sie bereits möchten, dass dieser Bereich alle Gruppen zulässt. Wenn weiterhin nur eine feste Menge von Gruppen-IDs berechtigt sein soll, verwenden Sie groups["*"] nicht als Prompt-Default. Wiederholen Sie den Prompt stattdessen auf jedem explizit zugelassenen Gruppeneintrag.
• Gruppenzulassung und Absenderautorisierung sind getrennte Prüfungen. groups["*"] erweitert die Menge der Gruppen, die die Gruppenverarbeitung erreichen können, autorisiert aber nicht automatisch jeden Absender in diesen Gruppen. Der Absenderzugriff wird weiterhin separat durch channels.whatsapp.groupPolicy und channels.whatsapp.groupAllowFrom gesteuert.
• channels.whatsapp.direct hat nicht dieselbe Nebenwirkung für DMs. direct["*"] stellt nur eine Standardkonfiguration für Direkt-Chats bereit, nachdem eine 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.
            "[email protected]": {
              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
• mehrere Konten: accounts.<id>.enabled, accounts.<id>.authDir, Overrides 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

• Pairing
• Gruppen
• Sicherheit
• Channel-Routing
• Multi-Agent-Routing
• Fehlerbehebung