NanoClaw 완전 가이드: 컨테이너 격리형 Claude AI 에이전트 구축 및 활용법 (2026 최신)

[사용자] WhatsApp / Telegram / Discord / Slack
         ↓ 메시지
[Node.js Host Process] ─── SQLite DB (영구 메모리)
  ├── WhatsApp (Baileys 라이브러리)  ← 내장 기본 채널
  ├── Telegram / Discord / Slack    ← /add-* 스킬로 추가
  ├── Cron 예약 작업 엔진
  └── 에이전트 컨테이너 오케스트레이터
         ↓ 메시지 + 컨텍스트 전달
[Per-Session Agent Container] (Linux · Docker / Apple Container)
  ├── Claude Code (Claude Agent SDK)
  ├── CLAUDE.md  ← 그룹별 독립 지식/메모리
  ├── 내장 도구: shell · 파일 읽기/쓰기 · 웹 검색 · Chromium 브라우저
  └── 에이전트 위임 (Swarm 서브에이전트)
         ↓ 응답
[Node.js Host] → 사용자에게 메시지 전송

# Node.js 버전 확인 (20+ 필요)
node --version
# v20.x 이상이어야 함

# pnpm 설치 확인
pnpm --version || npm install -g pnpm

# Docker 확인
docker --version       # 24.x 이상
docker info            # Docker daemon 실행 확인

# Claude Code 설치 (없으면)
npm install -g @anthropic-ai/claude-code
claude --version       # 설치 확인

# Anthropic API 키 환경변수 확인
echo $ANTHROPIC_API_KEY  # 비어있으면 다음 단계에서 설정

cd nanoclaw
claude             # Claude Code 실행
# Claude Code 안에서:
/setup             # 대화형 설치 시작 — Claude가 각 단계를 안내
# 의존성 설치, 컨테이너 빌드, 채널 페어링까지 자동 진행

version: '3.8'

services:
  nanoclaw-core:
    image: node:20-alpine    # ⚠️ 18-alpine → 20-alpine 필수 업데이트
    container_name: nanoclaw-core
    restart: unless-stopped
    working_dir: /app
    command: sh -c "pnpm install && npm start"
    volumes:
      - ./:/app
      - /var/run/docker.sock:/var/run/docker.sock  # DooD: 에이전트 컨테이너 생성용
      - nanoclaw-data:/app/data
    environment:
      - NODE_ENV=production
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}    # .env 파일에서 주입
      - NANOCLAW_SECRET_KEY=${NANOCLAW_SECRET_KEY}
    ports:
      - "3000:3000"    # API 포트 (내부망만 노출 권장)
    networks:
      - nanoclaw-net

volumes:
  nanoclaw-data:

networks:
  nanoclaw-net:
    driver: bridge

ANTHROPIC_API_KEY=sk-ant-여기에입력
NANOCLAW_SECRET_KEY=$(openssl rand -base64 32)   # 웹훅 서명용
NODE_ENV=production
# Telegram (선택)
TELEGRAM_BOT_TOKEN=
TELEGRAM_WEBHOOK_URL=https://yourdomain.com/webhooks/telegram
# Discord (선택)
DISCORD_BOT_TOKEN=

# Claude Code 실행
claude

# Telegram Bot 추가
/add-telegram
# → 스킬이 소스 코드에 Telegram 어댑터를 직접 추가
# → .env에 TELEGRAM_BOT_TOKEN 추가 안내

# Discord 추가
/add-discord

# Slack 추가
/add-slack

# ⚠️ 스킬은 소스 코드를 직접 수정하므로 git commit 권장
git add . && git commit -m "feat: add telegram channel"

[채널 수신] WhatsApp Baileys / Telegram Bot API / Discord Gateway
    ↓
[메시지 파서] 그룹 JID 추출 · 발신자 정보 · 메시지 타입
    ↓
[그룹 큐] 그룹별 FIFO 큐 (동일 그룹 메시지는 순서 보장)
    ↓
[컨테이너 스폰] Docker/Apple Container에서 에이전트 실행
  - CLAUDE.md 마운트 (그룹별 독립 메모리)
  - SQLite DB 마운트 (세션 영구 메모리)
  - 스킬 모듈 주입
    ↓
[Claude Agent SDK] 도구 실행 (shell·파일·웹검색·Chromium·Swarm 위임)
    ↓
[응답] 원본 채널로 메시지 전송

// ⚠️ 2026년 수정: whatsapp-web.js(Puppeteer) 아님 — Baileys 직접 연결 방식
// NanoClaw 공식 코드는 Baileys 라이브러리를 내부적으로 사용합니다.
// npm run auth로 QR 페어링 후 ./data/whatsapp-sessions/에 세션 저장

import { makeWASocket, useMultiFileAuthState, DisconnectReason } from '@whiskeysockets/baileys';
import { Boom } from '@hapi/boom';
import { enqueueMessage } from '../group-queue';

export async function startWhatsAppClient() {
  const { state, saveCreds } = await useMultiFileAuthState('./data/whatsapp-sessions');

  const sock = makeWASocket({
    auth: state,
    printQRInTerminal: true,   // 터미널 QR 출력 (브라우저보다 안정적)
  });

  sock.ev.on('creds.update', saveCreds);

  sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
    if (connection === 'close') {
      const shouldReconnect =
        (lastDisconnect?.error as Boom)?.output?.statusCode !== DisconnectReason.loggedOut;
      if (shouldReconnect) startWhatsAppClient(); // 자동 재연결
    }
  });

  sock.ev.on('messages.upsert', async ({ messages }) => {
    for (const msg of messages) {
      if (!msg.key.fromMe && msg.message) {
        const jid   = msg.key.remoteJid!;     // 그룹 또는 개인 JID
        const text  = msg.message.conversation
          || msg.message.extendedTextMessage?.text || '';
        if (text) enqueueMessage({ jid, text, sock });
      }
    }
  });
}

import TelegramBot from 'node-telegram-bot-api';
import { enqueueMessage } from '../group-queue';

export function startTelegramGateway(): void {
  const token = process.env.TELEGRAM_BOT_TOKEN;
  if (!token) { console.warn('[Telegram] TELEGRAM_BOT_TOKEN 없음 — 스킵'); return; }

  const bot = new TelegramBot(token, { polling: true });

  bot.on('message', (msg) => {
    const chatId  = String(msg.chat.id);
    const text    = msg.text || '';
    if (text) {
      enqueueMessage({
        jid: `tg-${chatId}`,     // Telegram 채팅 ID를 NanoClaw JID로 변환
        text,
        sendFn: (reply: string) => bot.sendMessage(msg.chat.id, reply),
      });
    }
  });

  console.log('[Telegram] Polling 시작됨');
}

# [에이전트 시스템 컨텍스트]
- 그룹 식별자: telegram--100123456
- 마지막 동기화: 2026-06-14T09:00:00Z
- 에이전트 역할: 개인 비서 및 리서치 어시스턴트

## 운영 규칙
- 모든 응답은 한국어로
- 코드 스니펫은 마크다운 코드 블록 사용
- 불확실한 정보는 반드시 "확인 필요" 명시
- 개인정보(이름·연락처·위치)는 응답에 포함 금지

## 영구 지식 베이스
- 사용자 선호 언어: 한국어
- 프로젝트 컨텍스트: agibop.com 블로그 운영
- 자주 쓰는 스택: Ubuntu 24.04, Docker, Ollama, n8n
- 홈 서버: Dell R730 (192.168.1.250), NAS DS925+

## 예약 작업 등록됨
- 매일 07:00 KST: 코스피 시황 브리핑
- 매주 일요일 09:00: 주간 요약 리포트

## 히스토리 요약
[에이전트가 대화 후 자동 업데이트하는 영역]

# 백업 후 재초기화
cp ./data/store/db.sqlite ./data/store/db.sqlite.backup
rm ./data/store/db.sqlite
npm run init        # DB 재생성

# WhatsApp 세션 초기화 (QR 재스캔 필요)
rm -rf ./data/whatsapp-sessions/*
npm run auth        # QR 코드 재스캔

import cron from 'node-cron';
import { EventEmitter } from 'events';

export interface AutomatedJob {
  id:       string;
  cronExpr: string;     // 표준 cron 표현식
  targetJid:string;     // 메시지 전송 대상 그룹/채팅
  prompt:   string;     // 에이전트에게 전달할 명령
  enabled:  boolean;
}

const jobEmitter = new EventEmitter();

export function registerCronJob(job: AutomatedJob) {
  if (!job.enabled) return;

  cron.schedule(job.cronExpr, async () => {
    console.log(`[Cron] 작업 실행: ${job.id}`);
    jobEmitter.emit('trigger', { jid: job.targetJid, prompt: job.prompt });
  }, {
    timezone: 'Asia/Seoul'   // KST 기준
  });
}

[
  {
    "id": "morning-market-brief",
    "cronExpr": "0 7 * * 1-5",
    "targetJid": "[email protected]",
    "prompt": "오늘 코스피·코스닥 시황과 주요 뉴스 3개를 한국어로 정리해줘.",
    "enabled": true
  },
  {
    "id": "weekly-review",
    "cronExpr": "0 9 * * 0",
    "targetJid": "[email protected]",
    "prompt": "지난 주 내가 진행한 작업들과 미완료 항목을 CLAUDE.md를 참고해서 정리해줘.",
    "enabled": true
  },
  {
    "id": "daily-server-health",
    "cronExpr": "0 8 * * *",
    "targetJid": "[email protected]",
    "prompt": "홈서버 상태를 확인해줘. docker ps 결과와 디스크 사용량을 보고해줘.",
    "enabled": true
  }
]

import { execFile } from 'child_process';
import * as path from 'path';
import * as fs from 'fs';

const SKILLS_DIR = path.resolve('./skills');

export function executePythonSkill(
  skillName: string,
  payload: Record
): Promise {
  return new Promise((resolve, reject) => {
    const skillPath = path.join(SKILLS_DIR, skillName, 'main.py');
    if (!fs.existsSync(skillPath)) {
      reject(new Error(`스킬 없음: ${skillName}`));
      return;
    }

    const input = JSON.stringify(payload);
    execFile('python3', [skillPath], {
      timeout: 30_000,          // 30초 타임아웃
      maxBuffer: 1024 * 1024,   // 1MB 출력 제한
    }, (err, stdout, stderr) => {
      if (err) { reject(new Error(stderr || err.message)); return; }
      try { resolve(JSON.parse(stdout)); }
      catch { resolve(stdout.trim()); }
    }).stdin?.end(input);
  });
}

#!/usr/bin/env python3
"""KIS Developers API를 통한 주식 시세 조회 스킬"""
import sys, json, os, requests

def get_stock_price(ticker: str) -> dict:
    """한국투자증권 API로 실시간 시세 조회"""
    app_key    = os.environ.get('KIS_APP_KEY', '')
    app_secret = os.environ.get('KIS_APP_SECRET', '')
    # 실제 구현: 토큰 발급 → 시세 API 호출
    return {
        "ticker":  ticker,
        "price":   "실시간 조회 결과",
        "change":  "+1.23%",
        "volume":  "1,234,567주",
    }

if __name__ == '__main__':
    payload = json.loads(sys.stdin.read() or '{}')
    ticker  = payload.get('ticker', '005930')  # 삼성전자 기본값
    result  = get_stock_price(ticker)
    print(json.dumps(result, ensure_ascii=False))

## 사용 가능한 Custom Skills

### stock-price
- 용도: 한국 주식 실시간 시세 조회
- 호출: execute_python_skill("stock-price", {"ticker": "005930"})
- 반환: {ticker, price, change, volume}

### youtube-summary
- 용도: YouTube 영상 자막 추출 및 요약
- 호출: execute_python_skill("youtube-summary", {"url": "https://..."})
- 반환: {title, summary, key_points}

### translate
- 용도: 다국어 번역 (DeepL API)
- 호출: execute_python_skill("translate", {"text": "...", "target": "ko"})

import { Anthropic } from '@anthropic-ai/sdk';

const client = new Anthropic();

interface SubAgentTask {
  name:    string;
  prompt:  string;
  context: string;
}

async function runSwarm(
  masterPrompt: string,
  subTasks: SubAgentTask[]
): Promise {
  // 1단계: 서브에이전트 병렬 실행
  const subResults = await Promise.all(
    subTasks.map(async (task) => {
      const res = await client.messages.create({
        model: 'claude-sonnet-4-6',    // 서브에이전트 — 속도 최적화 모델
        max_tokens: 2048,
        messages: [{
          role: 'user',
          content: `컨텍스트: ${task.context}\n\n태스크: ${task.prompt}`
        }]
      });
      const text = res.content[0].type === 'text' ? res.content[0].text : '';
      return { name: task.name, result: text };
    })
  );

  // 2단계: 오케스트레이터가 서브에이전트 결과 통합
  const aggregated = subResults
    .map(r => `## ${r.name}\n${r.result}`)
    .join('\n\n');

  const final = await client.messages.create({
    model: 'claude-opus-4-6',    // 오케스트레이터 — 최고 품질 모델
    max_tokens: 4096,
    messages: [{
      role: 'user',
      content: `${masterPrompt}\n\n서브에이전트 결과:\n${aggregated}`
    }]
  });

  return final.content[0].type === 'text' ? final.content[0].text : '';
}

async function stockAnalysisSwarm(ticker: string) {
  return runSwarm(
    `${ticker}에 대한 종합 투자 분석 보고서를 작성해줘.`,
    [
      {
        name: '재무분석 에이전트',
        prompt: `${ticker}의 최근 4분기 재무제표를 분석해줘.`,
        context: '재무 분석 전문가. PER, PBR, ROE, 영업이익률 중심 분석.'
      },
      {
        name: '뉴스감성 에이전트',
        prompt: `${ticker} 관련 최근 뉴스 감성 분석을 해줘.`,
        context: '금융 뉴스 분석 전문가. 웹 검색 활용 가능.'
      },
      {
        name: '기술분석 에이전트',
        prompt: `${ticker} RSI, MACD 기술적 분석 결과를 알려줘.`,
        context: '기술적 분석 전문가. 매수/매도 신호 판별.'
      },
      {
        name: '리스크 에이전트',
        prompt: `${ticker} 투자 시 주요 리스크 요인을 정리해줘.`,
        context: '리스크 관리 전문가. 하방 시나리오 중심.'
      }
    ]
  );
}

# 에이전트 컨테이너 빌드 확인
echo '{}' | docker run -i --entrypoint /bin/echo \
  nanoclaw-agent:latest "Container OK"
# → "Container OK" 출력되면 격리 정상

# 실행 중인 에이전트 컨테이너 확인
docker ps --filter "name=nanoclaw-agent" --format "table {{.ID}}\t{{.Status}}\t{{.Names}}"

# 컨테이너 호스트 접근 제한 확인
docker inspect nanoclaw-agent:latest | grep -E "Privileged|CapAdd|NetworkMode"

const BLACKLIST_PATTERNS = [
  /ignore\s+previous\s+instructions/i,
  /forget\s+(everything|all)/i,
  /you\s+are\s+now\s+(?:a|an)\s+/i,
  /act\s+as\s+(?:if\s+)?(?:you\s+(?:are|were)|an?)\s+/i,
  /system\s*:\s*/i,
  /\[INST\]/i,
  /<\|im_start\|>/i,
];

export function sanitizeInput(text: string): {
  safe: boolean;
  reason?: string;
} {
  for (const pattern of BLACKLIST_PATTERNS) {
    if (pattern.test(text)) {
      return { safe: false, reason: `금지 패턴 탐지: ${pattern}` };
    }
  }
  if (text.length > 4096) {
    return { safe: false, reason: '최대 입력 길이 초과 (4096자)' };
  }
  return { safe: true };
}

[Unit]
Description=NanoClaw Personal AI Agent
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
User=evan
WorkingDirectory=/opt/nanoclaw
ExecStart=/usr/bin/npm start
Restart=always
RestartSec=10
EnvironmentFile=/opt/nanoclaw/.env
StandardOutput=journal
StandardError=journal
SyslogIdentifier=nanoclaw

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now nanoclaw
sudo systemctl status nanoclaw
journalctl -u nanoclaw -f    # 실시간 로그 확인