원문 보기
GitHub - gavrielc/nanoclaw: My personal Claude assistant that runs in Apple containers. Lightweight, secure, and built to be understood and customized for your own needs.
Service

GitHub - gavrielc/nanoclaw: My personal Claude assistant that runs in Apple containers. Lightweight, secure, and built to be understood and customized for your own needs.

gavrielc
2026.02.02
·GitHub·by web-ghost
#Claude#AI#Assistant#macOS#Container

핵심 포인트

  • 1NanoClaw는 Apple 컨테이너에서 실행되는 개인 Claude 어시스턴트로, 이해하고 커스터마이징하기 쉬운 가볍고 안전한 설계를 목표로 합니다.
  • 2에이전트는 Linux 컨테이너에 격리되어 보안을 강화하며, 복잡한 설정 파일 대신 코드 변경을 통해 사용자별 맞춤화를 지향하고, Claude Code가 설정 및 디버깅을 돕는 AI-native 방식을 채택합니다.
  • 3이 프로젝트는 'features'를 직접 추가하는 대신, 사용자가 자신의 포크에 적용할 수 있는 '/add-telegram'과 같은 'skills' 형태로 기능을 확장하고 기여하는 독특한 방식을 제안합니다.

NanoClaw는 Apple 컨테이너에서 실행되는 개인용 Claude 어시스턴트로, 복잡성을 줄이고 OS 수준의 격리를 통한 보안을 강조하는 프로젝트입니다. 이 프로젝트는 기존 AI 어시스턴트 프로젝트들이 가질 수 있는 복잡성(다수의 모듈, 종속성, 설정 파일, 공유 메모리, 애플리케이션 수준 보안)에 대한 대안으로 설계되었습니다.

핵심 철학 및 방법론 (Core Philosophy & Methodology):

  1. 간단성 (Small enough to understand): NanoClaw는 하나의 Node.js 프로세스로 실행되며, 소스 파일의 수가 적습니다. 마이크로서비스, 메시지 큐, 추상화 계층 없이 단일 통합 시스템으로 구축되어, 코드베이스를 쉽게 이해하고 수정할 수 있도록 합니다. 이는 복잡한 아키텍처 대신 명료하고 직접적인 접근 방식을 채택합니다.
  1. 격리를 통한 보안 (Secure by isolation): 핵심적인 보안 메커니즘은 OS 수준의 컨테이너 격리입니다. 에이전트(agents)는 실제 Linux 컨테이너(Apple Container) 내에서 실행되며, 이 컨테이너는 명시적으로 마운트된 디렉토리만 접근할 수 있습니다. 이는 에이전트가 시스템의 다른 부분에 접근하는 것을 엄격하게 제한하여 보안 취약점을 줄입니다. Bash 접근도 컨테이너 내부에서 안전하게 이루어집니다.
  1. 단일 사용자 지향 (Built for one user): NanoClaw는 범용 프레임워크가 아니라, 특정 사용자의 요구에 맞춰 설계된 작동하는 소프트웨어입니다. 사용자들은 자신의 필요에 따라 코드를 직접 수정함으로써 시스템을 커스터마이징합니다. 설정 파일 대신 코드 변경을 통해 동작을 수정하는 방식을 채택하여, 설정 관리의 복잡성을 제거합니다.
  1. AI-native 접근 (AI-native): 설정 마법사, 모니터링 대시보드, 디버깅 도구 없이, 모든 관리 및 문제 해결은 Claude Code를 통해 이루어집니다. 사용자는 자연어 명령을 통해 설정을 변경하고, 시스템 상태를 질의하며, 문제 발생 시 Claude에게 해결을 요청합니다.
  1. 기능보다 스킬 (Skills over features): 프로젝트에 새로운 기능을 직접 추가하는 대신, 기여자들은 claude code skills를 개발하여 기여합니다. 예를 들어, Telegram 지원을 추가하려면 _claude/skills/add-telegram/SKILL.md와 같은 스킬 파일을 생성합니다. 사용자는 자신의 포크(fork)에서 /add-telegram 명령을 실행하여 해당 기능을 자신의 NanoClaw 설치에 통합하며, 이는 코드를 직접 변형시키는 방식입니다. 이 접근 방식은 핵심 코드베이스를 최소화하고 각 사용자가 필요한 기능만 선택적으로 추가할 수 있도록 합니다.
  1. 아키텍처 (Architecture):
    • 흐름: WhatsApp(baileys)−−>SQLite−−>Pollingloop−−>Container(ClaudeAgentSDK)−−>ResponseWhatsApp (baileys) --> SQLite --> Polling loop --> Container (Claude Agent SDK) --> Response
    • 단일 Node.js 프로세스: src/index.ts (메인 앱, WhatsApp 연결, 라우팅, IPC), src/container-runner.ts (에이전트 컨테이너 생성), src/task-scheduler.ts (예약 작업 실행), src/db.ts (SQLite 작업) 등으로 구성됩니다.
    • 컨테이너 기반 에이전트 실행: 에이전트는 격리된 Linux 컨테이너 내에서 실행되며, 각 그룹은 자체 CLAUDE.md 메모리, 격리된 파일 시스템을 가지며 독립적인 컨테이너 샌드박스에서 실행됩니다.
    • 파일 시스템을 통한 IPC (Inter-Process Communication): 프로세스 간 통신은 복잡한 데몬이나 큐 없이 파일 시스템을 통해 이루어집니다.

지원 기능 및 특징:

  • WhatsApp I/O: 휴대폰에서 Claude와 메시지를 주고받을 수 있습니다.
  • 격리된 그룹 컨텍스트: 각 그룹은 독립적인 메모리 및 파일 시스템을 가집니다.
  • 메인 채널: 관리 제어를 위한 개인 채널입니다.
  • 예약 작업 (Scheduled tasks): Claude가 정기적으로 작업을 수행하고 사용자에게 메시지를 보낼 수 있습니다.
  • 웹 접근: 콘텐츠 검색 및 가져오기 기능을 지원합니다.
  • 선택적 통합 (Optional integrations): 스킬을 통해 Gmail과 같은 추가 서비스를 통합할 수 있습니다.

NanoClaw는 macOS Tahoe (26) 이상 및 Node.js 20+ 환경에서 실행되며, 경량화되고 이해하기 쉬운 코드베이스를 통해 사용자가 직접 시스템을 제어하고 커스터마이징할 수 있도록 설계된 개인 AI 어시스턴트 솔루션입니다.