Hermes WhatsApp 설정의 새로운 기능

Hermes Agent 시리즈를 계속 따라오고 계셨다면, 저희가 모든 것을 단순하게 만드는 걸 좋아한다는 걸 아실 거예요. 오늘은 업데이트된 WhatsApp 설정에 대해 자세히 알아보겠습니다 — 내부적으로 큰 변화가 있었거든요.

이제 Hermes는 Baileys 기반의 내장 브리지를 통해 WhatsApp에 연결됩니다. WhatsApp 웹 세션을 에뮬레이션하는 방식이라고 생각하면 돼요. Meta 개발자 계정도, 비즈니스 인증도, 공개 URL도 필요 없습니다. 그냥 여러분과 휴대폰, 그리고 QR 코드만 있으면 됩니다.

빠른 시작: hermes gateway setup을 실행하고 WhatsApp을 선택하면 단계별 안내를 받을 수 있어요.

두 가지 WhatsApp 통합 방식 — 차이점 알아보기

더 진행하기 전에, 자주 혼동되는 부분을 먼저 정리할게요. WhatsApp을 Hermes에 연결하는 방법은 두 가지가 있습니다:

통합 방식	적합한 경우	필요 사항
Baileys 브리지 (이 가이드)	개인 봇, 빠른 테스트, 공개 URL 불필요	WhatsApp이 설치된 휴대폰만 있으면 됨
WhatsApp Business Cloud API	실제 비즈니스 봇, 안정성, 차단 위험 제로	Meta 비즈니스 계정, 공개 웹훅 URL

Baileys 브리지는 비공식 방식입니다 — 약간의 차단 위험이 있어요. Business Cloud API는 Meta가 공식 지원하는 경로입니다. 필요하다면 다른 전화번호로 두 가지를 동시에 실행할 수도 있습니다.

⚠️ 중요한 경고 두 가지

차단 위험: WhatsApp은 Business API 외부의 서드파티 봇을 공식적으로 지원하지 않습니다. 안전하게 사용하려면:

봇 전용 전용 전화번호를 사용하세요 (개인 번호 말고)
대량 발송이나 스팸 메시지를 보내지 마세요 — 대화 형식을 유지하세요
먼저 메시지를 보내지 않은 사람에게 자동 발신 메시지를 보내지 마세요

프로토콜 업데이트: WhatsApp은 주기적으로 웹 프로토콜을 업데이트하며, 이로 인해 서드파티 브리지가 일시적으로 작동하지 않을 수 있습니다. WhatsApp 업데이트 후 봇이 작동을 멈추면, 최신 Hermes 버전을 받아서 다시 페어링하면 됩니다.

두 가지 모드 — 원하는 스타일을 선택하세요

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

사전 요구 사항

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

좋은 소식: 현재 Baileys 기반 브리지는 더 이상 Chromium이나 Puppeteer가 필요하지 않습니다. 훨씬 가벼워졌어요.

1단계: 설정 마법사 실행

hermes whatsapp

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

어떤 모드를 원하는지 묻습니다 (봇 또는 셀프 채팅)
필요한 경우 브리지 의존성을 설치합니다
터미널에 QR 코드를 표시합니다
스캔할 때까지 기다립니다

QR 코드 스캔 방법:

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

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

팁: QR 코드가 깨져 보이면 터미널 너비를 최소 60열 이상으로 설정하고 유니코드를 지원하는지 확인하세요.

2단계: 두 번째 전화번호 얻기 (봇 모드)

봇 모드에서는 WhatsApp에 아직 등록되지 않은 번호가 필요합니다. 세 가지 옵션이 있어요:

옵션	비용	참고 사항
Google Voice	무료	미국만 가능. Google Voice 앱을 통해 SMS로 WhatsApp을 인증하세요.
선불 SIM	$5–15 일회성	활성화하고 인증한 후, SIM은 서랍에 보관하면 됩니다. 90일마다 한 번씩 전화를 걸어 활성 상태를 유지하세요.
VoIP 서비스	무료–월 $5	TextNow, TextFree 등. 일부 번호는 WhatsApp에서 차단될 수 있으니 여러 개 시도해 보세요.

번호를 얻은 후:

휴대폰에 WhatsApp을 설치합니다 (또는 듀얼 SIM 지원 시 WhatsApp Business 앱 사용)
새 번호를 등록합니다
hermes 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=*로 설정하면 모든 발신자가 허용됩니다 — WHATSAPP_ALLOW_ALL_USERS=true와 동일합니다. 대신 페어링 흐름을 사용하려면 두 변수를 모두 제거하고 DM 페어링 시스템에 의존하세요.

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

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

pair (전역 기본값)는 알 수 없는 DM 발신자에게 페어링 코드를 보냅니다.
ignore는 승인되지 않은 DM에 대해 WhatsApp을 조용히 유지합니다 — 개인 번호에는 보통 이 옵션이 더 좋습니다.

그런 다음 게이트웨이를 시작하세요:

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

세션 유지 및 재페어링

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

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

세션이 손상된 경우 (휴대폰 초기화, WhatsApp 업데이트, 수동 연결 해제), 로그에서 연결 오류를 확인할 수 있습니다. 다음 명령으로 해결하세요:

hermes whatsapp

그러면 재페어링을 위한 새 QR 코드가 생성됩니다.

이것이 새로운 WhatsApp 설정의 핵심입니다. 빠르고, 가볍고, Meta 서류 작업이 필요 없어요. 다음 시리즈에서는 이 브리지를 WhatsApp Business Cloud API와 나란히 비교해 보겠습니다 — 기대해 주세요!