문제 설명
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는 세션 인증 정보를 로컬 파일에 저장합니다. 이 파일이 손상되거나 만료되면 연결을 복구할 수 없으며, QR 코드를 다시 스캔하여 페어링해야 합니다.
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
해결 방안
방안 1: 기기 재페어링
이전 세션 데이터를 삭제하고 QR 코드를 다시 스캔합니다:
# OpenClaw 중지
openclaw stop
# 이전 세션 백업 (만약을 위해)
mv ~/.openclaw/sessions/whatsapp ~/.openclaw/sessions/whatsapp.bak
# 재시작, 새 QR 코드가 생성됨
openclaw start
시작 후 터미널에 QR 코드가 표시되며, 핸드폰 WhatsApp으로 스캔합니다. 핸드폰 WhatsApp의 "연결된 기기"에서 먼저 모든 이전 연결된 기기를 제거한 후 다시 스캔하여 연결합니다.
방안 2: 세션 저장소 최적화
기본 파일 시스템 저장소는 높은 빈도의 읽기/쓰기에서 경쟁 조건이 발생할 수 있습니다. ~/.openclaw/openclaw.json에서 더 안정적인 저장 방식을 설정합니다:
{
"channels": {
"whatsapp": {
"sessionStore": {
"type": "sqlite",
"path": "~/.openclaw/sessions/whatsapp.db"
}
}
}
}
SQLite 저장소는 트랜잭션 보장을 제공하여 세션 파일 손상의 가능성을 줄입니다.
방안 3: 재연결 전략 설정
설정 파일에서 재연결 매개변수를 조정하여 연결 복구를 더 안정적으로 만듭니다:
{
"channels": {
"whatsapp": {
"reconnect": {
"maxRetries": 20,
"baseDelay": 3000,
"maxDelay": 60000,
"backoffFactor": 1.5
},
"keepAlive": {
"intervalMs": 25000,
"timeoutMs": 60000
}
}
}
}
keepAlive 설정은 연결을 활성 상태로 유지하기 위해 정기적으로 하트비트 패킷을 전송합니다. reconnect의 지수 백오프 전략은 빈번한 재연결로 인해 WhatsApp 서버에 의해 제한되는 것을 방지합니다.
방안 4: Baileys 종속성 업데이트
최신 버전의 Baileys 라이브러리를 사용하고 있는지 확인합니다:
npm update -g openclaw
OpenClaw의 최신 버전에서도 여전히 오래된 Baileys를 사용하는 경우, OpenClaw의 GitHub Issues에서 업데이트 진행 상황을 확인할 수 있습니다.
방안 5: 네트워크 환경 확인
프록시 또는 VPN 뒤에서 OpenClaw을 실행하는 경우, WebSocket 연결이 프록시에 의해 중단되지 않도록 합니다:
# WhatsApp 서버로의 연결 테스트
curl -v https://web.whatsapp.com
일부 기업 방화벽은 WebSocket 장기 연결을 차단합니다. 이 경우 네트워크 제한이 없는 환경에 OpenClaw을 배포하는 것을 고려하세요.
예방 조치
연결 끊김 빈도를 줄이기 위해 다음 모범 사례를 따르는 것을 권장합니다:
- 하나의 OpenClaw 인스턴스에서만 같은 WhatsApp 계정을 사용하세요
- OpenClaw과 시스템 시간을 동기화하세요 (NTP 시간 편차가 인증 실패를 유발할 수 있음)
~/.openclaw/sessions/whatsapp/디렉토리를 정기적으로 백업하세요- 프로세스 관리자(PM2 또는 systemd)로 OpenClaw 프로세스를 관리하여, 크래시 후 자동 재시작을 보장하세요