WhatsApp

​

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.

openclaw plugins install clawhub:@openclaw/whatsapp

​

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>

​

Aktuellen Anfragenden mit MeowCaller anrufen (experimentell)

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

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git
cd meowcaller
git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f
mkdir -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"

• 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

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

​

Plugin-Hooks und Datenschutz

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

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

​

Zugriffskontrolle und Aktivierung

​

Konfigurierte ACP-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" },
      },
    },
  ],
}

• 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

• 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

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

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

• 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 whatsapp
openclaw channels status

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

openclaw channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

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

​

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

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.

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

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