포스트

Nanoclaw는 가벼운 개인 AI 에이전트인가: 구조, 격리, 도입 가이드

Nanoclaw는 작은 핵심 코드와 컨테이너 격리를 앞세운 개인용 AI 에이전트 프로젝트입니다. WhatsApp 입력, 작업별 기억, 예약 실행처럼 일상 자동화에 필요한 흐름을 단순한 구조로 묶지만, 코드가 작거나 컨테이너를 쓴다는 이유만으로 안전이 보장되지는 않습니다. 도입 전에는 실제 코드와 버전, 호스트 마운트, 네트워크, 메신저 권한, 자연어로 생성된 변경 diff를 직접 확인해야 합니다.

Nanoclaw는 어떤 문제를 작게 풀려 하나요?

Nanoclaw는 보안(Security)과 간결함(Simplicity)을 최우선으로 하는 개인용 AI 어시스턴트입니다.

프로젝트가 내세우는 방향은 사용자가 핵심 실행 경로를 읽고 바꿀 수 있을 정도로 구조를 제한하는 것입니다. Anthropic의 Claude Agent SDK를 기반으로 작동하며 WhatsApp 등을 입력 채널로 사용합니다. “몇 분 안에 읽을 수 있다”거나 특정 줄 수라는 표현은 프로젝트가 소개하는 규모의 인상으로 보아야 하며, 의존성, 컨테이너 이미지, 생성된 변경까지 모두 검토했다는 뜻은 아닙니다.

어떤 설계 선택이 있나요?

  1. 제한된 핵심 구조: 프로젝트가 핵심으로 정의한 코드 경로를 작게 유지해 추적 범위를 줄이려 합니다.
  2. 컨테이너 격리: 애플리케이션 권한 확인에만 의존하지 않고 OS 수준의 컨테이너 경계를 사용합니다.
  3. 커스터마이징: 복잡한 설정 파일 대신, “코드 자체가 설정”입니다. Claude에게 “이 기능 추가해줘”라고 말하면 코드를 수정해 줍니다.

핵심 기능은 어떤 권한을 사용하나요?

README 공식 문서에 소개된 Nanoclaw의 주요 기능은 다음과 같습니다.

컨테이너 격리는 무엇을 제한하나요?

Nanoclaw의 작업은 Linux 컨테이너 또는 지원되는 컨테이너 런타임 안에서 수행되도록 구성됩니다.

  • 파일 범위: 에이전트가 볼 디렉터리를 마운트 설정으로 제한할 수 있습니다.
  • 실행 범위: 컨테이너 안의 명령과 호스트 명령을 분리할 수 있지만, 쓰기 가능한 마운트, 소켓, 네트워크 권한이 넓으면 호스트 데이터나 외부 서비스에 여전히 영향을 줄 수 있습니다.

WhatsApp 연동은 어떤 데이터를 다루나요?

복잡한 웹 대시보드 대신, 우리가 매일 쓰는 WhatsApp을 인터페이스로 사용합니다.

  • 개인 채팅이나 그룹 채팅에서 AI와 대화할 수 있습니다.
  • 음성 메시지, 이미지 인식 등을 지원합니다.

여러 에이전트는 어떻게 범위를 나누나요?

프로젝트 문서에 소개된 멀티 에이전트 흐름은 하나의 대화에서 작업을 나눌 수 있게 합니다. 에이전트 수가 늘면 파일, 메시지, 비용 권한도 함께 늘 수 있으므로 각 작업의 입력과 결과를 구분해야 합니다.

예약 작업과 기억은 무엇을 보존하나요?

  • 기억력: 그룹별로 독립된 메모리 파일(CLAUDE.md 등)을 가져 대화 맥락을 유지합니다.
  • 자동화: “매주 월요일 아침 9시에 뉴스 요약해줘”와 같은 반복 작업을 자체 스케줄러로 처리합니다.

자연어 설정은 실제로 무엇을 바꾸나요?

Claude Code를 통해 설치와 기능 변경을 요청하는 흐름을 사용합니다. 자연어가 별도 추상 설정으로 남는 것이 아니라 실제 코드와 환경 구성을 바꿀 수 있으므로, 적용 전후 diff와 검증 명령이 설정 기록 역할을 해야 합니다.

단일 프로세스 구조는 무엇을 단순화하나요?

Nanoclaw의 아키텍처는 ‘단일 프로세스(One Process)’ 원칙을 따릅니다. 마이크로서비스나 메시지 큐 같은 복잡한 요소를 모두 제거했습니다.

  1. Core Process: TypeScript로 작성된 단일 Node.js 프로세스가 메인 로직을 담당합니다.
  2. Docker/Container Runtime: 실제 작업(코드 실행, 파일 조작)은 격리된 컨테이너 내에서 수행됩니다.
  3. Direct SDK Usage: 별도의 두꺼운 추상 계층보다 Anthropic Agent SDK를 직접 사용하는 흐름을 택합니다.

구성 요소가 적으면 호출 흐름을 따라가기 쉬울 수 있습니다. 그러나 런타임, SDK, 메신저 라이브러리와 컨테이너 이미지까지 포함한 전체 공급망은 핵심 파일 수보다 넓으므로 의존성 목록과 잠금 파일도 함께 보아야 합니다.

설치 전에 어떤 계정과 런타임이 필요한가요?

아래는 프로젝트 문서에 소개된 설치 흐름입니다. 명령을 실행하기 전에 현재 README와 스크립트가 무엇을 설치하고 어떤 파일을 만드는지 확인합니다.

사전 준비

  • OS: macOS 또는 Linux (Windows는 WSL2 권장)
  • 필수 도구: git, npm, 그리고 Docker(또는 런타임)
  • 인증: 현재 프로젝트가 요구하는 모델 인증 방식을 확인합니다.

단계별 설치

  1. 저장소 복제
    1
2

    git clone https://github.com/qwibitai/nanoclaw.git
cd nanoclaw
  2. Claude Code 실행 터미널에서 claude 명령어를 입력하여 Claude Code 인터페이스를 엽니다.
    1

    claude
  3. 셋업 스킬 실행 Claude 프롬프트 내에서 다음 명령어를 입력합니다.
    1

    /setup

    이 명령어를 입력하면 설정 흐름에서 다음 작업을 수행할 수 있습니다. 실제 변경 목록은 현재 스킬과 diff에서 확인합니다.

    • 필요한 의존성 설치
    • 컨테이너 환경 구성
    • WhatsApp 인증(QR 코드 생성)
    • 서비스 초기화를 진행합니다.

첫 사용에서 무엇을 제한해야 하나요?

설치가 완료되면 터미널에 QR 코드가 나타나며, WhatsApp으로 스캔하여 연동합니다.

기본 대화는 어떻게 구분하나요?

  • 1:1 채팅: 등록된 봇 계정으로 메시지를 보내면 Claude가 답변합니다.
  • 그룹 채팅: 봇을 그룹에 초대한 뒤, @Andy (기본 봇 이름)를 태그하여 말을 걸 수 있습니다.

스킬 변경은 어떻게 검토하나요?

Nanoclaw는 기능을 확장할 때 ‘플러그인’ 대신 ‘스킬’ 개념을 사용합니다. 예를 들어 텔레그램 연동을 원한다면, 기능을 추가해달라고 요청하는 것이 아니라 “텔레그램 스킬을 적용해줘”라고 명령하여 코드를 변환시킵니다.

  • /add-telegram: 텔레그램 지원 추가
  • /debug: 문제 발생 시 로그 분석 및 자동 수정

예약 작업은 어떻게 시험하나요?

채팅창에 다음과 같이 자연어로 명령하세요.

“@Andy, 매일 아침 8시에 Hacker News의 인기 AI 기사를 요약해서 이 채팅방에 브리핑해줘.”

등록 뒤에는 스케줄, 시간대, 전송 대상과 실패 시 재시도 규칙을 확인합니다. 먼저 한 번만 실행해 결과와 비용을 검토한 다음 반복 일정을 켜는 편이 안전합니다.

다른 에이전트와 무엇을 같은 조건에서 비교해야 하나요?

구분NanoclawOpenClaw / 기존 프레임워크
검토 범위핵심 실행 경로를 작게 유지하려는 설계기능과 플러그인 범위에 따라 달라짐
격리 방식컨테이너 경계를 중심으로 구성제품별 권한, 격리 방식을 확인해야 함
설정 방식자연어 요청이 코드 변경으로 이어짐설정 파일, UI, 코드 등 제품별로 다름
기능 범위필요한 기능을 선택해 추가하는 방향기본 제공 범위가 넓을 수 있음
확장 비용직접 수정한 코드의 테스트, 업데이트 책임공식 확장의 호환성과 정책을 확인해야 함

컨테이너가 있어도 어떤 실패가 남나요?

컨테이너는 파일 시스템과 프로세스 경계를 제공하지만 구성에 따라 효과가 달라집니다. 호스트 디렉터리를 쓰기 가능으로 마운트하면 그 안의 파일은 변경될 수 있고, Docker 소켓이나 넓은 네트워크 권한을 제공하면 격리 범위가 크게 넓어집니다. 비밀키를 환경 변수로 넣는 경우 작업 프로세스와 로그가 이를 노출하지 않는지도 살펴야 합니다.

메신저 연동에는 별도의 위험이 있습니다. 그룹의 누가 봇을 호출할 수 있는지, 인용된 과거 메시지가 작업 지시로 해석되는지, 예약 결과가 어느 채팅방으로 전송되는지를 시험합니다. 개인 데이터가 모델 제공자와 메신저를 거치는 경로를 그리고, 기억 파일의 저장 위치, 백업, 삭제 방법을 정해야 합니다.

자연어로 바꾼 코드는 어떻게 유지보수하나요?

“기능을 추가해 줘”라는 요청은 편리하지만 생성된 코드는 이후 업데이트와 충돌할 수 있습니다. 변경 전 커밋을 남기고, 수정 파일과 새 의존성을 확인하며, 메신저 입력, 예약 실행, 권한 거부의 정상 및 실패 사례를 테스트합니다. 프로젝트의 새 버전을 받을 때는 직접 수정한 부분이 덮어써지거나 보안 수정에서 벗어나지 않는지도 점검합니다.

작은 코드베이스의 실질적 장점은 안전을 자동으로 얻는 데 있지 않고, 사용자가 자신의 위협 모델에 맞춰 전체 경로를 검토할 가능성을 높이는 데 있습니다. Nanoclaw가 적합한지는 핵심 줄 수보다 필요한 기능이 현재 구조 안에서 단순하게 유지되는지, 컨테이너와 메신저 권한을 최소화할 수 있는지, 팀이 직접 수정한 코드를 계속 테스트할 수 있는지로 판단해야 합니다.

함께 읽으면 이해가 이어지는 글

References

THE END / OPSOAI

여기까지 읽었습니다

핵심 장면을 한 번 더 떠올려 보세요. 이해가 남았다면 이 책은 제 역할을 다했습니다.

다른 책 고르기
표지 1 —

←→ 키와 좌우 스와이프를 지원합니다. 읽던 페이지는 이 기기에 저장됩니다.

CONTENTS

이 책의 목차

    10개 장 17 분읽는 시간