$cd ../troubleshooting/
⚠ High Impact#WhatsApp
WhatsAppセッションが切れ続ける
WhatsAppセッションの死亡ループは、OpenClawの新規ユーザーが最もよく遭遇する問題の一つです。根本原因はほぼ常に3つのうちどれかです：コンテナ再起動時に認証ファイルが保持されない、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が新しいQRコードのスキャンを要求する
✓ 切断ウィンドウ中に送信されたメッセージが静かに失われる
✓ セッションが数時間または数日保持された後、予告なく突然切れる
root_cause.md
🧪 根本原因（該当するものを選択）
#A
再起動後に認証ファイルが保持されない
// ボリュームマウントなしでDockerを実行している場合、Baileys authフォルダは毎回の再起動時に削除されます。authフォルダにはOpenClawがリンクされたデバイスであることを証明する暗号化されたセッションキーが含まれています。
#B
電話でWhatsAppからログアウト
// WhatsApp Webセッションは電話のWhatsAppアカウントに紐づいています。電話のWhatsAppがログアウト、アンインストール、またはSIM変更されると、すべてのリンクされたWebセッションが即座に無効化されます。
#C
ボリュームなしでDockerコンテナが再作成された
// '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に設定して一時的なネットワーク障害から自動回復する
❓ FAQ
Q1. なぜ再起動のたびにQRコードが表示されますか？
認証状態ファイルが失われるとWhatsAppセッションが期限切れになります。authフォルダにはOpenClawがリンクされたデバイスであることを証明する暗号化されたキーが含まれています。永続的なストレージなしでは、Dockerは再起動のたびにこのフォルダを削除します。解決策は~/.openclaw/whatsapp-auth/をDockerボリュームとしてマウントすることです。マウントすれば、電話がアクティブな限りセッションは再起動後も無期限に継続します。
Q2. WhatsApp Webセッションはどのくらい持続しますか？
電話が少なくとも14日に1回WhatsAppサーバーに接続している限り、WhatsAppマルチデバイスセッションは無期限です。セッションは時間制限によって期限切れにはなりません — 電話のWhatsAppがアンインストール、ログアウト、またはWhatsApp設定でリンクデバイスを手動で取り消した場合にのみ期限切れになります。
Q3. WhatsApp Business APIはWebプロトコルの代わりに使えますか？
OpenClawは現在、個人のWhatsAppアカウントで動作するBaileysマルチデバイスWebプロトコルを使用しています。公式WhatsApp Business APIはMeta Businessアカウントが必要で、異なる承認プロセスを経ます。Webプロトコルは個人の自動化、中小企業、1日約1000件未満のコミュニティボットに十分です。
Q4. 同時にいくつのデバイスをリンクできますか？
WhatsAppはアカウントあたり最大4台のリンクデバイスを許可します。OpenClawは1台としてカウントされます。すでに上限に達している場合は、OpenClawをリンクする前に1台のリンクを解除する必要があります。電話のWhatsAppで「リンク済みデバイス」に移動し、使用していないデバイスのリンクを解除してください。
Q5. 切断ウィンドウ中に送信されたメッセージは後で配信されますか？
いいえ。セッションが切断されている間にOpenClawに送信されたメッセージはWhatsAppによってキューに入れられません。送信者には1つのチェックマーク（送信済み）が表示されますが、OpenClawが再接続して次のメッセージを受信するまで処理されません。自動再接続を有効にすると（修正B）、このウィンドウを数時間から数秒に短縮できます。
Q6. セッションがちょうど12-14時間後に切れます。原因は何ですか？
この規則的なパターンは通常、認証の問題ではなくネットワークの問題を示しています。ISPやVPSプロバイダーがNATセッションをサイクルする場合、長時間のWebSocket接続が固定のアイドルタイムアウト後に静かに切断される可能性があります。設定でWhatsApp keepalive（ping_interval_ms: 20000）を有効にして、接続がアイドル状態に見えないようにしてください。