OpenClaw 채널 연결 끊김 및 재연결 문제 해결 튜토리얼

서문

채널 연결 끊김은 OpenClaw 사용 중 가장 골치 아픈 문제 중 하나입니다. 사용자가 채팅 앱에서 메시지를 보냈는데 답장이 오지 않는 경우, 대부분 채널 연결이 끊어진 것이 원인입니다. 본 글에서는 각 플랫폼별 연결 끊김 원인, 해결 방법 및 예방 조치를 체계적으로 소개합니다.

1. 공통 진단 단계

어떤 채널에서 연결이 끊기든 먼저 다음 공통 진단을 수행할 수 있습니다:

# 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

채널 상태 의미

2. 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/

3. 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 Long Polling 모드

Webhook에 계속 문제가 있다면 Long Polling 모드로 전환할 수 있습니다:

// ~/.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
    }
  }
}

4. 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. 공통 재연결 및 Keep-Alive 설정

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. 진단 명령어 참고

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. 자동화된 연결 끊김 복구

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 -

8. 연결 끊김 예방 모범 사례

1. 네트워크 안정성 유지: 서버 운영 시 Wi-Fi 대신 유선 네트워크 사용
2. 프로세스 관리자 사용: PM2 또는 Systemd로 충돌 시 자동 재시작 구현
3. 정기적인 Session 백업: 특히 WhatsApp의 Session 파일
4. 채널 상태 모니터링: Uptime Kuma 또는 Prometheus와 연동하여 모니터링
5. 로그 알림: disconnect 키워드가 감지되면 알림 발송
6. 소프트웨어 최신 업데이트 유지: npm update -g openclaw@latest로 최신 연결 수정 사항 반영
7. 합리적인 재연결 전략 설정: 지수 백오프를 사용하여 과도한 재연결 방지

위의 방법으로 문제를 해결하고 설정을 구성하면 OpenClaw의 채널 연결이 더욱 안정적이고 신뢰할 수 있게 됩니다.