WhatsApp

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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.

openclaw plugins install @openclaw/whatsapp

winget install --id Git.Git -e

​

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

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

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

​

Zugriffskontrolle und Aktivierung

​

Verhalten bei persönlicher Nummer und Selbst-Chat

• 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

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

​

Reaktionsstufe

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

​

Bestätigungsreaktionen

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

• 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

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.

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.

• 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.

{
  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

• Konfigurationsreferenz - WhatsApp

• 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