openclaw-whatsapp-qrcode-text

CLI tool for linking WhatsApp accounts via QR code scanning. Designed for the OpenClaw ecosystem — credentials are stored in the standard OpenClaw directory (~/.openclaw/credentials/whatsapp/<account>/), ready for the gateway to use.

Install

npm install -g openclaw-whatsapp-qrcode-text

Usage

Commands

# Link a WhatsApp account (skips if already linked)
openclaw-wa-qr login

# Check if an account is linked (exit code 0 = linked, 1 = not linked)
openclaw-wa-qr status

# Clear existing credentials and re-link
openclaw-wa-qr relogin

Options

| Option | Description | Default | |---|---|---| | --account <id> | Account identifier | default | | --json | Output all messages as JSON (one object per line) | off | | --port <port> | Start an HTTP server for polling the latest QR and status | off | | --timeout <seconds> | Auto-exit if not scanned within this duration | 300 |

Examples

# Basic login
openclaw-wa-qr login --account myaccount

# JSON output mode (for machine consumption)
openclaw-wa-qr login --json

# HTTP polling mode (for backend integration)
openclaw-wa-qr login --account default --port 9700

HTTP Polling Mode

When --port is specified, an HTTP server starts on the given port. Any GET request returns the current state as JSON.

curl http://localhost:9700

Response Format

{
  "status": "qr",
  "qr": "2@abc123...",
  "account": "default",
  "authDir": "/root/.openclaw/credentials/whatsapp/default",
  "updatedAt": "2026-04-29T12:30:00.000Z",
  "error": null
}

Status Values

| Status | Description | |---|---| | waiting | Starting up, QR not yet received | | qr | QR code available in qr field (always the latest) | | connected | Successfully linked | | error | Something went wrong, see error field |

Lifecycle

1. Process starts → status is waiting
2. WhatsApp sends QR → status becomes qr, updates on every refresh
3. User scans QR → status becomes connected
4. Process exits automatically after 20 seconds (gives pollers time to read connected)
5. If nobody scans within the timeout (default 5 min) → process exits with code 1

Credential Storage

Credentials are stored at:

~/.openclaw/credentials/whatsapp/<account>/
├── creds.json
├── app-state-sync-key-*.json
└── ...

This is the standard OpenClaw credential directory. The OpenClaw gateway reads these files to operate WhatsApp channels.

How It Works

• Uses @whiskeysockets/baileys (WhatsApp Web API)
• QR codes are output as raw data strings (not ASCII art), suitable for rendering with any QR library
• No message history sync, no online status — authentication only
• Automatic reconnect on restartRequired disconnect
• Automatic credential cleanup and retry on loggedOut disconnect

License

MIT