nanocoai/nanoclaw

NanoClaw – 안전하고 컨테이너로 격리된 AI 어시스턴트

개요

• AI 에이전트(Claude, OpenAI, Ollama 등)를 별도의 Docker 컨테이너에서 실행할 수 있게 해주는 오픈소스 프레임워크입니다. 각 에이전트는 고유한 파일 시스템, 메모리, 자격 증명을 가지므로 호스트 머신은 모델의 실행 환경으로부터 격리됩니다.
• 작고 이해하기 쉬운 설계: 단일 Node.js 프로세스가 모든 것을 오케스트레이션하며, 핵심 코드는 소수의 파일로 구성됩니다.

주요 기능

기능	설명
에이전트별 컨테이너 격리	모든 에이전트는 자체 Linux 컨테이너에서 실행되며, 명시적으로 마운트한 디렉토리만 에이전트에 노출됩니다.
다중 채널 메시징	Slack, Discord, Telegram, WhatsApp, iMessage, Microsoft Teams, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, 이메일(Resend 경유) 및 로컬 CLI용 어댑터가 내장되어 있습니다. /add-<channel> 스킬을 통해 필요에 따라 새 어댑터를 추가하세요.
자격 증명 게이트웨이	API 키는 컨테이너에 절대 노출되지 않습니다. 아웃바운드 요청은 자격 증명 게이트웨이 서비스(기본값: OneCLI의 Agent Vault)를 통해 프록시되며, 이 서비스는 에이전트별로 올바른 비밀 정보를 주입하고 속도 제한을 적용합니다.
에이전트 템플릿	templates/ 또는 공개 템플릿 라이브러리에 저장된 템플릿을 사용하여 즉시 실행 가능한 에이전트를 빠르게 생성합니다.
예약 작업	반복적인 작업(예: 일일 브리핑)을 정의하면 컨테이너가 필요할 때만 실행하며, 스크립트 게이트를 통해 선택적으로 보호할 수 있습니다.
하이브리드 AI 네이티브 워크플로우	설치 및 오류 복구는 스크립트로 자동화되어 있지만, 판단이 필요한 단계에서는 시스템이 Claude Code(Anthropic의 "코드 어시스턴트")에 작업을 넘겨 자동으로 진단하고 계속 진행하도록 합니다.
제로 설정 커스터마이징	방대한 설정 파일을 편집하는 대신 Claude Code에게 원하는 바(예: 트리거 단어 변경)를 말하면 소스 코드를 직접 수정해 줍니다.
교차 모델 지원	Claude가 기본 제공자이지만, 간단한 /add-<provider> 명령어를 통해 OpenAI Codex, OpenCode를 통한 OpenRouter, Cursor의 로컬 SDK 또는 모든 Ollama 모델을 추가할 수 있습니다.

설치 및 빠른 시작

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash nanoclaw.sh   # Node, pnpm, Docker 설치(필요 시), Anthropic 자격 증명 등록, 첫 번째 에이전트 컨테이너 빌드 및 채널(Slack, Telegram 등) 페어링 수행

스크립트가 모든 단계를 안내하며, 문제가 발생하면 Claude Code가 자동으로 호출되어 디버깅 및 재개를 수행합니다.

에이전트와 상호작용하는 방법

• 트리거 단어(기본값 @Andy)를 선택합니다.
• 연결된 채널에서 자연어 명령을 보냅니다. 예:

  @Andy send an overview of the sales pipeline every weekday morning at 9 am (has access to my Obsidian vault folder)
  @Andy review the git history for the past week each Friday and update the README if there’s drift
  

• @Andy list all scheduled tasks 또는 @Andy join the Family Chat group과 같은 채팅 명령어로 그룹, 작업 및 채널 연결을 관리합니다.

NanoClaw 확장하기

• 스킬 (Skills) – 새로운 기능은 핵심 기능이 아닌 스킬로 추가됩니다. 스킬은 자체 폴더(payload/)에 위치하며 슬래시 명령어(/add-telegram, /add-opencode 등)로 설치됩니다.
• 채널 (Channels) – 채널 어댑터는 전용 channels 브랜치에 있습니다. 리포지토리를 포크하고 커스텀 어댑터를 추가한 뒤 자신의 설치 환경에 복사하여 사용할 수 있습니다.
• 제공자 (Providers) – 대체 LLM 백엔드도 같은 방식으로 추가되어 메인 코드베이스를 최소한으로 유지합니다.

보안 모델

• OS 수준 격리 – Docker 컨테이너를 통해 각 에이전트는 고유한 PID, 네트워크 네임스페이스 및 파일 시스템 뷰를 가집니다.
• 자격 증명 처리 – 비밀 정보는 호스트에만 저장되며 요청 시 자격 증명 게이트웨이에 의해 주입됩니다. 컨테이너는 원본 키를 볼 수 없습니다.
• 사용자 계정 없음 – NanoClaw는 클라우드 계정을 생성하지 않습니다. 유일한 아웃바운드 연결은 혜택(예: 강화된 사전 빌드 이미지 또는 관리형 Slack 앱)을 위한 선택적 커뮤니티 포털 연결뿐입니다. 모든 진단 정보는 익명이며 NANOCLAW_NO_DIAGNOSTICS=1을 통해 비활성화할 수 있습니다.

일반적인 사용 사례

• 개인 보관소의 파일을 읽고 쓰고, 보고서를 예약하며, 버전 관리와 상호작용하는 개인 생산성 어시스턴트.
• API 키 노출 없이 웹 브라우징, 데이터 가져오기, 사용자 대리 실행이 가능한 안전한 셀프 호스팅 챗봇.
• 각 팀원이 격리된 에이전트를 가지면서 공통 채널(예: Slack 워크스페이스)을 공유하는 다중 사용자 팀 봇.
• 런타임 환경을 동일하게 유지하면서 다양한 LLM 제공자를 테스트하기 위한 실험 플랫폼.

커뮤니티 및 지원

• Discord 커뮤니티: https://discord.gg/VDdww8qS42
• 문서 사이트: https://docs.nanoclaw.dev
• 공개 템플릿 라이브러리: https://github.com/nanocoai/nanoclaw-templates

라이선스

• MIT – 개인, 학술 또는 상업적 용도로 무료 사용 가능.

---

NanoClaw는 방대한 모놀리식 코드베이스를 다룰 필요 없이, 이해하고 감사하며 조정할 수 있는 투명하고 컨테이너로 격리된 AI 어시스턴트를 파워 유저에게 제공하는 것을 목표로 합니다.