WhatsApp (Web-Kanal)¶

Status: Nur WhatsApp Web über Baileys. Das Gateway besitzt die Sitzung(en).

Default DM policy is pairing for unknown senders. Cross-channel diagnostics and repair playbooks. Full channel config patterns and examples.

Quick setup¶

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

openclaw channels login --channel whatsapp

```
For a specific account:
```

openclaw channels login --channel whatsapp --account work

openclaw gateway

Genehmigen mit: `openclaw pairing approve whatsapp <code>` (Liste mit `openclaw pairing list whatsapp`).

```
Codes laufen nach 1 Stunde ab; ausstehende Anfragen sind auf 3 pro Kanal begrenzt.
```

Ideal, um Ihr persönliches WhatsApp getrennt zu halten — installieren Sie WhatsApp Business und registrieren Sie dort die OpenClaw-Nummer. (The channel metadata and onboarding flow are optimized for that setup, but personal-number setups are also supported.)

Deployment patterns¶

This is the cleanest operational mode:

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

Onboarding supports personal-number mode and writes a self-chat-friendly baseline:

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

The messaging platform channel is WhatsApp Web-based (Baileys) in current OpenClaw channel architecture.

```
There is no separate Twilio WhatsApp messaging channel in the built-in chat-channel registry.
```

Runtime model¶

Gateway owns the WhatsApp socket and reconnect loop.
Outbound sends require an active WhatsApp listener for the target account.
Status-/Broadcast-Chats werden ignoriert.
Direct chats use DM session rules (session.dmScope; default main collapses DMs to the agent main session).
Gruppen werden auf agent:<agentId>:whatsapp:group:<jid>-Sitzungen abgebildet.

Access control and activation¶

DM-Richtlinie: channels.whatsapp.dmPolicy steuert den Zugriff auf Direktchats (Standard: pairing).

```
Offen: erfordert, dass `channels.whatsapp.allowFrom` `"*"` enthält.
```

Group access has two layers:

```
`channels.whatsapp.groups` (Gruppen-Allowlist + Mention-Gating-Defaults; verwenden Sie `"*"`, um alle zu erlauben)
```

Group replies require mention by default.

```
Mention detection includes:

- explicit WhatsApp mentions of the bot identity
- configured mention regex patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
- implicit reply-to-bot detection (reply sender matches bot identity)

Session-level activation command:

- `/activation mention`
- `/activation always`

`activation` updates session state (not global config). It is owner-gated.
```

Personal-number and self-chat behavior¶

When the linked self number is also present in allowFrom, WhatsApp self-chat safeguards activate:

skip read receipts for self-chat turns
ignore mention-JID auto-trigger behavior that would otherwise ping yourself
Self-Chat-Antworten verwenden standardmäßig [{identity.name}], wenn gesetzt (ansonsten [openclaw]),
falls messages.responsePrefix nicht gesetzt ist.

Message normalization and context¶

Incoming WhatsApp messages are wrapped in the shared inbound envelope.

````
If a quoted reply exists, context is appended in this form:

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

Reply metadata fields are also populated when available (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, sender JID/E.164).
````

Eingehende Nachrichten nur mit Medien verwenden Platzhalter:

```
- `<media:image>`
- `<media:video>`
- `<media:audio>`
- `<media:document>`
- `<media:sticker>`

Location and contact payloads are normalized into textual context before routing.
```

For groups, unprocessed messages can be buffered and injected as context when the bot is finally triggered.

```
Aktuelle _unverarbeitete_ Nachrichten (Standard 50) werden eingefügt unter:
`[Chat messages since your last reply - for context]` (Nachrichten, die bereits in der Sitzung sind, werden nicht erneut injiziert)
```

Read receipts are enabled by default for accepted inbound WhatsApp messages.

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

Delivery, chunking, and media¶

Optionale Newline-Chunking: Setzen Sie channels.whatsapp.chunkMode="newline", um vor dem Längen-Chunking an Leerzeilen (Absatzgrenzen) zu trennen.

- supports image, video, audio (PTT voice-note), and document payloads - audio/ogg is rewritten to audio/ogg; codecs=opus for voice-note compatibility - animated GIF playback is supported via gifPlayback: true on video sends - captions are applied to the first media item when sending multi-media reply payloads - media source can be HTTP(S), file://, or local paths

- inbound media save cap: channels.whatsapp.mediaMaxMb (default 50) - outbound media cap for auto-replies: agents.defaults.mediaMaxMb (default 5MB) - images are auto-optimized (resize/quality sweep) to fit limits - on media send failure, first-item fallback sends text warning instead of dropping the response silently

Acknowledgment reactions¶

channels.whatsapp.ackReaction (Auto-Reaktion beim Nachrichteneingang: {emoji, direct, group}).

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

Verhalten:

sent immediately after inbound is accepted (pre-reply)
failures are logged but do not block normal reply delivery
group mode mentions reacts on mention-triggered turns; group activation always acts as bypass for this check
WhatsApp ignoriert messages.ackReaction; verwenden Sie stattdessen channels.whatsapp.ackReaction.

Multi-account and credentials¶

Standardkonto (wenn --account weggelassen wird): default, falls vorhanden, sonst die erste konfigurierte Konto-ID (sortiert).

Anmeldedaten gespeichert in ~/.openclaw/credentials/whatsapp/<accountId>/creds.json./creds.json- backup file:creds.json.bak- legacy default auth in~/.openclaw/credentials/` is still recognized/migrated for default-account flows

Multi-Account-Login: openclaw channels login --account <id> (<id> = accountId).]` clears WhatsApp auth state for that account.

```
In legacy auth directories, `oauth.json` is preserved while Baileys auth files are removed.
```

Tools, actions, and config writes¶

Werkzeug: whatsapp mit Aktion react (chatJid, messageId, emoji, optional remove).
Action gates:
channels.whatsapp.actions.reactions (Gating für WhatsApp-Werkzeugreaktionen).
`channels.whatsapp.accounts.
{ channels: { whatsapp: { configWrites: false } }, }

Troubleshooting¶

Symptom: channels status zeigt linked: false oder warnt „Not linked“.

```
Logout: `openclaw channels logout` (oder `--account <id>`) löscht den WhatsApp-Auth-Status (behält jedoch gemeinsame `oauth.json`).
```

Symptom: linked account with repeated disconnects or reconnect attempts.

```
Lösung: `openclaw doctor` (oder Gateway neu starten). Wenn es anhält, erneut verknüpfen über `channels login` und `openclaw logs --follow` prüfen.
```

Outbound sends fail fast when no active gateway listener exists for the target account.

```
Make sure gateway is running and the account is linked.
```

Check in this order:

```
Gruppenrichtlinie: `channels.whatsapp.groupPolicy = open|disabled|allowlist` (Standard `allowlist`).
```

WhatsApp gateway runtime should use Node. WhatsApp (Baileys) und Telegram sind unter Bun unzuverlässig. Führen Sie das Gateway mit Node aus.

Configuration reference pointers¶

Primary reference:

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

High-signal WhatsApp fields:

access: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
delivery: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction
multi-account: accounts.<id>.enabled, accounts.<id>.authDir, account-level overrides
operations: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
session behavior: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>messages.groupChat.historyLimit`

Pairing
Channel routing
Leitfaden zur Fehlerbehebung: Gateway troubleshooting.