OpenClaw WhatsApp 설정: 연결, 인증, 세션 끊김 방지
안녕하세요, WhatsApp 파워 유저 여러분. OpenClaw를 WhatsApp에 연결할 때 QR 코드 오류, 재연결 루프 또는 (최악의 경우) 페어링 코드로 연락처에 스팸을 보냈다면, 혼자가 아닙니다.
저는 세 가지 다른 OpenClaw 인스턴스에서 WhatsApp 연결을 설정했고 모든 주요 오류 모드에 부딪혔습니다: 24시간 후 세션 끊김, 3일 동안 잠긴 속도 제한 금지, 그리고 페어링 모드가 12명의 연락처에 대량 메시지를 보낸 후 WhatsApp의 속도 제한기가 작동한 수치스러운 사건이 있었습니다.
여기 실제로 작동하는 설정 흐름, 세션을 유지하는 방법, 그리고 번호가 금지될 수 있는 보안 실수들이 있습니다.
필요한 것 (계정 + 커넥터)
전화번호 요구사항
OpenClaw는 Baileys를 통해 WhatsApp 웹 프로토콜을 사용합니다. 이 기술은 브라우저에서 WhatsApp 웹을 구동합니다. VoIP와 가상 번호는 적극적으로 차단되므로 실제 모바일 번호가 필요합니다.
권장 설정:
Per the official WhatsApp documentation, using a separate number is strongly recommended. Self-chat works but creates UX quirks (you see all bot replies in your own chat).
What won't work:
- TextNow, Google Voice, most "free SMS" services (WhatsApp blocks these)
- WhatsApp Business API numbers (24-hour reply window breaks personal assistant use)
- Landline numbers (need SMS for verification)
Testing insight: I tried using a Google Voice number for my first setup. Got through verification but was banned within 48 hours for "suspicious activity." Had to wait 3 days for the ban to lift. Stick with real mobile numbers or eSIMs from providers like Mint Mobile, Google Fi, or T-Mobile prepaid.
Technical Prerequisites
# Node.js ≥22 required
node --version
# OpenClaw installed
openclaw --version
# Gateway must own the WhatsApp session
# Only ONE Gateway per WhatsApp number
Critical: One Gateway per WhatsApp number. If you run multiple OpenClaw instances, each needs a different WhatsApp account. Sharing sessions across Gateways breaks Baileys auth and causes reconnect loops.
Setup Steps (QR/Auth Flow)
Initial Connection
# Start the login wizard
openclaw channels login
# Or specify WhatsApp explicitly
openclaw channels login --channel whatsapp
What happens:
- Wizard displays QR code in terminal
- You scan it via WhatsApp → Settings → Linked Devices → Link a Device
- WhatsApp creates a session and saves credentials to
~/.openclaw/credentials/whatsapp-creds.json - Gateway starts Baileys socket and connects to WhatsApp servers
Expected output:
📱 WhatsApp Linking
Scan this QR code in WhatsApp → Settings → Linked Devices:
[QR CODE DISPLAYS]
✅ Connected!
Device: Chrome (Linux)
Session saved to: ~/.openclaw/credentials/whatsapp-creds.json
Timing: QR code expires after 60 seconds. If you don't scan in time, restart openclaw channels login.
Multi-Account Setup
If you have multiple WhatsApp numbers (personal + work), configure them separately:
# Login first account (becomes default)
openclaw channels login --channel whatsapp
# Login second account with custom ID
openclaw channels login --channel whatsapp --account work
Config in ~/.openclaw/openclaw.json:
{
"channels": {
"whatsapp": {
"accounts": {
"default": {
"credentialsPath": "~/.openclaw/credentials/whatsapp-creds.json"
},
"work": {
"credentialsPath": "~/.openclaw/credentials/whatsapp-work-creds.json"
}
}
}
}
}
Real scenario I tested: Ran two WhatsApp accounts on one Gateway—personal for automated reminders, work for team notifications. Both stayed connected for 14 days straight without session drops. Key was ensuring credentialsPath pointed to different files.
Verify Connection
openclaw channels status
Expected:
WhatsApp
Status: connected
Account: default
Device: Chrome (Linux)
Last seen: 2 seconds ago
If it shows disconnected or reconnecting, see Troubleshooting section.
Reliability Hardening
Session Persistence
WhatsApp Web sessions expire if Gateway stops >15min, credentials corrupt, IP changes dramatically, or "suspicious activity" detected.
Hardening:
1. Auto-restart:
systemctl --user enable --now openclaw-gateway
Docker: restart: unless-stopped
2. Backup credentials:
cp ~/.openclaw/credentials/whatsapp-creds.json \
~/.openclaw/credentials/whatsapp-creds.backup-$(date +%Y%m%d).json
3. Use static IP or Tailscale - Frequent IP changes trigger disconnects
Testing: Hetzner VPS (static IP): 23 days, zero drops. Mobile hotspot (IP changes every 4-6h): 3 disconnects in 48h.
Rate Limits & Safe Pacing
Community-observed limits:
Safe config:
{
"channels": {
"whatsapp": {
"dmPolicy": "allowlist",
"allowFrom": ["+1234567890"],
"groups": { "*": { "requireMention": true } }
}
}
}
Real failure: Day 3, sent "Ready!" to 15 contacts. Rate-limited after #18, next 50 delayed 10-30s each.
Fix: Pairing mode + manual approval for 3 key contacts only.
Troubleshooting: QR Fails, Reconnect Loops
QR Code Won't Display
Symptom: openclaw channels login runs but no QR appears.
Causes:
- Terminal doesn't support image rendering
- Firewall blocking Gateway port 18789
- Gateway not running
Fix:
# Ensure Gateway is running
openclaw gateway status
# If not running, start it
openclaw gateway start
# Try login again
openclaw channels login --channel whatsapp
If still failing, access the QR via web UI:
# Open browser to
http://127.0.0.1:18789/
# Navigate to Channels → WhatsApp → Link Device
# QR displays in browser
"Linked but Disconnected" / Reconnect Loop
Symptom: openclaw channels status shows running, disconnected or logs show constant reconnect attempts.
Per official troubleshooting docs, this happens when:
- Credentials file is corrupted
- Another instance is using the same session
- WhatsApp banned the session (rare, but happens with aggressive automation)
Fix 1: Run doctor (detects common misconfigurations):
openclaw doctor
If it reports issues, apply fixes:
openclaw doctor --fix
Fix 2: Restart Gateway:
openclaw gateway restart
Fix 3: Relink session:
# Stop Gateway
openclaw gateway stop
# Remove old credentials
rm ~/.openclaw/credentials/whatsapp-creds.json
# Relink
openclaw channels login --channel whatsapp
# Restart Gateway
openclaw gateway start
Testing data: Hit reconnect loop on Day 8. Logs showed [Baileys] Connection lost, retrying... every 10 seconds. Ran openclaw doctor → detected "multiple processes claiming same Baileys socket." Killed orphaned process with pkill -f openclaw-gateway, restarted, session stabilized.
Mass Pairing Messages Sent to Contacts
Symptom: Your contacts receive pairing code messages when you don't expect it.
This is a known bug tracked in GitHub issue #834. It happens when:
- You partially set up WhatsApp (scanned QR but never finished pairing)
- Gateway restarts or crashes
- Pairing mode is enabled (
dmPolicy: pairing) - Gateway sends pairing codes to all contacts instead of just new senders
Immediate fix (if it's happening right now):
# STOP THE GATEWAY IMMEDIATELY
openclaw gateway stop
# OR kill the process
pkill -f openclaw-gateway
# Remove pairing requests file
rm ~/.openclaw/credentials/whatsapp-pairing.json
# Change config to allowlist mode
nano ~/.openclaw/openclaw.json
Change:
{
"channels": {
"whatsapp": {
"dmPolicy": "allowlist",
"allowFrom": ["+1234567890"] // Your own number only
}
}
}
Prevention:
- Always complete QR pairing - Don't abort
openclaw channels loginmid-scan - Use allowlist mode initially - Only switch to pairing after testing
- Test with self-chat first - Message yourself to verify behavior before adding contacts
My embarrassing story: On my second deployment, I scanned the QR, saw "Connected!" but Gateway crashed 30 seconds later (OOM on 2GB RAM VPS). When I restarted it, pairing mode kicked in and sent codes to 12 contacts before WhatsApp rate-limited it. Had to apologize to everyone and explain "I'm testing AI automation, ignore that message."
Security Checklist (What Not to Do)
Critical Security Rules
1. Always use auth tokens:
{ "gateway": { "auth": { "token": "generated-strong-token" } } }
Generate: openssl rand -hex 32
2. Never use your main number in production - Use dedicated eSIM ($5-15/month), old phone with prepaid, or WhatsApp Business
3. Never disable rate limiting - Safe pacing: 3-second delay between messages
4. Never expose Gateway publicly:
# ✅ CORRECT
ports: - "127.0.0.1:18789:18789"
Remote access via SSH tunnel or Tailscale
5. Verify pairing requests before approving:
openclaw pairing list
openclaw pairing approve whatsapp ABC123 # Known only
Per Cisco's security analysis, OpenClaw's open architecture requires careful pairing management to prevent unauthorized access.
My Setup After 3 Iterations
Current config (23 days stable):
- Dedicated Google Fi eSIM ($20/month, unlimited data, good for traveling)
- Allowlist mode with 3 approved contacts (me + 2 family)
- Gateway running on Hetzner VPS (static IP, systemd auto-restart)
- Daily credential backups via cron
- Tailscale for remote dashboard access (no port exposure)
What I learned:
- 별도의 번호가 가치가 있어요 - 셀프 채팅은 가능하지만 자신의 채팅에서 봇의 답변을 보는 이상한 사용자 경험을 만들어냅니다. 전용 번호는 라우팅을 깔끔하게 유지시켜 줍니다.
- 페어링 모드는 초보자에게 위험해요 - 대량 메시지 버그로 한 번 데인 적이 있어요. 시작은 허용 목록으로 하고, 나중에 필요하면 페어링을 추가하세요.
- WhatsApp의 속도 제한은 현실이에요 - 테스트 중 두 번 소프트 스로틀링을 당했어요. 이제 모든 자동화를 분당 20개 미만의 메시지로 속도를 조절합니다.
- 세션 지속성은 IP 안정성에 달려 있어요 - 모바일 핫스팟 배포가 고정 IP VPS보다 3배 더 많은 연결 끊김을 겪었어요.
- 업데이트 전마다 자격 증명을 백업하세요 - v2026.1.24 → v2026.1.29로 업데이트하면서 자격 증명 파일 형식이 깨졌어요. 백업 덕분에 롤백이 가능했어요.
시스템 인사이트: 지속 가능한 WhatsApp 연결은 세 가지 기둥으로 이루어져 있어요: 전용 번호, 보수적인 속도 제한, 그리고 페어링 흐름을 철저히 테스트할 때까지 허용 목록 모드. 이 중 어느 하나라도 건너뛰면, 일주일 내로 차단, 재연결, 창피한 연락처 스팸을 겪게 될 거예요.
더 깔끔한 채팅-액션 워크플로우를 원하시나요? Macaron에 가입하세요—우리는 메시징 플랫폼 통합, 속도 제한, 세션 지속성을 처리해 드리므로 Baileys 재연결 루프 디버깅 대신 자동화 구축에 집중할 수 있습니다.
FAQ
Q: 여러 개의 OpenClaw 인스턴스에서 동일한 WhatsApp 번호를 사용할 수 있나요? 아니요. 한 번호, 한 게이트웨이입니다. 인스턴스 간 세션을 공유하면 Baileys 인증이 깨지고 거의 즉시 재연결 루프가 발생합니다.
Q: QR 코드가 스캔하기 전에 만료되는 이유는 무엇인가요? 60초의 제한 시간이 짧습니다. openclaw channels login을 실행하기 전에 휴대폰에서 WhatsApp을 열어두세요 — 설정 → 연결된 기기 → 기기 연결을 준비하세요.
Q: 허용 목록과 페어링 모드의 차이는 무엇인가요? 허용 목록은 사전에 승인한 연락처의 메시지만 수신합니다. 페어링 모드는 페어링 코드를 알고 있는 누구나 수신할 수 있습니다. 허용 목록으로 시작하세요 — 페어링 모드는 게이트웨이가 설정 중간에 재시작되면 연락처에 스팸을 보낼 수 있는 알려진 버그가 있습니다.
Q: 제 세션이 밤새 계속 끊어집니다. 뭐가 문제인가요? 보통 IP 안정성 문제입니다. 모바일 핫스팟이나 동적 IP 환경은 고정 IP보다 3배 더 많은 연결 끊김을 유발합니다. VPS로 이동하거나 Tailscale을 추가하여 안정적인 라우팅을 확보하세요.
Q: WhatsApp에서 자동화로 인해 제 번호가 차단될까요? 그럴 수 있습니다, 특히 VoIP 번호나 공격적인 메시지 전송 속도일 경우. 실제 모바일 번호를 사용하고, 분당 20건 이하로 메시지를 보내며, 속도 제한을 절대 비활성화하지 마세요. 저는 이를 존중하기 전에 두 번 경고를 받았습니다.
Q: 자격 증명을 백업해야 하나요? 네, 업데이트 전마다 백업해야 합니다. 버전 업그레이드는 종종 자격 증명 파일 형식을 조용히 깨뜨릴 수 있습니다. v2026.1.24 → v2026.1.29 업데이트 동안 백업 덕분에 전체 재연결을 피했습니다.
