问题描述
使用 OpenClaw 的 WhatsApp 频道时，连接可能会频繁断开，终端中反复出现以下日志：
[openclaw:whatsapp] Connection closed. Reason: 408 (Connection timed out)
[openclaw:whatsapp] Reconnecting in 5s... (attempt 3/10)
或者更严重的断连：
[openclaw:whatsapp] Connection closed. Reason: 515 (Stream error)
[openclaw:whatsapp] Session invalidated. Please re-scan QR code.
OpenClaw 的 WhatsApp 频道基于 Baileys 库实现，这是一个非官方的 WhatsApp Web API 客户端。由于 WhatsApp 没有提供官方的 Bot API（Business API 需要付费申请），Baileys 通过模拟 Web 客户端的方式连接，因此连接稳定性受多种因素影响。
常见原因
1. 多设备登录冲突
WhatsApp 的多设备功能有连接数限制。如果你在多个地方同时运行 OpenClaw 实例连接同一个 WhatsApp 账号，或者同时在浏览器上使用 WhatsApp Web，可能会导致会话冲突。
2. 会话凭证过期或损坏
Baileys 将会话认证信息存储在本地文件中。如果这些文件损坏或过期，连接将无法恢复，必须重新扫码配对。
3. 网络不稳定
WhatsApp 的服务器对连接质量敏感。高延迟、频繁丢包或代理不稳定都可能导致连接超时。
4. WhatsApp 服务端更新
WhatsApp 会定期更新其协议，Baileys 库需要相应更新以保持兼容。使用过旧版本的 Baileys 可能导致连接被拒绝。
诊断步骤
查看 OpenClaw 的 WhatsApp 频道日志，启用详细调试模式：
DEBUG=openclaw:whatsapp* openclaw start
检查会话存储目录是否存在且有内容：
ls -la ~/.openclaw/sessions/whatsapp/
正常情况下，这个目录应包含 creds.json 和若干 app-state-sync-*.json 文件。
检查 Baileys 库的版本：
npm list -g @whiskeysockets/baileys
解决方案
方案一：重新配对设备
清除旧的会话数据并重新扫描 QR 码：
# 停止 OpenClaw
openclaw stop
# 备份旧会话（以防万一）
mv ~/.openclaw/sessions/whatsapp ~/.openclaw/sessions/whatsapp.bak
# 重新启动，将生成新的 QR 码
openclaw start
启动后终端会显示 QR 码，用手机 WhatsApp 扫描即可。在手机 WhatsApp 中进入「已关联设备」，先移除所有旧的关联设备，然后重新扫码关联。
方案二：优化会话存储
默认的文件系统存储在高频读写下可能出现竞态问题。在 ~/.openclaw/openclaw.json 中配置使用更可靠的存储方式：
{
"channels": {
"whatsapp": {
"sessionStore": {
"type": "sqlite",
"path": "~/.openclaw/sessions/whatsapp.db"
}
}
}
}
SQLite 存储提供了事务保证，减少了会话文件损坏的可能性。
方案三：配置重连策略
在配置文件中调整重连参数，使连接恢复更可靠：
{
"channels": {
"whatsapp": {
"reconnect": {
"maxRetries": 20,
"baseDelay": 3000,
"maxDelay": 60000,
"backoffFactor": 1.5
},
"keepAlive": {
"intervalMs": 25000,
"timeoutMs": 60000
}
}
}
}
keepAlive 设置会定期发送心跳包以维持连接活跃。reconnect 的指数退避策略可以避免因频繁重连而被 WhatsApp 服务器限制。
方案四：更新 Baileys 依赖
确保使用最新版本的 Baileys 库：
npm update -g openclaw
如果 OpenClaw 的最新版本仍然使用旧版 Baileys，可以关注 OpenClaw 的 GitHub Issues 了解更新进度。
方案五：检查网络环境
如果你在代理或 VPN 后面运行 OpenClaw，确保 WebSocket 连接不会被代理中断：
# 测试到 WhatsApp 服务器的连接
curl -v https://web.whatsapp.com
某些企业防火墙会阻止 WebSocket 长连接。如果是这种情况，考虑将 OpenClaw 部署在没有网络限制的环境中。
预防措施
为了减少断连的发生频率，建议遵循以下最佳实践：
- 只在一个 OpenClaw 实例中使用同一个 WhatsApp 账号
- 保持 OpenClaw 和系统时间同步（NTP 时间偏差可能导致认证失败）
- 定期备份
~/.openclaw/sessions/whatsapp/目录 - 使用进程管理器（如 PM2 或 systemd）管理 OpenClaw 进程，确保崩溃后自动重启