AI 에이전트 관련 영상을 보다가 NanoClaw라는 걸 알게 됐다. OpenClaw에서 보안이 강화된 버전인데, 텔레그램으로 Claude를 조종할 수 있다니 바로 해보고 싶었다. 알리에서 구매한 서버 관련 부품이 아직 하나 안 온 게 있어서 서버 환경에는 구성을 못하고, 윈도우에 설치한 WSL2 환경에 본가에서 접속해서 설치를 시도했다.
결론부터 말하면 성공했다. 기본 봇에 추가로 4개의 프로젝트별 방까지 만들었다. 이 글에서는 삽질 과정 포함해서 처음부터 끝까지 정리한다.
NanoClaw가 뭔데?
NanoClaw는 Claude Code 기반의 개인용 AI 에이전트 런타임이다. 쉽게 말하면 텔레그램이나 WhatsApp으로 메시지를 보내면, 그 메시지를 받아서 Docker 컨테이너 안에서 작업을 수행해주는 시스템이다.
핵심 특징은 이렇다:
- 경량 구조: 약 15개 파일, 3,900줄. 코드를 직접 읽고 이해할 수 있는 수준
- 컨테이너 격리: 모든 작업이 Docker 컨테이너 안에서 실행. 호스트 OS에 직접 접근 불가
- 그룹별 메모리: 프로젝트마다 독립된 CLAUDE.md와 대화 히스토리 유지
- 보안 우선: ~/.ssh, ~/.aws, .env 같은 민감 디렉터리는 기본적으로 마운트 안 됨
구조를 간단히 그리면 이렇다:
텔레그램/WhatsApp → NanoClaw 서버 → Docker 컨테이너 (Claude Code 실행)
↕
groups/{그룹}/CLAUDE.md (영구 메모리)
컨테이너는 30분 유휴 시 자동 종료되지만, CLAUDE.md와 대화 아카이브는 호스트에 영구 저장된다. 그래서 컨테이너가 날아가도 대화를 이어갈 수 있다.
설치 환경
| OS | Windows WSL2 (Ubuntu 24.04) |
| 접속 방식 | VS Code Remote SSH |
| 상황 | 본가에서 원격 접속 |
Phase 1: 리눅스 기본 환경
# 시스템 업데이트 sudo apt update && sudo apt upgrade -y # 필수 개발 도구 sudo apt install -y curl git build-essential # Node.js 20.x 설치 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs # 확인 node -v npm -v
build-essential은 npm 네이티브 패키지 빌드에 필요하다. 없으면 나중에 에러 난다.
Phase 2: Docker Engine 설치
WSL2 환경에서는 Docker Desktop 대신 Docker Engine을 직접 설치하는 게 낫다. SSH로 접속해서 터미널로 작업하는 환경에는 GUI가 필요 없기 때문이다.
# 기존 Docker 관련 패키지 정리 for pkg in docker.io docker-doc docker-compose docker-compose-v2 \ podman-docker containerd runc; do sudo apt-get remove -y "$pkg" done # GPG 키 설정 sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \ -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc # Docker 저장소 등록 echo "deb [arch=$(dpkg --print-architecture) \ signed-by=/etc/apt/keyrings/docker.asc] \ https://download.docker.com/linux/ubuntu \ $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # Docker 설치 sudo apt-get update sudo apt-get install -y \ docker-ce docker-ce-cli containerd.io \ docker-buildx-plugin docker-compose-plugin # sudo 없이 Docker 사용 sudo groupadd docker 2>/dev/null || true sudo usermod -aG docker "$USER" newgrp docker # 확인 docker --version docker run hello-world
systemd 확인 (중요)
WSL2에서 Docker 서비스가 자동 시작되려면 systemd가 활성화되어 있어야 한다.
ps -p 1 -o comm=
출력이 init이면 아래 설정 후 WSL 재시작이 필요하다:
sudo tee /etc/wsl.conf << EOF [boot] systemd=true EOF
Windows PowerShell에서 wsl --shutdown 후 다시 열면 된다.
sudo systemctl enable docker sudo systemctl start docker
Phase 3: Claude Code 설치
npm install -g @anthropic-ai/claude-code
claude --version
claude auth login # 브라우저로 Anthropic 계정 로그인
여기서 주의할 점이 있다. NanoClaw는 Max 구독 OAuth 토큰을 사용할 수 없다. API 키가 필수다.
| 용도 | 인증 방식 | 비용 |
|---|---|---|
| Claude Code (터미널) | Max 구독 OK | 월정액 |
| NanoClaw (텔레그램 봇) | API 키 필수 | 토큰당 과금 |
| Claude.ai (웹/앱) | Max 구독 OK | 월정액 |
API 키는 Anthropic Console에서 발급받고, OneCLI로 등록한다:
export PATH="$HOME/.local/bin:$PATH" onecli secrets create --name Anthropic --type anthropic \ --value YOUR_API_KEY --host-pattern api.anthropic.com
이 두 명령어는 반드시 따로 실행해야 한다. 한 줄에 붙여서 실행하면 export가 뒤쪽 전체를 환경변수로 해석해버린다.
Phase 4: NanoClaw 설치 및 텔레그램 봇 연동
git clone https://github.com/qwibitai/nanoclaw.git cd nanoclaw claude # Claude Code 실행 /setup # 설정 마법사 npm start # 실행
텔레그램 봇 만들기
- 텔레그램에서
@BotFather에게/newbot명령 - 봇 이름과 username 설정
- 발급된 봇 토큰을 NanoClaw 설정에 입력
Group Privacy 끄기 (필수!)
@BotFather → /mybots → 봇 선택 → Bot Settings → Group Privacy → Turn off
이걸 안 하면 그룹 채팅에서 봇이 메시지를 아예 못 본다.
Phase 5: 프로젝트별 방(그룹) 만들기
NanoClaw의 진짜 강점은 여기서 나온다. 텔레그램 그룹 = 프로젝트 방이다.
npx tsx setup/index.ts --step register \ -- --jid "tg:채팅ID" \ --name "그룹이름" \ --folder "폴더명" \ --trigger "@봇이름" \ --channel telegram \ --no-trigger-required
기본 봇 채팅에 추가로 4개의 프로젝트별 방을 만들었다:
~/nanoclaw/groups/ ├── telegram_main/ # 메인 (1:1 개인 채팅) ├── telegram_room1/ # 프로젝트 방 1 ├── telegram_room2/ # 프로젝트 방 2 ├── telegram_room3/ # 프로젝트 방 3 └── telegram_room4/ # 프로젝트 방 4
등록 후에는 반드시 서비스를 재시작해야 한다:
sudo systemctl restart nanoclaw
Phase 6: 백그라운드 서비스로 등록
터미널을 닫아도 봇이 계속 돌아가려면 systemd 서비스로 등록해야 한다.
# 서비스 파일 생성 + 등록 + 시작 (한 번에)
printf '[Unit]\nDescription=NanoClaw\nAfter=network.target docker.service\n\n[Service]\nType=simple\nUser=사용자명\nWorkingDirectory=/home/사용자명/nanoclaw\nExecStart=/home/사용자명/.nvm/versions/node/버전/bin/npm start\nEnvironment=PATH=/home/사용자명/.nvm/versions/node/버전/bin:/usr/bin:/bin\nSupplementaryGroups=docker\nRestart=always\n\n[Install]\nWantedBy=multi-user.target\n' \
| sudo tee /etc/systemd/system/nanoclaw.service > /dev/null \
&& sudo systemctl enable nanoclaw \
&& sudo systemctl start nanoclaw
여기서 핵심 주의사항 3가지:
- ExecStart에 nvm 전체 경로:
which npm으로 확인한 경로를 써야 한다 - Environment에 PATH 직접 지정: systemd는 사용자 셸 환경을 안 읽는다
- SupplementaryGroups=docker: Docker 소켓 접근 권한 필요
일상 관리 명령어
# 서비스 관리 sudo systemctl status nanoclaw sudo systemctl restart nanoclaw # 로그 확인 tail -f ~/nanoclaw/logs/nanoclaw.log # 프로세스 확인 (하나만 돌아가야 정상!) ps aux | grep "node dist/index" | grep -v grep
모델별 비용
| 모델 | 입력 | 출력 | 용도 |
|---|---|---|---|
| Haiku 4.5 | $1/MTok | $5/MTok | 간단한 대화 |
| Sonnet 4.6 | $3/MTok | $15/MTok | 대부분 작업에 충분 |
| Opus 4.6 | $5/MTok | $25/MTok | 복잡한 추론 |
보안 체크리스트
NanoClaw가 해주는 것:
- 작업은 Docker 컨테이너 안에서만 실행
- ~/.ssh, ~/.aws, .env 등 민감 디렉터리 마운트 차단
- 유휴 컨테이너 30분 후 자동 종료
사용자가 해야 할 것:
- 민감 작업은 1:1 메인 채팅에서만
- API 키가 노출되면 즉시 재발급
- 필요 시 Docker 네트워크로 outbound 제한
- 공유 그룹에서는 프롬프트 인젝션 주의
삽질 모음 — 이거 안 보면 나처럼 고생한다
공백/오타 실수
| 뭘 잘못했나 | 에러 메시지 |
|---|---|
dpkg--print-architecture (공백 누락) |
command not found |
export PATH"$HOME..." (= 누락) |
not a valid identifier |
npm install -g anthropic-ai/claude-code (@ 누락) |
GitHub 저장소로 인식 |
systemd 에러 3종 세트
| 에러 | 원인 | 해결 |
|---|---|---|
| status=203/EXEC | npm 경로 틀림 | which npm으로 확인 |
| status=127 | node를 못 찾음 | Environment=PATH=… 추가 |
| Docker 권한 오류 | docker 그룹 미소속 | SupplementaryGroups=docker |
프로세스 중복 실행
npm start로 직접 실행한 프로세스가 남아있는 상태에서 systemd를 시작하면, 같은 봇 토큰으로 2개가 붙어서 텔레그램 전송이 실패한다.
# 프로세스 정리 후 서비스 시작
pkill -f "node dist/index.js" && sleep 2 && sudo systemctl start nanoclaw
마무리
NanoClaw를 설치하고 텔레그램으로 Claude와 대화할 수 있게 됐다. 프로젝트별로 방을 분리하니까 맥락이 섞이지 않아서 좋다.
다음에는 각 방의 CLAUDE.md를 좀 더 정교하게 세팅해서, 진짜 프로젝트별 AI 비서 시스템으로 발전시켜볼 생각이다.
한 줄 요약: WSL2 + Docker + NanoClaw + 텔레그램 = 내 손 안의 AI 에이전트.