OpenClawチャネル切断と再接続のトラブルシューティングチュートリアル

はじめに

チャネルの切断は、OpenClaw の使用中に最も頭を悩ませる問題の一つです。ユーザーがチャットアプリでメッセージを送信しても、なかなか返信が届かない場合、チャネル接続が中断していることが原因であることが多いです。本記事では、各プラットフォームの切断原因、トラブルシューティング方法、および予防策を体系的にご紹介します。

一、共通の診断手順

どのチャネルで切断が発生しても、まず以下の共通診断を実行できます：

# 1. OpenClaw サービスの状態を確認
curl -s http://localhost:18789/health/detail | jq '.channels'

# 2. チャネル関連のログを確認
openclaw logs | grep -i "channel\|connect\|disconnect\|reconnect"

# 3. 総合診断の実行
openclaw doctor

# 4. ネットワーク接続性の確認
ping api.telegram.org
ping web.whatsapp.com
ping discord.com

チャネルステータスの意味

二、WhatsApp の切断トラブルシューティング

WhatsApp は接続メカニズムが比較的複雑なため、最も切断が頻繁に発生するチャネルです。

2.1 よくある切断原因

2.2 Session 期限切れの対処

# WhatsApp 接続ステータスの確認
openclaw logs | grep -i "whatsapp"

# session expired と表示される場合、再認証が必要
openclaw restart

# 再起動後、ログで新しい QR コードを確認
openclaw logs | grep -A 20 "QR Code"

2.3 Session の永続化設定

// ~/.config/openclaw/openclaw.json5
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      // Session の保存パス（デフォルトは ~/.openclaw/sessions/）
      "sessionPath": "/home/user/.openclaw/sessions/whatsapp",
      // オンライン維持のハートビート間隔（秒）
      "keepAliveInterval": 30,
      // 切断後の自動再接続
      "autoReconnect": true,
      // 最大再接続試行回数
      "maxReconnectAttempts": 10,
      // 再接続間隔（秒）
      "reconnectInterval": 15
    }
  }
}

2.4 WhatsApp 安定性の最適化

# session ファイルに正しいパーミッションがあることを確認
ls -la ~/.openclaw/sessions/whatsapp/
chmod 700 ~/.openclaw/sessions/whatsapp/

# session ファイルのバックアップ（頻繁な QR コード再スキャンを回避）
cp -r ~/.openclaw/sessions/whatsapp/ ~/whatsapp-session-backup/

三、Telegram の切断トラブルシューティング

Telegram は Bot API または MTProto プロトコルを使用しており、接続は比較的安定していますが、Webhook モードで問題が発生する場合があります。

3.1 Webhook モードの障害トラブルシューティング

# Webhook が正しく設定されているか確認
curl -s "https://api.telegram.org/bot<TOKEN>/getWebhookInfo" | jq .

# 正常なレスポンスには以下が含まれる：
# {
#   "url": "https://your-domain.com/webhook/telegram",
#   "has_custom_certificate": false,
#   "pending_update_count": 0,
#   "last_error_date": null,
#   "last_error_message": null
# }

Webhook のよくある問題と解決策：

# 問題1：SSL 証明書が無効
# 解決：Telegram Webhook は有効な HTTPS 証明書を要求します
sudo certbot renew

# 問題2：Webhook URL に到達できない
# 解決：ファイアウォールでポートが開放されていること、ドメイン名解決が正しいことを確認
curl -sf https://your-domain.com/webhook/telegram

# 問題3：メッセージの滞留が多すぎる
# 解決：滞留をクリアして Webhook をリセット
curl "https://api.telegram.org/bot<TOKEN>/deleteWebhook?drop_pending_updates=true"
# その後 OpenClaw を再起動すると、自動的に Webhook を再設定します
openclaw restart

3.2 ロングポーリングモード

Webhook で問題が続く場合、ロングポーリングモードに切り替えることができます：

// ~/.config/openclaw/openclaw.json5
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "mode": "polling",  // polling に変更
      "pollingInterval": 1000
    }
  }
}

3.3 Telegram の再接続メカニズム

{
  "channels": {
    "telegram": {
      "autoReconnect": true,
      "maxReconnectAttempts": 20,
      "reconnectInterval": 10,
      "keepAliveInterval": 25
    }
  }
}

四、Discord の切断トラブルシューティング

Discord は WebSocket Gateway 接続を使用しており、切断原因は通常 Gateway イベントに関連しています。

4.1 Gateway 切断コード

4.2 Discord Intents の設定

多くの切断問題は、必要な Gateway Intents が不足していることが原因です：

# 1. Discord Developer Portal にアクセス
# https://discord.com/developers/applications

# 2. Bot を選択 -> Bot 設定
# 3. 以下の Privileged Gateway Intents を有効化：
#    - Presence Intent
#    - Server Members Intent
#    - Message Content Intent

4.3 Discord の再接続設定

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "autoReconnect": true,
      "maxReconnectAttempts": 15,
      "reconnectInterval": 10,
      // ハートビート間隔（Discord サーバーが指定、通常 41250ms）
      "heartbeatInterval": 41250
    }
  }
}

五、共通の再接続とキープアライブ設定

5.1 グローバル再接続戦略

// ~/.config/openclaw/openclaw.json5
{
  "connection": {
    // グローバル自動再接続
    "autoReconnect": true,
    // 指数バックオフ再接続戦略
    "backoff": {
      "initialDelay": 5000,      // 初回再接続は 5秒待機
      "maxDelay": 300000,        // 最大 5分待機
      "multiplier": 2            // 毎回2倍
    },
    // 接続ヘルスチェック
    "healthCheck": {
      "enabled": true,
      "interval": 60000          // 60秒ごとにチェック
    }
  }
}

5.2 Keep-Alive 設定

{
  "connection": {
    "keepAlive": {
      "enabled": true,
      "interval": 30000,    // 30秒ごとにハートビート送信
      "timeout": 10000      // ハートビートタイムアウト時間
    }
  }
}

5.3 ネットワーク層の最適化

# システムレベルの TCP keepalive 設定を追加
echo "net.ipv4.tcp_keepalive_time = 60" | sudo tee -a /etc/sysctl.conf
echo "net.ipv4.tcp_keepalive_intvl = 10" | sudo tee -a /etc/sysctl.conf
echo "net.ipv4.tcp_keepalive_probes = 6" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

六、診断コマンドリファレンス

6.1 各チャネルのステータス確認

# 全チャネルのステータスを一括確認
curl -s http://localhost:18789/health/detail | jq '{
  channels: .channels,
  uptime: .uptime,
  status: .status
}'

6.2 切断イベントのリアルタイム監視

# 接続状態の変化をリアルタイム表示
openclaw logs | grep --line-buffered -E "connect|disconnect|reconnect|session|auth"

6.3 接続履歴の照会

# 直近の切断記録を確認
openclaw logs | grep -i "disconnect" | tail -20

# 各チャネルの切断回数を集計
openclaw logs | grep -i "disconnect" | awk '{print $NF}' | sort | uniq -c | sort -rn

七、切断からの自動復旧

7.1 外部監視スクリプト

#!/bin/bash
# /usr/local/bin/openclaw-channel-watchdog.sh

HEALTH_URL="http://localhost:18789/health/detail"
EXPECTED_CHANNELS=("whatsapp" "telegram" "discord")

check_channels() {
    local health=$(curl -sf "$HEALTH_URL" 2>/dev/null)
    if [ -z "$health" ]; then
        echo "[$(date)] OpenClaw サービスが利用不可" >> /var/log/openclaw-watchdog.log
        openclaw restart
        return
    fi

    for channel in "${EXPECTED_CHANNELS[@]}"; do
        local status=$(echo "$health" | jq -r ".channels.$channel" 2>/dev/null)
        if [ "$status" != "connected" ]; then
            echo "[$(date)] $channel ステータス異常: $status" >> /var/log/openclaw-watchdog.log
            # 再起動して復旧を試みる
            openclaw restart
            break
        fi
    done
}

check_channels

# 5分ごとに実行
chmod +x /usr/local/bin/openclaw-channel-watchdog.sh
echo "*/5 * * * * /usr/local/bin/openclaw-channel-watchdog.sh" | crontab -

八、切断を予防するためのベストプラクティス

1. ネットワークを安定させる：サーバーは Wi-Fi ではなく有線ネットワークを使用する
2. プロセスマネージャーを使用：PM2 または Systemd でクラッシュ時の自動再起動を実現
3. Session を定期的にバックアップ：特に WhatsApp の Session ファイル
4. チャネルステータスを監視：Uptime Kuma や Prometheus と連携した監視
5. ログアラート：disconnect キーワードの検出時に通知を送信
6. ソフトウェアを最新に保つ：npm update -g openclaw@latest で最新の接続修正を取得
7. 適切な再接続戦略を設定：指数バックオフで過度に頻繁な再接続を回避

以上の方法でトラブルシューティングと設定を行えば、OpenClaw のチャネル接続はより安定かつ信頼性の高いものになります。