NanoClaw란 무엇인가
이 글에서는 NanoClaw라는 오픈소스 프로젝트를 중심으로, Apple 컨테이너 환경에서 실행되는 개인용 Claude 기반 AI 어시스턴트의 구조와 특징을 정리합니다.
NanoClaw는 약 500줄의 TypeScript 코드로 구성된 매우 작은 코드베이스를 기반으로 하면서도, 컨테이너 격리를 통한 보안, 스킬 기반 확장성, 그리고 AI 네이티브한 커스터마이징 방식을 제공하는 것이 특징입니다. 복잡한 프레임워크 없이도 개인 개발자나 소규모 팀이 안전하게 AI 비서를 구축할 수 있다는 점에서 의미 있는 사례로 볼 수 있습니다.
프로젝트 개요
NanoClaw는 Apple Container 환경에서 동작하는 개인용 Claude 어시스턴트입니다. 핵심 목표는 경량성과 보안성입니다.
- 단일 Node.js 프로세스로 실행
- 각 에이전트는 리눅스 컨테이너 안에서 동작하며 파일 시스템이 완전히 격리됨
- 전체 코드베이스는 약 500줄의 TypeScript
- 프로젝트 설명에 따르면 전체 구조를 8분 내 이해 가능한 수준을 목표로 설계
- MIT 라이선스로 공개되어 있으며 GitHub에서 500개 이상의 Star를 획득
이러한 구성은 “작지만 이해 가능한 AI 시스템”을 만들겠다는 방향성을 분명히 보여줍니다.
NanoClaw의 설계 철학
이해 가능한 규모
NanoClaw는 마이크로서비스, 메시지 큐, 복잡한 추상화 계층을 사용하지 않습니다. 단일 프로세스 구조를 유지함으로써, 사용자가 시스템 전체를 직접 파악하고 수정할 수 있도록 설계되었습니다.
격리를 통한 보안
보안은 컨테이너 격리를 통해 확보합니다.
- 명시적으로 마운트된 디렉터리만 접근 가능
- Bash 명령 역시 컨테이너 내부에서만 실행
- 그룹별로 파일 시스템과 대화 기록이 완전히 분리됨
이는 개인용 AI 어시스턴트임에도 불구하고, 명확한 보안 경계를 유지하려는 의도를 반영합니다.
단일 사용자 중심
NanoClaw는 범용 프레임워크가 아니라 개인 맞춤형 소프트웨어를 지향합니다. 사용자는 프로젝트를 포크한 뒤 직접 코드를 수정해 자신에게 맞는 AI 비서를 만들 수 있습니다.
설정 대신 코드 수정
일반적인 설정 파일 중심 접근 대신, NanoClaw는 설정 파일을 최소화합니다. 원하는 동작은 코드 변경으로 구현하며, 이 변경 과정 자체를 Claude Code와의 대화를 통해 진행합니다.
AI 네이티브 접근
설치, 디버깅, 모니터링까지 모두 Claude Code 대화형 인터페이스를 통해 수행합니다. AI를 단순히 기능으로 사용하는 것이 아니라, 개발 과정의 일부로 통합한 구조입니다.
주요 기능 정리
WhatsApp 기반 입출력
NanoClaw는 WhatsApp을 기본 인터페이스로 사용합니다. 사용자는 휴대폰에서 Claude와 직접 메시지를 주고받을 수 있습니다.
그룹별 컨텍스트 격리
- 각 그룹은 고유한 CLAUDE.md 메모리를 가짐
- 그룹마다 독립적인 컨테이너 파일 시스템 사용
- 관리용 메인 채널은 다른 그룹과 완전히 분리
이를 통해 대화 맥락과 데이터가 섞이지 않도록 설계되어 있습니다.
스케줄링 작업
주기적인 작업 실행과 자동 메시지 전송을 지원합니다. 개인 리마인더나 정기 요약 작업에 활용할 수 있습니다.
웹 접근
웹 검색과 콘텐츠 수집 기능을 제공해, 외부 정보 기반 응답이 가능합니다.
선택적 외부 서비스 연동
기본 기능 외에도 스킬을 통해 Gmail 등 외부 서비스와의 연동이 가능합니다.
스킬 기반 확장 구조
NanoClaw의 확장은 코드 직접 추가가 아닌, .claude/skills 디렉터리에 스킬 파일을 추가하는 방식으로 이뤄집니다.
대표적인 확장 예시는 다음과 같습니다.
- /add-telegram, /add-slack, /add-discord : 통신 채널 확장
- /convert-to-docker : Apple Container 기반 구조를 Docker로 변환
- /setup-windows : WSL2 기반 Windows 환경 지원
- /add-clear : 세션 요약 및 대화 압축 기능 추가
이 구조는 기능 확장을 단순화하면서도, 핵심 코드의 복잡도를 유지하지 않도록 돕습니다.
커스터마이징 방식
NanoClaw는 설정 파일 없이도 높은 수준의 커스터마이징을 지원합니다.
- Claude Code와의 대화를 통해 직접 변경
- 예시 요청
- “트리거 단어를 @Bob으로 변경”
- “응답을 더 짧게”
- “매주 대화 요약 저장”
- /customize 명령을 통해 단계별 수정 가능
- 코드베이스가 작아 Claude가 직접 안전하게 수정 가능
이는 AI가 단순 응답을 넘어, 실제 코드 변경을 돕는 역할을 수행한다는 점에서 특징적입니다.
시스템 구조와 요구사항
시스템 요구사항
- macOS Tahoe(26) 이상
- Node.js 20+
- Claude Code
- Apple Container
아키텍처 흐름
WhatsApp(baileys) → SQLite → Polling loop → Container(Claude Agent SDK) → Response
주요 파일 구성
- src/index.ts : 메인 애플리케이션 및 WhatsApp 연결
- src/container-runner.ts : 컨테이너 실행 관리
- src/task-scheduler.ts : 스케줄링 기능
- src/db.ts : SQLite 연동
- groups/*/CLAUDE.md : 그룹별 메모리 저장
FAQ에서 드러나는 프로젝트 방향성
- WhatsApp 사용 이유: 개인 사용 환경에 맞춘 선택이며, 다른 채널은 스킬로 대체 가능
- Apple Container 선택 이유: macOS 내장 환경으로 가볍고 빠름
- Linux 실행: Claude Code를 통해 약 30분 내 포팅 가능
- 보안: 컨테이너 격리를 통해 명시적 마운트 외 접근 불가
- 설정 파일 부재: 설정 확산을 방지하고 코드 중심 커스터마이징 유지
- 디버깅: Claude Code에 직접 질문해 해결
- 허용 변경 사항: 보안, 버그 수정, 기본 구성 개선 위주
NanoClaw는 대규모 AI 플랫폼이나 복잡한 프레임워크와는 다른 방향을 제시합니다.
작은 코드베이스, 명확한 보안 경계, AI 네이티브 개발 경험을 통해 **“이해 가능한 개인용 AI 어시스턴트”**라는 목표를 분명히 드러냅니다.
특히 개인 개발자나 스타트업 관점에서 보면, NanoClaw는 AI 비서를 직접 소유하고 통제할 수 있는 현실적인 출발점이 될 수 있습니다. 향후 이러한 경량·코드 중심 AI 어시스턴트 모델이 개인 생산성과 개발 문화에 어떤 영향을 줄지 기대해볼 만합니다.
https://github.com/gavrielc/nanoclaw
GitHub - gavrielc/nanoclaw: My personal Claude assistant that runs in Apple containers. Lightweight, secure, and built to be und
My personal Claude assistant that runs in Apple containers. Lightweight, secure, and built to be understood and customized for your own needs. - gavrielc/nanoclaw
github.com
'인공지능' 카테고리의 다른 글
| Cloudflare Workers에서 실행하는 개인 AI 에이전트, Moltworker 기술 정리 (0) | 2026.02.03 |
|---|---|
| Meta Seal: 생성형 AI 전반을 아우르는 오픈소스 보이지 않는 워터마킹 프레임워크 (0) | 2026.02.03 |
| 마이크로소프트 내부에서 확산 중인 Claude Code, AI 코딩 도구 전략의 변화 (0) | 2026.02.03 |
| 피지컬 AI 모델 시장 지도: 로봇 지능 경쟁의 구조와 핵심 시사점 (0) | 2026.02.03 |
| 4,000줄 코드로 구현한 초경량 개인 AI 에이전트, nanobot 정리 (0) | 2026.02.02 |
