WhatsApp Keeper

Keep your OpenClaw WhatsApp connection alive. Actually solve the disconnect problem.

What This Does

OpenClaw uses Baileys (a reverse-engineered WhatsApp Web client) for WhatsApp messaging. Baileys sessions are inherently fragile:

• 428 Timeout: WhatsApp kills idle sessions after ~24 hours
• Session Corruption: Container restarts corrupt credential state
• QR Race Condition: The login flow has a race condition requiring a gateway restart mid-scan
• Device Conflicts: Multiple device registrations cause device_removed errors

WhatsApp Keeper is a daemon that runs alongside your OpenClaw gateway and prevents all of these.

How It Works

1. Presence Keepalive: Sends sendPresenceUpdate("available") every 25 seconds (WhatsApp's timeout is ~30s). This prevents the 428 timeout that kills most sessions.

2. Credential Snapshots: Before any state change, backs up the full auth directory. If credentials corrupt on restart, automatically restores from the last known-good snapshot.

3. Health Monitoring: Watches the Baileys WebSocket connection state. On disconnect, triggers immediate reconnect with saved credentials (not a fresh QR scan).

4. Graceful Restart Handling: On gateway restart/container restart, properly closes the WebSocket before shutdown and restores session state on startup.

5. Uptime Logging: Tracks connection uptime, disconnect events, and recovery times. Alerts via webhook or log when intervention is needed.

Installation

npm install whatsapp-keeper

Usage

As a standalone daemon

npx whatsapp-keeper --auth-dir ~/.openclaw/credentials/whatsapp

As a systemd service (recommended)

# Install the service
sudo cp whatsapp-keeper.service /etc/systemd/system/
sudo systemctl enable whatsapp-keeper
sudo systemctl start whatsapp-keeper

Configuration

{
  "authDir": "~/.openclaw/credentials/whatsapp",
  "keepaliveIntervalMs": 25000,
  "backupIntervalMs": 300000,
  "maxReconnectAttempts": 20,
  "webhookUrl": null,
  "logFile": "~/.openclaw/whatsapp-keeper.log"
}

Architecture

┌──────────────────┐     ┌──────────────────┐
│  OpenClaw        │     │  WhatsApp Keeper  │
│  Gateway         │     │  Daemon           │
│                  │     │                   │
│  ┌────────────┐  │     │  ┌─────────────┐ │
│  │ Baileys    │──┼─────┼──│ Health      │ │
│  │ WebSocket  │  │     │  │ Monitor     │ │
│  └────────────┘  │     │  └─────────────┘ │
│                  │     │                   │
│  ┌────────────┐  │     │  ┌─────────────┐ │
│  │ Auth State │──┼─────┼──│ Credential  │ │
│  │ (on disk)  │  │     │  │ Backup      │ │
│  └────────────┘  │     │  └─────────────┘ │
│                  │     │                   │
│                  │     │  ┌─────────────┐ │
│                  │     │  │ Keepalive   │ │
│                  │     │  │ Pinger      │ │
│                  │     │  └─────────────┘ │
└──────────────────┘     └──────────────────┘

Built by Milo

https://getmilo.dev