OpenClaw WhatsApp 设置：连接、认证，避免会话中断

你好，WhatsApp 高级用户。如果你在将 OpenClaw 连接到 WhatsApp 时遇到二维码失败、重连循环，或最糟糕的是不小心用配对代码轰炸了你的联系人，不用担心，你并不孤单。

我在三个不同的 OpenClaw 实例上设置了 WhatsApp 连接，遇到了每种主要故障模式：24 小时后会话中断、导致我被锁定 3 天的速率限制禁令，还有一次尴尬的事件，在 WhatsApp 的速率限制器启动之前，配对模式向 12 个联系人群发了信息。

以下是实际有效的设置流程，如何保持会话活跃，以及那些会导致你的号码被禁用的安全错误。

所需条件（账户 + 连接器）

手机号码要求

OpenClaw 通过 Baileys 使用 WhatsApp Web 协议，这项技术同样驱动着浏览器中的 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 号码吗？ 不行。一个号码，一个网关。在不同实例间共享会话会破坏 Baileys 认证，并几乎立刻导致重新连接循环。

问：为什么我的二维码在扫描前就过期了？ 60 秒的窗口很紧。运行 openclaw channels login 前，先在手机上打开 WhatsApp — 设置 → 已连接设备 → 连接设备，准备就绪。

问：白名单模式和配对模式有什么区别？ 白名单只接受您预先批准的联系人信息。配对模式接受任何知道您的配对码的人。建议先使用白名单模式 — 配对模式有一个已知的错误，如果网关在设置过程中重启，可能会向您的联系人发送垃圾信息。

问：我的会话总是在夜间掉线。出了什么问题？ 通常是 IP 稳定性问题。移动热点或动态 IP 环境导致的断连比静态 IP 多 3 倍。建议转移到 VPS 或添加 Tailscale 以获得稳定的路由。

问：WhatsApp 会因为自动化而封禁我的号码吗？ 可能会，尤其是使用 VoIP 号码或消息发送速率过高时。使用真实的手机号码，保持发送速度在每分钟 20 条以下，永远不要禁用速率限制。我之前被软限制过两次，后来才遵循这个规则。

问：我需要备份凭证吗？ 需要，每次更新前都要备份。版本升级可能会默默破坏凭证文件格式。一次备份让我在 v2026.1.24 → v2026.1.29 更新时避免了完全重新链接。