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，避免与其它通道共用同一会话落盘目录导致串会话。Gateway 生产化反代与回滚可对照：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 挂载为命名卷；换镜像前务必备份该卷，否则二维码扫十遍也会在重启后回到原点。

3. 二维码配对与会话持久化

首次在日志或 openclaw 提供的本地终端里展示 QR，用本机 WhatsApp「已连接的设备」扫码。凭据多为 JSON / 嵌入式 KV，必须落在上述持久卷；系统时间漂移过大时常见「扫码成功立刻掉线」，先对齐 chrony/timedatectl 再查应用日志。多通道抢会话、权限矩阵与 Telegram/Discord 侧经验可交叉阅读：2026 OpenClaw Telegram与Discord双通道接入实操：Bot配置、配对放行、权限矩阵与多通道冲突排障FAQ。

4. 断连与 429：分层排障表