2026 OpenClaw 接入 WhatsApp（Linux 雲 VPS）：二維碼配對、工作階段持久化與多通道並存——可復現步驟與斷連／429 分層排障 FAQ

在 Linux 雲 VPS 上掛 WhatsApp 通道，本質是託管「手機掃碼授權＋類 Web 長連線」：閘道程序要常駐、憑證目錄要落在持久卷、主機時間要可信，才能把二維碼配對、斷線重連與 429 限流拆成可復現的值班步驟。下文依我們線上踩坑順序撰寫，指令名稱以你安裝的 OpenClaw 發行版文件為準。

1. 前置：HTTPS、出口與目錄隔離

先完成公網 HTTPS（憑證鏈完整、反向代理到本機監聽埠無誤），再執行 openclaw doctor 做 TLS／寫入權限基線。與 Slack、Telegram 並存時，請為 WhatsApp 單獨指定 OPENCLAW_HOME 或獨立 profile，避免與其他通道共用同一工作階段落盤目錄而發生串線。閘道生產化 HTTPS 反代與回滾可對照：2026 OpenClaw Gateway 生產化：`openclaw onboard` 向導要點、`openclaw doctor`／`openclaw fix` 排障、Nginx／Caddy HTTPS 反代與升級回滾（Linux 雲主機可復現步驟與 FAQ）。

2. 可復現骨架（systemd 使用者單元示意）

# 1) 專用使用者 + 持久目錄
sudo useradd -r -m -s /bin/bash openclaw-wa
sudo mkdir -p /var/lib/openclaw-wa/{data,logs} && sudo chown -R openclaw-wa: /var/lib/openclaw-wa

# 2) onboard 勾選 WhatsApp／對應外掛，憑證目錄指向上方 data
# 3) 使用者層級 systemd（單元名稱依發行版文件）
loginctl enable-linger openclaw-wa
sudo -u openclaw-wa systemctl --user enable --now openclaw-gateway.service

以容器部署時請將 data 掛載為具名卷；更換映像檔前務必備份該卷，否則 QR 掃再多次，重開機仍會回到原點。單元啟停、日誌與連接埠探測的分級處置可延伸閱讀：2026 OpenClaw Linux 常駐排障：systemd 守護進程、openclaw logs 與網關連接埠探測的分級處置 FAQ。

3. 二維碼配對與工作階段持久化

首次於日誌或 openclaw 提供的本機終端機顯示二維碼，請以手機 WhatsApp「已連結的裝置」掃碼。憑證多為 JSON／嵌入式 KV，必須落於前述持久卷；系統時間漂移過大時常見「掃碼成功立刻掉線」，請先對齊 chrony／timedatectl 再查應用程式日誌。多通道搶工作階段時，維持單一 writer、獨立資料目錄是底線。

4. 斷連與 429：分層排障表