WhatsApp은 대화가 일어나는 곳이다. Slack도, Discord도, Telegram도 아닌 — 세계 대부분의 사람들에게 WhatsApp이 기본이다. 월간 활성 사용자 20억 명, 유럽, 라틴 아메리카, 남아시아, 아프리카에서 지배적이다. 일상에 진정으로 녹아드는 AI 어시스턴트를 원한다면, 일상 대화가 이미 이루어지는 곳에 있어야 한다.
문제는 WhatsApp이 개인용 봇 API를 제공하지 않는다는 것이다. WhatsApp Business API가 있지만, 비즈니스 계정, Meta 승인, 고객 서비스용으로 설계된 메시지당 요금 구조가 필요하다. 개인 WhatsApp에 AI 봇을 원하는 개발자 — 그룹 채팅에서 응답하고, 컨텍스트를 기억하고, 자체 하드웨어에서 실행되는 — 에게 공식 경로는 막다른 길이다.
NanoClaw는 WhatsApp Web 클라이언트와 같은 방식으로 WhatsApp 서버에 연결하는 오픈소스 WhatsApp Web 라이브러리인 Baileys로 이를 해결한다. QR 코드를 스캔하면 연결이 설정되고, NanoClaw가 당신의 WhatsApp 계정으로 메시지를 주고받을 수 있다. Business API 없이, Meta 승인 없이, 메시지당 요금 없이.
아키텍처: WhatsApp이 특별한 이유
NanoClaw의 WhatsApp 통합은 단순한 메시지 브릿지가 아니다 — 전체 아키텍처가 설계된 기본 채널이다. 다른 채널(Telegram, Discord, Slack)은 Claude Code 스킬을 통해 추가되지만, WhatsApp은 핵심에 내장되어 있다. 편애가 아니라, WhatsApp의 그룹 모델이 NanoClaw의 보안 모델에 자연스럽게 매핑되는 방식을 반영한 것이다.
WhatsApp 그룹이 격리 경계다. 각 그룹은 자체 컨테이너, 자체 CLAUDE.md 메모리 파일, 자체 쓰기 가능 작업 공간을 갖는다. 가족 그룹에서 누군가 메시지를 보내면, 응답하는 에이전트는 해당 그룹의 기록과 메모리에만 접근할 수 있다. 업무 그룹의 메시지를 볼 수 없고, 개인 채팅 기록에 접근할 수 없으며, 다른 그룹에 속한 파일을 읽을 수 없다. 격리는 애플리케이션 로직이 아닌 컨테이너 마운트에 의해 시행된다.
이 그룹별 격리가 사람들이 실제로 WhatsApp을 사용하는 방식에서 NanoClaw를 안전하게 만드는 것이다. 가족 그룹은 개인적인 이야기를 나눈다. 업무 그룹은 독점 프로젝트를 논의한다. 친구 그룹은 공개적으로 공유하지 않을 것들을 나눈다. 이 각각의 컨텍스트는 분리되어야 하며, NanoClaw는 이를 보장한다 — 버그가 있을 수 있는 접근 제어 목록이 아닌, 애플리케이션 수준 익스플로잇으로 우회할 수 없는 물리적 컨테이너 분리를 통해.
설정하기
설정 과정은 약 10분이며, 대부분은 npm install을 기다리는 시간이다.
저장소를 클론하고 의존성을 설치한다:
```bash git clone https://github.com/qwibitai/NanoClaw.git cd NanoClaw npm install ```
환경을 설정한다. 최소 설정은 Anthropic API 키 하나뿐이다:
```bash echo 'ANTHROPIC_API_KEY=sk-ant-your-key-here' > .env ```
WhatsApp 페어링을 실행한다:
```bash npm run auth ```
터미널에 QR 코드가 표시된다. 휴대폰에서 WhatsApp을 열고, 연결된 기기로 가서 코드를 스캔한다. 연결이 설정되고, NanoClaw가 메시지를 수신하기 시작한다.
에이전트를 시작한다:
```bash npm start ```
끝이다. 봇을 활성화하고 싶은 WhatsApp 그룹에 메시지를 보내고, 어시스턴트 이름(.env의 ASSISTANT_NAME으로 설정 가능)을 멘션하면 응답한다. 첫 응답은 컨테이너가 시작되면서 몇 초 걸리고, 같은 세션의 후속 메시지는 컨테이너가 웜 상태를 유지하므로 더 빠르다.
메시지 흐름
메시지 흐름을 이해하면 컨테이너 오버헤드에도 불구하고 NanoClaw가 왜 반응적으로 느껴지는지 설명된다. WhatsApp에 메시지가 도착하면, 호스트 프로세스 — NanoClaw의 약 500줄 TypeScript 핵심 — 가 Baileys를 통해 수신한다. 메시지가 어시스턴트에게 보내진 것인지 확인한다(이름 멘션 또는 다이렉트 메시지). 맞다면, 호스트가 그룹의 컨테이너 상태를 조회한다.
해당 그룹에 이미 컨테이너가 실행 중이면(최근 대화에서), 메시지가 IPC를 통해 라우팅된다. 컨테이너 안의 에이전트가 메시지를 받고, Claude Agent SDK로 처리하고, IPC를 통해 응답을 돌려보낸다. 호스트가 응답을 WhatsApp으로 전달한다. 추가 지연: IPC에 몇 밀리초, 그리고 Claude API 응답 시간.
실행 중인 컨테이너가 없으면, 호스트가 하나를 생성한다. macOS의 Apple Container로는 200-400ms, Linux의 Docker로는 1-2초. 컨테이너는 그룹의 CLAUDE.md 메모리 파일, SQLite의 대화 기록, stdin을 통한 API 키를 받는다. 메시지를 처리하고 응답한다. 컨테이너는 생성 오버헤드 없이 후속 메시지를 처리하기 위해 설정 가능한 타임아웃(기본: 30분) 동안 활성 상태를 유지한다.
결과적으로 대부분의 메시지 — 활발한 대화 중에 오는 것들 — 는 즉각적으로 느껴진다. AI 응답 시간은 NanoClaw의 인프라가 아닌 Claude API 지연에 의해 좌우된다. 오랜 침묵 후 첫 메시지만 컨테이너 시작 오버헤드가 있으며, 그마저도 사용자가 거의 알아채지 못할 만큼 빠르다.
그룹별 메모리: 진정으로 유용하게 만드는 기능
그룹별 CLAUDE.md 파일이 상태 없는 챗봇을 진정으로 유용한 어시스턴트로 바꾸는 것이다. 각 그룹의 메모리 파일은 시간이 지남에 따라 컨텍스트를 축적한다 — 선호도, 진행 중인 프로젝트, 반복되는 주제, 내부 농담. 에이전트는 모든 대화 턴 시작 시 이 파일을 읽으며, 이는 지난주에 말한 것을 반복하지 않아도 기억한다는 뜻이다.
가족 그룹에서 메모리는 식이 선호도, 학교 일정, 반복 활동을 기록할 수 있다. 업무 그룹에서는 프로젝트 마감일, 팀 선호도, 기술적 결정을 추적할 수 있다. 친구 그룹에서는 여행 계획, 레스토랑 추천, 공유 관심사를 기억할 수 있다.
메모리는 편집 가능하다. 에이전트에게 특정 것을 기억하라고 요청하거나("엄마가 갑각류 알레르기가 있다는 거 기억해") 잊으라고 할 수 있다("깜짝 파티에 대해 말한 거 잊어"). CLAUDE.md 파일을 직접 편집할 수도 있다 — 데이터베이스에 잠긴 게 아닌 파일시스템의 일반 텍스트 파일이다.
프라이버시 현실
WhatsApp AI 봇을 운영하면 정당한 프라이버시 질문이 제기되며, 이에 대해 솔직할 가치가 있다. NanoClaw가 처리하는 메시지는 Claude가 응답을 생성하기 위해 Anthropic의 API로 전송된다. 이는 WhatsApp 메시지 — 적어도 어시스턴트에게 보내진 것들 — 가 기기를 떠나 Anthropic 서버에서 처리된다는 뜻이다.
NanoClaw는 여러 방법으로 이를 완화한다. 어시스턴트에게 명시적으로 보내진 메시지만 API로 전송된다 — 봇은 자신에게 보내지지 않은 메시지를 처리하거나 저장하지 않는다. SQLite에 저장된 대화 기록은 당신의 머신에 남는다. CLAUDE.md 메모리 파일은 당신의 머신에 남는다. 그리고 Anthropic 대신 Ollama를 사용하도록 NanoClaw를 설정하면, AI 처리도 로컬에서 이루어진다 — 네트워크를 떠나는 것이 없다.
대부분의 사용자에게 실질적인 프라이버시 상태는: WhatsApp 메시지는 AI 어시스턴트에게 명시적으로 질문할 때를 제외하고 기기에 남으며, 그 경우 해당 특정 메시지가 Anthropic으로 전송된다(또는 Ollama로 로컬 처리된다). 이는 입력하는 모든 것을 처리하고 저장하는 클라우드 AI 서비스보다 의미 있게 더 나은 프라이버시 이야기다.
WhatsApp은 당신의 삶이 일어나는 곳이다. NanoClaw는 거기에 AI 어시스턴트를 놓는다 — 정말 중요한 것을 논의하는 그룹에서 안전하게 사용할 수 있는 격리, 메모리, 프라이버시 모델과 함께.