NanoClaw – Apple 컨테이너 격리 환경에서 실행되는 500줄짜리 TypeScript 기반 Claude 어시스턴트

1 week ago 6

NanoClaw는 Apple 컨테이너에서 실행되는 개인용 Claude 기반 AI 어시스턴트로, 단일 프로세스 구조와 소수의 파일로 구성된 경량형 시스템
각 그룹별 컨테이너 격리를 통해 대화 기록과 파일 시스템을 분리하며, WhatsApp 메시징, 스케줄링 작업, 웹 접근 등을 지원
설정 파일 없이 Claude Code가 설치와 커스터마이징을 안내하며, 사용자는 직접 코드를 수정해 자신에게 맞게 조정 가능
새로운 기능은 코드 추가 대신 ‘스킬(Skill)’ 파일로 확장하며, /add-telegram, /convert-to-docker 등 다양한 확장 요청이 제시됨
복잡한 프레임워크 대신 이해 가능한 보안 구조와 단순성을 중시해, 개인 개발자나 스타트업이 안전하게 AI 비서를 구축할 수 있는 기반 제공

프로젝트 개요

NanoClaw는 Apple Container 환경에서 동작하는 개인용 Claude 어시스턴트로, 경량성과 보안성을 핵심으로 설계
- 단일 Node.js 프로세스에서 실행되며, 각 에이전트는 리눅스 컨테이너 내에서 격리된 파일 시스템을 사용
- 코드베이스는 약 500줄의 TypeScript로 구성되어 있으며, 사용자가 전체 구조를 8분 내 이해 가능하다고 설명
MIT 라이선스로 공개되어 있으며, GitHub에서 500개 이상의 Star를 획득

설계 철학

이해 가능한 규모: 마이크로서비스, 메시지 큐, 복잡한 추상화 없이 단일 프로세스로 구성
격리를 통한 보안: 명시적으로 마운트된 디렉터리만 접근 가능하며, Bash 명령도 컨테이너 내부에서만 실행
단일 사용자 중심: 프레임워크가 아닌 개인 맞춤형 소프트웨어로, 포크 후 직접 수정 가능
설정 대신 코드 수정: 설정 파일을 최소화하고, 원하는 동작은 코드 변경으로 구현
AI 네이티브 접근: 설치, 디버깅, 모니터링 모두 Claude Code 대화형 인터페이스를 통해 수행
스킬 기반 확장성: 기능 추가는 코드 변경이 아닌 .claude/skills 디렉터리의 스킬 파일로 처리

주요 기능

WhatsApp I/O: 휴대폰에서 Claude와 직접 메시지 교환
그룹별 컨텍스트 격리: 각 그룹은 고유한 CLAUDE.md 메모리와 컨테이너 파일 시스템을 가짐
메인 채널: 관리용 개인 채널로, 다른 그룹과 완전히 분리
스케줄링 작업: 주기적 작업 실행 및 자동 메시지 전송
웹 접근: 검색 및 콘텐츠 수집 기능
선택적 통합: /add-gmail 등 스킬을 통해 Gmail 등 외부 서비스 연동 가능

커스터마이징

설정 파일 없이 Claude Code 대화로 직접 변경 가능
- 예: “트리거 단어를 @Bob으로 변경”, “응답을 더 짧게”, “매주 대화 요약 저장” 등
/customize 명령으로 단계별 수정 지원
코드베이스가 작아 Claude가 직접 안전하게 수정 가능

확장 및 기여 방식

새로운 기능은 PR로 직접 추가하지 않고 스킬로 제공
- 예: /add-telegram, /add-slack, /add-discord 등 통신 채널 확장
- /convert-to-docker로 Apple Container를 Docker로 전환
- /setup-windows로 WSL2 기반 Windows 지원
- /add-clear로 세션 요약 및 압축 기능 추가
기여자는 스킬을 통해 자신의 포크를 변환하고, 이를 다시 프로젝트에 공유

시스템 요구사항 및 구조

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 사용 이유: 개인적으로 WhatsApp을 사용하기 때문이며, 다른 채널은 스킬로 교체 가능
Apple Container 선택 이유: macOS 내장, 가볍고 빠름
Linux 실행 가능 여부: Claude Code를 통해 약 30분 내 포팅 가능
보안성: 컨테이너 격리 기반으로, 명시적 마운트 외 접근 불가
설정 파일 부재 이유: 설정 확산을 방지하고, 코드 중심 커스터마이징 유지
디버깅 방법: Claude Code에 직접 질문하여 문제 해결
허용되는 변경 사항: 보안·버그 수정 및 기본 구성 개선만 허용

라이선스

MIT License로 배포
누구나 자유롭게 수정 및 재배포 가능

Read Entire Article