OpenClaw WhatsApp 設定：連接、驗證與避免連線中斷

嘿，WhatsApp 的重度使用者們。如果你在將 OpenClaw 連接到 WhatsApp 時遇到 QR 碼失敗、重新連接迴圈，或（最糟糕的情況）不小心給聯絡人群發了配對碼，你並不孤單。

我在三個不同的 OpenClaw 實例上設置了 WhatsApp 連接，並遇到了每一個主要的故障模式：24 小時後的連線中斷、導致我被鎖定 3 天的速率限制封禁，以及一次尷尬的事件，配對模式在 WhatsApp 的速率限制器啟動之前群發了 12 個聯絡人。

這裡是實際有效的設定流程，如何保持會話活躍，以及會讓你的號碼被封禁的安全錯誤。

所需條件（帳戶 + 連接器）

手機號碼要求

OpenClaw 使用 WhatsApp Web 協議 透過 Baileys，這是驅動瀏覽器中 WhatsApp Web 的技術。你需要一個真實的手機號碼—VoIP 和虛擬號碼會被嚴格封鎖。

推薦設定：

Option

Best For

Cost

Setup Time

Dedicated phone + eSIM

Clean routing, no self-chat

$5-15/month eSIM

15 min

WhatsApp Business (same device)

Separate number, same phone

Free

10 min

Your main number (self-chat)

Testing only

Free

5 min

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:

Action

Limit

Window

Result

Messages

~40-50

1 min

Soft throttle

Messages

~200-300

1 hour

Hard throttle

New contacts

~20-30

1 day

Account flag

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 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:

獨立號碼值得擁有 - 自行聊天功能可行，但會造成奇怪的使用者體驗（在自己的聊天中看到機器人回應）。專用號碼可保持路由清晰。
配對模式對初學者來說很危險 - 群發消息錯誤曾經讓我吃過虧。先從允許名單開始，如果需要再添加配對。
WhatsApp 的速率限制是真實的 - 測試時我曾被軟限制兩次。現在我將所有自動化控制在每分鐘少於 20 條信息。
會話持續性取決於 IP 穩定性 - 移動熱點部署的斷線次數是靜態 IP VPS 的三倍。
每次更新前備份憑證 - 從 v2026.1.24 升級到 v2026.1.29 損壞了我的憑證文件格式。幸虧我有備份，才能進行回滾。

系統洞察： 持久的 WhatsApp 連接有三個支柱：專用號碼、保守的速率限制和允許名單模式，直到您廣泛測試配對流程。忽略其中任何一個，您將在一週內遇到封禁、重新連接或尷尬的聯繫人垃圾信息。

想要更流暢的聊天到行動工作流程嗎？註冊 Macaron——我們負責消息平台集成、速率限制和會話持續性，讓您專注於構建自動化，而不是調試 Baileys 重連循環。

常見問題

問：我可以在多個 OpenClaw 實例上使用相同的 WhatsApp 號碼嗎？ 不能。一個號碼對應一個 Gateway。在多個實例間共享會話會破壞 Baileys 認證，幾乎立刻導致重連循環。

問：為什麼我的 QR 碼在掃描前就過期了？ 60 秒的時限很緊。運行 openclaw channels login 前，先在手機上開啟 WhatsApp — 設定 → 已連結的裝置 → 連結裝置，準備就緒。

問：許可名單和配對模式有什麼區別？ 許可名單只接受您預先批准的聯絡人發送的消息。配對模式接受任何知道您配對代碼的人。從許可名單開始，因為配對模式有一個已知的錯誤，在 Gateway 中途重啟時可能會向聯絡人發送垃圾信息。

問：為什麼我的會話在夜間經常中斷？ 通常是 IP 穩定性問題。移動熱點或動態 IP 環境造成的斷連次數是靜態 IP 的三倍。移動到 VPS 或添加 Tailscale 以獲得穩定路由。

問：WhatsApp 會因為自動化而封禁我的號碼嗎？ 可能會，特別是使用 VoIP 號碼或高頻訊息發送時。使用真實的手機號碼，將發送量控制在每分鐘 20 條以下，並且絕不要禁用速率限制。在我遵守這些規則前，我被軟限制了兩次。

問：我需要備份憑據嗎？ 需要，每次更新之前都要備份。版本升級可能會默默破壞憑據文件格式。在 v2026.1.24 → v2026.1.29 更新期間，備份幫我避免了一次完全重新連結。