OpenClaw을 사용하여 여러 채팅 플랫폼에 연결할 때 다양한 연결 문제를 피할 수 없습니다. 이 글에서는 각 채널에서 가장 흔하게 발생하는 장애 시나리오와 문제 해결 방법을 정리하여, 문제를 빠르게 파악하고 해결하는 데 도움을 드립니다.
일반적인 문제 해결 절차
어떤 채널에서 문제가 발생하든, 먼저 다음과 같은 일반적인 점검을 수행하는 것이 좋습니다:
채널 상태 확인: openclaw channels status 명령을 실행하여 각 설정된 채널의 연결 상태, 마지막 활동 시간, 오류 정보를 확인합니다.
로그 확인: OpenClaw의 로그 파일에는 자세한 연결 및 메시지 처리 정보가 포함되어 있습니다. openclaw logs --channel <channel-name>을 사용하여 특정 채널의 로그를 필터링할 수 있습니다. 더 자세한 정보가 필요하면 설정에서 로그 레벨을 debug로 조정할 수 있습니다.
설정 파일 검증: openclaw config validate를 사용하여 openclaw.json의 구문 오류 및 필수 필드 누락을 확인합니다. 많은 문제의 원인은 설정 파일의 오타나 필드 누락입니다.
네트워크 연결 확인: OpenClaw 인스턴스가 대상 플랫폼의 API 서버에 접근할 수 있는지 확인합니다. 웹훅이 필요한 채널의 경우, 서버가 외부에서 접근 가능한지 확인하세요.
Telegram 일반적인 문제
Bot이 메시지를 수신하지 못함: 가장 흔한 원인은 다른 프로그램이 동일한 Bot Token으로 getUpdates를 호출하고 있는 경우입니다. Telegram의 Bot API는 두 클라이언트가 동시에 롱 폴링을 사용하는 것을 허용하지 않습니다. 해당 봇을 사용하는 OpenClaw 인스턴스가 하나만 실행 중인지 확인하세요.
그룹에서 응답하지 않음: Privacy Mode 설정을 확인하세요. Privacy Mode가 활성화되어 있으면(기본값) 봇은 명령과 @멘션만 수신할 수 있습니다. BotFather에서 Privacy Mode를 비활성화한 후, 그룹에서 봇을 제거하고 다시 추가해야 합니다.
메시지 서식 문제: Telegram의 MarkdownV2는 특수 문자에 대한 엄격한 이스케이프 규칙이 있습니다. AI 응답에 _, *, [ 같은 문자가 포함되면 서식 오류가 발생할 수 있습니다. parseMode를 HTML 또는 일반 텍스트로 변경해 보세요.
WhatsApp 일반적인 문제
QR 코드 만료: WhatsApp QR 코드는 유효 기간이 짧아 만료 전에 스캔해야 합니다. 만료된 경우 openclaw channels login whatsapp을 실행하여 QR 코드를 재생성하세요.
잦은 연결 끊김: WhatsApp은 장기 WebSocket 연결을 사용하므로 불안정한 네트워크에서 연결이 끊기기 쉽습니다. OpenClaw에는 대부분의 경우 복구를 처리하는 자동 재연결 메커니즘이 내장되어 있습니다. 연결 끊김이 지속되면 서버의 네트워크 품질과 방화벽 설정을 확인하세요.
계정 차단 위험: WhatsApp은 자동화된 사용에 대해 엄격한 제한이 있습니다. 봇이 너무 자주 메시지를 보내거나 많은 신고를 받으면 계정이 차단될 수 있습니다. 전송 빈도를 제어하고, 대량 메시지를 능동적으로 보내지 말며, 봇이 알려진 사용자의 요청에만 응답하도록 하세요.
다중 기기 로그인 충돌: Baileys는 다중 기기 프로토콜을 사용하지만, 휴대폰에서 WhatsApp Web에서 로그아웃하거나 휴대폰을 변경하면 봇의 연결이 무효화되어 QR 코드를 다시 스캔해야 합니다.
Discord 일반적인 문제
Bot이 오프라인으로 표시: Bot Token이 유효하고 봇이 대상 서버에 초대되었는지 확인합니다. 초대 링크의 권한 범위에 bot과 applications.commands가 포함되어 있는지 확인하세요.
메시지를 읽을 수 없음: Discord의 Privileged Gateway Intents는 Discord Developer Portal에서 수동으로 활성화해야 합니다. Bot 설정 페이지에서 Message Content Intent를 활성화하세요. 그렇지 않으면 봇이 메시지 내용을 읽을 수 없습니다.
권한 부족: 서버에서 봇의 역할 권한을 확인하여 "메시지 읽기" 및 "메시지 보내기" 권한이 있는지 확인합니다. 채널 수준의 권한 재정의로 인해 봇이 특정 채널에서 작동하지 못할 수도 있습니다.
Slack 일반적인 문제
이벤트 구독 실패: Slack은 이벤트 구독 설정 시 검증을 위한 challenge 요청을 보냅니다. OpenClaw의 웹훅 엔드포인트가 외부에서 접근 가능하고 challenge 응답을 올바르게 처리하는지 확인하세요.
Bot이 응답하지 않음: OAuth Scopes에 chat:write, channels:history, im:history 등 필요한 권한이 포함되어 있는지 확인합니다. Socket Mode와 Event API 모드는 설정 요구사항이 다릅니다. 올바른 모드를 사용하고 있는지 확인하세요.
토큰 만료: Bot Token 대신 사용자 토큰을 사용하는 경우 만료될 수 있습니다. 만료되지 않는 Bot Token을 항상 사용하는 것을 권장합니다.
Signal 일반적인 문제
signal-cli 연결 문제: OpenClaw의 Signal 채널은 signal-cli 도구에 의존합니다. signal-cli가 올바르게 설치되었고 번호 등록/연결이 완료되었는지 확인하세요. signal-cli -u +번호 receive를 실행하여 메시지가 정상적으로 수신되는지 테스트할 수 있습니다.
메시지 지연: signal-cli는 폴링 방식으로 메시지를 가져오므로 몇 초의 지연이 발생할 수 있습니다. 이는 정상적인 현상이며 폴링 간격을 조정하여 최적화할 수 있습니다.
플러그인 채널 일반적인 문제
플러그인 시스템을 통해 설치된 채널(Lark, Mattermost, Nostr 등)의 일반적인 문제는 다음과 같습니다:
플러그인 버전 비호환: openclaw plugin update <plugin-name>을 실행하여 최신 버전으로 업데이트합니다. 플러그인 버전과 OpenClaw 본체 버전 간에 호환성 요구사항이 있을 수 있습니다.
플러그인 로드 실패: openclaw plugin list 출력에서 플러그인 상태가 active로 표시되는지 확인합니다. error로 표시되면 자세한 로그에서 구체적인 오류 원인을 확인하세요.
웹훅 관련 문제
여러 채널(Lark, Zalo, Google Chat 등)은 웹훅에 의존하여 메시지를 수신합니다. 일반적인 웹훅 문제는 다음과 같습니다:
SSL 인증서 문제: 대부분의 플랫폼은 웹훅에 HTTPS를 요구합니다. SSL 인증서가 유효하고 만료되지 않았는지 확인하세요. 자체 서명 인증서는 일반적으로 허용되지 않습니다.
타임아웃 문제: 웹훅 요청을 보낸 후 플랫폼은 보통 몇 초 이내에 응답을 기대합니다. AI 처리에 더 많은 시간이 필요한 경우, OpenClaw은 먼저 200 확인 응답을 반환한 후 비동기적으로 메시지를 처리하고 능동적으로 답장을 보냅니다.
IP 화이트리스트: 일부 플랫폼(예: Lark)은 특정 IP 범위에서만 웹훅 요청을 보냅니다. 방화벽에 인바운드 규칙이 있는 경우, 이러한 IP가 허용되는지 확인하세요.
자동 재연결 메커니즘
OpenClaw은 모든 채널에 대해 자동 재연결 메커니즘을 내장하고 있습니다. 연결 끊김이 감지되면 시스템은 지수 백오프 전략을 사용하여 재시도합니다. 첫 번째 연결 끊김 후 즉시 재시도하고, 이후 간격을 점진적으로 증가시킵니다(1초, 2초, 4초, 8초...). 기본 최대 간격은 60초입니다.
설정에서 재연결 매개변수를 조정할 수 있습니다:
{
"reconnect": {
"maxRetries": 50,
"maxInterval": 60,
"resetAfter": 300
}
}
resetAfter는 재시도 카운터가 초기화되기 전에 연결이 안정적으로 유지되어야 하는 시간(초)을 나타냅니다.
도움 받기
위의 문제 해결 방법으로도 문제가 해결되지 않으면, OpenClaw의 GitHub 저장소에 민감한 정보가 제거된 설정 파일과 관련 로그를 첨부하여 Issue를 제출할 수 있습니다. 커뮤니티는 보통 1~2일 이내에 응답합니다. Issue를 제출할 때 OpenClaw 버전, 운영 체제, 영향을 받는 채널 이름을 명시해 주세요.