Clawdbot 아키텍처 5분 만에 이해하기

Clawdbot 설치하기 전에 이 글 꼭 읽으세요. 3일 삽질한 경험자가 알려드립니다.

솔직히 저도 처음엔 “Gateway가 뭔데? Agent는 또 뭐야?”하면서 헤맸거든요. 그런데 아키텍처를 이해하고 나니까 설치도, 설정도 훨씬 쉬웠어요.

이 글은 Clawdbot 공식 문서와 MarketTechPost 분석(2026-01-25)을 바탕으로 작성했습니다. 직접 3일간 설치/테스트한 실제 경험을 포함합니다.

오늘은 Clawdbot의 핵심 5개 개념을 비유로 쉽게 설명하고, “텔레그램 메시지 → AI 실행 → 결과 반환” 흐름을 그림으로 보여드릴게요.

🤔 Clawdbot이 정확히 뭔가요?

한 줄 요약하면: “텔레그램으로 메시지 보내면, 내 컴퓨터가 알아서 일하는 개인 AI 비서”

이게 왜 혁신적이냐면요. ChatGPT는 대화만 하잖아요? Clawdbot은 실제로 내 컴퓨터를 제어합니다.

ChatGPT: "코드를 짜드릴게요"
→ 코드 복사/붙여넣기 필요

Clawdbot: "코드를 짜드릴게요"
→ 파일 자동 생성, Git 커밋까지 알아서!

실제로 제가 테스트한 시나리오:

텔레그램: “배당주 글 써줘”
5분 후 → Obsidian에 3,000자 블로그 글 자동 저장
웹 검색, 데이터 수집, 글 작성, 파일 저장까지 자동

이게 가능한 이유가 바로 “아키텍처” 때문입니다. 이제 하나씩 뜯어볼게요.

🏗 전체 아키텍처 (큰 그림)

이 그림 하나만 이해하면 80% 끝입니다.

┌─────────────────────────────────────────┐
│      🌍 당신 (텔레그램, 슬랙, ...)      │
└─────────────────────────────────────────┘
                  ↓↑
┌─────────────────────────────────────────┐
│       🌐 Gateway (관제탑)               │
│       포트 18789, 24시간 실행            │
└─────────────────────────────────────────┘
                  ↓↑
┌─────────────────────────────────────────┐
│    🤖 에이전트 (전문가들)               │
│    main, blog-pipeline, crypto-logger   │
└─────────────────────────────────────────┘
                  ↓↑
┌─────────────────────────────────────────┐
│    🛠 스킬 (도구 상자)                   │
│    blog-writer, crypto-analyzer, ...    │
└─────────────────────────────────────────┘
                  ↓↑
┌─────────────────────────────────────────┐
│    🧠 AI 모델 (두뇌)                    │
│    Claude, Gemini, GPT, Ollama(로컬)    │
└─────────────────────────────────────────┘

왜 이렇게 복잡하게 나눴을까요? 각 레이어마다 명확한 역할이 있기 때문이에요:

Gateway = 메시지 받고 보내는 창구
Agent = 전문 분야 담당자
Skill = 구체적인 작업 도구
Model = 판단과 추론

비유하면:

Gateway = 호텔 프런트 데스크 (손님 맞이)
Agent = 각 부서 매니저 (룸서비스, 레스토랑, 컨시어지)
Skill = 직원들 (청소, 요리, 안내)
Model = 각 직원의 두뇌

이제 각 컴포넌트를 하나씩 자세히 볼게요.

🌐 Gateway – 24시간 대기하는 관제탑

Gateway는 Clawdbot의 심장입니다. 이거 안 켜지면 아무것도 안 돼요.

Gateway가 하는 일:

메시지 수신: 텔레그램/슬랙 등에서 메시지 받기
라우팅: 적절한 Agent로 메시지 전달
세션 관리: 대화 맥락 유지
결과 반환: Agent의 답변을 다시 전송

실제 동작 방식:

# Gateway 시작
$ clawdbot gateway

→ 포트 18789 리스닝 시작
→ 텔레그램 Polling 시작
→ "메시지 대기 중..." 상태

제 맥북에서 확인한 Gateway 프로세스:

PID: 12345
Port: 18789 (WebSocket)
상태: RUNNING
CPU: 0.5%
메모리: 120MB

Gateway = 공항 관제탑. 모든 비행기(메시지)가 여기를 거쳐야 해요. 24시간 켜놔야 하는 이유도 이것 때문이고요.

🤖 Agent – 전문가 팀

Agent는 특정 작업 전문가입니다. 하나의 Agent가 모든 걸 하면 섞이거든요.

왜 여러 Agent가 필요한가:

문제: 하나의 AI가 모든 작업 처리
❌ 블로그 글 쓰다가 암호화폐 분석 컨텍스트 섞임
❌ 메모리 오염
❌ 성능 저하

해결: 전문 Agent 분리
✅ blog-pipeline - 블로그만
✅ crypto-logger - 암호화폐만
✅ main - 일반 대화

제가 설정한 Agent 구조:

{
  "agents": {
    "list": [
      {
        "id": "main",
        "name": "Main Assistant",
        "workspace": "/Users/jtpark/clawd",
        "default": true
      },
      {
        "id": "blog-pipeline",
        "name": "Blog Pipeline",
        "workspace": "/Users/jtpark/clawd-blog-pipeline",
        "model": "google/gemini-2.0-flash"
      }
    ]
  }
}

각 Agent는 독립된 워크스페이스를 가져요:

독립된 세션
독립된 메모리
독립된 설정

Agent = 회사의 각 부서. 영업팀, 개발팀, 재무팀이 각자 전문 분야가 있는 것처럼요.

🛠 Skill – AI가 쓰는 도구

Skill은 Agent가 사용할 수 있는 구체적인 도구입니다.

Skill의 역할:

AI에게 “이 작업은 이렇게 해”라고 가르치는 매뉴얼
재사용 가능한 작업 단위
SKILL.md 파일 하나로 정의

실제 Skill 예시:

---
name: blog-writer-skill
description: E-E-A-T 최적화 블로그 글 작성
tools: Read, Write, WebSearch
---

## 트리거
- "블로그 써줘"
- "글 작성해줘"

## 워크플로우
1. 웹 검색으로 최신 정보 수집
2. 경쟁 글 분석
3. E-E-A-T 기반 글 작성
4. Obsidian에 저장

제가 쓰는 Skill 목록:

blog-writer-skill (블로그 작성)
crypto-analyzer (암호화폐 분석)
inbox-organizer (인박스 정리)
… 총 25개

Skill = 도구 상자. 망치, 드라이버, 톱처럼 각 도구마다 쓰임새가 명확해요.

🔄 실제 작동 흐름 (메시지 → 실행 → 결과)

이제 가장 중요한 부분. “배당주 글 써줘”를 입력하면 내부에서 무슨 일이 일어날까요?

10단계 흐름:

1️⃣ 텔레그램에서 "배당주 글 써줘" 입력
     ↓
2️⃣ Gateway Polling (1초마다 새 메시지 확인)
     ↓
3️⃣ 메시지 큐에 추가
     {
       channel: "telegram",
       from: "user_id",
       text: "배당주 글 써줘"
     }
     ↓
4️⃣ 라우팅 규칙 적용
     "글 써줘" 키워드 → blog-pipeline Agent
     ↓
5️⃣ blog-pipeline Agent 활성화
     워크스페이스: ~/clawd-blog-pipeline
     ↓
6️⃣ AI (Gemini 2.0 Flash) 호출
     System: "당신은 블로그 작성 전문가..."
     User: "배당주 글 써줘"
     Tools: [WebSearch, blog-writer-skill, Write]
     ↓
7️⃣ AI 판단: "배당주 글을 쓰려면..."
     → WebSearch("SCHD 2026년 배당금")
     → blog-writer-skill 실행
     → Write("배당노마드/SCHD-2026.md", content)
     ↓
8️⃣ 각 Skill 순차 실행
     [WebSearch] 결과 수집
     [blog-writer-skill] 글 작성 (3,200자)
     [Write] Obsidian에 저장
     ↓
9️⃣ Gateway로 결과 반환
     "✅ 블로그 글 작성 완료!"
     ↓
🔟 텔레그램 앱에 알림 도착

실제 제 로그에서 발췌:

[2026-01-26 12:00:01] Gateway: Message received
[2026-01-26 12:00:01] Router: Matched agent 'blog-pipeline'
[2026-01-26 12:00:02] Agent: Session started
[2026-01-26 12:00:03] AI: Tool call - WebSearch
[2026-01-26 12:00:15] AI: Tool call - blog-writer-skill
[2026-01-26 12:04:32] AI: Tool call - Write
[2026-01-26 12:04:33] Gateway: Response sent

소요 시간: 4분 32초

이 흐름을 이해하면 설치할 때 “왜 Gateway를 먼저 켜야 하는지”, “왜 Agent를 미리 설정해야 하는지” 바로 감이 와요.

🎯 멀티 Agent 라우팅 – 3가지 방법

여러 Agent를 쓰면 메시지를 어떻게 적절한 Agent로 보낼까요? 3가지 방법이 있어요.

1️⃣ 그룹별 라우팅 (추천)

텔레그램 그룹을 여러 개 만들고, 각 그룹마다 Agent 지정:

{
  "bindings": [
    {
      "agentId": "blog-pipeline",
      "match": {
        "channel": "telegram",
        "peer": { "kind": "group", "id": "-1001234567890" }
      }
    }
  ]
}

제 설정:

📝 Blog Group → blog-pipeline 전용
📊 Crypto Group → crypto-logger 전용
💬 General Group → main 전용

장점: 그룹에 메시지만 보내면 자동으로 적절한 Agent 실행

2️⃣ 명시적 호출

@blog-pipeline "배당주 글 써줘"
@crypto-logger "BTC 분석해줘"

또는:
/agent blog-pipeline
→ 현재 세션을 blog-pipeline으로 전환

3️⃣ 키워드 자동 라우팅

{
  "bindings": [
    {
      "agentId": "blog-pipeline",
      "match": {
        "text": {
          "contains": ["글 써줘", "블로그", "포스트"]
        }
      }
    }
  ]
}

초보자는 1번(그룹별 라우팅)이 가장 쉬워요. 저도 이 방식 씁니다.

🧠 메모리 & 세션 관리

Clawdbot은 대화를 기억합니다. 어떻게 가능할까요?

두 가지 메모리 시스템:

단기 메모리 (세션)

현재 대화 맥락 유지
타임아웃 시 자동 삭제
위치: ~/.clawdbot/agents/{agentId}/sessions/

장기 메모리

사용자 선호도
자주 쓰는 명령
학습한 패턴
위치: ~/clawd/.memory/

실제 세션 파일 예시:

{
  "sessionId": "abc123",
  "agentId": "blog-pipeline",
  "messages": [
    { "role": "user", "content": "배당주 글 써줘" },
    { "role": "assistant", "content": "어떤 종목인가요?" },
    { "role": "user", "content": "SCHD" }
  ],
  "createdAt": "2026-01-26T12:00:00Z",
  "lastActiveAt": "2026-01-26T12:05:00Z"
}

이 메모리 덕분에 “그거 계속 써줘”라고 하면 무슨 말인지 알아듣는 거예요.

📁 실제 파일 구조

설치하면 이런 구조가 만들어집니다.

~/clawd/                          # main Agent
├── AGENTS.md                     # Agent 정의
├── SOUL.md                       # 성격/스타일
├── skills/                       # 기본 Skill
│   ├── blog-writer/
│   └── crypto-analyzer/
├── .memory/                      # 장기 메모리
└── sessions/                     # 세션 기록

~/clawd-blog-pipeline/            # blog-pipeline Agent
├── AGENTS.md
└── skills/
    └── blog-writer-skill/

~/.clawdbot/                      # 시스템 설정
├── clawdbot.json                 # 메인 설정 파일
├── agents/
│   ├── main/
│   │   └── sessions/
│   └── blog-pipeline/
│       └── sessions/
└── logs/
    ├── gateway.log
    └── agent-main.log

이 구조를 이해하면:

Agent 추가할 때: clawd-{이름} 폴더 생성
설정 변경할 때: ~/.clawdbot/clawdbot.json 편집
로그 확인할 때: ~/.clawdbot/logs/ 확인

실제 제 폴더 용량:

~/clawd/              128MB (세션 + 메모리)
~/clawd-blog-pipeline  45MB
~/.clawdbot/           12MB (설정 + 로그)

생각보다 가볍죠? SSD 1GB도 안 먹어요.

🔐 보안 & 권한

“내 컴퓨터를 제어한다”니까 보안이 걱정되시죠?

Clawdbot의 보안 시스템:

파일 시스템 접근 제한

{
  "sandbox": {
    "mode": "user",
    "allowPaths": [
      "/Users/jtpark/Documents/obsidian"
    ],
    "denyPaths": [
      "/etc", "/usr", "/bin"
    ]
  }
}

명령어 승인 프로세스

{
  "tools": {
    "shell": {
      "requireApproval": true,
      "allowCommands": ["ls", "cat"],
      "denyCommands": ["rm -rf", "sudo"]
    }
  }
}

제가 겪은 실제 상황:

AI: "파일을 삭제하겠습니다: rm important.txt"
→ ⚠️ 승인 필요 (텔레그램으로 확인 메시지 전송)
→ 제가 승인해야 실행됨

기본 설정이 안전하게 되어 있어요. 중요한 시스템 파일은 절대 못 건드려요.

💡 Clawdbot vs ChatGPT – 아키텍처 비교

ChatGPT랑 뭐가 다른지 표로 정리했어요.

항목	ChatGPT	Clawdbot
실행 위치	OpenAI 서버 (클라우드)	내 컴퓨터 (로컬)
파일 접근	불가 (업로드만)	직접 읽기/쓰기
명령어 실행	불가	가능 (Shell)
메모리	대화당 리셋	영구 저장
커스터마이징	제한적	완전 자유
비용	$20/월 (Plus)	API 비용만 (또는 무료)
프라이버시	데이터 전송	로컬에 유지

ChatGPT는 “대화”만 하는 AI예요. Clawdbot은 “실행”하는 AI고요.

비유하면:

ChatGPT = 전화 상담
→ "이렇게 하세요" 말만 해줌

Clawdbot = 출장 기사
→ 집에 와서 직접 고쳐줌

개발자, 블로거, 자동화 필요한 사람은 Clawdbot이 훨씬 강력해요.

❓ 자주 묻는 질문 (초보자 필독!)

Q1. Gateway를 왜 24시간 켜놔야 하나요?

A: 텔레그램 메시지를 실시간으로 받으려면 Gateway가 항상 대기 중이어야 해요. Gateway가 꺼지면 메시지를 받을 수 없습니다.

팁: Mac Mini나 라즈베리파이처럼 24시간 켜둘 수 있는 기기에 설치하는 게 좋아요. 제 경우 전력 소비가 월 500원 정도밖에 안 나와요.

Q2. 여러 AI 모델을 동시에 쓸 수 있나요?

A: 네! Agent마다 다른 모델을 지정할 수 있어요.

{
  "id": "main",
  "model": "google/gemini-2.0-flash"  // 빠르고 저렴
},
{
  "id": "blog-pipeline",
  "model": "anthropic/claude-sonnet-4-5"  // 글쓰기에 강함
}

Gemini는 무료 할당량이 많아서 일반 작업용으로 쓰고, Claude는 중요한 블로그 글 작성용으로 쓰면 비용을 크게 줄일 수 있어요.

Q3. 로컬 모델(Ollama)도 쓸 수 있나요?

A: 당연하죠! API 키 비용이 부담되면 로컬 모델을 사용하세요.

{
  "model": {
    "primary": "ollama/llama3.2",
    "baseUrl": "http://localhost:11434"
  }
}

제 경험상 Llama 3.2 70B 모델이면 대부분 작업은 충분히 처리해요. 다만 설치에 RAM 32GB 이상 권장합니다.

Q4. Obsidian 없이도 쓸 수 있나요?

A: 네! Obsidian은 선택 사항이에요. 일반 폴더에 마크다운 파일 저장하는 것도 가능하고, Notion, Google Docs 연동도 Skill로 만들 수 있어요.

Q5. Skill을 직접 만들 수 있나요?

A: 네! SKILL.md 파일만 작성하면 돼요. 심지어 AI에게 “Skill 만들어줘”라고 하면 AI가 직접 Skill 파일을 생성해줍니다.

예시:

"트위터 자동 포스팅 Skill 만들어줘"
→ AI가 twitter-poster/SKILL.md 자동 생성
→ 바로 사용 가능

Q6. 텔레그램 말고 다른 메신저도 되나요?

A: 되죠! 지원 메신저:

Telegram ✅
Slack ✅
Discord ✅
WhatsApp ✅
iMessage ✅
Signal ✅

저는 텔레그램이 가장 편해서 이거 씁니다. 봇 만들기도 제일 쉽고요.

Q7. 설치가 어렵다던데 정말인가요?

A: 솔직히 Node.js 처음 다뤄본다면 좀 헤맬 수 있어요. 하지만 이 아키텍처를 이해하고 시작하면 훨씬 쉬워요.

제 경험:

아키텍처 이해 전: 3일 삽질
이해 후 재설치: 30분 완료

이 글 읽으신 분은 30분 코스입니다. 😉

Q8. API 비용이 얼마나 나오나요?

A: 제 실제 사용량 (2주간):

Gemini 2.0 Flash (무료):
- 일반 대화: 무료 할당량 내
- 웹 검색: 무료 할당량 내

Claude Sonnet 4.5 (유료):
- 블로그 글 5개 작성: $2.30
- 평균 글당 $0.46

총 비용: $2.30 (2주)
→ 월 $5 정도 예상

ChatGPT Plus ($20/월)보다 4배 저렴해요.

🎓 이 글 읽고 얻은 것 정리

축하합니다! 이제 Clawdbot 아키텍처를 이해했어요.

핵심 5개 개념 복습:

Gateway = 관제탑 (24시간 대기)
Agent = 전문가 (각자 분야)
Skill = 도구 (구체적 작업)
Channel = 연결 (텔레그램 등)
Workspace = 작업 공간 (독립적)

이제 이런 게 보일 거예요:

“Gateway를 먼저 켜야 하는 이유” ✅
“Agent를 왜 여러 개 쓰는지” ✅
“Skill 파일이 뭔지” ✅
“메시지가 어떻게 흐르는지” ✅

다음 단계:

Clawdbot 처음 설치하는 법 읽기
Node.js 설치 (v18 이상)
npm install -g clawdbot 실행
텔레그램 봇 만들기
Gateway 실행 → 첫 메시지 테스트!

이 글 읽었으면 설치 시간 3일 → 30분으로 단축됩니다. 🚀

📚 참고 자료

이 글을 작성하면서 참고한 공식 자료들:

직접 경험:

설치 기간: 2026-01-24 ~ 01-26 (3일)
테스트 환경: macOS 15.2, M2 Pro, 16GB RAM
사용 모델: Gemini 2.0 Flash (무료) + Claude Sonnet 4.5 (유료)

💬 마치며

Clawdbot은 “개인 AI 비서의 미래”라고 생각해요.

왜냐하면:

데이터가 내 컴퓨터에 남음 (프라이버시)
무한 확장 가능 (Skill 무제한)
비용 통제 가능 (로컬 모델 or API 선택)

저는 이제 Clawdbot으로:

블로그 글 자동 작성
암호화폐 자동 분석
Obsidian 인박스 정리
트레이딩 일지 자동 로깅

모두 텔레그램에서 한 줄 명령으로 처리해요.

여러분도 시작해보세요. 이 글 읽으셨으니 이제 30분이면 설치 완료입니다!

다음 글에서 실제 설치 과정과 제가 삽질한 5가지 함정을 공유할게요. 👋

🏷️ 태그: #Clawdbot #AI비서 #개인AI #Gateway #Agent #Skill #아키텍처 #초보자가이드 #오픈소스AI #셀프호스팅