nanoclaw

에이전트를 자체 컨테이너 안에서 안전하게 실행하는 AI 어시스턴트. 가볍고, 쉽게 이해할 수 있도록 만들어졌으며, 필요에 맞게 완전히 커스터마이즈할 수 있습니다.

nanoclaw.dev •
docs •
中文 •
日本語 •
한국어 •
•

Slack 속 에이전트: 에이전트당 앱 하나
설정 시 각 에이전트에 전용 Slack 앱이 프로비저닝됩니다: 매니페스트, 아바타, 워크스페이스 설치까지, 붙여넣을 토큰이 없습니다.
채팅에서 팀원 생성: 각자 고유한 봇 아이덴티티, 컨테이너, 메모리를 가지며, 공유 룸과 캔버스를 함께 사용합니다.

NanoClaw를 만든 이유
OpenClaw는 인상적인 프로젝트이지만, 제가 이해하지 못하는 복잡한 소프트웨어에 제 삶에 대한 전면적인 접근 권한을 준다면 잠을 이룰 수 없었을 것입니다. OpenClaw는 거의 50만 줄의 코드, 53개의 설정 파일, 70개 이상의 의존성을 가지고 있습니다. 보안은 진정한 OS 수준 격리가 아니라 애플리케이션 수준(허용 목록, 페어링 코드)에 머물러 있습니다. 모든 것이 공유 메모리를 가진 하나의 Node 프로세스에서 실행됩니다.

NanoClaw는 동일한 핵심 기능을 제공하지만, 이해할 수 있을 만큼 작은 코드베이스로 제공합니다: 하나의 프로세스와 몇 개의 파일. 에이전트는 단순히 권한 검사 뒤에 있는 것이 아니라, 파일시스템 격리를 갖춘 자체 Linux 컨테이너에서 실행됩니다.

빠른 시작
git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash nanoclaw.sh
nanoclaw.sh는 새 머신에서 메시지를 보낼 수 있는 이름 붙은 에이전트까지 안내합니다. Node, pnpm, Docker가 없으면 설치하고, 자격 증명 게이트웨이를 설치하고 Anthropic 자격 증명을 등록하며, 에이전트 컨테이너를 빌드하고, 첫 번째 채널(Slack, Telegram, Discord, WhatsApp, iMessage 또는 로컬 CLI)을 페어링합니다. 단계가 실패하면 Claude Code가 자동으로 호출되어 진단하고 중단된 지점부터 재개합니다.

NanoClaw v1에서 마이그레이션하시나요?
v1 설치 옆의 새 v2 체크아웃에서 실행하세요:

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash migrate-v2.sh
migrate-v2.sh는 v1 설치를 찾아(형제 디렉터리 또는 NANOCLAW_V1_PATH=/path/to/nanoclaw), 상태를 v2 체크아웃으로 마이그레이션한 다음, 판단이 필요한 부분(소유자 시딩, 공유 메모리 마이그레이션, 포크 커스터마이제이션 재적용)을 마무리하기 위해 Claude Code로 exec합니다.

스크립트는 Claude 세션 내부가 아니라 직접 실행하세요 — 결정론적 부분은 Node/pnpm 부트스트랩, Docker, 자격 증명 게이트웨이, 컨테이너 빌드를 위한 대화형 프롬프트와 실제 셸 I/O가 필요합니다.

하는 일: .env를 병합하고, registered_groups에서 v2 DB를 시딩하고, 그룹 폴더 + 세션 데이터 + 예약된 작업을 복사하고, 선택한 채널 어댑터를 설치하고, 채널 인증 상태를 복사하고(WhatsApp용 Baileys 키스토어 포함 — LID 매핑은 이제 Baileys v7 어댑터가 메시지별로 해석하며, 마이그레이션되지 않음), 에이전트 컨테이너를 빌드합니다.

하지 않는 일: 시스템 서비스를 전환하지 않습니다. 프롬프트에서 "switch to v2"를 선택하거나 테스트 후 수동으로 하세요 — v1 설치는 그대로 유지됩니다.

무엇이 달라졌는지는 docs/v1-to-v2-changes.md를, 개발 노트는 docs/migration-dev.md를 참고하세요.

철학
이해할 수 있을 만큼 작게. 하나의 프로세스, 몇 개의 소스 파일, 마이크로서비스 없음. 전체 NanoClaw 코드베이스를 이해하고 싶다면 Claude Code에게 안내를 요청하세요.

격리로 안전하게. 에이전트는 Linux 컨테이너에서 실행되며 명시적으로 마운트된 것만 볼 수 있습니다. Bash 접근이 안전한 이유는 명령이 호스트가 아니라 컨테이너 내부에서 실행되기 때문입니다.

개인 사용자를 위해 만들어짐. NanoClaw는 모놀리식 프레임워크가 아니라 각 사용자의 정확한 요구에 맞는 소프트웨어입니다. 블로트웨어가 되는 대신, NanoClaw는 맞춤형으로 설계되었습니다. 자신만의 포크를 만들고 Claude Code가 필요에 맞게 수정하도록 하세요.

커스터마이제이션 = 코드 변경. 설정 범람 없음. 다른 동작을 원하시나요? 코드를 수정하세요. 코드베이스가 작아서 변경하기 안전합니다.

AI 네이티브, 설계상 하이브리드. 설치 및 온보딩 흐름은 빠르고 결정론적인 최적화된 스크립트 경로입니다. 판단이 필요한 단계 — 실패한 설치, 안내된 결정, 커스터마이제이션 — 에서는 제어가 Claude Code로 매끄럽게 넘어갑니다. 설정 이후에도 모니터링 대시보드나 디버깅 UI는 없습니다: 채팅에서 문제를 설명하면 Claude Code가 처리합니다.

기능보다 스킬. 트렁크는 레지스트리와 인프라를 제공하며, 특정 채널 어댑터나 대체 에이전트 제공자는 제공하지 않습니다. 채널(Discord, Slack, Telegram, WhatsApp, …)은 장기 유지되는 channels 브랜치에 있고, 대체 제공자(OpenCode, Codex, Cursor)는 각자의 스킬 payload/ 폴더 안에 제공됩니다. /add-telegram, /add-opencode 등을 실행하면 스킬이 필요한 모듈만 포크에 복사합니다. 요청하지 않은 기능은 없습니다.

최고의 하네스, 최고의 모델. NanoClaw는 Anthropic의 공식 Claude Agent SDK를 통해 Claude Code를 기본으로 사용하므로, 최신 Claude 모델과 Claude Code의 전체 도구 세트를 얻을 수 있으며, 여기에는 자신의 NanoClaw 포크를 수정하고 확장하는 능력도 포함됩니다. 다른 제공자는 드롭인 옵션입니다: OpenAI의 Codex용 /add-codex(ChatGPT 구독 또는 API 키), OpenCode를 통한 OpenRouter, Google, DeepSeek 등용 /add-opencode, Cursor의 로컬 Agent SDK용 /add-cursor(Cursor 계정 또는 API 키), 로컬 오픈 웨이트 모델용 /add-ollama-provider. 제공자는 에이전트 그룹별로 구성할 수 있습니다.

지원하는 것

멀티 채널 메시징 — WhatsApp, Telegram, Discord, Slack, Microsoft Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, 그리고 Resend를 통한 이메일. /add-<channel> 스킬로 필요 시 설치합니다. 하나 또는 여러 개를 동시에 실행할 수 있습니다.
유연한 격리 — 각 채널을 자체 에이전트에 연결해 완전한 프라이버시를 누리거나, 하나의 에이전트를 여러 채널에 걸쳐 공유해 별도의 대화와 함께 통합된 메모리를 사용하거나, 여러 채널을 하나의 공유 세션으로 통합해 하나의 대화가 여러 표면에 걸치도록 할 수 있습니다. /manage-channels로 채널별로 선택하세요. docs/isolation-model.md를 참고하세요.
에이전트별 워크스페이스 — 각 에이전트 그룹은 자체 CLAUDE.md, 자체 메모리, 자체 컨테이너, 그리고 허용한 마운트만 가집니다. 연결하지 않으면 경계를 넘는 것은 없습니다.
예약된 작업: 에이전트가 실행하는 반복 작업으로, 작업이 없을 때 에이전트를 깨우지 않도록 하는 선택적 스크립트 게이트 포함
웹 접근 — 웹에서 검색하고 콘텐츠 가져오기
컨테이너 격리 — 에이전트는 Docker 컨테이너에서 샌드박스화됩니다(macOS/Linux/WSL2)
자격 증명 보안 — 에이전트는 원시 API 키를 절대 보유하지 않습니다. 아웃바운드 요청은 요청 시점에 자격 증명을 주입하고 에이전트별 정책과 속도 제한을 적용하는 자격 증명 게이트웨이를 통해 라우팅됩니다. 어떤 게이트웨이를 쓸지는 여러분이 선택합니다: 설정이 제공자 심(seam) 뒤에 하나(현재 OneCLI의 Agent Vault)를 설치합니다.
에이전트 템플릿: 재사용 가능한 번들에서 바로 실행 가능한 에이전트(지침 + MCP 도구 + 스킬, 시크릿 없음)를 ncl groups create --template <ref>로 찍어냅니다. 템플릿은 로컬 templates/ 폴더에서 로드되며, 수동으로 채우거나 공개 라이브러리에서 복사해 채웁니다. docs/templates.md를 참고하세요.

계정과 머신을 떠나는 것
NanoClaw에는 사용자 계정이 없습니다. 보고하는 유일한 것은 익명 설정 진단이며,
NANOCLAW_NO_DIAGNOSTICS=1로 끌 수 있습니다. 에이전트, 메시지, 파일, 키는 절대
머신을 떠나지 않습니다.

한 가지 옵트인 예외: 로컬에서 빌드하는 대신 미리 빌드된 에이전트 이미지를
가져올 수 있습니다. 저희 것을 가져오려면 무료 계정이 필요하므로, 저희는 여러분의 이메일 주소와
이미지를 요청한 시점을 봅니다 — 에이전트에 관한 것은 아무것도, 이미지가 도착한 이후로도 아무것도 아닙니다. 로컬에서
빌드하는 것은 계정이 필요 없고 아무것도 접촉하지 않으며, 이것이 기본값입니다. 동일한 계정으로 아래의
혜택이 열립니다.

혜택
무료 계정은 portal.nanoclaw.dev의 커뮤니티 포털도 열어줍니다,
계정이 제공하는 것을 켜는 대시보드입니다. 현재는 Echo의 강화된 에이전트
이미지와 에이전트용 관리형 Slack 앱으로, 붙여넣을 토큰 없이 생성되고 설치됩니다. NanoClaw의 다른 모든 것은 이것 없이도 작동합니다.

설정은 포털을 한 번 엽니다. 브라우저에서 로그인하고, 설정을 실행 중인 터미널을 승인하고,
혜택을 활성화하세요. 마법사가 이를 감지하고 스스로 계속합니다. Echo 활성화는
제품 및 보안 이메일 수신 여부를 포함해 Echo의 약관에 동의하는 곳입니다. 아무것도 활성화하지 않고
페이지를 닫으면 설정은 혜택 없이 계속되고, 나중에 다시 한 번 제안합니다.

머신에 남는 것: ~/.config/nanoclaw/account.json의 로그인 기록과 설치 토큰,
머신당 하나의 디바이스 키 ~/.config/nanoclaw/device-key.json, 그리고 이 체크아웃의 저널
data/community-portal.json(어떤 혜택이 켜져 있는지, 설정 진행 상황, 혜택이 건네준 자격 증명), 모두 모드 0600입니다. 설치 토큰은 절대 브라우저를 거치지 않습니다: 브라우저는
일회성 로그인 코드만 보고, 토큰은 계정 서비스에서 이 머신으로 직접 도달합니다.
호스트는 브라우저에서 변경한 혜택이 실행 중인 에이전트에 도달하도록 포털에 대한 아웃바운드 연결 하나를 유지합니다; 에이전트, 메시지, 파일에 관한 것은 아무것도 보내지 않습니다.

pnpm exec tsx setup/portal.ts --stage echo 또는 --stage slack으로 단계를 다시 방문하세요. 머신을
로그아웃하려면 포털의 Devices에서 잊으세요: 토큰이 작동을 멈추고 호스트가
연결을 끊습니다. 파일, 복구 명령, 문제 해결: docs/community-portal.md.

사용법
트리거 단어(기본값: @Andy)로 어시스턴트와 대화하세요:

@Andy 매주 평일 아침 9시에 영업 파이프라인 개요를 보내줘 (내 Obsidian vault 폴더에 접근 가능)
@Andy 매주 금요일 지난 한 주의 git 히스토리를 검토하고 드리프트가 있으면 README를 업데이트해줘
@Andy 매주 월요일 오전 8시에 Hacker News와 TechCrunch에서 AI 개발 관련 뉴스를 정리해서 브리핑을 보내줘

소유하거나 관리하는 채널에서 그룹과 작업을 관리할 수 있습니다:

@Andy 모든 그룹의 예약된 작업 목록을 보여줘
@Andy 월요일 브리핑 작업을 일시 중지해줘
@Andy Family Chat 그룹에 참여해줘

커스터마이징
NanoClaw는 설정 파일을 사용하지 않습니다. 변경하려면 Claude Code에게 원하는 것을 말하기만 하세요:

"트리거 단어를 @Bob으로 바꿔줘"
"앞으로 응답을 더 짧고 직접적으로 해줘"
"내가 좋은 아침이라고 하면 커스텀 인사말을 추가해줘"
"대화 요약을 매주 저장해줘"

또는 안내된 변경을 위해 /customize를 실행하세요.

코드베이스가 작아서 Claude가 안전하게 수정할 수 있습니다.

기여하기
기능을 추가하지 마세요. 스킬을 추가하세요.

새 채널이나 에이전트 제공자를 추가하려면 트렁크에 추가하지 마세요. 새 채널 어댑터는 channels 브랜치에 들어가고, 새 에이전트 제공자는 main의 스킬 payload/ 폴더에 코드를 둡니다. 사용자는 /add-<name> 스킬로 자신의 포크에 설치하며, 이 스킬은 관련 모듈을 표준 경로로 복사하고, 등록을 연결하고, 의존성을 고정합니다.

이렇게 하면 트렁크는 순수한 레지스트리와 인프라로 유지되고, 모든 포크는 간결하게 유지됩니다 — 사용자는 요청한 채널과 제공자만 얻고 그 외에는 아무것도 얻지 않습니다.

RFS (Request for Skills)
현재 요청된 채널 또는 제공자 스킬은 없습니다 — 이슈로 제안하세요.

요구 사항

macOS 또는 Linux (Windows는 WSL2 경유)
Node.js 22.23.4+, 24.22.1+ 또는 26.12.1+ 및 pnpm 10+ (설치 프로그램이 필요 시 둘 다 설치하거나 업데이트합니다)
Docker Desktop (macOS/Windows) 또는 Docker Engine (Linux)
/customize, /debug, 설정 중 오류 복구, 모든 /add-<channel> 스킬을 위한 Claude Code

아키텍처
메시징 앱 → 호스트 프로세스(라우터) → inbound.db → 컨테이너(Bun, Claude Agent SDK) → outbound.db → 호스트 프로세스(전달) → 메시징 앱

단일 Node 호스트가 세션별 에이전트 컨테이너를 조율합니다. 메시지가 도착하면 호스트는 엔티티 모델(사용자 → 메시징 그룹 → 에이전트 그룹 → 세션)을 통해 라우팅하고, 세션의 inbound.db에 쓰고, 컨테이너를 깨웁니다. 컨테이너 내부의 agent-runner는 inbound.db를 폴링하고, 에이전트를 실행하고, 응답을 outbound.db에 씁니다. 호스트는 outbound.db를 폴링하고 채널 어댑터를 통해 다시 전달합니다.

세션당 두 개의 SQLite 파일, 각각 정확히 하나의 작성자 — 교차 마운트 경합 없음, IPC 없음, stdin 파이핑 없음. 채널과 대체 제공자는 시작 시 자체 등록합니다; 트렁크는 레지스트리와 Chat SDK 브리지를 제공하고, 어댑터 자체는 포크별로 스킬 설치됩니다.

전체 아키텍처 설명은 docs/architecture.md를, 3단계 격리 모델은 docs/isolation-model.md를 참고하세요.

주요 파일:

src/index.ts — en…