إعداد OpenClaw WhatsApp: الاتصال، المصادقة، وتجنب انقطاع الجلسات

مرحبًا، مستخدمي واتساب المتميزين. إذا كنت تقوم بتوصيل OpenClaw إلى واتساب وتواجه مشاكل في فشل رمز الاستجابة السريعة أو تكرار الاتصال أو (في أسوأ الحالات) أرسلت عن طريق الخطأ رموز الاقتران لجهات الاتصال الخاصة بك، فأنت لست وحدك.

لقد قمت بتوصيل واتساب على ثلاث حالات مختلفة من OpenClaw وواجهت كل أنواع الفشل الكبرى: انقطاع الجلسات بعد 24 ساعة، حظر بسبب تجاوز الحدود الذي أبعدني لمدة 3 أيام، وحادث محرج حيث قام وضع الاقتران بإرسال رسائل إلى 12 جهة اتصال قبل أن يتدخل محدد السرعة في واتساب.

إليك تدفق الإعداد الذي يعمل بالفعل، كيفية الحفاظ على الجلسات نشطة، وأخطاء الأمان التي قد تؤدي إلى حظر رقمك.

ما هو مطلوب (حساب + موصل)

متطلبات رقم الهاتف

يستخدم OpenClaw بروتوكول واتساب ويب عبر Baileys، وهي نفس التقنية التي تعمل على تشغيل واتساب ويب في متصفحك. ستحتاج إلى رقم هاتف جوال حقيقي - حيث يتم حظر أرقام 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:

1. Wizard displays QR code in terminal
2. You scan it via WhatsApp → Settings → Linked Devices → Link a Device
3. WhatsApp creates a session and saves credentials to ~/.openclaw/credentials/whatsapp-creds.json
4. 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:

1. Terminal doesn't support image rendering
2. Firewall blocking Gateway port 18789
3. 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:

1. You partially set up WhatsApp (scanned QR but never finished pairing)
2. Gateway restarts or crashes
3. Pairing mode is enabled (dmPolicy: pairing)
4. 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 login mid-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:

1. قيمة الرقم المخصص - الدردشة الذاتية تعمل ولكنها تخلق تجربة مستخدم غريبة (رؤية ردود البوت في دردشتك الخاصة). الرقم المخصص يحافظ على توجيه نظيف.
2. وضع الإقران خطير للمبتدئين - خطأ في الرسائل الجماعية أضرني مرة. ابدأ بقائمة السماح، ثم أضف الإقران لاحقًا إذا لزم الأمر.
3. حدود معدلات واتساب حقيقية - تعرضت للتقييد مرتين أثناء الاختبار. الآن أقوم بتوزيع جميع الأتمتة أقل من 20 رسالة/الدقيقة.
4. استمرار الجلسة يعتمد على استقرار IP - عمليات النشر عبر نقطة الاتصال المحمولة تعرضت لانقطاعات أكثر بثلاث مرات من VPS الثابت.
5. نسخ بيانات الاعتماد قبل كل تحديث - الإصدار v2026.1.24 → v2026.1.29 أفسد تنسيق ملف بيانات الاعتماد. عمل التراجع فقط لأنني كنت أملك نسخة احتياطية.

نصيحة النظام: اتصال واتساب الذي يدوم هو الذي يستند إلى ثلاثة أعمدة: رقم مخصص، تحديد معدل محافظ، ووضع قائمة السماح حتى تقوم باختبار تدفقات الإقران بشكل مكثف. إذا أغفلت أيًا من هذه ستواجه حظر، إعادة اتصال، أو رسائل مزعجة في غضون أسبوع.

تريد سير عمل أنظف من الدردشة إلى العمل؟ اشترك في Macaron - نحن نتعامل مع تكاملات منصات الرسائل، تحديد المعدلات، واستمرار الجلسات حتى تتمكن من التركيز على بناء الأتمتة بدلاً من تصحيح حلقات إعادة الاتصال في Baileys.

الأسئلة الشائعة

س: هل يمكنني استخدام نفس رقم WhatsApp على عدة OpenClaw حالات؟ لا. رقم واحد، بوابة واحدة. مشاركة الجلسات عبر الحالات تعطل مصادقة Baileys وستتعرض لدورات إعادة الاتصال بسرعة كبيرة.

س: لماذا تنتهي صلاحية رمز الاستجابة السريعة قبل أن أتمكن من مسحه ضوئيًا؟ نافذة 60 ثانية ضيقة. افتح WhatsApp على هاتفك قبل تشغيل openclaw channels login — الإعدادات → الأجهزة المرتبطة → ربط جهاز، كن جاهزًا.

س: ما الفرق بين وضع القائمة البيضاء ووضع الاقتران؟ وضع القائمة البيضاء يقبل فقط الرسائل من جهات الاتصال التي قمت بالموافقة عليها مسبقًا. وضع الاقتران يقبل أي شخص يعرف رمز الاقتران الخاص بك. ابدأ بوضع القائمة البيضاء — وضع الاقتران به خطأ معروف يمكن أن يرسل رسائل غير مرغوب فيها إلى جهات الاتصال الخاصة بك إذا أعيد تشغيل البوابة في منتصف الإعداد.

س: جلستي تستمر في الانقطاع طوال الليل. ما المشكلة؟ عادةً ما تكون مشكلة استقرار IP. تتسبب نقطة الاتصال المتنقلة أو بيئات IP الديناميكية في انقطاعات أكثر 3 مرات من IP الثابت. انتقل إلى VPS أو أضف Tailscale لتوجيه مستقر.

س: هل سيحظر WhatsApp رقمي بسبب الأتمتة؟ يمكن، خاصة مع أرقام VoIP أو معدلات الرسائل العدوانية. استخدم رقم هاتف حقيقي، حافظ على الإرسال تحت 20 رسالة/دقيقة، ولا تقم أبدًا بتعطيل تحديد المعدل. تعرضت لتحديد السرعة الناعمة مرتين قبل أن أحترم ذلك.

س: هل أحتاج إلى نسخ بيانات الاعتماد احتياطيًا؟ نعم، في كل مرة قبل التحديث. يمكن لترقيات الإصدار أن تكسر بصمت تنسيق ملف الاعتماد. أنقذني النسخ الاحتياطي من إعادة الربط بالكامل خلال v2026.1.24 → v2026.1.29.