[Bug]: WhatsApp QR code displayed but not recognized by mobile app

Summary

WhatsApp QR code appears in the Gateway Control UI but is consistently not recognized when scanned with WhatsApp mobile app. Tested multiple times with fresh QR codes, different browsers (Chrome, Brave), and verified no device limit issues.

Environment

Clawdbot version: 2026.1.24-3
Node.js version: v22.22.0
OS: Ubuntu 24.04.3 LTS
Installation method: npm install -g clawdbot
Setup: Remote VPS, accessed via SSH tunnel from macOS client

Gateway configuration:

• Port: 18790
• Mode: local
• Auth: Claude OAuth sessionKey (copied from working local instance)
• Workspace: /root/clawd

WhatsApp plugin:

• Location: /usr/lib/node_modules/clawdbot/extensions/whatsapp
• Status: Loaded successfully (confirmed in logs: "WhatsApp QR received")

Client access:

• SSH tunnel: ssh -L 18790:localhost:18790 root@VPS_IP -N
• Browser: Chrome/Brave (macOS) → http://localhost:18790?token=<gateway-token>

Steps to Reproduce

1. Fresh Clawdbot installation on Ubuntu VPS:

   # Install Node.js 22.22.0
   curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
   apt-get install -y nodejs
   
   # Install Clawdbot
   npm install -g clawdbot
   
   # Create workspace
   mkdir -p /root/clawd
   cd /root/clawd
   
   # Configure Gateway
   clawdbot doctor --fix  # Auto-corrects config
   clawdbot gateway install
   systemctl --user start clawdbot-gateway.service

2. Copy auth.json with valid Claude sessionKey from working local instance

3. Access Gateway UI via SSH tunnel:

   ssh -L 18790:localhost:18790 root@VPS_IP -N &

4. Open browser: http://localhost:18790?token=<gateway-token>

5. Navigate to: Channels → WhatsApp → Show QR

6. Scan QR with WhatsApp mobile app:

   • WhatsApp → Settings → Linked Devices → Link a Device
   • Scan displayed QR code

Expected Behavior

WhatsApp should recognize the QR code and complete the pairing process, linking the VPS instance as a new device.

Actual Behavior

• QR code displays correctly in Gateway UI (standard WhatsApp Web QR format)
• WhatsApp mobile app does not recognize it - no response, no error message
• Scanning multiple times produces same result
• Refreshing QR and scanning immediately (<15 seconds) makes no difference

What DOES work:

• Same QR-based pairing works perfectly on local macOS Clawdbot instance
• Same WhatsApp account successfully linked to 2 other devices (within limits)
• Gateway UI responds correctly (can access all sections, see config, etc.)

Gateway logs:

2026-02-13T14:45:44.786Z WhatsApp QR received.
2026-02-13T14:51:16.894Z WhatsApp QR received.
2026-02-13T15:06:34.457Z WhatsApp QR received.

No error messages, no connection attempts from WhatsApp servers.

What We've Ruled Out

1. Device limit: WhatsApp allows 4 linked devices. Currently have 2 (space available).

2. Configuration errors:

   • Ran clawdbot doctor --fix successfully
   • No invalid keys in config
   • Gateway status: healthy, running

3. Network/firewall issues:

   • Gateway responds correctly via SSH tunnel
   • Can access all UI sections
   • Logs show QR being generated

4. Expired QR:

   • Scanned within 10-15 seconds of generation
   • Tried refreshing QR multiple times

5. Port conflicts:

   • Verified local gateway stopped to avoid conflicts
   • Confirmed SSH tunnel connecting to correct VPS instance

6. Browser issues:

   • Tested both Chrome and Brave
   • Both show same QR behavior

Additional Context

Pairing code alternative:
Checked if 8-digit pairing code (Baileys requestPairingCode()) is available as alternative to QR. It exists in Baileys library but is not exposed in Clawdbot's current interface.

Related Baileys issues:

• WhiskeySockets/Baileys#2293 - Similar intermittent pairing issues
• WhiskeySockets/Baileys#2306 - Pairing code generated but not received

Use case:
Goal is to run Clawdbot 24/7 on VPS accessed via WhatsApp, separate from local instance. This architectural pattern (main + sub-agent on VPS) is useful for delegating tasks but currently blocked by WhatsApp pairing.

Questions for Maintainers

1. Is WhatsApp pairing known to work on VPS setups?
   Most examples/docs show local installations. Are there known issues with VPS deployments?

2. Is there any additional WhatsApp plugin configuration required?
   Current config:

   "channels": {
     "whatsapp": {
       "dmPolicy": "disabled",
       "selfChatMode": false,
       "allowFrom": [],
       "groupPolicy": "allowlist",
       "mediaMaxMb": 50,
       "debounceMs": 0
     }
   }

3. Could this be a Baileys version mismatch?
   WhatsApp changes protocols frequently. Is the bundled Baileys version current?

4. Are there alternative pairing methods?

   • Phone number + 8-digit code (via requestPairingCode())
   • Direct credential import
   • Any other workarounds?

5. Detailed logging for debugging?
   What log level / debug flags would help diagnose why WhatsApp servers aren't responding to the QR?

Logs

Gateway startup:

$ systemctl --user status clawdbot-gateway.service
● clawdbot-gateway.service - Clawdbot Gateway (v2026.1.24-3)
   Active: active (running)

WhatsApp plugin loading:

2026-02-13T15:05:31.389Z [gateway] listening on ws://127.0.0.1:18790
2026-02-13T15:05:31.407Z [browser/server] Browser control listening on http://127.0.0.1:18792/

QR generation (no errors):

2026-02-13T15:06:34.457Z WhatsApp QR received.

Workaround Request

If fixing the QR issue requires significant changes, would appreciate guidance on:

• Manually importing WhatsApp credentials from working local instance to VPS
• Alternative communication channels that work reliably on VPS
• Any debug/verbose logging flags to help troubleshoot

Impact: Blocking production use of Clawdbot on VPS for WhatsApp-based workflows.

Willing to help: Can provide additional logs, test patches, or help debug if maintainers need more info.