NanoClaw 소개
최근 인공지능 기술의 발전과 함께, 개발자와 일반 사용자 모두 자신의 일상과 업무를 자동화해 줄 '개인용 AI 에이전트'에 대한 관심이 급증하고 있습니다. 특히 단순히 질문에 답하는 챗봇을 넘어, 스스로 계획을 세우고 외부 도구를 활용하며 메신저를 통해 소통할 수 있는 에이전트 프레임워크들이 다수 등장했습니다. 하지만 기존의 유명한 에이전트 프레임워크들은 수십만 줄의 코드와 수많은 의존성을 가진 거대한 모놀리식(Monolithic) 시스템으로 변모하는 경향이 있었습니다. 이러한 복잡성은 사용자가 시스템의 내부 동작을 완벽히 이해하기 어렵게 만들며, 개인의 모든 데이터와 일상에 접근 권한을 부여해야 하는 AI 에이전트의 특성상 심각한 보안 불안감을 초래하기도 합니다.
NanoClaw는 바로 이러한 문제의식에서 출발한 프로젝트로, '작고 이해하기 쉬우며 완벽하게 격리된 안전한 AI 에이전트'를 지향합니다. 이 프로젝트는 기존의 무거운 프레임워크들이 제공하는 핵심 기능들을 그대로 유지하면서도, 코드베이스를 한 번의 자리에서 모두 읽고 이해할 수 있을 만큼 혁신적으로 줄였습니다. Anthropic의 Agents SDK를 기반으로 직접 구동되며, 사용자가 매뉴얼이나 설정 파일을 만지는 대신 Claude Code에게 지시하여 자신만의 맞춤형 에이전트로 코드를 직접 수정(Fork & Modify)하게 하는 독창적인 AI 네이티브(AI-native) 접근 방식을 취하고 있습니다.
무엇보다 NanoClaw가 강조하는 것은 'OS 수준의 컨테이너 격리(Isolation)'를 통한 강력한 보안입니다. 애플리케이션 레벨에서 단순히 권한을 체크하는 것에 그치지 않고, 모든 에이전트 세션은 macOS의 Apple Container나 Linux/macOS의 Docker와 같은 독립된 리눅스 컨테이너 내부에서 실행됩니다. 에이전트는 명시적으로 마운트된 디렉터리에만 접근할 수 있으므로, AI가 호스트 시스템에 예기치 않은 영향을 미치는 것을 원천적으로 차단합니다. 이를 통해 사용자는 안심하고 복잡한 작업을 AI에게 위임할 수 있으며, WhatsApp이나 Telegram 같은 친숙한 메신저를 통해 언제 어디서나 자신만의 강력한 AI 비서와 소통할 수 있습니다.
NanoClaw vs. OpenClaw 비교
NanoClaw를 이해하는 가장 좋은 방법은, 이 프로젝트에 영감을 주었으나 구조적으로 상반된 길을 걷고 있는 대표적인 프레임워크인 'OpenClaw'와 비교하는 것입니다. NanoClaw는 OpenClaw의 훌륭한 핵심 기능을 제공하면서도 불필요한 복잡성을 완전히 걷어냈습니다.
| 비교 항목 | NanoClaw | OpenClaw |
|---|---|---|
| 소스 파일 수 | 15개 | 3,680개 |
| 코드 라인 수 (LOC) | 약 3,900줄 | 434,453줄 |
| 의존성 (Dependencies) | 10개 미만 | 70개 이상 |
| 설정 파일 (Config files) | 0개 | 53개 |
| 코드 파악 소요 시간 | 약 8분 | 1~2주 |
| 보안 모델 | OS 컨테이너 격리 (Apple Container, Docker) |
애플리케이션 레벨의 권한 검사 |
| 아키텍처 구조 | 단일 프로세스 + 격리된 컨테이너 | 단일 프로세스 + 공유 메모리 |
NanoClaw의 주요 특징
NanoClaw의 핵심 철학 (Philosophy)
NanoClaw의 설계는 철저히 개인 사용자(Individual user)를 중심으로 맞춰져 있습니다. 거대한 범용 프레임워크를 지양하고, 사용자가 코드를 직접 포크(Fork)하여 자신의 입맛에 맞게 재단할 수 있는 '작업용 소프트웨어'를 표방합니다.
기능(Features) 대신 스킬(Skills) 중심의 설계: 핵심 코드베이스에 Telegram 지원과 같은 새로운 기능을 억지로 욱여넣어 시스템을 무겁게 만들지 않습니다. 대신 기여자는 /add-telegram과 같은 'Claude Code 스킬 파일'을 기여하며, 사용자는 자신의 포크된 저장소에서 이 스킬을 실행하여 코드를 동적으로 변환합니다. 사용자는 자신이 필요로 하는 기능만 가진 깨끗한 코드를 유지할 수 있습니다.
AI-Native 환경 지향: NanoClaw에는 복잡한 설치 마법사나 모니터링 대시보드가 존재하지 않습니다. 설치부터 구성, 디버깅까지 모든 과정을 "Claude에게 물어보고 해결하는" 방식을 따릅니다.
설정 파일 없는 구조(No configuration sprawl) 지향: 설정 파일(.json, .yaml 등)을 통한 커스터마이징을 배제합니다. 동작 방식을 바꾸고 싶다면, Claude Code에게 "트리거 단어를 @Bob으로 바꿔줘"라고 명령하여 코드 자체를 수정하게 합니다.
NanoClaw의 주요 기능
-
다양한 메신저 I/O 지원: 기본적으로 WhatsApp을 지원하며, 스킬 시스템을 통해 Telegram, Discord, Slack, Signal 등을 손쉽게 추가할 수 있습니다. 사용자는 스마트폰의 메신저 앱으로 자신의 에이전트와 직접 대화할 수 있습니다.
-
에이전트 군단 (Agent Swarms): 복잡한 작업을 위해 서로 협력하는 특화된 에이전트 팀을 생성할 수 있습니다. 이는 개인용 AI 비서 프레임워크 중 최초로 지원되는 기능입니다.
-
그룹별 독립 메모리 및 격리: 각 채팅 그룹은 고유의
CLAUDE.md메모리를 가지며, 완전히 격리된 자체 파일 시스템과 컨테이너 샌드박스 내부에서 실행됩니다. 그룹 간 데이터 교차 접근은 불가능합니다. -
스케줄링된 작업 (Scheduled Tasks): 특정 시간에 반복적으로 실행되는 크론(Cron) 작업을 설정할 수 있습니다. (예: "매일 아침 9시에 해커뉴스 요약 브리핑 보내줘")
-
웹 액세스: 웹 검색, 콘텐츠 가져오기 및 페이지 브라우징 기능을 통해 에이전트가 최신 정보를 수집하고 연구할 수 있습니다.
NanoClaw 구조
NanoClaw는 마이크로서비스나 무거운 메시지 브로커를 사용하지 않는 단일 Node.js 프로세스 기반으로 작동합니다. 전체적인 흐름은 다음과 같습니다:
WhatsApp (baileys) --> SQLite --> 그룹 큐(Polling loop) --> 컨테이너 (Claude Agent SDK) --> 응답 스트리밍
이러한 구조는 하나의 Node.js 프로세스가 메시지를 폴링하고, 큐를 관리하며, 컨테이너를 생성하고, IPC(프로세스 간 통신)를 처리합니다.
또한, GroupQueue를 통해 동시에 실행되는 컨테이너의 수를 제한하는 방식(기본값 3)으로 동시성 제어 (Concurrency Control) 를 구현하였습니다. 각 그룹별로 FIFO(선입선출) 방식을 따르며, 실패 시 지수 백오프(Exponential backoff)를 이용해 재시도합니다. 각 컨테이너는 그룹별 디렉터리에 있는 JSON 파일을 통해 호스트와 통신하는 파일 시스템을 통한 IPC로 구현되어 있습니다. 호스트는 이를 폴링하여 권한을 검증하고, 실행한 뒤 정리합니다.
[NanoClaw의 핵심 소스 파일 구성]
src/index.ts: 시스템 오케스트레이터. 상태 관리, 메시지 루프, 에이전트 호출을 담당합니다.src/container-runner.ts: 마운트가 격리된 상태로 컨테이너를 생성하고, 출력값을 스트리밍합니다.src/group-queue.ts: 동시성 제한 및 재시도 로직이 포함된 그룹별 FIFO 큐를 관리합니다.src/ipc.ts: 컨테이너의 IPC 요청을 처리하고 권한을 검사합니다.src/db.ts: SQLite를 이용해 메시지, 세션, 그룹, 작업, 라우터 상태 등을 관리합니다.src/task-scheduler.ts: 크론(Cron), 인터벌, 일회성 예약 작업의 실행을 담당합니다.
NanoClaw 설치 및 사용법
NanoClaw를 시작하려면 Node.js(버전 20 이상)와 Claude Code, 그리고 컨테이너 런타임(macOS의 경우 Apple Container 또는 Docker, Linux의 경우 Docker)이 필요합니다.
# 1. 저장소 복제(clone)
git clone https://github.com/qwibitai/nanoclaw.git
# 2. 디렉터리 이동
cd nanoclaw
# 3. Claude Code 실행
claude
이후 터미널의 Claude 인터페이스에서 /setup 명령어를 입력하면, Claude Code가 의존성 설치, 메신저 채널 인증, 컨테이너 런타임 설정 및 백그라운드 서비스 구성까지 모든 과정을 대화형으로 알아서 처리해 줍니다.
라이선스
NanoClaw 프로젝트는 MIT 라이선스로 공개 및 배포되고 있습니다.
NanoClaw 공식 홈페이지
NanoClaw 프로젝트 GitHub 저장소
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 