TL;DR

OpenWA는 자체 호스팅 가능한 오픈소스 WhatsApp API 게이트웨이로 Docker Compose와 번들된 React 대시보드를 통해 빠르게 배포하고 운영할 수 있다. 플러거블 어댑터로 SQLite에서 PostgreSQL·MinIO·Redis로 백엔드를 전환할 수 있으며 멀티 세션과 세부적인 보안 제어(IP 화이트리스트, HMAC 웹훅, 비루트 컨테이너 실행)를 기본으로 제공한다. 선택적으로 MCP를 활성화하면 약 39개의 선별된 도구를 에이전트용 HTTP 엔드포인트로 노출할 수 있고 이 경로는 기본 비활성화와 최소 권한 키·레이트리밋 같은 방어 설정으로 보호된다. 프로덕션 배포는 docker-compose 프로파일을 통해 단계적으로 확장할 수 있으나 /mcp 엔드포인트를 공용으로 노출하면 보안 위험이 발생하므로 전면 공개 전 별도 인증 프록시나 제한된 네트워크 환경 구성이 필요하다.

주요 기능

• REST API를 통해 세션 생성·시작·메시지 전송·웹훅 등록 같은 운영 작업을 자동화할 수 있으며 Swagger UI로 인터랙티브한 API 스펙을 확인할 수 있다. 이 기능은 X-API-Key 기반 인증과 HMAC 웹훅 옵션을 포함해 보안 제어를 함께 제공한다. 예시 요청은 README에 curl 형태로 수록되어 있어 빠르게 연동을 검증할 수 있다.
• 멀티 세션을 운영해 한 인스턴스에서 여러 WhatsApp 계정을 동시에 관리할 수 있으며 각 세션별로 프록시·스토리지·권한을 분리해 운영할 수 있다. 세션 관리와 QR 코드 인증 흐름은 REST 엔드포인트로 노출되어 자동화가 가능하다. 대시보드는 세션 상태·웹훅·API 키 관리를 시각적으로 제공한다.
• 플러거블 아키텍처로 데이터베이스(SQLite/PostgreSQL), 스토리지(Local/S3/MinIO), 캐시(Memory/Redis) 어댑터를 설정만으로 교체할 수 있다. 이 설계는 로컬 개발과 프로덕션 구성 간 마이그레이션을 용이하게 한다. 마이그레이션 도구와 데이터 이관 기능도 문서에 포함되어 있다.
• MCP(Model Context Protocol) 옵션을 통해 에이전트가 호출할 수 있는 약 39개의 선별된 도구를 HTTP 엔드포인트로 노출할 수 있으며 이 기능은 기본적으로 비활성화되어 있다. 에이전트용 경량 인터페이스는 권한 범위와 레이트리밋을 통해 위험을 최소화하도록 설계되었다. MCP 관련 설정은 환경변수와 compose 프로파일로 제어된다.
• Docker Compose 및 다중 아키텍처 GHCR 이미지로 손쉬운 배포를 지원하며 production용 compose 프로파일로 PostgreSQL·Redis·MinIO 등을 옵션으로 구성할 수 있다. 컨테이너는 비루트 실행을 권장하고 docker-socket을 직접 노출하지 않도록 sidecar proxy 패턴을 사용한다. Health checks와 Kubernetes 준비를 위한 설정도 포함되어 있어 클러스터 환경으로 이식이 가능하다.

어떻게 동작하는가

OpenWA는 NestJS 기반 API 서버가 REST 엔드포인트와 번들된 React 대시보드를 동일 포트에서 제공하는 구조이다. 내부적으로 엔진 추상화를 통해 whatsapp-web.js 또는 baileys 중 원하는 엔진을 선택할 수 있고 데이터·스토리지를 어댑터로 분리해 설정만으로 전환할 수 있다. MCP를 활성화하면 API 서버에 POST /mcp 경로를 추가해 에이전트가 인증된 도구 호출을 수행하도록 하고 모든 도구 호출은 동일한 API 키 권한·세션 스코프·레이트리밋 정책을 거치게 된다.

해결 문제

OpenWA는 상용 WhatsApp API 서비스의 종속과 사용료 문제를 회피하고 자체 호스팅으로 메시징 인프라를 운영할 수 있게 한다. 이 프로젝트는 멀티 계정 운영, 웹 대시보드 기반 관리, 플러거블 백엔드 선택과 같은 운영 문제를 통합된 솔루션으로 해결한다.

차별점

• 플러거블 어댑터 설계는 데이터베이스와 스토리지, 캐시 구현을 설정만으로 교체할 수 있게 해 배포 민첩성을 제공한다. 이로 인해 개발 환경에서는 SQLite와 로컬 스토리지를 사용하다가 프로덕션에서는 PostgreSQL·MinIO·Redis로 전환하는 절차가 간단하다. README에 마이그레이션과 프로파일별 compose 예시가 포함되어 있어 이 전환을 문서화된 절차로 따라할 수 있다.
• 대시보드가 API 이미지에 번들되어 동일 포트에서 제공되므로 별도 프록시나 정적 호스팅 없이도 관리자 인터페이스를 운영할 수 있다. 이 구성은 개발 시 Vite 기반의 핫리로드를 지원하는 별도 dev 서버를 제공하면서도 프로덕션에서는 하나의 API 엔드포인트로 통합되는 장점을 가진다. 번들된 UI와 Swagger 문서는 운영과 디버깅에서 즉시 활용 가능한 관리 경험을 만든다.
• MCP 도구 노출은 기본 비활성화이고 활성화 시 제약된 도구 세트만 에이전트 경로로 노출하는 보안 중심 설계를 따른다. 에이전트용 API 키는 세션 범위·권한 제한·레이트리밋으로 제어할 수 있으며 README는 최소 권한 키 사용·읽기전용 옵션·레이트 설정 등 구체적 보안 권고를 제공한다. 또한 Docker 소켓 접근은 docker-proxy sidecar로 제한해 호스트 리소스 노출 위험을 줄였다.

사용 사례

• 고객 서비스봇을 자체 인프라로 운영해 WhatsApp 메시지 송수신과 이벤트 처리를 내부 시스템과 통합할 수 있다. OpenWA는 웹훅·API 키 기반 인증·라벨 관리 같은 기능을 제공해 CRM·티켓 시스템과 연동을 쉽게 만든다. 멀티 세션 지원으로 다중 브랜드·다수 상담원 계정을 하나의 인프라로 운영할 수 있다.
• 내부 자동화 파이프라인에서 WhatsApp 알림을 발송하거나 대량 메시징을 수행하는 워크플로를 구성할 수 있다. Docker Compose 프로파일을 통해 간단한 SQLite 기반 배포에서부터 Redis·PostgreSQL을 포함한 완전 스택까지 단계적으로 확장할 수 있다. README의 bulk messaging과 rate limiting 옵션은 대량 전송 시 운영 안전성을 확보하는 데 도움이 된다.
• AI 에이전트가 WhatsApp을 통해 사용자와 상호작용하도록 에이전트 도구 표면을 제공하는 브리지로 활용할 수 있다. MCP를 활성화하면 에이전트는 제한된 도구 집합을 통해 세션 상태 조회나 메시지 전송 같은 안전한 작업만 수행하도록 구성할 수 있다. README는 에이전트용 최소 권한 키와 MCP_READONLY 같은 보호 설정 권고를 포함해 에이전트 노출 위험을 줄이는 지침을 제공한다.

시작하기

레포를 클론한 후 Docker Compose 개발 파일로 컨테이너를 띄우면 대시보드와 API가 자동으로 실행된다. 로컬 개발 시에는 npm install로 종속성을 설치한 뒤 npm run dev로 Vite 기반 대시보드와 API를 핫리로드 모드로 실행해 바로 접근할 수 있다. MCP를 활성화하려면 MCP_ENABLED=true 환경변수를 설정해 프로덕션 스타트 명령이나 .env/compose 파일에서 해당 변수를 전달하면 된다.

요구사항

• Node.js 22 LTS 런타임이 설치되어야 한다.
• Docker와 Docker Compose 또는 Podman이 설치되어 있어야 하며 Podman 사용 시 시스템 소켓 설정이 필요하다.
• 프로덕션 구성에서 PostgreSQL·Redis·MinIO 같은 선택적 서비스는 해당 프로파일 활성화 시 필요하다.