WhatsApp — AI for the World's Most-Used Chat | Easy Understand Hermes Agent

WhatsApp — 세계에서 가장 많이 쓰는 채팅에 AI를 더하다

WhatsApp은 어디에나 있습니다. 전 세계 20억 명이 넘는 사람들이 매일 사용하고 있으며, 이제 Hermes를 WhatsApp에 바로 연결할 수 있습니다. Meta 개발자 계정도, 비즈니스 인증도, 복잡한 API 설정도 필요 없습니다. QR 코드만 스캔하면 친구에게 메시지 보내는 바로 그 앱에서 AI 에이전트와 대화할 수 있습니다.

작동 방식

Hermes는 Baileys 기반의 내장 브리지를 통해 WhatsApp에 연결됩니다. 브라우저를 휴대폰에 연결하는 것과 같은 방식으로 WhatsApp Web 세션을 에뮬레이션한다고 생각하면 됩니다. 공식 WhatsApp Business API가 아니므로 시작하기 위해 특별한 승인이 필요 없습니다.

hermes gateway setup을 실행하고 WhatsApp을 선택하면 단계별 안내를 받을 수 있습니다.

두 가지 사용 방법

모드	작동 방식	추천 대상
별도 봇 번호 (권장)	봇 전용 전화번호를 사용합니다. 사람들이 그 번호로 직접 메시지를 보냅니다.	깔끔한 UX, 여러 사용자, 차단 위험 낮음
개인 셀프 채팅	본인 WhatsApp을 사용합니다. 자신에게 메시지를 보내 에이전트와 대화합니다.	빠른 설정, 단일 사용자, 테스트

별도 봇 번호 방식이 더 깔끔합니다. AI가 고유한 정체성을 가지게 되고, 개인 채팅과 봇 대화가 섞이지 않습니다. 셀프 채팅 모드는 빠른 테스트 실행에 완벽합니다.

시작 전 준비사항

다음이 필요합니다:

Node.js v18+ 및 npm — WhatsApp 브리지는 Node.js 프로세스로 실행됩니다
WhatsApp이 설치된 휴대폰 (QR 코드 스캔용)

좋은 소식: 기존의 브라우저 기반 브리지와 달리 Chromium이나 Puppeteer를 설치할 필요가 없습니다. 설정이 훨씬 가볍습니다.

1단계: 설정 마법사 실행

hermes whatsapp

마법사가 다음을 수행합니다:

어떤 모드를 사용할지 묻습니다 (bot 또는 self-chat)
필요한 경우 브리지 의존성을 설치합니다
터미널에 QR 코드를 표시합니다
스캔할 때까지 기다립니다

QR 코드 스캔 방법:

휴대폰에서 WhatsApp을 엽니다
설정 → 연결된 기기로 이동합니다
기기 연결을 탭합니다
카메라를 터미널의 QR 코드에 맞춥니다

연결이 완료되면 마법사가 연결을 확인하고 종료됩니다. 세션은 자동으로 저장됩니다.

팁: QR 코드가 깨져 보이면 터미널 너비가 최소 60열 이상이고 Unicode를 지원하는지 확인하세요. 다른 터미널 에뮬레이터를 시도해 볼 수도 있습니다.

2단계: 두 번째 전화번호 확보 (봇 모드)

봇 모드에서는 WhatsApp에 아직 등록되지 않은 번호가 필요합니다. 선택지는 다음과 같습니다:

옵션	비용	참고 사항
Google Voice	무료	미국 한정. voice.google.com에서 번호를 받으세요. Google Voice 앱을 통해 SMS로 WhatsApp을 인증합니다.
선불 SIM	$5–15 일회성	모든 통신사 가능. 활성화하고 WhatsApp을 인증한 후 SIM은 서랍에 보관해도 됩니다. 번호는 활성 상태를 유지해야 합니다 (90일마다 한 번씩 전화).
VoIP 서비스	무료–월 $5	TextNow, TextFree 등. 일부 VoIP 번호는 WhatsApp에서 차단됩니다 — 첫 번째가 안 되면 몇 개 시도해 보세요.

번호를 확보한 후:

휴대폰에 WhatsApp을 설치합니다 (또는 듀얼 SIM 지원 시 WhatsApp Business 앱 사용)
새 번호를 WhatsApp에 등록합니다
hermes whatsapp을 실행하고 해당 WhatsApp 계정에서 QR 코드를 스캔합니다

3단계: Hermes 설정

~/.hermes/.env 파일에 다음을 추가합니다:

# 필수
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # "bot" 또는 "self-chat"

# 접근 제어 — 다음 옵션 중 하나를 선택하세요:
WHATSAPP_ALLOWED_USERS=15551234567         # 쉼표로 구분된 전화번호 (국가 코드 포함, + 제외)
# WHATSAPP_ALLOWED_USERS=*                 # 또는 *를 사용해 모두 허용
# WHATSAPP_ALLOW_ALL_USERS=true            # 또는 이 플래그를 설정 ( *와 동일한 효과)

모두 허용 단축 표기: WHATSAPP_ALLOWED_USERS=*로 설정하면 모든 발신자가 허용됩니다. 대신 페어링 흐름을 사용하려면 두 변수를 모두 제거하고 DM 페어링 시스템에 의존하세요.

~/.hermes/config.yaml의 선택적 동작 설정:

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

unauthorized_dm_behavior: pair는 전역 기본값입니다. 알 수 없는 DM 발신자에게 페어링 코드가 제공됩니다.
whatsapp.unauthorized_dm_behavior: ignore로 설정하면 WhatsApp이 승인되지 않은 DM에 대해 침묵을 유지합니다 — 개인 번호의 경우 보통 이쪽이 더 나은 선택입니다.

그런 다음 게이트웨이를 시작합니다:

hermes gateway              # 포그라운드 실행
hermes gateway install      # 사용자 서비스로 설치
sudo hermes gateway install --system   # Linux 전용: 부팅 시 시스템 서비스로 실행

게이트웨이는 저장된 세션을 사용해 WhatsApp 브리지를 자동으로 시작합니다.

세션 유지

Baileys 브리지는 세션을 ~/.hermes/platforms/whatsapp/session에 저장합니다. 즉:

세션은 재시작 후에도 유지됩니다 — 매번 QR 코드를 다시 스캔할 필요가 없습니다
세션 데이터에는 암호화 키와 기기 자격 증명이 포함됩니다
이 세션 디렉토리를 공유하거나 커밋하지 마세요 — WhatsApp 계정에 대한 전체 액세스 권한을 부여합니다

재연결

세션이 끊어진 경우 (휴대폰 초기화, WhatsApp 업데이트, 수동 연결 해제) 게이트웨이 로그에 연결 오류가 표시됩니다. 해결 방법:

hermes whatsapp

그러면 재연결을 위한 새 QR 코드가 생성됩니다.

주의사항

WhatsApp은 Business API 외부의 타사 봇을 공식적으로 지원하지 않습니다. 타사 브리지를 사용하면 계정 제한의 약간의 위험이 있습니다. 위험을 최소화하려면:

봇 전용 전화번호를 사용하세요 (개인 번호가 아닌)
대량/스팸 메시지를 보내지 마세요 — 대화형으로 사용하세요
먼저 메시지를 보내지 않은 사람에게 발신 메시지를 자동화하지 마세요

또한 WhatsApp은 주기적으로 Web 프로토콜을 업데이트하여 타사 브리지와의 호환성이 일시적으로 깨질 수 있습니다. 이런 경우 Hermes가 브리지 의존성을 업데이트합니다. WhatsApp 업데이트 후 봇이 작동을 멈추면 최신 Hermes 버전을 받아 다시 연결하세요.

더 공식적인 방법을 원하시나요?

실제 비즈니스 봇을 운영 중이고 안정성이 필요하다면 WhatsApp Business Cloud API 가이드를 대신 확인하세요. Meta가 공식 지원하는 경로입니다: 계정 차단 위험이 없지만 Meta 비즈니스 계정과 공개 웹훅 URL이 필요합니다. 두 어댑터는 필요하다면 서로 다른 전화번호에 대해 병렬로 실행할 수도 있습니다.

하지만 대부분의 개인 프로젝트와 실험에는 Baileys 브리지가 WhatsApp에 AI를 연결하는 가장 빠른 방법입니다. 스캔하고, 설정하고, 대화를 시작하세요.