OpenClaw WhatsApp 채널
메시징
보통
Baileys 프로토콜을 사용하여 OpenClaw를 WhatsApp에 연결합니다. 이 통합을 통해 Business API 없이도 AI 어시스턴트가 WhatsApp에서 메시지를 주고받을 수 있습니다. 스마트폰으로 QR 코드를 스캔하기만 하면 바로 사용할 수 있습니다. 깔끔한 라우팅을 위해 전용 전화번호 사용을 권장합니다.
기본 정보
난이도보통
카테고리메시징
지원 기능 수5 / 6
WhatsApp 지원 기능
텍스트 메시지
지원
미디어 및 파일
지원
리액션
지원
스레드
미지원
음성 메시지
지원
그룹 채팅
지원
WhatsApp 사전 요구사항
- WhatsApp 전용 전화번호 (개인 번호와 분리 권장)
- 서버에 Node.js 18+ 설치 (Bun은 권장하지 않음)
- OpenClaw Gateway 실행 및 구성 완료
WhatsApp 빠른 설정
1
WhatsApp 채널 구성 추가
~/.openclaw/openclaw.json에 WhatsApp 채널 구성을 추가합니다. dmPolicy(allowlist, pairing 또는 open)와 allowFrom 목록을 설정하여 어시스턴트에게 메시지를 보낼 수 있는 사용자를 제어합니다.
2
로그인 명령 실행 및 QR 코드 스캔
터미널에서 'openclaw channels login'을 실행합니다. QR 코드가 표시됩니다. 스마트폰의 WhatsApp으로 스캔하세요 (설정 > 연결된 기기 > 기기 연결). 인증 정보는 ~/.openclaw/credentials/whatsapp/에 저장됩니다.
3
테스트 메시지 전송
다른 스마트폰에서 WhatsApp 번호로 다이렉트 메시지를 보냅니다. allowlist 정책을 사용하는 경우 발신자 번호가 allowFrom 목록에 있는지 확인하세요. 기본 pairing 정책을 사용하는 경우 'openclaw pairing approve whatsapp <code>'로 발신자를 승인하세요.
WhatsApp 구성 예시
config.json
{
"channels": {
"whatsapp": {
"dmPolicy": "allowlist",
"allowFrom": ["+15551234567"]
}
}
}WhatsApp 상세 문서
아키텍처 개요
OpenClaw는 Baileys 라이브러리를 통해 WhatsApp에 연결됩니다. Baileys는 WhatsApp Web 멀티 디바이스 프로토콜의 리버스 엔지니어링된 오픈소스 구현체입니다. 공식 WhatsApp Business API(Meta 승인 필요, 대화당 과금)와 달리 Baileys는 연결된 기기를 에뮬레이션하여 직접 연결합니다.
아키텍처는 간단합니다: 스마트폰이 기본 기기로 유지되고, Gateway가 연결된 동반 기기로 작동합니다. 메시지는 평소처럼 WhatsApp 서버를 통해 전달되며, OpenClaw는 수신 메시지를 가로채 AI로 처리하고 응답을 다시 보냅니다.
연결이 스마트폰 기반이므로 스마트폰이 온라인 상태를 유지해야 합니다. 약 14일 이상 오프라인 상태가 되면 WhatsApp이 세션 연결을 해제합니다.
Baileys는 멀티 디바이스를 기본 지원합니다. 전화번호당 최대 4개의 연결된 기기를 가질 수 있으며, Gateway는 그 중 하나로 계산됩니다.
전화번호 설정
전용 전화번호 사용을 강력히 권장합니다. 개인 번호를 사용할 수도 있지만, 개인 대화와 봇 대화를 혼합하면 라우팅 혼란이 발생하고 연락처에 불편을 줄 수 있습니다.
WhatsApp 초기 등록을 위해 SMS 또는 음성 통화를 수신할 수 있는 실제 전화번호가 필요합니다. 등록 후에는 WhatsApp이 설치된 스마트폰에서 번호가 활성 상태를 유지하기만 하면 됩니다.
openclaw.json
{
"channels": {
"whatsapp": {
"accounts": {
"default": {
"phone": "+15551234567"
}
}
}
}
}VoIP 번호(예: TextNow, Google Voice, 무료 SMS 서비스)는 사용을 피하세요. WhatsApp은 VoIP로 등록된 계정을 자주 차단합니다. 최상의 안정성을 위해 실제 SIM 카드, 선불 SIM 또는 전용 eSIM을 사용하세요.
로그인 및 인증 정보
채널 구성 후 스마트폰을 Gateway와 페어링해야 합니다. 로그인 명령을 실행하면 터미널에 QR 코드가 표시됩니다. 스마트폰의 WhatsApp으로 스캔하세요 (설정 → 연결된 기기 → 기기 연결).
인증 정보는 ~/.openclaw/credentials/whatsapp/<accountId>/creds.json에 자동 저장되며 재시작 후에도 유지됩니다. 손상 시 복구를 위한 백업(creds.json.bak)이 자동으로 생성됩니다. 세션이 만료되거나 수동으로 취소되지 않는 한 QR 코드 스캔은 한 번만 하면 됩니다.
터미널
openclaw channels login whatsapp디스플레이 없는 서버(헤드리스)에서 실행하는 경우 --qr-terminal 플래그를 사용하여 QR 코드를 ASCII 아트로 터미널에 직접 렌더링할 수 있습니다.
DM 정책
DM(다이렉트 메시지) 정책은 AI 어시스턴트와 상호작용할 수 있는 사용자를 제어합니다. OpenClaw는 네 가지 정책을 지원합니다:
• pairing (기본값) — 새로운 연락처는 페어링 과정을 거쳐야 합니다. 메시지를 보내면 페어링 코드를 받고, CLI에서 승인 또는 거부합니다. 승인 후 자유롭게 채팅할 수 있습니다.
• allowlist — allowFrom에 명시적으로 나열된 전화번호만 봇에 메시지를 보낼 수 있습니다. 나머지는 무시됩니다.
• open — 번호로 메시지를 보내는 모든 사람이 응답을 받습니다. 프로덕션 환경에서는 주의하여 사용하세요.
• disabled — DM 처리가 완전히 비활성화됩니다. 봇은 어떤 다이렉트 메시지에도 응답하지 않습니다.
openclaw.json
{
"channels": {
"whatsapp": {
"dmPolicy": "pairing",
"allowFrom": ["+15551234567", "+15559876543"]
}
}
}그룹 채팅 관리
OpenClaw는 WhatsApp 그룹 채팅에 참여할 수 있습니다. 기본적으로 공유 대화에서 원치 않는 AI 응답을 방지하기 위해 그룹 지원은 비활성화되어 있습니다.
활성화하면 봇은 이름으로 멘션되거나 구성된 키워드로 트리거될 때만 응답합니다. 활성 그룹과 봇 활성화 방법을 제어할 수 있습니다.
openclaw.json
{
"channels": {
"whatsapp": {
"groupPolicy": "allowlist",
"groupActivation": "mention",
"groupAllowList": ["group-jid-1", "group-jid-2"]
}
}
}그룹 JID는 그룹 메시지를 수신할 때 Gateway 로그에서 확인할 수 있습니다. 메시지 페이로드의 'from' 필드를 확인하세요.
읽음 확인
OpenClaw가 메시지 처리 시 읽음 확인(파란색 체크)을 보낼지 여부를 구성할 수 있습니다. 기본적으로 자연스러운 대화 느낌을 유지하기 위해 읽음 확인이 전송됩니다.
읽음 확인을 비활성화하면 봇이 덜 "활동적"으로 보이게 하거나 메시지를 비동기적으로 처리할 때 유용합니다.
openclaw.json
{
"channels": {
"whatsapp": {
"sendReadReceipts": true
}
}
}확인 리액션
OpenClaw는 AI 응답이 준비되기 전에 수신 메시지에 이모지로 반응하여 수신을 확인할 수 있습니다. AI 응답이 몇 초 걸릴 수 있으므로, 리액션을 통해 발신자에게 메시지가 수신되었음을 알립니다.
다이렉트 메시지와 그룹 채팅에 대해 다른 리액션을 구성하거나 기능을 완전히 비활성화할 수 있습니다.
openclaw.json
{
"channels": {
"whatsapp": {
"ackReaction": {
"emoji": "👀",
"direct": true,
"group": true
}
}
}
}발신 메시지 및 미디어
OpenClaw는 WhatsApp을 통해 텍스트, 이미지, 문서, 오디오, 비디오 전송을 지원합니다. 미디어 파일은 자동으로 처리됩니다. Gateway가 WhatsApp 서버에 업로드하고 적절한 메시지 유형으로 전송합니다.
긴 AI 응답의 경우 WhatsApp 메시지 크기 제한 내에서 텍스트가 자동으로 청크로 분할됩니다. 청크 크기와 동작을 구성할 수 있습니다.
기본 수신 미디어 크기 제한은 50 MB(mediaMaxMb)입니다. 발신 미디어 제한은 5 MB(agents.defaults.mediaMaxMb)이며, 초과 크기 이미지에 대해 자동 JPEG 최적화 및 리사이즈가 적용됩니다.
속도 제한 및 전송 제한
WhatsApp은 연결된 기기에 속도 제한을 적용합니다. 개인 계정에 대한 공식적인 공개 제한은 없지만, 너무 빠르게 너무 많은 메시지를 보내면 일시적 차단이나 계정 제한이 발생할 수 있습니다.
OpenClaw에는 계정을 보호하기 위한 내장 속도 제한이 포함되어 있습니다. 기본 설정은 보수적이며 대부분의 사용 사례에 적합합니다.
openclaw.json
{
"channels": {
"whatsapp": {
"textChunkLimit": 5,
"mediaMaxMb": 50
}
}
}왜 Twilio / WhatsApp Business API를 사용하지 않나요?
OpenClaw가 공식 WhatsApp Business API(Twilio, MessageBird 등을 통해) 대신 Baileys를 사용하는 이유가 궁금할 수 있습니다. 이유는 다음과 같습니다:
• 비용 — Business API는 대화당 과금됩니다(지역에 따라 메시지당 약 $0.005~$0.08). 개인 또는 소규모 팀 사용 시 비용이 빠르게 증가합니다. Baileys는 무료입니다.
• 승인 — Business API는 Meta 인증, 등록된 사업체, 메시지 템플릿 승인이 필요합니다. Baileys는 모든 개인 WhatsApp 계정으로 작동합니다.
• 유연성 — Business API는 발신 메시지에 대한 엄격한 템플릿 요구사항과 24시간 대화 창이 있습니다. Baileys에는 이러한 제한이 없습니다.
• 셀프 호스팅 — Baileys를 사용하면 모든 것이 자체 서버에서 실행됩니다. 타사 API 제공업체가 메시지를 볼 수 없습니다.
트레이드오프는 안정성입니다: Business API는 공식적으로 지원되는 반면, Baileys는 리버스 엔지니어링에 의존하며 WhatsApp이 프로토콜을 변경하면 작동이 중단될 수 있습니다. 대부분의 셀프 호스팅 사용 사례에서 이 트레이드오프는 충분히 가치 있습니다.
WhatsApp 구성 참조
| Key | Type | Default | Description |
|---|---|---|---|
| dmPolicy | string | "pairing" | 봇에 DM을 보낼 수 있는 사용자 제어. 옵션: pairing, allowlist, open, disabled |
| selfChatMode | string | "disabled" | 자신에게 보내는 메시지 처리 방법. 옵션: disabled, ai, note |
| allowFrom | string[] | [] | 봇에 메시지를 보낼 수 있는 전화번호 목록 (dmPolicy가 allowlist일 때) |
| sendReadReceipts | boolean | true | 메시지 처리 시 파란색 체크 읽음 확인 전송 여부 |
| ackReaction.emoji | string | "👀" | 메시지 수신 확인에 사용되는 이모지 |
| ackReaction.direct | boolean | true | 다이렉트 메시지에서 확인 리액션 전송 |
| ackReaction.group | boolean | true | 그룹 메시지에서 확인 리액션 전송 |
| textChunkLimit | number | 5 | AI 응답당 최대 텍스트 청크 수 |
| mediaMaxMb | number | 50 | 최대 수신 미디어 파일 크기(MB). 발신 제한은 agents.defaults.mediaMaxMb로 제어 (기본 5 MB) |
| groupPolicy | string | "disabled" | 그룹 채팅 정책. 옵션: disabled, allowlist, open |
| groupActivation | string | "mention" | 그룹에서 봇을 트리거하는 방법. 옵션: mention, always |
| historyLimit | number | 50 | AI 컨텍스트로 포함할 최근 메시지 수 |
| chunkMode | string | "split" | 긴 응답 처리 방법. 옵션: split, newline, truncate |
| messagePrefix | string | "" | 모든 발신 메시지에 추가되는 선택적 접두사 |
| accounts.<id>.* | object | {} | 계정별 설정 (전화번호, 인증 정보 경로, 재정의) |
dmPolicy
Type: stringDefault: "pairing"
봇에 DM을 보낼 수 있는 사용자 제어. 옵션: pairing, allowlist, open, disabled
selfChatMode
Type: stringDefault: "disabled"
자신에게 보내는 메시지 처리 방법. 옵션: disabled, ai, note
allowFrom
Type: string[]Default: []
봇에 메시지를 보낼 수 있는 전화번호 목록 (dmPolicy가 allowlist일 때)
sendReadReceipts
Type: booleanDefault: true
메시지 처리 시 파란색 체크 읽음 확인 전송 여부
ackReaction.emoji
Type: stringDefault: "👀"
메시지 수신 확인에 사용되는 이모지
ackReaction.direct
Type: booleanDefault: true
다이렉트 메시지에서 확인 리액션 전송
ackReaction.group
Type: booleanDefault: true
그룹 메시지에서 확인 리액션 전송
textChunkLimit
Type: numberDefault: 5
AI 응답당 최대 텍스트 청크 수
mediaMaxMb
Type: numberDefault: 50
최대 수신 미디어 파일 크기(MB). 발신 제한은 agents.defaults.mediaMaxMb로 제어 (기본 5 MB)
groupPolicy
Type: stringDefault: "disabled"
그룹 채팅 정책. 옵션: disabled, allowlist, open
groupActivation
Type: stringDefault: "mention"
그룹에서 봇을 트리거하는 방법. 옵션: mention, always
historyLimit
Type: numberDefault: 50
AI 컨텍스트로 포함할 최근 메시지 수
chunkMode
Type: stringDefault: "split"
긴 응답 처리 방법. 옵션: split, newline, truncate
messagePrefix
Type: stringDefault: ""
모든 발신 메시지에 추가되는 선택적 접두사
accounts.<id>.*
Type: objectDefault: {}
계정별 설정 (전화번호, 인증 정보 경로, 재정의)
WhatsApp 자주 묻는 질문
WhatsApp 문제 해결
WhatsApp에 '연결되지 않음'이 표시되거나 QR 코드가 스캔되지 않음
세션 인증 정보가 만료되었거나, 스마트폰의 WhatsApp 앱이 업데이트되어 연결된 세션이 무효화되었을 수 있습니다.
~/.openclaw/credentials/whatsapp/ 아래의 인증 정보 폴더를 삭제하고 'openclaw channels login whatsapp'를 다시 실행하여 재페어링하세요. QR 스캔 시 스마트폰의 인터넷 연결이 안정적인지 확인하세요.
봇이 연결되지만 반복적으로 끊어짐
보통 스마트폰이 장기간 오프라인이거나, 다른 연결된 기기가 Gateway 세션과 충돌할 때 발생합니다.
스마트폰이 인터넷에 연결된 상태를 유지하는지 확인하세요. 연결된 기기 4대 제한을 초과하지 않았는지 확인하세요. WhatsApp 설정 → 연결된 기기에서 사용하지 않는 연결 기기를 제거한 후 다시 로그인하세요.
메시지 전송 실패 (타임아웃 또는 배달 실패)
속도 제한, 네트워크 문제, 또는 수신자가 번호를 차단했을 수 있습니다.
Gateway 로그에서 특정 오류 코드를 확인하세요. 속도 제한 오류가 보이면 전송 빈도를 줄이세요. 네트워크 문제의 경우 서버의 인터넷 연결이 안정적인지 확인하세요. 스마트폰에서 수동으로 메시지를 보내 번호가 제한되지 않았는지 확인하세요.