WhatsApp 채널 구성 완전 가이드

이 튜토리얼을 완료하면 할 수 있는 것

QR 코드를 통해 WhatsApp 계정을 Clawdbot에 연결하기
다중 계정 WhatsApp 지원 구성하기
DM 접근 제어 설정하기(페어링/화이트리스트/공개)
WhatsApp 그룹 지원 활성화 및 관리하기
자동 메시지 확인 및 읽음 확인 구성하기

지금 당신이 겪고 있는 어려움

WhatsApp은 가장 자주 사용하는 메시징 플랫폼이지만, AI 어시스턴트는 아직 WhatsApp 메시지를 수신할 수 없습니다. 당신은 다음을 원합니다:

앱을 전환하지 않고 WhatsApp에서 직접 AI와 대화하기
AI에게 메시지를 보낼 수 있는 사람 제어하기
여러 WhatsApp 계정(업무/개인 분리) 지원하기

이 방법을 사용할 때

WhatsApp에 AI 어시스턴트를 연결해야 할 때
업무/개인 WhatsApp 계정을 분리해야 할 때
AI에게 메시지를 보낼 수 있는 사람을 정밀하게 제어하고 싶을 때

Baileys란 무엇인가요?

Baileys는 WhatsApp Web 라이브러리로, 프로그램이 WhatsApp Web 프로토콜을 통해 메시지를 주고받을 수 있게 합니다. Clawdbot은 Baileys를 사용하여 WhatsApp에 연결하므로 WhatsApp Business API를 사용할 필요가 없어 더 프라이버시 보호와 유연성을 제공합니다.

🎒 시작하기 전 준비사항

WhatsApp 채널을 구성하기 전에 다음을 확인하세요:

[ ] Clawdbot Gateway가 설치되고 실행 중인지
[ ] 빠른 시작을 완료했는지
[ ] 사용 가능한 전화번호가 있는지(추천: 여분 번호)
[ ] WhatsApp 앱이 인터넷에 접속할 수 있는지(QR 코드 스캔용)

주의사항

독립 번호 사용 추천: 개인 사용 방지를 위해 별도의 SIM 카드 또는 구형 휴대전화 사용
가상 번호 피하기: TextNow, Google Voice 등의 가상 번호는 WhatsApp에서 차단됨
Node 런타임: WhatsApp과 Telegram은 Bun에서 불안정하므로 Node ≥22 사용

핵심 개념

WhatsApp 채널의 핵심 아키텍처:

당신의 WhatsApp 휴대전화 ←--(QR 코드)--> Baileys ←--→ Clawdbot Gateway
                                                      ↓
                                                  AI Agent
                                                      ↓
                                                  메시지 답장

핵심 개념:

Baileys 세션: WhatsApp Linked Devices를 통해 연결 설정
DM 정책: AI에게 개인 메시지를 보낼 수 있는 사람 제어
다중 계정 지원: 하나의 Gateway가 여러 WhatsApp 계정 관리
메시지 확인: 사용자 경험 향상을 위한 자동 이모지/읽음 확인

따라하기

1단계: 기본 설정 구성

이유 WhatsApp 접근 제어 정책을 설정하여 AI 어시스턴트가 남용되지 않도록 보호합니다.

~/.clawdbot/clawdbot.json을 편집하고 WhatsApp 구성을 추가하세요:

json

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "allowFrom": ["+15551234567"]
    }
  }
}

필드 설명:

필드	타입	기본값	설명
`dmPolicy`	string	`"pairing"`	DM 접근 정책: `pairing`(페어링), `allowlist`(화이트리스트), `open`(공개), `disabled`(비활성화)
`allowFrom`	string[]	`[]`	허용된 발신자 전화번호 목록(E.164 형식, 예: `+15551234567`)

DM 정책 비교:

정책	동작	사용 사례
`pairing`	알 수 없는 발신자가 페어링 코드를 받으며 수동 승인 필요	추천, 보안과 편의성 균형
`allowlist`	`allowFrom` 목록의 번호만 허용	엄격한 제어, 알려진 사용자
`open`	누구나 보낼 수 있음(`allowFrom`에 `"*"` 포함 필요)	공개 테스트 또는 커뮤니티 서비스
`disabled`	모든 WhatsApp 메시지 무시	일시적으로 채널 비활성화

보여야 하는 것: 구성 파일이 성공적으로 저장되고 JSON 형식 오류가 없어야 합니다.

2단계: WhatsApp에 로그인

이유 QR 코드를 통해 WhatsApp 계정을 Clawdbot에 연결하면 Baileys가 세션 상태를 유지합니다.

터미널에서 다음을 실행하세요:

bash

clawdbot channels login whatsapp

다중 계정 로그인:

특정 계정 로그인:

bash

clawdbot channels login whatsapp --account work

기본 계정 로그인:

bash

clawdbot channels login whatsapp

작업 단계:

터미널에 QR 코드가 표시됩니다(CLI 인터페이스에 표시될 수도 있음)
WhatsApp 휴대전화 앱을 엽니다
Settings → Linked Devices로 이동합니다
Link a Device를 탭합니다
터미널에 표시된 QR 코드를 스캔합니다

보여야 하는 것:

✓ WhatsApp linked successfully!
Credentials stored: ~/.clawdbot/credentials/whatsapp/default/creds.json

자격 증명 저장소

WhatsApp 로그인 자격 증명은 ~/.clawdbot/credentials/whatsapp/<accountId>/creds.json에 저장됩니다. 첫 번째 로그인 후, 후속 시작 시 세션이 자동으로 복원되므로 QR 코드를 반복해서 스캔할 필요가 없습니다.

3단계: Gateway 시작

이유 Gateway를 시작하여 WhatsApp 채널이 메시지를 수신하고 전송할 수 있도록 합니다.

bash

clawdbot gateway

또는 데몬 모드 사용:

bash

clawdbot gateway start

보여야 하는 것:

[WhatsApp] Connected to WhatsApp Web
[WhatsApp] Default account linked: +15551234567
Gateway listening on ws://127.0.0.1:18789

4단계: 테스트 메시지 보내기

이유 WhatsApp 채널이 올바르게 구성되었는지 확인하고 정상적으로 메시지를 주고받을 수 있는지 검증합니다.

WhatsApp 휴대전화에서 연결된 번호로 메시지를 보내세요:

안녕하세요

보여야 하는 것:

터미널에 수신된 메시지 로그가 표시됨
WhatsApp에서 AI 응답을 받음

체크포인트 ✅

[ ] Gateway 로그에 [WhatsApp] Received message from +15551234567이 표시됨
[ ] WhatsApp에서 AI 응답을 받음
[ ] 응답 내용이 입력과 관련됨

5단계: 고급 옵션 구성(선택사항)

자동 메시지 확인 활성화

clawdbot.json에 다음을 추가하세요:

json

{
  "channels": {
    "whatsapp": {
      "ackReaction": {
        "emoji": "👀",
        "direct": true,
        "group": "mentions"
      }
    }
  }
}

필드 설명:

필드	타입	기본값	설명
`emoji`	string	-	확인 이모지(예: `"👀"`, `"✅"`), 빈 문자열은 비활성화
`direct`	boolean	`true`	개인 채팅에서 확인을 보낼지 여부
`group`	string	`"mentions"`	그룹 동작: `"always"`(모든 메시지), `"mentions"`(@멘션만), `"never"`(절대 안 함)

읽음 확인 구성

기본적으로 Clawdbot은 메시지를 자동으로 읽음으로 표시합니다(파란색 체크). 비활성화하려면:

json

{
  "channels": {
    "whatsapp": {
      "sendReadReceipts": false
    }
  }
}

메시지 제한 조정

json

{
  "channels": {
    "whatsapp": {
      "textChunkLimit": 4000,
      "mediaMaxMb": 50,
      "chunkMode": "length"
    }
  }
}

필드	기본값	설명
`textChunkLimit`	4000	단일 텍스트 메시지 최대 문자 수
`mediaMaxMb`	50	수신할 미디어 파일 최대 크기(MB)
`chunkMode`	`"length"`	분할 모드: `"length"`(길이 기준), `"newline"`(문단 기준)

보여야 하는 것: 구성이 적용되면 긴 메시지가 자동으로 분할되고 미디어 파일 크기가 제어됩니다.

함정 주의사항

문제 1: QR 코드 스캔 실패

증상: QR 코드를 스캔한 후 터미널에 연결 실패 또는 시간 초과가 표시됩니다.

원인: 네트워크 연결 문제 또는 WhatsApp 서비스 불안정.

해결 방법:

휴대전화 네트워크 연결 확인
Gateway 서버가 인터넷에 액세스할 수 있는지 확인

로그아웃 후 다시 로그인:

bash

clawdbot channels logout whatsapp
clawdbot channels login whatsapp

문제 2: 메시지가 전달되지 않거나 지연됨

증상: 메시지를 보낸 후 응답을 받기까지 오랜 시간이 걸립니다.

원인: Gateway가 실행 중이지 않거나 WhatsApp 연결이 끊어짐.

해결 방법:

Gateway 상태 확인: clawdbot gateway status
Gateway 재시작: clawdbot gateway restart
로그 확인: clawdbot logs --follow

문제 3: 페어링 코드를 받지 못함

증상: 낯선 사람이 메시지를 보낸 후 페어링 코드를 받지 못했습니다.

원인: dmPolicy가 pairing으로 설정되지 않음.

해결 방법:

clawdbot.json에서 dmPolicy 설정을 확인하세요:

json

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing"  // ← "pairing"인지 확인
    }
  }
}

문제 4: Bun 런타임 문제

증상: WhatsApp과 Telegram이 자주 연결이 끊기거나 로그인 실패가 발생합니다.

원인: Baileys와 Telegram SDK는 Bun에서 불안정합니다.

해결 방법:

Node ≥22에서 Gateway를 실행하세요:

현재 런타임 확인:

bash

node --version

전환이 필요한 경우 Node로 Gateway 실행:

bash

clawdbot gateway --runtime node

이 레슨 요약

WhatsApp 채널 구성 요점:

기본 구성: dmPolicy + allowFrom로 접근 제어
로그인 절차: clawdbot channels login whatsapp로 QR 코드 스캔
다중 계정: --account 매개변수로 여러 WhatsApp 계정 관리
고급 옵션: 자동 메시지 확인, 읽음 확인, 메시지 제한
문제 해결: Gateway 상태, 로그, 런타임 확인

다음 레슨 미리보기

다음 레슨에서는 Telegram 채널 구성을 학습합니다.
배울 내용:
Bot Token을 사용하여 Telegram Bot 구성하기
명령 및 인라인 쿼리 설정하기
Telegram 특정 보안 정책 관리하기

부록: 소스 코드 참조

소스 코드 위치 보기

업데이트 날짜: 2026-01-27

기능	파일 경로	라인 번호
WhatsApp 구성 타입 정의	`src/config/types.whatsapp.ts`	1-160
WhatsApp 구성 Schema	`src/config/zod-schema.providers-whatsapp.ts`	13-100
WhatsApp 온보딩 구성	`src/channels/plugins/onboarding/whatsapp.ts`	1-341
WhatsApp 문서	`docs/channels/whatsapp.md`	1-363
WhatsApp 로그인 도구	`src/channels/plugins/agent-tools/whatsapp-login.ts`	1-72
WhatsApp Actions 도구	`src/agents/tools/whatsapp-actions.ts`	1-42

핵심 구성 항목:

dmPolicy: DM 접근 정책(pairing/allowlist/open/disabled)
allowFrom: 허용된 발신자 목록(E.164 형식 전화번호)
ackReaction: 자동 메시지 확인 구성({emoji, direct, group})
sendReadReceipts: 읽음 확인 전송 여부(기본값 true)
textChunkLimit: 텍스트 분할 제한(기본 4000 문자)
mediaMaxMb: 미디어 파일 크기 제한(기본 50 MB)

핵심 함수:

loginWeb(): WhatsApp QR 코드 로그인 실행
startWebLoginWithQr(): QR 코드 생성 절차 시작
sendReactionWhatsApp(): WhatsApp 이모지 반응 전송
handleWhatsAppAction(): WhatsApp 특정 작업 처리(예: 반응)

핵심 상수:

DEFAULT_ACCOUNT_ID: 기본 계정 ID("default")
creds.json: WhatsApp 인증 자격 증명 저장 경로

처음부터 사용하기

일반적으로 사용되는 채팅 도구 연결

AI 초능력 잠금 해제

문제가 발생하면

WhatsApp 채널 구성 완전 가이드

이 튜토리얼을 완료하면 할 수 있는 것

지금 당신이 겪고 있는 어려움

이 방법을 사용할 때

🎒 시작하기 전 준비사항

핵심 개념

따라하기

1단계: 기본 설정 구성

2단계: WhatsApp에 로그인

3단계: Gateway 시작

4단계: 테스트 메시지 보내기

5단계: 고급 옵션 구성(선택사항)

자동 메시지 확인 활성화

읽음 확인 구성

메시지 제한 조정

함정 주의사항

문제 1: QR 코드 스캔 실패

문제 2: 메시지가 전달되지 않거나 지연됨

문제 3: 페어링 코드를 받지 못함

문제 4: Bun 런타임 문제

이 레슨 요약

다음 레슨 미리보기

부록: 소스 코드 참조

WhatsApp 채널 구성 완전 가이드 ​

이 튜토리얼을 완료하면 할 수 있는 것 ​

지금 당신이 겪고 있는 어려움 ​

이 방법을 사용할 때 ​

🎒 시작하기 전 준비사항 ​

핵심 개념 ​

따라하기 ​

1단계: 기본 설정 구성 ​

2단계: WhatsApp에 로그인 ​

3단계: Gateway 시작 ​

4단계: 테스트 메시지 보내기 ​

5단계: 고급 옵션 구성(선택사항) ​

자동 메시지 확인 활성화 ​

읽음 확인 구성 ​

메시지 제한 조정 ​

함정 주의사항 ​

문제 1: QR 코드 스캔 실패 ​

문제 2: 메시지가 전달되지 않거나 지연됨 ​

문제 3: 페어링 코드를 받지 못함 ​

문제 4: Bun 런타임 문제 ​

이 레슨 요약 ​

다음 레슨 미리보기 ​

부록: 소스 코드 참조 ​

WhatsApp 채널 구성 완전 가이드

이 튜토리얼을 완료하면 할 수 있는 것

지금 당신이 겪고 있는 어려움

이 방법을 사용할 때

🎒 시작하기 전 준비사항

핵심 개념

따라하기

1단계: 기본 설정 구성

2단계: WhatsApp에 로그인

3단계: Gateway 시작

4단계: 테스트 메시지 보내기

5단계: 고급 옵션 구성(선택사항)

자동 메시지 확인 활성화

읽음 확인 구성

메시지 제한 조정

함정 주의사항

문제 1: QR 코드 스캔 실패

문제 2: 메시지가 전달되지 않거나 지연됨

문제 3: 페어링 코드를 받지 못함

문제 4: Bun 런타임 문제

이 레슨 요약

다음 레슨 미리보기

부록: 소스 코드 참조