WhatsApp (Web-Kanal)

WhatsApp in 30 Sekunden verbinden: openclaw channels login, QR scannen, fertig. Status: WhatsApp Web nur über Baileys. Das Gateway besitzt die Sitzung(en).

Schnelleinrichtung (Anfänger)

Wenn möglich eine eigene Telefonnummer nutzen (empfohlen).
WhatsApp in ~/.clawdbot/openclaw.json konfigurieren.
openclaw channels login ausführen, um den QR-Code zu scannen (Verknüpfte Geräte).
Gateway starten.

Minimale Konfiguration:


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

Ziele

Mehrere WhatsApp-Konten (Mehrkonten) in einem Gateway-Prozess.
Deterministisches Routing: Antworten gehen zurück zu WhatsApp, kein Modell-Routing.
Das Modell sieht genug Kontext, um Zitat-Antworten zu verstehen.

Konfig schreibt

Standardmäßig darf WhatsApp Konfigurationsaktualisierungen schreiben, die durch /config set|unset ausgelöst werden (erfordert commands.config: true). Deaktivieren mit:


{
  channels: { whatsapp: { configWrites: false } }
}

Architektur (wer was besitzt)

Gateway besitzt den Baileys-Socket und die Inbox-Schleife.
CLI / macOS-App sprechen mit dem Gateway; keine direkte Baileys-Nutzung.
Aktiver Listener ist für ausgehende Sendungen erforderlich; sonst schlägt Senden schnell fehl.

Telefonnummer besorgen (zwei Modi)

WhatsApp benötigt eine echte Mobilnummer zur Verifizierung. VoIP- und virtuelle Nummern werden meist blockiert. Zwei unterstützte Wege, OpenClaw mit WhatsApp zu betreiben:

Dedizierte Nummer (empfohlen)

Eine eigene Telefonnummer für OpenClaw nutzen. Beste UX, klares Routing, keine Self-Chat-Sonderfälle. Ideales Setup: Ersatz-/altes Android-Handy + eSIM. An WLAN und Strom lassen und per QR verknüpfen. WhatsApp Business: Sie können WhatsApp Business auf demselben Gerät mit einer anderen Nummer nutzen. Gut, um Ihr persönliches WhatsApp getrennt zu halten – WhatsApp Business installieren und die OpenClaw-Nummer dort registrieren. Beispiel-Konfiguration (dedizierte Nummer, Einzelbenutzer-Zulassen-Liste):


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

Pairing-Modus (optional): Für Pairing statt Zulassen-Liste channels.whatsapp.dmPolicy auf pairing setzen. Unbekannte Absender erhalten einen Kopplungscode; Freigabe mit: openclaw pairing approve whatsapp <code>

Persönliche Nummer (Fallback)

Schneller Fallback: OpenClaw mit Ihrer eigenen Nummer betreiben. Sich selbst schreiben (WhatsApp „Nachricht an dich selbst“) zum Testen, um Kontakte nicht zuzuspammen. Verifizierungscodes während Setup und Experimenten auf dem Haupttelefon lesen. Self-Chat-Modus muss aktiviert werden. Wenn der Assistent nach Ihrer persönlichen WhatsApp-Nummer fragt, die Telefonnummer eingeben, von der aus Sie schreiben (Eigentümer/Absender), nicht die Assistenten-Nummer. Beispiel-Konfiguration (persönliche Nummer, Self-Chat):


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

Self-Chat-Antworten nutzen standardmäßig [{identity.name}], wenn gesetzt (sonst [openclaw]), wenn messages.responsePrefix nicht gesetzt ist. Explizit setzen, um das Präfix anzupassen oder zu deaktivieren ("" zum Entfernen).

Tipps zur Nummern-Beschaffung

Lokale eSIM vom Mobilfunkanbieter Ihres Landes (am zuverlässigsten)
- Österreich: hot.at
- UK: giffgaff — kostenlose SIM, ohne Vertrag
Prepaid-SIM — günstig, braucht nur eine SMS zur Verifizierung

Vermeiden: TextNow, Google Voice, die meisten „kostenlosen SMS“-Dienste — WhatsApp blockiert diese stark. Tipp: Die Nummer muss nur eine Verifizierungs-SMS empfangen. Danach bleiben WhatsApp-Web-Sitzungen über creds.json erhalten.

Warum nicht Twilio?

Frühe OpenClaw-Versionen unterstützten Twilios WhatsApp-Business-Integration.
WhatsApp-Business-Nummern passen schlecht zu einem persönlichen Assistenten.
Meta erzwingt ein 24-Stunden-Antwortfenster; wenn Sie in den letzten 24 Stunden nicht geantwortet haben, kann die Business-Nummer keine neuen Nachrichten initiieren.
Hohe Nutzung oder „geschwätzige“ Nutzung löst aggressive Blockierung aus, da Business-Konten nicht für Dutzende persönliche Assistenten-Nachrichten gedacht sind.
Ergebnis: unzuverlässige Zustellung und häufige Blockierungen, daher wurde die Unterstützung entfernt.

Login-Befehl: openclaw channels login (QR über Verknüpfte Geräte).
Mehrkonten-Login: openclaw channels login --account <id> (<id> = accountId).
Standardkonto (wenn --account weggelassen): default, falls vorhanden, sonst die erste konfigurierte Konto-ID (sortiert).
Anmeldedaten in ~/.clawdbot/credentials/whatsapp/<accountId>/creds.json gespeichert.
Backup-Kopie unter creds.json.bak (wird bei Korruption wiederhergestellt).
Legacy-Kompatibilität: ältere Installationen speicherten Baileys-Dateien direkt in ~/.clawdbot/credentials/.
Logout: openclaw channels logout (oder --account <id>) löscht den WhatsApp-Auth-Zustand (behält gemeinsames oauth.json).
Abgemeldeter Socket => Fehler weist auf erneute Verknüpfung hin.

Eingehender Fluss (DM + Gruppe)

WhatsApp-Events kommen von messages.upsert (Baileys).
Inbox-Listener werden beim Herunterfahren getrennt, um sich anhäufende Event-Handler bei Tests/Neustarts zu vermeiden.
Status-/Broadcast-Chats werden ignoriert.
Direkte Chats nutzen E.164; Gruppen nutzen Gruppen-JID.
DM-Richtlinie: channels.whatsapp.dmPolicy steuert den Zugang zu Direktchats (Standard: pairing).
- Pairing: unbekannte Absender erhalten einen Kopplungscode (Freigabe über openclaw pairing approve whatsapp <code>; Codes laufen nach 1 Stunde ab).
- Open: erfordert, dass channels.whatsapp.allowFrom "*" enthält.
- Ihre verknüpfte WhatsApp-Nummer ist implizit vertrauenswürdig; eigene Nachrichten überspringen die Prüfungen von channels.whatsapp.dmPolicy und channels.whatsapp.allowFrom.

Persönliche-Nummer-Modus (Fallback)

Wenn Sie OpenClaw mit Ihrer persönlichen WhatsApp-Nummer betreiben, channels.whatsapp.selfChatMode aktivieren (siehe Beispiel oben). Verhalten:

Ausgehende DMs lösen nie Pairing-Antworten aus (verhindert Kontakt-Spam).
Eingehende unbekannte Absender folgen weiterhin channels.whatsapp.dmPolicy.
Self-Chat-Modus (allowFrom enthält Ihre Nummer) vermeidet automatische Lesebestätigungen und ignoriert Erwähnungs-JIDs.
Lesebestätigungen werden für Nicht-Self-Chat-DMs gesendet.

Lesebestätigungen

Standardmäßig markiert das Gateway eingehende WhatsApp-Nachrichten als gelesen (blaue Häkchen), sobald sie angenommen sind. Global deaktivieren:


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

Pro Konto deaktivieren:


{
  channels: {
    whatsapp: {
      accounts: {
        personal: { sendReadReceipts: false }
      }
    }
  }
}

Hinweise:

Self-Chat-Modus überspringt immer Lesebestätigungen.

WhatsApp FAQ: Nachrichten senden + Pairing

Schickt OpenClaw zufälligen Kontakten Nachrichten, wenn ich WhatsApp verknüpfe?

Nein. Standard-DM-Richtlinie ist Pairing, daher erhalten unbekannte Absender nur einen Kopplungscode und ihre Nachricht wird nicht verarbeitet. OpenClaw antwortet nur auf Chats, die es empfängt, oder auf Sendungen, die Sie explizit auslösen (Agent/CLI). Wie funktioniert Pairing bei WhatsApp?

Pairing ist eine DM-Sperre für unbekannte Absender:

Erste DM von einem neuen Absender liefert einen kurzen Code (Nachricht wird nicht verarbeitet).
Freigabe mit: openclaw pairing approve whatsapp <code> (Auflistung mit openclaw pairing list whatsapp).
Codes laufen nach 1 Stunde ab; ausstehende Anfragen sind auf 3 pro Kanal begrenzt.

Können mehrere Personen verschiedene OpenClaws auf einer WhatsApp-Nummer nutzen?

Ja, indem jeder Absender über bindings (Peer kind: "dm", Absender E.164 z. B. +15551234567) einem anderen Agenten zugeordnet wird. Antworten kommen weiterhin vom gleichen WhatsApp-Konto, und Direktchats werden der Hauptsitzung jedes Agenten zugeordnet – also ein Agent pro Person. DM-Zugriffskontrolle (dmPolicy/allowFrom) ist global pro WhatsApp-Konto. Siehe Multi-Agent-Routing. Warum fragt der Assistent nach meiner Telefonnummer?

Der Assistent nutzt sie, um Ihre Zulassen-Liste/Eigentümer zu setzen, damit Ihre eigenen DMs erlaubt sind. Sie wird nicht für automatisches Senden genutzt. Bei Betrieb mit Ihrer persönlichen WhatsApp-Nummer dieselbe Nummer angeben und channels.whatsapp.selfChatMode aktivieren.

Nachrichten-Normalisierung (was das Modell sieht)

Body ist der aktuelle Nachrichten-Body mit Envelope.
Zitat-Antwort-Kontext wird immer angehängt:


[Replying to +1555 id:ABC123]
<quoted text or <media:...>>
[/Replying]

Antwort-Metadaten ebenfalls gesetzt:
- ReplyToId = stanzaId
- ReplyToBody = zitierter Text oder Medien-Platzhalter
- ReplyToSender = E.164 wenn bekannt
Nur-Medien-Nachrichten nutzen Platzhalter:
- <media:image|video|audio|document|sticker>

Gruppen

Gruppen werden agent:<agentId>:whatsapp:group:<jid>-Sitzungen zugeordnet.
Gruppenrichtlinie: channels.whatsapp.groupPolicy = open|disabled|allowlist (Standard allowlist).
Aktivierungsmodi:
- mention (Standard): erfordert @Erwähnung oder Regex-Match.
- always: löst immer aus.
/activation mention|always ist nur für Eigentümer und muss als eigenständige Nachricht gesendet werden.
Eigentümer = channels.whatsapp.allowFrom (oder eigene E.164 wenn nicht gesetzt).
Historie-Injection (nur ausstehend):
- Aktuelle unverarbeitete Nachrichten (Standard 50) eingefügt unter: [Chat messages since your last reply - for context] (bereits in der Sitzung vorhandene Nachrichten werden nicht erneut injiziert)
- Aktuelle Nachricht unter: [Current message - respond to this]
- Absender-Suffix angehängt: [from: Name (+E164)]
Gruppen-Metadaten 5 Min. gecacht (Betreff + Teilnehmer).

Antwort-Zustellung (Threading)

WhatsApp Web sendet Standardnachrichten (kein Zitat-Antwort-Threading im aktuellen Gateway).
Antwort-Tags werden auf diesem Kanal ignoriert.

Bestätigungs-Reaktionen (Auto-Reaktion beim Empfang)

WhatsApp kann automatisch Emoji-Reaktionen auf eingehende Nachrichten unmittelbar beim Empfang senden, bevor der Bot antwortet. So erhalten Nutzer sofort Rückmeldung, dass ihre Nachricht angekommen ist. Konfiguration:


{
  "whatsapp": {
    "ackReaction": {
      "emoji": "👀",
      "direct": true,
      "group": "mentions"
    }
  }
}

Optionen:

emoji (string): Emoji für die Bestätigung (z. B. „👀“, „✅“, „📨“). Leer oder weggelassen = Funktion deaktiviert.
direct (boolean, Standard: true): Reaktionen in Direkt-/DM-Chats senden.
group (string, Standard: "mentions"): Gruppen-Chat-Verhalten:
- "always": Auf alle Gruppennachrichten reagieren (auch ohne @Erwähnung)
- "mentions": Nur reagieren, wenn der Bot @erwähnt wird
- "never": In Gruppen nie reagieren

Pro-Konto-Override:


{
  "whatsapp": {
    "accounts": {
      "work": {
        "ackReaction": {
          "emoji": "✅",
          "direct": false,
          "group": "always"
        }
      }
    }
  }
}

Verhaltenshinweise:

Reaktionen werden unmittelbar beim Nachrichtenempfang gesendet, vor Tipp-Indikatoren oder Bot-Antworten.
In Gruppen mit requireMention: false (Aktivierung: always) wird bei group: "mentions" trotzdem auf alle Nachrichten reagiert (nicht nur @Erwähnungen).
Fire-and-forget: Reaktionsfehler werden protokolliert, verhindern aber nicht die Bot-Antwort.
Teilnehmer-JID wird für Gruppen-Reaktionen automatisch einbezogen.
WhatsApp ignoriert messages.ackReaction; stattdessen channels.whatsapp.ackReaction nutzen.

Agent-Tool (Reaktionen)

Tool: whatsapp mit Aktion react (chatJid, messageId, emoji, optional remove).
Optional: participant (Gruppen-Absender), fromMe (Reaktion auf eigene Nachricht), accountId (Mehrkonten).
Reaktions-Entfernung: siehe /tools/reactions.
Tool-Steuerung: channels.whatsapp.actions.reactions (Standard: aktiviert).

Limits

Ausgehender Text wird auf channels.whatsapp.textChunkLimit (Standard 4000) gechunkt.
Optionale Zeilenumbruch-Chunking: channels.whatsapp.chunkMode="newline" setzen, um vor Längen-Chunking an Leerzeilen (Absatzgrenzen) zu teilen.
Eingehende Medien-Speicherungen sind durch channels.whatsapp.mediaMaxMb (Standard 50 MB) begrenzt.
Ausgehende Medien-Einträge sind durch agents.defaults.mediaMaxMb (Standard 5 MB) begrenzt.

Ausgehende Sendung (Text + Medien)

Nutzt aktiven Web-Listener; Fehler, wenn Gateway nicht läuft.
Text-Chunking: max. 4k pro Nachricht (konfigurierbar über channels.whatsapp.textChunkLimit, optional channels.whatsapp.chunkMode).
Medien:
- Bild/Video/Audio/Dokument unterstützt.
- Audio als PTT gesendet; audio/ogg => audio/ogg; codecs=opus.
- Bildunterschrift nur beim ersten Medien-Eintrag.
- Medien-Abruf unterstützt HTTP(S) und lokale Pfade.
- Animierte GIFs: WhatsApp erwartet MP4 mit gifPlayback: true für Inline-Loop.
  - CLI: openclaw message send --media <mp4> --gif-playback
  - Gateway: send-Parameter enthalten gifPlayback: true

Sprachnotizen (PTT-Audio)

WhatsApp sendet Audio als Sprachnotizen (PTT-Blase).

Beste Ergebnisse: OGG/Opus. OpenClaw schreibt audio/ogg in audio/ogg; codecs=opus um.
[[audio_as_voice]] wird für WhatsApp ignoriert (Audio wird bereits als Sprachnotiz gesendet).

Medien-Limits + Optimierung

Standard-Ausgangs-Limit: 5 MB (pro Medien-Eintrag).
Override: agents.defaults.mediaMaxMb.
Bilder werden automatisch auf JPEG unter dem Limit optimiert (Größenänderung + Qualitätssweep).
Überdimensionierte Medien => Fehler; Medien-Antwort fällt auf Textwarnung zurück.

Heartbeats

Gateway-Heartbeat protokolliert Verbindungsgesundheit (web.heartbeatSeconds, Standard 60s).
Agent-Heartbeat kann pro Agent (agents.list[].heartbeat) oder global über agents.defaults.heartbeat konfiguriert werden (Fallback, wenn keine Pro-Agent-Einträge gesetzt).
- Nutzt den konfigurierten Heartbeat-Prompt (Standard: Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.) + HEARTBEAT_OK-Skip-Verhalten.
- Zustellung standardmäßig an den zuletzt genutzten Kanal (oder konfiguriertes Ziel).

Reconnect-Verhalten

Backoff-Richtlinie: web.reconnect:
- initialMs, maxMs, factor, jitter, maxAttempts.
Bei Erreichen von maxAttempts stoppt die Web-Überwachung (degradiert).
Abgemeldet => Stopp und erneute Verknüpfung erforderlich.

Konfig-Kurzübersicht

channels.whatsapp.dmPolicy (DM-Richtlinie: pairing/allowlist/open/disabled).
channels.whatsapp.selfChatMode (Same-Phone-Setup; Bot nutzt Ihre persönliche WhatsApp-Nummer).
channels.whatsapp.allowFrom (DM-Zulassen-Liste). WhatsApp nutzt E.164-Telefonnummern (keine Benutzernamen).
channels.whatsapp.mediaMaxMb (eingehendes Medien-Speicher-Limit).
channels.whatsapp.ackReaction (Auto-Reaktion beim Nachrichtenempfang: {emoji, direct, group}).
channels.whatsapp.accounts.<accountId>.* (Pro-Konto-Einstellungen + optional authDir).
channels.whatsapp.accounts.<accountId>.mediaMaxMb (Pro-Konto-eingehendes Medien-Limit).
channels.whatsapp.accounts.<accountId>.ackReaction (Pro-Konto-Ack-Reaktions-Override).
channels.whatsapp.groupAllowFrom (Gruppen-Absender-Zulassen-Liste).
channels.whatsapp.groupPolicy (Gruppenrichtlinie).
channels.whatsapp.historyLimit / channels.whatsapp.accounts.<accountId>.historyLimit (Gruppen-Historie-Kontext; 0 deaktiviert).
channels.whatsapp.dmHistoryLimit (DM-Historie-Limit in Benutzer-Turns). Pro-Benutzer-Overrides: channels.whatsapp.dms["<phone>"].historyLimit.
channels.whatsapp.groups (Gruppen-Zulassen-Liste + Erwähnungs-Standards; "*" für alle)
channels.whatsapp.actions.reactions (WhatsApp-Tool-Reaktionen steuern).
agents.list[].groupChat.mentionPatterns (oder messages.groupChat.mentionPatterns)
messages.groupChat.historyLimit
channels.whatsapp.messagePrefix (eingehendes Präfix; pro Konto: channels.whatsapp.accounts.<accountId>.messagePrefix; veraltet: messages.messagePrefix)
messages.responsePrefix (ausgehendes Präfix)
agents.defaults.mediaMaxMb
agents.defaults.heartbeat.every
agents.defaults.heartbeat.model (optionaler Override)
agents.defaults.heartbeat.target
agents.defaults.heartbeat.to
agents.defaults.heartbeat.session
agents.list[].heartbeat.* (Pro-Agent-Overrides)
session.* (scope, idle, store, mainKey)
web.enabled (Kanalstart deaktivieren wenn false)
web.heartbeatSeconds
web.reconnect.*

Logs + Fehlerbehebung

Subsysteme: whatsapp/inbound, whatsapp/outbound, web-heartbeat, web-reconnect.
Log-Datei: /tmp/openclaw/openclaw-YYYY-MM-DD.log (konfigurierbar).
Fehlerbehebungs-Anleitung: Gateway-Fehlerbehebung.

Fehlerbehebung (schnell)

Nicht verknüpft / QR-Login erforderlich

Symptom: channels status zeigt linked: false oder warnt „Not linked“.
Behebung: openclaw channels login auf dem Gateway-Host ausführen und QR scannen (WhatsApp → Einstellungen → Verknüpfte Geräte).

Verknüpft aber getrennt / Reconnect-Schleife

Symptom: channels status zeigt running, disconnected oder warnt „Linked but disconnected“.
Behebung: openclaw doctor (oder Gateway neu starten). Bei anhaltendem Problem erneut verknüpfen über channels login und openclaw logs --follow prüfen.

Bun-Runtime

Bun wird nicht empfohlen. WhatsApp (Baileys) und Telegram sind unter Bun unzuverlässig. Gateway mit Node betreiben. (Siehe Getting Started Runtime-Hinweis.)