<p align="center">
<img src="https://raw.githubusercontent.com/nanocoai/nanoclaw/HEAD/assets/nanoclaw-logo.png" alt="NanoClaw" width="400">
</p>
<p align="center">
자신의 컨테이너 내에서 에이전트를 안전하게 실행하는 AI 어시스턴트입니다. 가볍고, 이해하기 쉬우며, 사용자의 필요에 맞게 완전히 사용자 정의되도록 구축되었습니다.
</p>
<p align="center">
<a href="https://nanoclaw.dev">nanoclaw.dev</a> •
<a href="https://docs.nanoclaw.dev">문서(docs)</a> •
<a href="README_zh.md">중국어</a> •
<a href="README_ja.md">일본어</a> •
<a href="README_ko.md">한국어</a> •
<a href="https://discord.gg/VDdww8qS42"><img src="https://img.shields.io/discord/1470188214710046894?label=Discord&logo=discord&v=2" alt="Discord" valign="middle"></a> •
<a href="repo-tokens"><img src="https://raw.githubusercontent.com/nanocoai/nanoclaw/HEAD/repo-tokens/badge.svg" alt="repo tokens" valign="middle"></a>
</p>
<div align="center">
<img src="https://img.shields.io/badge/NEW!-2EB67D?style=for-the-badge" alt="NEW!" valign="middle"> 슬랙(Slack) 에이전트 기능: 에이전트당 하나의 앱을 사용합니다 <img src="https://raw.githubusercontent.com/nanocoai/nanoclaw/HEAD/assets/slack-icon.svg" alt="" width="22" valign="middle">
각 에이전트에 대해 매니페스트, 아바타 및 워크스페이스 설치가 제공되며, 토큰을 붙여넣을 필요가 없습니다. 채팅에서 팀원을 생성하세요: 모든 팀원은 고유한 봇 ID, 컨테이너 및 메모리를 가지며, 공유된 공간과 캔버스를 사용합니다.
Quick Start
</div>
왜 NanoClaw를 만들었는가
OpenClaw는 인상적인 프로젝트이지만, 제가 이해하지 못하는 복잡한 소프트웨어에 제 삶 전체에 대한 완전한 접근 권한을 부여했다면 잠을 잘 수 없었을 것입니다. OpenClaw는 거의 50만 줄의 코드, 53개의 설정 파일, 그리고 70개 이상의 의존성을 가지고 있습니다. 이 소프트웨어의 보안은 진정한 OS 레벨 격리(isolation)가 아니라 애플리케이션 레벨(허용 목록(allowlists), 페어링 코드)에 있습니다. 모든 것이 공유 메모리를 가진 하나의 Node 프로세스에서 실행됩니다.
NanoClaw는 동일한 핵심 기능을 제공하지만, 이해하기에 충분히 작은 코드베이스(one process and a handful of files)로 구현되었습니다. 에이전트는 단순한 권한 확인을 넘어 자체적인 파일 시스템 격리(filesystem isolation)가 적용된 Linux 컨테이너 내에서 실행됩니다.
빠른 시작 (Quick Start)
git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash nanoclaw.sh
nanoclaw.sh는 사용자를 초기 상태의 기기부터 메시지를 보낼 수 있는 이름 지정된 에이전트까지 안내합니다. 누락된 경우 Node, pnpm, Docker를 설치하고, 자격 증명 게이트웨이(credential gateway)를 설치한 후 Anthropic 자격 증명을 여기에 등록하며, 에이전트 컨테이너를 빌드하고 첫 번째 채널(Slack, Telegram, Discord, WhatsApp, iMessage 또는 로컬 CLI)을 연결합니다. 만약 단계 중 하나가 실패하면, Claude Code가 자동으로 호출되어 진단하고 오류가 발생한 지점부터 재개합니다.
<details>
<summary><strong >NanoClaw v1에서 마이그레이션하기?</strong></summary>
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 체크아웃으로 마이그레이션한 다음, 판단이 필요한 부분(owner seeding, shared-memory migration, fork-customisation replay)을 완료하기 위해 Claude Code로 exec합니다.
스크립트를 Claude 세션 내부가 아닌 직접 실행해야 합니다. — 결정론적 측면은 Node/pnpm 부트스트랩, Docker, 자격 증명 게이트웨이 및 컨테이너 빌드를 위한 대화형 프롬프트와 실제 셸 I/O를 필요로 하기 때문입니다.
작동 방식: .env 파일을 병합하고, registered_groups로부터 v2 DB에 시드(seed)하며, 그룹 폴더 + 세션 데이터 + 예약된 작업을 복사하고, 선택한 채널 어댑터(channel adapters)를 설치하며, 채널 인증 상태(WhatsApp의 Baileys keystore 포함 — LID 매핑은 이제 Baileys v7 어댑터에 의해 메시지별로 해결되며 마이그레이션되지 않음)를 복사하고, 에이전트 컨테이너를 빌드합니다.
</details>
작동하지 않는 것: 시스템 서비스를 전환(flip)하지 않습니다. 프롬프트에서 “v2로 전환하기(switch to v2)”를 선택하거나, 테스트 후 수동으로 진행하면 됩니다. 사용자의 v1 설치는 그대로 유지됩니다.
어떤 부분이 다른지 알아보려면 docs/v1-to-v2-changes.md를 참고하고, 개발 관련 노트는 docs/migration-dev.md를 확인하세요.
철학 (Philosophy)
이해하기에 충분히 작습니다. 하나의 프로세스, 몇 개의 소스 파일, 그리고 마이크로서비스(microservices)가 없습니다. NanoClaw의 전체 코드베이스를 이해하고 싶다면 Claude Code에게 안내를 요청하기만 하면 됩니다.
격리 기반 보안 (Secure by isolation). 에이전트(Agents)는 Linux 컨테이너 내에서 실행되며 명시적으로 마운트된 것만 볼 수 있습니다. Bash 접근은 안전한데, 명령어들이 호스트가 아닌 컨테이너 내부에서 실행되기 때문입니다.
개별 사용자에게 맞춰 설계되었습니다. NanoClaw는 모놀리식 프레임워크(monolithic framework)가 아닙니다. 각 사용자의 정확한 요구 사항에 맞는 소프트웨어입니다. 무겁고 불필요한 소프트웨어(bloatware)가 되는 대신, NanoClaw는 맞춤 제작되도록 설계되었습니다. 사용자가 직접 포크(fork)를 만들고 Claude Code에게 필요한 기능에 맞춰 수정하도록 할 수 있습니다.
커스터마이징 = 코드 변경. 설정의 복잡성(configuration sprawl)이 없습니다. 다른 동작을 원하십니까? 코드를 수정하십시오. 이 코드베이스는 변경하기에 충분히 작아 안전합니다.
AI 네이티브, 하이브리드 설계. 설치 및 온보딩 흐름은 빠르고 결정론적인 최적화된 스크립트 경로입니다. 실패한 설치, 안내가 필요한 의사 결정, 또는 커스터마이징 등 단계별 판단이 필요할 때 제어권이 Claude Code로 원활하게 이관됩니다. 설정 이후에는 모니터링 대시보드나 디버깅 UI도 없습니다. 채팅으로 문제를 설명하면 Claude Code가 처리합니다.
기능보다 스킬 (Skills over features). Trunk는 특정 채널 어댑터나 대체 에이전트 제공업체가 아닌 레지스트리(registry)와 인프라를 배포합니다. 채널(Discord, Slack, Telegram, WhatsApp 등)은 장기간 유지되는 channels 브랜치에 존재하며, 대체 제공업체(OpenCode, Codex, Cursor)는 자체 스킬의 payload/ 폴더 안에 포함됩니다. 사용자는 /add-telegram, /add-opencode 등을 실행하고, 스킬이 필요한 모듈만을 정확히 포크로 복사합니다. 요청하지 않은 기능은 없습니다.
최고의 하네스, 최고의 모델입니다. NanoClaw는 Anthropic의 공식 Claude Agent SDK를 통해 네이티브하게 Claude Code를 사용하므로, 최신 Claude 모델과 사용자 자신의 NanoClaw 포크를 수정하고 확장할 수 있는 기능을 포함한 Claude Code의 전체 도구 세트를 얻을 수 있습니다. 다른 제공업체들도 드롭인 옵션입니다: OpenAI의 Codex용 /add-codex (ChatGPT 구독 또는 API 키), OpenCode를 통해 OpenRouter, Google, DeepSeek 등 다수 제공업체를 위한 /add-opencode, Cursor의 로컬 Agent SDK용 /add-cursor (Cursor 계정 또는 API 키), 그리고 로컬 오픈 웨이트 모델을 위한 /add-ollama-provider가 있습니다. 제공업체는 에이전트 그룹별로 구성 가능합니다.
지원 기능 (What It Supports)
- 다중 채널 메시징 (Multi-channel messaging) — WhatsApp, Telegram, Discord, Slack, Microsoft Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, WeChat 및 Resend를 통한 이메일 지원.
/add-<channel> 스킬을 통해 필요할 때 설치합니다. 하나 또는 여러 개를 동시에 실행할 수 있습니다.
- 유연한 격리(Flexible isolation) — 각 채널을 자체 에이전트에 연결하여 완벽한 개인 정보 보호를 하거나, 여러 채널에 하나의 에이전트를 공유하여 별도의 대화가 있는 통합 메모리를 사용하거나, 또는 여러 채널을 단일 공유 세션으로 접어 한 대화가 많은 표면(surfaces)에 걸쳐 진행되도록 할 수 있습니다.
/manage-channels를 통해 채널별로 선택합니다. docs/isolation-model.md 참조.
- 에이전트별 작업 공간 (Per-agent workspace) — 각 에이전트 그룹은 자체
CLAUDE.md, 자체 메모리, 자체 컨테이너 및 허용하는 마운트만 가집니다. 연결하지 않는 한 경계를 넘나드는 것은 없습니다.
- 예약 작업 (Scheduled tasks): 에이전트에 의해 실행되는 반복적인 작업이며, 작업이 없을 때 깨어나는 것을 방지하는 선택적 스크립트 게이트를 가집니다.
- 웹 접근 (Web access) — 웹에서 콘텐츠 검색 및 가져오기
- 컨테이너 격리(Container isolation) — 에이전트는 Docker 컨테이너(macOS/Linux/WSL2)에 샌드박스됩니다.
- 자격 증명 보안(Credential security) — 에이전트는 절대 원시 API 키를 보유하지 않습니다. 아웃바운드 요청은 자격 증명 게이트웨이를 통해 라우팅되며, 이 게이트웨이가 요청 시점에 자격 증명을 주입하고 에이전트별 정책 및 속도 제한을 강제합니다.
선택할 게이트웨이는 무엇입니까? 설정 과정에서 하나의 게이트웨이(현재 OneCLI의 Agent Vault)가 제공자 시점 뒤에 설치됩니다.
- 에이전트 템플릿 (Agent templates): 재사용 가능한 번들로부터 즉시 실행 가능한 에이전트(지침 + MCP 도구 + 스킬, 비밀 정보 제외)를
ncl groups create --template <ref> 명령을 통해 생성합니다. 템플릿은 로컬의 templates/ 폴더에서 로드되며, 이 폴더는 수동으로 채우거나 공개 라이브러리에서 복사하여 채울 수 있습니다. 자세한 내용은 docs/templates.md를 참조하십시오.
계정 및 기기 외부로 나가는 데이터
NanoClaw는 사용자 계정을 가지고 있지 않습니다. 이 도구가 보고하는 유일한 것은 익명의 설정 진단 정보이며, NANOCLAW_NO_DIAGNOSTICS=1을 사용하면 이를 비활성화할 수 있습니다. 귀하의 에이전트, 메시지, 파일 및 키는 절대 기기를 벗어나지 않습니다.
선택적 예외 사항: 로컬에서 빌드하는 대신 미리 구축된 에이전트 이미지를 가져올 수 있습니다. 저희 이미지를 가져오려면 무료 계정이 필요하므로, 귀하의 이메일 주소와 이미지 요청 시점만 확인하며 — 귀하의 에이전트에 대한 정보는 전혀 알지 못하고, 이미지가 도착한 후에도 아무것도 기록하지 않습니다. 로컬 빌드는 계정이 필요 없으며 어떤 연락처도 접촉하지 않으므로 기본값입니다. 동일한 계정으로 아래에 나열된 혜택(perks)을 활성화할 수 있습니다.
혜택 (Perks)
무료 계정을 사용하면 또한 portal.nanoclaw.dev의 커뮤니티 포털에 접속할 수 있으며, 이곳은 해당 계정이 제공하는 기능을 활성화하는 대시보드입니다. 현재는 Echo의 강화된 에이전트 이미지와 에이전트를 위한 관리형 Slack 앱이며, 붙여넣을 토큰 없이 생성 및 설치됩니다. NanoClaw의 다른 모든 기능은 이것 없이도 작동합니다.
설정 과정에서 포털에 한 번 접속하게 됩니다. 브라우저에서 로그인하고, 설정을 실행하는 터미널을 승인하며, 혜택을 활성화하면 마법사가 이를 감지하고 자동으로 진행됩니다. Echo를 활성화할 때는 제품 및 보안 이메일 수신 여부를 포함하여 Echo의 약관에 동의하게 됩니다. 아무것도 활성화하지 않고 페이지를 닫아도 설정은 혜택 없이 계속 진행되며, 나중에 다시 한번 해당 혜택을 제공합니다.
사용자 기기에 유지되는 정보는 다음과 같습니다. 바로 ~/.config/nanoclaw/account.json에 있는 로그인 기록과 설치 토큰, ~/.config/nanoclaw/device-key.json에 있는 장치별 키(one device key per machine), 그리고 이 체크아웃의 저널인 data/community-portal.json(어떤 혜택이 활성화되었는지, 설정 진행 상황, 혜택이 제공한 자격 증명 등)입니다. 모든 파일은 모드 0600으로 설정됩니다. 설치 토큰은 브라우저를 거치지 않습니다. 브라우저는 일회성 로그인 코드만 보게 되며, 토큰은 계정 서비스에서 이 장치로 직접 전달됩니다. 호스트는 포털(portal)에 대한 아웃바운드 연결을 하나 유지하여, 사용자가 브라우저에서 변경한 혜택이 실행 중인 에이전트(agent)에 도달할 수 있게 합니다. 이때 사용자 에이전트, 메시지 또는 파일에 관한 정보는 전송되지 않습니다.
pnpm exec tsx setup/portal.ts --stage echo 또는 --stage slack 명령을 사용하여 단계를 다시 확인하거나, 포털의 Devices에서 장치를 잊어버림(forget)으로써 로그아웃할 수 있습니다. 그러면 해당 토큰은 작동을 멈추고 호스트는 연결이 끊깁니다. 파일, 복구 명령어 및 문제 해결 방법은 docs/community-portal.md를 참조하십시오.
사용법 (Usage)
트리거 단어(기본값: @Andy)로 어시스턴트와 대화하세요:
@Andy 매주 평일 아침 9시에 영업 파이프라인 개요를 보내줘 (내 Obsidian 볼트 폴더에 접근 가능)
@Andy 지난주 동안의 git 히스토리를 검토하고, 드리프트(drift)가 있으면 README 파일을 업데이트해줘
@Andy 매주 월요일 오전 8시에 Hacker News와 TechCrunch에서 AI 개발 관련 뉴스를 컴파일하여 브리핑 메시지를 보내줘
사용자가 소유하거나 관리하는 채널에서는 그룹 및 작업을 관리할 수 있습니다:
@Andy 그룹 전반에 걸쳐 예약된 모든 작업 목록을 보여줘
@Andy 월요일 브리핑 작업을 일시 중지해줘
@Andy Family Chat 그룹에 참여해줘
사용자 정의 (Customizing)
NanoClaw는 설정 파일을 사용하지 않습니다. 변경 사항을 적용하려면, 원하는 바를 Claude Code에게 말해주기만 하면 됩니다:
- "트리거 단어를 @Bob으로 바꿔줘"
- "앞으로는 응답을 더 짧고 직접적으로 만드는 것을 기억해줘"
- "내가 좋은 아침이라고 말할 때 사용자 정의 인사말을 추가해줘"
- "대화 요약을 주간 단위로 저장해줘"
또는 안내를 받으며 변경하려면 /customize를 실행하세요.
코드베이스가 충분히 작기 때문에 Claude가 안전하게 수정할 수 있습니다.
기여하기 (Contributing)
기능을 추가하지 마세요. 스킬(skills)을 추가하세요.
새로운 채널이나 에이전트 제공자(agent provider)를 추가하고 싶다면, 이를 trunk에 직접 추가하지 마세요. 새로운 채널 어댑터(channel adapters)는 channels 브랜치에 올라오고, 새로운 에이전트 제공자는 main의 스킬(skill) 내 payload/ 폴더에 코드를 유지합니다. 사용자는 자신의 포크(fork)에서 /add-<name> 스킬을 통해 이를 설치하며, 이 과정은 관련 모듈(module)들을 표준 경로로 복사하고, 등록(registration)을 연결하며, 의존성(dependencies)을 고정합니다.
이렇게 함으로써 trunk는 순수한 레지스트리 및 인프라(registry and infra) 역할을 유지하고, 모든 포크는 가볍게(lean) 유지됩니다. 즉, 사용자가 요청한 채널과 제공자만 얻고 그 외의 것은 아무것도 받지 않습니다.
RFS (스킬 요청서: Request for Skills)
현재 요청되는 채널이나 제공자 스킬은 없습니다. 이슈(issue)를 통해 제안해 주세요.
요구 사항 (Requirements)