OpenWA 딥다이브
— 월 사용료 없이 내 서버에서 돌리는 WhatsApp 자동화 게이트웨이

1프로젝트 한줄 요약

OpenWA는 본인 서버에 직접 띄우는 무료 오픈소스 WhatsApp API 게이트웨이다. 본인 시스템과 WhatsApp 사이에 다리를 놓아, 메시지 발송·수신·세션 관리·그룹·웹훅을 REST API 한 묶음으로 다룰 수 있게 해준다. "고객이 WhatsApp으로 '주문'을 보내면 자동 응답하고 구글 시트에 기록" 같은 자동화를, 외부 SaaS에 월 사용료를 내지 않고 본인 서버에서 만든다.

2왜 주목받는가

WhatsApp 자동화를 만들 때 보통 세 갈래 길이 있고, 앞의 두 갈래는 문제점이 명확하다.

경쟁/대안 비교

※ 수치는 2026-06 기준 GitHub: ⭐7.7k · 포크 1.6k · 최신 릴리스 v0.2.6(2026-06). 초기 버전대라 프로덕션 채택 시 안정성은 직접 검증 권장.

3기술 스택 전체 지도

언어 구성 (GitHub 집계)

핵심 런타임 / 프레임워크

데이터 / 저장 계층 (어댑터로 교체 가능)

프론트엔드 / 인프라

4아키텍처 심화 분석

시스템 구조도

핵심 설계 패턴 ①: 어댑터 패턴 (이 레포의 백미)

교체 가능한 부품은 3계층 — DB(SQLite↔PostgreSQL), 저장소(로컬↔S3/MinIO), 캐시(메모리↔Redis). 코드는 한 줄도 안 건드리고 설정/프로파일만 바꿔 갈아끼운다.

핵심 설계 패턴 ②: 멀티세션 매니저

SessionManager가 Map<세션ID, Session> 형태로 모든 세션을 들고, 각 세션은 자기만의 Puppeteer 브라우저를 가진다. 한 사람이 여러 노트북에 각각 다른 WhatsApp을 로그인해둔 셈.

핵심 설계 패턴 ③: 웹훅 + HMAC 서명

메시지 도착 등 이벤트를 본인 서버로 자동 HTTP POST한다. 위조 방지를 위해 HMAC-SHA256 서명을 본문에 박아, 비밀 키를 모르는 외부인이 가짜 이벤트를 쏘면 수신측이 거부한다. 발송 실패 시 큐가 자동 재시도해 메시지를 잃지 않는다.

핵심 설계 패턴 ④: 엔진 추상화 + WhatsApp Web 우회

engine/ 디렉토리가 whatsapp-web.js를 한 겹 감싸, 메시지 모듈이 특정 라이브러리에 직접 묶이지 않게 한다. 동작 원리는 Puppeteer로 실제 WhatsApp Web 페이지를 사람처럼 자동 조작하는 것 — Meta 입장에선 사람이 웹을 쓰는 것처럼 보인다.

5디렉토리 구조 해부

학습 동선 추천: main.ts → app.module.ts로 부팅 흐름을 잡고 → common/storage/에서 어댑터 인터페이스 1개를 정독 → modules/message/가 그 어댑터를 어떻게 "모양만 보고" 쓰는지 확인하면, 어댑터 패턴의 전체 그림이 한 번에 잡힌다.

docs/ 24개 문서(01~23) (설계 교재)

6학습 포인트 (기술별)

A. Pluggable Architecture (어댑터 교체 구조)

배울 것: 인터페이스로 계약을 정의하고 DI Factory가 설정값 보고 구현체를 골라 주입하는 패턴. 본인 프로젝트의 로그를 "콘솔↔파일↔Loki", 메일을 "SMTP↔SendGrid↔SES"로 추상화해보면 환경 분기(if-else) 지옥이 통째로 사라진다.

B. NestJS 모듈 설계 + DI

배울 것: 기능을 session/message/webhook처럼 모듈로 쪼개고 의존성 주입으로 결합도를 낮추는 방법. modules/ 8개가 그대로 모범 사례다.

C. HMAC 웹훅 서명

배울 것: 외부로 웹훅을 보낼 때 crypto.createHmac 한 줄로 서명을 박는 습관. 수신자가 위조 이벤트를 거부하게 해주는 1차 보안 방어선.

D. 큐 기반 재시도(안전망)

배울 것: 외부 호출(웹훅·발송)이 실패할 수 있다는 전제로 큐에 넣고 자동 재시도하는 설계. 일시적 장애에도 메시지를 잃지 않는다.

E. Docker Compose Profiles

배울 것: 한 docker-compose 파일에 profiles: [postgres, redis, minio, with-dashboard, with-proxy, full]로 태그를 달아 같은 파일로 개발·스테이징·프로덕션을 다른 구성으로 띄우는 법.

F. Health/Ready 분리

배울 것: /health("프로세스 살아있나?")와 /ready("트래픽 받을 준비 됐나?")를 분리해 Kubernetes liveness/readiness probe에 그대로 매핑하는 운영 패턴.

7하드웨어 / 시스템 요구사항

* RAM 수치는 README에 명시되지 않음 — 멀티세션이 Puppeteer 브라우저를 세션마다 띄우는 구조에서 도출한 추정치다. 실제 부하는 동시 세션 수·미디어 트래픽에 좌우된다.

주요 포트

8직접 해볼 수 있는 실습 과제

# 1. 클론 후 개발용 컴포즈로 기동
git clone https://github.com/rmyndharis/OpenWA
docker compose -f docker-compose.dev.yml up -d
# 2. 대시보드(:2886) 접속 → 세션 생성 → QR 스캔
# 3. 폰 WhatsApp → 연결된 기기 → 그 QR 스캔

# 텍스트 발송 (X-API-Key 헤더 필요)
POST /api/sessions/{sessionId}/messages/send-text
{ "chatId": "628123456789@c.us", "text": "Hello from OpenWA!" }

# MinIO 포함 프로파일로 기동
docker compose --profile minio up -d
# config/ 생성 파일에서 저장소 타입을 s3 계열로 전환 후 재시작

9관련 기술 심화 학습 로드맵

1주차: 띄우고 흐름 잡기

2주차: 어댑터 패턴 해부

3주차: 웹훅·보안·운영

4주차: 멀티세션·프로덕션 전환

10핵심 키워드 사전

11참고 링크

• GitHub 레포 — rmyndharis/OpenWA
• README (설치·API·스택)
• docs/ — 24개 문서(01~23) 설계 문서
• 릴리스 (v0.1.6 등)
• NestJS 공식 문서
• NestJS — Custom Providers (DI Factory)
• whatsapp-web.js 공식 문서
• Puppeteer 문서
• MinIO 문서 (S3 호환 스토리지)
• Docker Compose Profiles 가이드