NanoClaw 아키텍처 분석 보고서 / 실사용 시나리오 Q&A

╔══════════════════════════════════════════════════════════════════════════╗
║                          NanoClaw System                                 ║
║                                                                          ║
║  ┌─────────────────────────────────────────────────────────────────┐    ║
║  │              Channels (Self-Registering Skills)                  │    ║
║  │  WhatsApp │ Telegram │ Slack │ Discord │ Gmail │ (custom)        │    ║
║  │           └─────────────────┬───────────────────                 │    ║
║  │                  registerChannel() at startup                    │    ║
║  └───────────────────────────┬─────────────────────────────────────┘    ║
║                               │ onMessage(jid, NewMessage)               ║
║                               ▼                                          ║
║  ┌────────────────────────────────────────────────────────────────────┐ ║
║  │                     SQLite Database                                │ ║
║  │  chats │ messages │ scheduled_tasks │ sessions │ registered_groups │ ║
║  └───────────────────────────┬────────────────────────────────────────┘ ║
║                               │ poll every 2s                            ║
║                               ▼                                          ║
║  ┌────────────────────────────────────────────────────────────────────┐ ║
║  │              Orchestrator (src/index.ts)                           │ ║
║  │                                                                    │ ║
║  │  Message Loop ──┬── Trigger Check (@Andy)                         │ ║
║  │                 ├── Group Queue (per-group concurrency)            │ ║
║  │                 └── runAgent()                                     │ ║
║  │                                                                    │ ║
║  │  IPC Watcher ───── File-based IPC (poll every 1s)                 │ ║
║  │  Scheduler ─────── Cron/Interval/Once tasks (poll every 60s)      │ ║
║  │  Credential Proxy ─ HTTP proxy on port 3001                       │ ║
║  └───────────────────────────┬────────────────────────────────────────┘ ║
║                               │ spawn container                          ║
║                               ▼                                          ║
║  ┌────────────────────────────────────────────────────────────────────┐ ║
║  │              Container Agent (Docker / Apple Container)            │ ║
║  │                                                                    │ ║
║  │  entrypoint.sh → agent-runner/index.ts                            │ ║
║  │       ├── Claude Agent SDK (streaming)                            │ ║
║  │       ├── Tools: Bash, File I/O, Web, Browser                     │ ║
║  │       └── MCP: ipc-mcp-stdio.ts (scheduler tools)                 │ ║
║  └───────────────────────────┬────────────────────────────────────────┘ ║
║                               │ stdout (JSON markers)                    ║
║                               ▼                                          ║
║  ┌──────────────────────────────────────────────────────────────────┐   ║
║  │              Response Routing (src/router.ts)                    │   ║
║  │  Strip <internal> tags → findChannel() → sendMessage()          │   ║
║  └──────────────────────────────────────────────────────────────────┘   ║
╚══════════════════════════════════════════════════════════════════════════╝

[사용자 WhatsApp 메시지 수신]
        │
        ▼
WhatsApp Channel (Baileys)
  └── onMessage(jid, NewMessage) 콜백 호출
        │
        ▼
src/db.ts → storeMessage()
  └── SQLite messages 테이블에 저장
        │
        ▼
src/index.ts → startMessageLoop() [2초 폴링]
  └── getNewMessages() — 미처리 메시지 조회
        │
        ├── [비-Main 그룹] 트리거 패턴 확인 (@Andy)
        │     ├── 트리거 없음 → DB에서 대기
        │     └── 트리거 있음 → 계속 진행
        │
        ▼
processGroupMessages()
  └── 해당 그룹의 미처리 메시지 수집 & XML 포맷
        │
        ▼
src/group-queue.ts → enqueueMessageCheck()
  └── 동시 실행 그룹 수 확인 (MAX_CONCURRENT_CONTAINERS: 5)
        │
        ▼
src/container-runner.ts → runContainerAgent()
  └── 볼륨 마운트 구성 (그룹 폴더, 세션 디렉토리 등)
      └── docker run / container run 실행
            │
            ▼
  container/agent-runner/src/index.ts
    └── Claude Agent SDK (스트리밍 실행)
          │
          ├── Tool 실행 (Bash, 파일, 웹, 브라우저)
          └── MCP 도구 (schedule_task, send_message 등)
                │ stdout JSON (sentinel markers)
                ▼
src/index.ts → 결과 수신
  └── <internal> 태그 제거 → router.ts → 채널 응답
        │
        ▼
WhatsApp Channel → sendMessage() → 사용자 응답 전송

1. initDatabase() — SQLite 초기화 & 마이그레이션
2. startCredentialProxy() — 자격증명 프록시 시작 (포트 3001)
3. 채널 팩토리 로드 — registerChannel()로 자기 등록된 채널 초기화
4. getRegisteredGroups() — DB에서 등록된 그룹 목록 조회
5. startIpcWatcher() — 파일 IPC 감시 시작
6. startSchedulerLoop() — 예약 태스크 루프 시작
7. 미처리 메시지 복구 확인 (크래시 복구)
8. startMessageLoop() — 메인 메시지 폴링 루프 시작

// Main 그룹: 트리거 불필요, 모든 메시지 처리
// 비-Main 그룹: @Andy 패턴 확인 후 처리
const TRIGGER_PATTERN = new RegExp(`@${ASSISTANT_NAME}`, 'i')

if (!group.isMain && !messages.some(m => TRIGGER_PATTERN.test(m.content))) {
  // 메시지를 DB에 보관, 트리거 대기
  return
}

// 마지막 처리 타임스탬프 (그룹별)
lastAgentTimestamp: Record<groupFolder, timestamp>

// 그룹 세션 ID (컨테이너 연속성)
sessions: Map<groupFolder, sessionId>

// 등록된 그룹 정보
registeredGroups: Map<jid, RegisteredGroup>

호스트 프로세스
  └── docker run / container run
        ├── stdin  ← ContainerInput JSON
        │           { messages, group, sessionId, isScheduledTask, ... }
        └── stdout → ContainerOutput JSON (sentinel markers)
                     { result, sessionId, ... }

FROM node:22-slim

# Chromium 및 브라우저 자동화 라이브러리 설치
RUN apt-get install -y chromium ...

# 글로벌 패키지
RUN npm install -g agent-browser @anthropic-ai/claude-code

# 에이전트 러너 컴파일
COPY container/agent-runner/ /app/agent-runner/
RUN tsc ...

# 비-루트 사용자로 실행
USER node
ENTRYPOINT ["/app/entrypoint.sh"]

// stdin (호스트 → 컨테이너)
interface ContainerInput {
  messages: string          // XML 포맷 메시지
  group: RegisteredGroup    // 그룹 메타데이터
  sessionId?: string        // 세션 연속성
  isScheduledTask?: boolean // 예약 태스크 여부
  taskPrompt?: string       // 태스크 프롬프트
}

// stdout (컨테이너 → 호스트, sentinel markers로 감싸짐)
interface ContainerOutput {
  result: string            // 에이전트 응답
  sessionId: string         // 새 세션 ID
  error?: string
}

// 마커
const START = '---NANOCLAW_OUTPUT_START---'
const END   = '---NANOCLAW_OUTPUT_END---'

활성 컨테이너 실행 중 새 메시지 도착 시:

호스트 → /workspace/ipc/input/{timestamp}.json 파일 생성
컨테이너 (500ms 폴링) → 파일 감지 → MessageStream에 추가
에이전트 → 팔로업 메시지 처리 → 응답
(컨테이너 유지, 아이들 타임아웃 30분)

// src/channels/registry.ts
registerChannel('whatsapp', async (config) => {
  if (!process.env.WHATSAPP_ENABLED) return null
  return new WhatsAppChannel(config)
})

// 오케스트레이터에서 조회
const factory = getChannelFactory('whatsapp')
const channel = await factory?.(config)

interface Channel {
  name: string
  connect(): Promise<void>
  disconnect(): Promise<void>
  sendMessage(jid: string, text: string): Promise<void>
  isConnected(): boolean
  ownsJid(jid: string): boolean
  setTyping?(jid: string, typing: boolean): Promise<void>
  syncGroups?(): Promise<void>
}

// 자격증명 없으면 null 반환 → 오케스트레이터가 스킵
const factory = getChannelFactory(name)
if (!factory) return  // 채널 미설치
const channel = await factory(config)
if (!channel) return  // 자격증명 없음

// 응답을 원본 채널로 라우팅
function findChannel(jid: string): Channel | undefined {
  return channels.find(ch => ch.ownsJid(jid))
}

startSchedulerLoop() [60초 폴링]
  └── getDueTasks() — next_run <= now AND status='active'
        │
        ├── [cron] cron-parser로 다음 실행 시간 계산
        ├── [interval] 마지막 실행 + 간격 (드리프트 방지)
        └── [once] 단일 실행 후 completed로 변경
              │
              ▼
        group-queue.ts → enqueueTask()
              │
              ▼
        runContainerAgent() (isolated 또는 group 컨텍스트)
              │
              ▼
        결과 → send_message IPC 도구 → 채널 응답
        로그 → task_run_logs 테이블

컨테이너 측 (MCP 도구)
  ipc-mcp-stdio.ts
    └── /workspace/ipc/{group}/messages/{id}.json 파일 생성
          { type: 'schedule_task', payload: {...} }

호스트 측 (1초 폴링)
  src/ipc.ts → startIpcWatcher()
    └── 파일 감지 → 내용 파싱 → 명령 실행 → 파일 삭제

┌─────────────────────────────────────────────────────┐
│                   호스트 시스템                        │
│                                                     │
│  자격증명 프록시 ─────────── 실제 API 키 (컨테이너 불가) │
│  마운트 허용 목록 ─────────── .ssh, .aws 등 차단        │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │              컨테이너 (격리 경계)              │   │
│  │                                             │   │
│  │  비-루트 사용자 (node, uid 1000)             │   │
│  │  /workspace/group 만 읽기/쓰기 가능          │   │
│  │  플레이스홀더 자격증명만 주입                 │   │
│  │                                             │   │
│  │  ┌─────────────────────────────────────┐   │   │
│  │  │         에이전트 실행 공간            │   │   │
│  │  │  그룹 메모리, 세션 격리              │   │   │
│  │  └─────────────────────────────────────┘   │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘

컨테이너
  └── ANTHROPIC_API_KEY=placeholder
      ANTHROPIC_BASE_URL=http://host:3001
        │
        ▼ HTTP 요청
자격증명 프록시 (포트 3001)
  └── 실제 API 키 주입
        │ HTTP 요청 (헤더 교체)
        ▼
Anthropic API (api.anthropic.com)

// ~/.config/nanoclaw/mount-allowlist.json (호스트만 접근, 컨테이너 마운트 불가)
{
  "allowedRoots": [
    { "path": "~/Documents", "label": "Documents" }
  ],
  "blockedPatterns": [
    ".ssh", ".gnupg", ".aws", ".env", "credentials",
    "id_rsa", "id_ed25519", "*.pem", "*.key"
  ],
  "nonMainReadOnly": true
}

Main 그룹 컨테이너
  ├── 모든 JID로 메시지 전송 가능
  ├── 모든 그룹의 태스크 관리 가능
  └── 새 그룹 등록 가능

비-Main 그룹 컨테이너
  ├── 자신의 JID로만 메시지 전송 가능
  ├── 자신의 그룹 태스크만 관리 가능
  └── 그룹 등록 불가

-- 그룹/채팅 메타데이터
CREATE TABLE chats (
  jid TEXT PRIMARY KEY,
  name TEXT,
  last_message_time INTEGER,
  channel TEXT,        -- 'whatsapp', 'telegram', 등
  is_group INTEGER
);

-- 메시지 이력
CREATE TABLE messages (
  id TEXT PRIMARY KEY,
  chat_jid TEXT,
  sender TEXT,
  timestamp INTEGER,
  content TEXT,
  is_bot_message INTEGER DEFAULT 0
);

-- 예약 태스크
CREATE TABLE scheduled_tasks (
  id INTEGER PRIMARY KEY,
  group_folder TEXT,
  chat_jid TEXT,
  prompt TEXT,
  schedule_type TEXT,   -- 'cron' | 'interval' | 'once'
  schedule_value TEXT,  -- cron 식 또는 ms 또는 ISO 날짜
  context_mode TEXT,    -- 'group' | 'isolated'
  next_run INTEGER,
  status TEXT           -- 'active' | 'paused' | 'completed'
);

-- 태스크 실행 로그
CREATE TABLE task_run_logs (
  id INTEGER PRIMARY KEY,
  task_id INTEGER,
  started_at INTEGER,
  duration_ms INTEGER,
  status TEXT,
  result TEXT,
  error TEXT
);

-- 라우터 상태 (JSON 키-값)
CREATE TABLE router_state (
  key TEXT PRIMARY KEY,
  value TEXT
  -- last_timestamp: 전역 마지막 처리 타임스탬프
  -- last_agent_timestamp: { groupFolder: timestamp } JSON
);

-- 그룹 세션 ID
CREATE TABLE sessions (
  group_folder TEXT PRIMARY KEY,
  session_id TEXT
);

-- 등록된 그룹
CREATE TABLE registered_groups (
  jid TEXT PRIMARY KEY,
  name TEXT,
  folder TEXT,
  trigger TEXT,
  is_main INTEGER,
  added_at INTEGER
);

// 채널에서 호스트로 전달되는 메시지
interface NewMessage {
  id: string
  chat_jid: string      // "1234567890@s.whatsapp.net"
  sender: string
  sender_name: string
  content: string
  timestamp: number
  is_from_me?: boolean
  is_bot_message?: boolean
}

// DB에 저장된 그룹 메타데이터
interface RegisteredGroup {
  name: string
  folder: string        // "groups/family-chat"
  trigger: string       // "@Andy"
  added_at: number
  isMain?: boolean
  requiresTrigger?: boolean
  containerConfig?: ContainerConfig
}

// 예약 태스크
interface ScheduledTask {
  id: number
  group_folder: string
  chat_jid: string
  prompt: string
  schedule_type: 'cron' | 'interval' | 'once'
  schedule_value: string
  context_mode: 'group' | 'isolated'
  next_run: number
  status: 'active' | 'paused' | 'completed'
}

<messages timezone="Asia/Seoul">
  <message id="abc123" sender="+82101234567" sender_name="Alice" timestamp="2026-03-13T10:00:00+09:00">
    <content>@Andy 오늘 날씨 어때?</content>
  </message>
  <message id="def456" sender="+82109876543" sender_name="Bob" timestamp="2026-03-13T10:01:00+09:00">
    <content>나도 궁금해</content>
  </message>
</messages>

┌──────────────────────────────────────────────────────────────┐
│                     채널 레이어                                │
│  WhatsApp / Telegram / Slack / Discord / Gmail                │
│  (자기 등록, Channel 인터페이스 구현)                           │
└──────────────────────────────┬───────────────────────────────┘
                               │ onMessage callback
┌──────────────────────────────▼───────────────────────────────┐
│                     데이터 레이어                              │
│  src/db.ts (SQLite, better-sqlite3, 동기)                    │
│  storeMessage / getNewMessages / getRegisteredGroups / ...    │
└──────────────────────────────┬───────────────────────────────┘
                               │ DB 읽기/쓰기
┌──────────────────────────────▼───────────────────────────────┐
│                   오케스트레이션 레이어                         │
│  src/index.ts → src/group-queue.ts                           │
│  메시지 루프 / 트리거 체크 / 큐 관리 / 동시성 제어              │
└──────────────────────────────┬───────────────────────────────┘
                               │ spawn + stdin/stdout
┌──────────────────────────────▼───────────────────────────────┐
│                   컨테이너 레이어                              │
│  src/container-runner.ts                                     │
│  볼륨 마운트 / 자격증명 프록시 주입 / 스킬 동기화               │
└──────────────────────────────┬───────────────────────────────┘
                               │ Claude Agent SDK
┌──────────────────────────────▼───────────────────────────────┐
│                   에이전트 레이어                              │
│  container/agent-runner/src/index.ts                         │
│  Claude Agent SDK / MCP 서버 / IPC 폴링                      │
└──────────────────────────────┬───────────────────────────────┘
                               │ HTTP (proxy)
┌──────────────────────────────▼───────────────────────────────┐
│                   외부 레이어                                  │
│  Anthropic API (api.anthropic.com)                           │
└──────────────────────────────────────────────────────────────┘

병렬 시스템:
  src/ipc.ts         ─── 파일 IPC 감시 (1초 폴링)
  src/task-scheduler.ts ── 예약 태스크 (60초 폴링)
  src/credential-proxy.ts ─ HTTP 프록시 (포트 3001)

nanoclaw/
├── src/                          # 호스트 프로세스 소스
│   ├── index.ts                  # 오케스트레이터 (메인 엔트리)
│   ├── channels/
│   │   └── registry.ts           # 채널 자기 등록
│   ├── router.ts                 # 메시지 포맷 & 라우팅
│   ├── config.ts                 # 환경변수 설정
│   ├── container-runner.ts       # 컨테이너 스폰 & 마운트
│   ├── group-queue.ts            # 그룹별 큐 & 동시성
│   ├── ipc.ts                    # 파일 IPC 감시
│   ├── task-scheduler.ts         # 예약 태스크
│   ├── db.ts                     # SQLite CRUD
│   ├── credential-proxy.ts       # 자격증명 격리 프록시
│   ├── mount-security.ts         # 마운트 경로 검증
│   └── types.ts                  # 공통 타입 정의
│
├── container/                    # 컨테이너 관련
│   ├── Dockerfile                # 에이전트 컨테이너 이미지
│   ├── entrypoint.sh             # 컨테이너 엔트리포인트
│   ├── build.sh                  # 이미지 빌드 스크립트
│   ├── agent-runner/             # 컨테이너 내부 에이전트
│   │   └── src/
│   │       ├── index.ts          # Claude SDK 실행
│   │       └── ipc-mcp-stdio.ts  # MCP 도구 (스케줄러 등)
│   └── skills/                   # 에이전트에게 주입되는 스킬
│       └── agent-browser.md      # 브라우저 자동화 가이드
│
├── groups/                       # 그룹별 메모리 (격리)
│   ├── main/
│   │   └── CLAUDE.md             # Main 그룹 메모리
│   └── global/
│       └── CLAUDE.md             # 전역 공유 메모리 (읽기 전용)
│
├── data/                         # 런타임 데이터
│   ├── messages.db               # SQLite 데이터베이스
│   ├── sessions/                 # 그룹별 .claude/ 세션
│   └── ipc/                      # 파일 IPC 디렉토리
│       └── {group}/
│           ├── messages/         # 컨테이너 → 호스트 명령
│           └── input/            # 호스트 → 컨테이너 팔로업 메시지
│
├── store/                        # 채널 인증 상태
├── logs/                         # 로그 파일
├── launchd/                      # macOS 서비스 설정
│   └── com.nanoclaw.plist
├── docs/
│   ├── SPEC.md                   # 전체 사양 (31.7k)
│   ├── SECURITY.md               # 보안 모델
│   └── REQUIREMENTS.md           # 설계 결정
└── CLAUDE.md                     # Claude Code 컨텍스트

# 스킬 설치 예시 (WhatsApp 채널 추가)
git remote add whatsapp https://github.com/qwibitai/nanoclaw-whatsapp.git
git fetch whatsapp main
git merge whatsapp/main
npm run build

첫 번째 실행: sessionId = undefined → Claude가 새 세션 생성 → 반환된 sessionId 저장
두 번째 실행: sessionId = "abc123" → Claude가 기존 세션 이어서 실행