$cd ../troubleshooting/
⚠ High Impact#WhatsApp
WhatsApp 会话频繁断线
WhatsApp 会话死循环是新 OpenClaw 用户最常见的问题之一。根本原因几乎总是以下三种之一：容器重启时未持久化认证文件、WhatsApp 与手机绑定的会话模型撤销了 Web 会话，或者过时的 Baileys 库无法正确维护多设备协议。本指南针对每种原因提供精准修复——大多数用户能在 10 分钟内永久解决此问题。
symptom.log
🔍 症状
[ERROR] WhatsApp session expired. Reconnecting...
[INFO] QR code generated. Scan to re-authenticate.
[ERROR] Connection closed. Stream error: Invalid session
[INFO] Waiting 30s before retry...
✓ 在 openclaw 日志中看到此错误循环每隔几小时重复一次
✓ 每次重启后 WhatsApp 都要求扫描新二维码
✓ 断线窗口期内发送的消息被静默丢弃
✓ 会话保持数小时或数天后突然无预警中断
root_cause.md
🧪 根本原因（选择您的情况）
#A
认证文件未在重启后持久化
// 如果在没有 volume 挂载的 Docker 中运行，Baileys auth 文件夹在每次重启时都会被清除。auth 文件夹包含加密的会话密钥——没有它们，OpenClaw 每次都必须从头重新认证，意味着每次都需要新二维码。
#B
手机上 WhatsApp 已退出
// WhatsApp Web 会话与您的手机 WhatsApp 账号绑定。如果手机 WhatsApp 退出、卸载或更换 SIM 卡，所有关联的 Web 会话会立即被吊销。这是 WhatsApp 的安全设计，不是 Bug。
#C
Docker 容器在没有 volume 的情况下重建
// 运行 'docker compose up --force-recreate' 或 'docker rm' 会销毁容器文件系统，包括认证状态。即使之前有正常会话，在没有持久卷的情况下重建容器也会清除它。
#D
Baileys 版本不匹配
// 过旧的 Baileys 版本可能与当前 WhatsApp 多设备协议存在会话密钥格式不兼容问题。WhatsApp 会定期更新协议，旧库版本会静默失去兼容性。
fix.sh
✅ 修复方法
修复 A — 在 Docker Compose 中挂载 auth 卷
# docker-compose.yml
services:
openclaw:
volumes:
- ./data/whatsapp-auth:/app/auth # ← add this
修复 B — 在配置中启用自动重连
# config.yaml
channels:
whatsapp:
auto_reconnect: true
reconnect_interval_ms: 5000
max_reconnect_attempts: 10
notify_on_disconnect: true # Telegram alert
ping_interval_ms: 20000 # prevents idle timeout
修复 C — 更新 Baileys
$ npm update @whiskeysockets/baileys
$ rm -rf auth/ # wipe old auth, rescan QR once
$ openclaw gateway restart
🛡️ 预防清单
- ✓将 auth 目录挂载为命名 Docker 卷——切勿依赖容器文件系统
- ✓保持手机 WhatsApp 已安装且激活——不要在手机上退出 WhatsApp
- ✓每月运行 'npm update @whiskeysockets/baileys' 以跟上协议变更
- ✓启用 'notify_on_disconnect: true' 以在会话断线时立即收到 Telegram 提醒
- ✓将 max_reconnect_attempts 设置为至少 10，使短暂网络故障自动恢复
❓ 常见问题
Q1. 为什么每次重启后二维码都会重新出现？
WhatsApp 会话在认证状态文件丢失时过期。auth 文件夹包含证明 OpenClaw 是关联设备的加密密钥。没有持久存储，Docker 会在每次重启时清除此文件夹。解决方案是将 ~/.openclaw/whatsapp-auth/ 挂载为 Docker 卷。挂载后，只要手机保持活跃，会话可无限期在重启后存活。
Q2. WhatsApp Web 会话能持续多久？
只要手机至少每 14 天连接一次 WhatsApp 服务器，WhatsApp 多设备会话就是无限期的。会话不会因时间限制而过期——只有在手机 WhatsApp 被卸载、退出，或您在 WhatsApp 设置中手动撤销关联设备时才会过期。
Q3. 可以使用 WhatsApp Business API 代替 Web 协议吗？
OpenClaw 目前使用 Baileys 多设备 Web 协议，适用于任何个人 WhatsApp 账号。官方 WhatsApp Business API 需要 Meta Business 账号并经历不同的审批流程。Web 协议对个人自动化、小型企业和每天消息量不超过约 1000 条的社区机器人已足够。
Q4. 可以同时关联多少台设备？
WhatsApp 允许每个账号最多关联 4 台设备。OpenClaw 算一台。如果您已达到上限（手机、web.whatsapp.com、WhatsApp 桌面版等），需要先取消关联一台才能连接 OpenClaw。在手机 WhatsApp 中进入「关联设备」，取消关联任何未使用的设备。
Q5. 断线期间发送的消息之后会被送达吗？
不会。会话断线时发送给 OpenClaw 的消息不会被 WhatsApp 排队——从 OpenClaw 角度看它们会丢失。发送者会看到单个对勾（已发送），但消息在 OpenClaw 重新连接并收到下一条消息之前不会被处理。启用自动重连（修复 B）可将此窗口从数小时缩短至数秒。
Q6. 我的会话恰好在 12-14 小时后断线，原因是什么？
这种规律性通常指向网络问题而非认证问题。如果您的 ISP 或 VPS 提供商会循环 NAT 会话，长时间存活的 WebSocket 连接可能在固定空闲超时后被静默终止。在配置中启用 WhatsApp keepalive（ping_interval_ms: 20000）以防止连接看起来空闲。同时检查防火墙或 Docker 网络是否配置为断开长时间存活的连接。