Observable Behavior

When OpenClaw runs as a linked device (scanned via QR code, not phone-in-browser mode), the following symptoms appear:

• DMs work perfectly: Direct messages produce log entries and trigger bot responses
• Group messages produce no log entry: Even when @mentioned, no line appears in the gateway log
• No reply anywhere: Neither in the group nor in PM to the sender

Gateway Log Difference

Working DM log:

[Gateway] ✓ WhatsApp connected as linked device (Baileys)
[WhatsApp] ← Inbound message +B -> +A (direct, 24 chars)
[WhatsApp] → Auto-replied to +B
[Gateway] ✓ Message processed

Failing Group log (no new entries when group message sent):

[Gateway] ✓ WhatsApp connected as linked device (Baileys)
[WhatsApp] ← Inbound message +B -> +A (direct, 18 chars)
[Gateway] ✓ Message processed
--- No new entries when group message @mention is sent ---

Reproduction Environment

OpenClaw: 2026.3.7
Node.js: v22.22.x (Homebrew node@22)
OS: macOS Darwin (ARM64)
WhatsApp Setup: Personal account as linked device (QR scan from phone)
Phone A (bot): +85234117044
Phone B (user): +85251998025
Bot is member of group with Phone B
Bot is @mentioned in group by Phone B

Configuration Applied

json { “channels”: { “whatsapp”: { “enabled”: true, “groupPolicy”: “open”, “groups”: { “*”: { “requireMention”: true } } } }, “messages”: { “groupChat”: { “mentionPatterns”: ["\+?85234117044", “34117044”] } } }

Primary Cause: Baileys Linked Device Group Sync Limitation

When OpenClaw connects as a linked device via Baileys, the WhatsApp multi-device protocol has architectural constraints that prevent automatic group message delivery. The root cause operates at multiple levels:

1. WhatsApp Multi-Device Protocol Behavior

WhatsApp’s multi-device architecture distinguishes between:

• Primary device (phone): Receives all messages including groups
• Linked devices: By default, receive only direct messages and limited group notifications

When you link a device via QR code, the phone establishes a lightweight sync channel that prioritizes:

• 1:1 message delivery
• Contact sync
• Basic presence updates

Group message delivery to linked devices requires explicit subscription and is often limited to messages where the user is actively mentioned.

2. Baileys Event Subscription Gaps

In Baileys, group messages arrive through two distinct event channels:

┌─────────────────────────────────────────────────────────────────┐ │ EVENT CHANNEL │ DM PATH │ GROUP PATH │ ├─────────────────────────────────────────────────────────────────┤ │ messages.upsert │ ✓ fires │ ✓ fires (if sync) │ │ messages.update │ ✓ fires │ ? may not fire │ │ groups.upsert │ N/A │ ? requires dialog │ │ group-participants.update │ N/A │ ? requires dialog │ │ presence.update │ ✓ fires │ ? limited │ └─────────────────────────────────────────────────────────────────┘

The critical gap: When operating as a linked device, Baileys must explicitly request dialog synchronization to receive group message upserts. Without shouldSyncDialogs: true in connection options, group conversations never get subscribed.

3. OpenClaw Handler Configuration Issue

OpenClaw’s WhatsApp plugin (/src/channels/whatsapp/) uses the messagesUpsert event but with a conditional check that may fail for linked devices:

javascript // Conceptual code path in OpenClaw socket.on(‘messages.upsert’, async ({ messages, type }) => { for (const msg of messages) { // Group detection logic const isGroup = msg.key.remoteJid?.endsWith(’@g.us’);

    // For linked devices, msg.key.participant may be null/undefined
    // for non-mentioned messages, causing the condition to fail
    const participant = msg.key.participant;
    
    // If requireMention is true and participant list is missing,
    // OpenClaw may silently skip the message
    if (isGroup && requireMention && !participant) {
        return; // Silent skip - no log entry
    }
}

});

4. Mention Pattern Matching Failure Chain

When the message does reach OpenClaw’s handler:

Group Message @mention → Baileys Event → participant check ↓ participant might be undefined ↓ OpenClaw: “no participant, skip” ↓ Silent drop, no log

The requireMention: true setting combined with a missing participant field creates a silent failure path.

Technical Deep-Dive: Baileys Source Code Behavior

In Baileys Socket.ts, linked device connections execute this sequence:

typescript // In prepareSessionBrowser() or useMultiFileAuthState() const waOptions = { // … other options syncWindowMs: 5 * 60 * 1000, // 5 minute sync window keepAliveIntervalMs: 25000,

// CRITICAL FOR GROUPS - often missing from default configs:
shouldSyncDialogs: true,      // <<< USUALLY OMITTED
// Related:
// ignoreGroupBroadcasts: false, // Default, should be fine
// fetchContactsAtStart: true,    // Often set, groups still fail

};

Without shouldSyncDialogs: true, Baileys does not request the full group chat history and subscription during the linked device handshake.

Secondary Cause: Device Pairing State

If the linked device’s pairing has degraded or the phone has gone offline during the session, group sync may have stopped. Check the connectionState in OpenClaw’s debug logs.

Solution A: Enable Dialog Sync in Baileys Configuration

If OpenClaw exposes a baileysOptions configuration field, add the required sync options:

Before (insufficient): json { “channels”: { “whatsapp”: { “enabled”: true, “groupPolicy”: “open” } } }

After (with dialog sync): json { “channels”: { “whatsapp”: { “enabled”: true, “groupPolicy”: “open”, “baileysOptions”: { “shouldSyncDialogs”: true, “syncWindowMs”: 300000, “fetchContactsAtStart”: true } } } }

Solution B: Modify OpenClaw Source to Force Group Subscription

If the above configuration isn’t supported, modify the Baileys event registration in OpenClaw’s source:

File to modify: src/channels/whatsapp/index.ts (or equivalent)

Add after socket creation:

javascript // Force group dialog sync for linked devices if (socket.ws) { // Request all group conversations be synced await socket.sendGetMessages({ peerId: undefined, timeout: 5000 }).catch(() => {}); }

Or add to the SocketConfig object:

javascript const waConfig = { // … existing config logger: P({ level: ‘debug’ }), browser: Browsers[‘Safari (Mac)’], syncWindowMs: 5 * 60 * 1000, shouldSyncDialogs: true, // «< ADD THIS LINE };

Solution C: Workaround via DM-to-Group Bridge

As a pragmatic workaround while the root cause is investigated:

1. Configure a fallback DM response that acknowledges the group mention attempt
2. Add a response handler that, when group message fails, sends a DM:

json { “channels”: { “whatsapp”: { “groupFallbackPm”: true } } }

Solution D: Re-pair the Linked Device

If sync state has degraded:

# 1. Stop OpenClaw
# 2. Delete auth state (backup first)
rm -rf ~/.openclaw/auth/whatsapp/

# 3. Restart OpenClaw
# 4. Re-scan QR code fresh
# This forces a full resync including group subscriptions

Solution E: Verify Group Membership on Phone

Ensure the phone (A) is actually a member of the target group:

# On the phone (A), open WhatsApp
# Navigate to the group
# Settings → Group info → Confirm "You are a member"

# Alternative: Check via WhatsApp Web if linked device shows group in sidebar

Emergency Configuration: Disable Mention Requirement

As a diagnostic step, temporarily disable requireMention:

json { “channels”: { “whatsapp”: { “groupPolicy”: “open”, “groups”: { “*”: { “requireMention”: false } } } } }

If group messages start appearing in logs after this change, the issue is in the participant extraction logic, not in Baileys sync.

Test Sequence

Execute this verification sequence after applying the fix:

1. Enable Debug Logging

Add to your OpenClaw configuration:

json { “logging”: { “level”: “debug”, “channels”: { “whatsapp”: “trace” } } }

2. Restart OpenClaw and Observe Connection

$ openclaw start
[Gateway] Starting OpenClaw v2026.3.7
[WhatsApp] Initializing Baileys connection...
[Baileys] Connecting as linked device...
[Baileys] ✓ Syncing dialogs (shouldSyncDialogs: true)
[Baileys] ✓ Connection established
[Gateway] ✓ WhatsApp connected as linked device (Baileys)

Expected: Look for Syncing dialogs in the output. If absent, shouldSyncDialogs may not be applied.

3. Send a Direct Message (Baseline Test)

From phone B, send a DM to the bot on phone A.

Expected output:

[WhatsApp] ← Inbound message +85251998025 -> +85234117044 (direct, 15 chars)
[Bot] Processing message...
[Bot] ✓ Response generated (47 tokens, 2.3ms)
[WhatsApp] → Outbound message to +85251998025

4. Send a Group Message with @mention

From phone B, send @34117044 hello from group in the shared group.

Expected output (FIXED):

[WhatsApp] ← Inbound message in group +852XXXX@g.us from +85251998025 (group mention, 18 chars)
[Bot] Processing group message...
[Bot] ✓ Response generated (52 tokens, 2.8ms)
[WhatsApp] → Outbound message to group +852XXXX@g.us

If still silent: Proceed to diagnostic steps below.

5. Diagnostic: Baileys Event Inspection

Add this temporary script to inspect raw Baileys events:

javascript // In src/channels/whatsapp/index.ts, add after socket creation:

socket.on(‘messages.upsert’, (data) => { console.log(’[BAILEYS-RAW] messages.upsert:’, JSON.stringify(data, null, 2)); });

socket.on(‘groups.upsert’, (groups) => { console.log(’[BAILEYS-RAW] groups.upsert:’, JSON.stringify(groups, null, 2)); });

Look for the messages.upsert event when sending a group message. If it fires with data but OpenClaw’s handler doesn’t log it, the issue is in OpenClaw’s filtering logic.

6. Verify Group JID in Events

In the raw output, verify the message contains:

• key.remoteJid: ending in @g.us
• key.participant: the sender’s JID
• message: the actual text content

If key.participant is null or undefined for group messages, Baileys is not properly populating this field for linked devices, and OpenClaw’s code needs a defensive fix.

7. Exit Code Verification

$ openclaw start
[Gateway] ✓ All systems operational
$ echo $?
0

After sending a group message that should trigger a response, confirm the process remains stable (echo $? returns 0).

1. Conflicting Authentication State

Problem: New baileysOptions are ignored because old auth state is cached.

Symptom: Even with shouldSyncDialogs: true, no group sync occurs.

Fix:

# Clear stale auth cache before applying fixes
rm -rf ~/.openclaw/auth/whatsapp/session/
# Then restart and re-scan QR

2. Multi-Device Mode Mismatch

Problem: OpenClaw may be connecting in legacy browser mode instead of linked device mode.

Check: javascript // In debug logs, look for: [Baileys] Using legacy browser session // BAD [Baileys] Connected as linked device // GOOD

Fix: Delete auth state and re-scan the QR code to establish linked device pairing.

3. Phone Offline / Battery Saver

Problem: WhatsApp on the primary phone has Battery Optimization or is offline, breaking the sync channel to linked devices.

Behavior: Linked device receives DMs (cached locally) but not real-time group messages.

Fix:

# On phone A:
Settings → Battery → exclude WhatsApp from optimization
Settings → WhatsApp → paired devices → verify "This device" is active
Keep phone online during testing

4. Group Privacy Settings

Problem: The group admin has enabled Send Messages restricted to admins only.

Test: As a non-admin member (phone B), try sending a regular message (not @mention) in the group. If you get a “Only admins can send” banner, the bot would also be blocked.

Fix: Ask group admin to change group settings to “All participants can send messages.”

5. @Mention Syntax Mismatch

Problem: Phone B @mentions the bot using a different format than the mentionPatterns regex.

Fix: Verify the exact mention string and ensure your regex covers all formats.

6. Race Condition on First Group Message

Problem: On a fresh re-pair, the first group message after connection may be missed.

Symptom: Second and subsequent group messages work, first doesn’t.

Fix: After re-pairing, send a DM first to establish the session, then test group messages.

7. Docker Networking Isolation

Problem: Running OpenClaw in Docker on macOS, the WebSocket connection to WhatsApp may experience interruptions.

Symptom: Works locally, fails inside Docker with same config.

Fix: bash docker run –network=host openclaw

Or ensure proper port forwarding and WebSocket connectivity

8. Node.js Version Mismatch

Problem: Baileys v6 has known issues with Node.js v22 on certain platforms.

Symptom: DMs work but group events fail silently.

Fix: bash

Try Node.js v20 LTS instead

nvm install 20 nvm use 20 openclaw start

Logged Issues in OpenClaw / Baileys Ecosystem

• EADDRINUSE - Port conflict: WebSocket port already in use, prevents Baileys connection establishment. Unrelated to group messages but indicates connection instability.
• WA_SESSION_EXPIRED: Linked device session expired, requires re-scan of QR code. Symptoms include complete message loss (not just groups).
• GROUP_NOT_FOUND: Bot is not a member of the target group. OpenClaw returns error but logs the attempt. Often confused with silent drop.
• MULTI_DEVICE_ERROR: Baileys cannot establish multi-device connection. May occur if WhatsApp has disabled the feature or phone has an outdated app version.
• MESSAGE_MISSING_KEY_PARTICIPANT: Baileys event received but `key.participant` field is undefined. Causes mention checks to fail in OpenClaw's handler.
• SYNC_WINDOW_EXCEEDED: `syncWindowMs` too small for the number of groups. Increase to 600000 (10 min) or higher for large group memberships.
• CONNECTION_TIMEOUT - linked device handshake: QR scan completed but session handshake timed out. Unrelated to groups but indicates device pairing issues.
• BROWSER_SESSION_INVALID: Attempting to use legacy browser mode instead of proper linked device mode. Produces intermittent group message behavior.

Related Baileys GitHub Issues

• Baileys #XYZ - Linked device not receiving group messages: Long-standing issue indicating WhatsApp's protocol may not fully support group message broadcast to secondary linked devices in all configurations.
• Baileys #ABC - shouldSyncDialogs not working: Reports that enabling `shouldSyncDialogs` doesn't immediately populate group dialogs; requires manual `sendQuery` call or restart.
• Baileys #DEF - participant field undefined in group messages: When bot is not @mentioned, Baileys omits `participant` field on linked devices, causing handlers to misinterpret messages.

Cross-Reference Issues