WhatsApp Onboarding - Buddy Access
End-to-end guide for connecting a buddy to your KafClaw instance via WhatsApp.
See also: WhatsApp Setup (Default Deny) for CLI reference.
Overview
KafClaw uses default-deny for WhatsApp. New senders are blocked until the owner explicitly approves them. This guide walks through the full onboarding flow for adding a buddy.
Step 1: Initial Setup (one-time)
# First-time setup - creates config and workspace
kafclaw onboard
# Pair your WhatsApp account (scan QR code)
kafclaw whatsapp-auth
The QR code is saved to ~/.kafclaw/whatsapp-qr.png. Open it and scan with WhatsApp on your phone.
Step 2: Configure Auth Settings
# Set a pairing token (shared out-of-band with your buddy)
kafclaw whatsapp-setup
This prompts for:
- Pairing token - a shared secret your buddy sends as their first message
- Allowlist - JIDs to pre-approve (format:
[email protected]) - Denylist - JIDs to permanently block
Step 3: Start the Gateway
make run # standalone mode
# or
make run-full # group mode (if workshop is running)
Silent mode is enabled by default on every WhatsApp start. This prevents accidental outbound messages. Disable it from the dashboard when ready.
Step 4: Buddy Sends First Message
- Share the pairing token with your buddy out-of-band (text, email, etc.)
- Buddy sends the token as their first WhatsApp message to the bot’s number
- The message appears in the pending queue on the dashboard
Step 5: Approve on Dashboard
- Open
http://localhost:18791(dashboard) - Navigate to the WhatsApp section
- Find the pending message from your buddy
- Click Approve to add them to the allowlist
Once approved, the buddy can send messages normally. The bot responds according to its soul file personality.
Step 6: Disable Silent Mode
Once setup is verified and the buddy is approved:
- Dashboard → Settings
- Toggle Silent Mode off
- The bot will now send outbound responses via WhatsApp
Security Notes
- Silent mode resets to ON on every gateway restart. This is intentional - it prevents accidental sends after updates or crashes.
- Allowlist is persistent - approved buddies remain approved across restarts.
- Denylist is permanent - denied senders are blocked until explicitly removed.
- Token is one-time - after a buddy is approved, the token is no longer needed for that sender.
Current capability note
For channel parity status versus OpenClaw (what WhatsApp can do today in KafClaw, and what remains limited), see:
- WhatsApp Setup (Default Deny) -> Parity snapshot (OpenClaw vs KafClaw)
CLI Quick Reference
# Approve a sender
kafclaw whatsapp-auth --approve [email protected]
# Deny a sender
kafclaw whatsapp-auth --deny [email protected]
# List all auth entries
kafclaw whatsapp-auth --list