Clawdbot: 나만의 AI 자비스를 만들어보자

GitHub: https://github.com/clawdbot/clawdbot

2026년 1월, PSPDFKit 창립자 Peter Steinberger가 공개한 Clawdbot이 GitHub 스타 9천 개를 돌파하며 개발자 커뮤니티의 뜨거운 관심을 받고 있습니다. Clawdbot은 로컬에서 직접 구동하는 오픈소스 AI 비서로, 아이언맨의 자비스(Jarvis)를 현실로 만들어주는 프로젝트입니다.

---

왜 Clawdbot인가?

Siri가 2011년에 등장한 이후 15년이 지났지만, 기존 AI 비서들은 여전히 단순 명령 수행에 머물러 있습니다. ChatGPT도 세션을 닫으면 사용자를 잊어버리죠.

Clawdbot은 이런 한계를 정면으로 돌파합니다. 핵심 차별점은 능동적 상호작용입니다. 다른 챗봇들이 사용자 질문을 기다리는 것과 달리, Clawdbot은 먼저 메시지를 보냅니다. 아침이 되면 모닝 브리핑을, 일정 시간 전에는 캘린더 알림을, 중요 이메일이 오면 바로 알려줍니다.

또 하나의 혁신은 익숙한 메신저 연동입니다. WhatsApp, Telegram, Discord, Slack 등 이미 사용 중인 채팅 앱에서 바로 AI와 대화할 수 있어, 별도 앱 설치 없이 일상에 자연스럽게 녹아듭니다.

프로젝트 이름은 CLAW + TARDIS의 합성어로, 마스코트인 "우주 바닷가재" Clawd가 README에서 "EXFOLIATE! EXFOLIATE!"라며 반겨줍니다.

---

주요 기능

멀티채널 메시징

한 번 설정하면 WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage 등 모든 플랫폼을 동시에 모니터링합니다. 어디서 메시지를 보내든 동일한 AI 비서가 응답하죠. Microsoft Teams, Matrix, Zalo도 플러그인으로 추가 가능합니다.

강력한 도구 통합

단순 대화를 넘어 다양한 작업을 수행합니다:

• 웹 브라우저 제어: 인터넷 검색 및 페이지 요약
• 파일 시스템 접근: 로컬 파일 읽기/쓰기/실행
• 터미널 명령 실행: 시스템 스크립트 구동
• 카메라/스크린 캡처: "내 노트북 카메라로 사진 찍어줘" 가능
• Live Canvas: 채팅 중 그림이나 도표 표시

이 모든 확장 기능은 "스킬(Skills)" 시스템으로 관리되며, 공식 ClawdHub 레지스트리에서 커뮤니티 제작 스킬을 검색/설치할 수 있습니다.

유연한 LLM 연동

다양한 AI 모델을 백엔드로 사용할 수 있습니다:

• 기본 내장: Pi 코딩 에이전트 (경량 AI 모델)
• 외부 API: OpenAI GPT-4/3.5, Anthropic Claude (OAuth 또는 API 키)
• 로컬 LLM: Ollama로 Llama2 등 직접 호스팅

특히 Anthropic Claude 2 (Pro/Max)와 OpenAI GPT-4 조합이 긴 문맥 처리와 프롬프트 보안 면에서 권장됩니다.

자동화와 능동적 알림

• Morning Briefing: 매일 아침 일정, 날씨, 할 일 요약
• 캘린더 알림: 일정 시작 전 자동 알림
• 이메일 훅: 중요 이메일 도착 시 즉시 알림
• 크론 잡: "매주 월요일 9시에 지난주 업무 요약 보내줘" 같은 복잡한 자동화

로컬 우선 설계

모든 대화 내용과 설정은 사용자 기기에 마크다운 파일로 저장됩니다. 클라우드에 올라가지 않아 프라이버시가 보장되고, 인터넷 없이도 로컬 LLM으로 운영 가능합니다.

게이트웨이는 기본적으로 127.0.0.1에 바인딩되어 외부 접근이 차단됩니다. 원격 접속은 VPN이나 터널링이 필요할 정도로 보안에 신경 썼습니다.

멀티에이전트 관리

그룹 채팅마다 별도 세션이 할당되어 맥락이 섞이지 않습니다. 업무용 에이전트와 개인용 에이전트를 따로 운용하거나, 에이전트 간 작업 요청도 가능합니다.

---

Ubuntu 설치 가이드

Mac이나 Windows WSL2도 유사한 단계입니다. Mac은 Homebrew, Windows는 WSL2 Ubuntu를 권장합니다. 여기서는 Ubuntu 22.04 LTS 기준으로 설명합니다.

Step 1: Node.js 22 이상 설치

Clawdbot은 Node.js 런타임으로 작성되었으므로 Node.js 22 버전 이상이 필요합니다.

방법 1: NodeSource 사용

# Node.js 22.x 설치
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# 설치 확인
node -v    # v22.xx.xx 형태로 출력
npm -v     # npm 버전 출력

방법 2: nvm 사용

# nvm 설치 스크립트 실행
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.nvm/nvm.sh   # nvm.sh 로드

# Node 25 (최신 안정판) 설치
nvm install 25
nvm use 25

node -v   # v25.x.x 확인

pnpm을 사용하고 싶다면 npm install -g corepack && corepack enable pnpm을 실행하면 되지만, npm만으로도 충분합니다.

Step 2: Clawdbot 글로벌 설치

sudo npm install -g clawdbot@latest   # 전역 설치

# 버전 확인
clawdbot -v
# 2026.1.23-1

권한 문제 발생 시 npm install -g --unsafe-perm clawdbot을 시도하세요.

대안: 공식 설치 스크립트

curl -fsSL https://clawd.bot/install.sh | bash

이 스크립트는 의존성을 자동 설치하고 최신 버전을 세팅해주지만, 학습 목적이라면 수동 설치를 권장합니다.

Step 3: 채널 연동 준비 (Discord 예시)

Clawdbot은 각 플랫폼마다 인증 정보가 필요합니다:

• WhatsApp: 휴대폰 QR코드 로그인
• Telegram: BotFather에서 Bot API 토큰 발급
• Slack: OAuth 토큰 두 개
• Discord: 봇 토큰

Discord 봇 생성 과정:

1. Discord 개발자 포털에서 새 Application 생성 (예: "Clawdbot")
2. 좌측 메뉴 Bot 섹션에서 Add Bot 클릭
3. Privileged Gateway Intents 설정:
   • MESSAGE CONTENT INTENT 활성화 (메시지 내용 읽기 권한)
   • 필요에 따라 다른 Intent도 활성화
4. Reset Token 버튼으로 봇 토큰 발급 → 안전하게 보관
5. 좌측 OAuth2 > URL Generator에서:
   • Scopes: bot 체크
   • Bot Permissions: Send Messages, Read Message History 등 체크
   • 생성된 URL로 Discord 서버에 봇 초대

Step 4: 온보딩 마법사 실행

clawdbot onboard --install-daemon

ASCII 아트 로고와 함께 대화형 설정이 시작됩니다.

4-1. 보안 경고 및 동의

⚠️  Clawdbot agents can run commands, read/write files, 
    and act through any tools you enable...
    
Continue? [Yes/No]

Clawdbot이 가질 수 있는 강력한 권한에 대한 안내입니다. Yes를 선택해야 진행됩니다.

4-2. 온보딩 모드 선택

Select onboarding mode:
> QuickStart (recommended)
  Advanced

일반적으로 QuickStart를 선택합니다.

4-3. 게이트웨이 설정

Gateway Configuration:
- Port: 18789 (default)
- Bind Address: 127.0.0.1 (Loopback)
- Auth Mode: Token

QuickStart 모드에서는 기본값이 자동 적용됩니다. 원격 접속이 필요하면 bind 주소를 변경할 수 있지만, 보안상 기본값 유지를 권장합니다.

4-4. LLM 모델 및 공급자 설정

Select AI Provider:
> OpenAI
  Anthropic
  Local (Ollama)

OpenAI 선택 시:

Authentication method:
> OpenAI Codex OAuth (ChatGPT 웹 로그인)
  API Key

• OAuth 방식: 브라우저가 열리고 OpenAI 계정 로그인 → ChatGPT 세션 접근 허용
• API Key 방식: OPENAI_API_KEY 직접 입력

Anthropic 선택 시: Claude API 키 또는 OAuth 입력

로컬 모델 선택 시: Ollama 등 로컬 LLM 서버 주소 입력

모델 선택 완료 시:

✓ Default model set to openai/gpt-4

권장 조합: Anthropic Claude 2 (Pro/Max) + OpenAI GPT-4 Codex - 긴 문맥 처리와 프롬프트 보안에 좋은 성능

4-5. 채널 설정

Channel Status:
- Telegram: not configured
- WhatsApp: not configured  
- Discord: not configured
- Slack: not configured

Configure channels now? [Yes/No]

Discord 설정 방법 (두 가지):

1. 환경 변수 사전 설정 (권장):

export DISCORD_BOT_TOKEN="봇토큰문자열"

이렇게 하면 자동으로 Discord: configured로 표시됩니다.

1. 온보딩 중 직접 입력: 프롬프트에서 Discord 토큰 값을 입력

다른 채널:

• WhatsApp: QR 코드가 터미널에 출력 → 휴대폰으로 스캔
• Telegram: BotFather에서 받은 토큰 입력

모든 채널을 건너뛰어도 나중에 설정 가능합니다.

4-6. 데몬 설치 및 완료

Install Clawdbot as background service? [Yes/No]

--install-daemon 옵션을 주었으므로 Yes 선택:

• Ubuntu: ~/.config/systemd/user/clawdbot.service 생성, 로그인 시 자동 실행
• Mac: LaunchAgent로 등록
• Windows WSL2: 별도 설정 필요

✓ Clawdbot gateway service installed and started
✓ Web dashboard available at http://127.0.0.1:18789/

Step 5: 상태 확인 및 트러블슈팅

clawdbot gateway status

정상 출력:

Gateway: running (pid 12345)
Listening on 127.0.0.1:18789
Connected channels: Discord, Telegram

웹 대시보드 접속: http://127.0.0.1:18789/

문제 발생 시:

# 포그라운드 모드로 실행해 로그 확인
clawdbot gateway --port 18789 --verbose

# 설정 오류 검사
clawdbot doctor

Step 6: 초기 설정 다듬기 (선택)

설정 파일 직접 편집

~/.clawdbot/clawdbot.json:

{
  "agent": {
    "model": "openai/gpt-4"
  },
  "channels": {
    "discord": {
      "token": "YOUR_DISCORD_BOT_TOKEN"
    },
    "telegram": {
      "botToken": "123456:ABCDEF"
    }
  }
}

설정 변경 후 재시작:

clawdbot gateway restart

API 키 환경변수 설정

OAuth 대신 API Key를 사용하는 경우:

# ~/.bashrc 또는 ~/.zshrc에 추가
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

Sandbox 모드 설정 (보안 강화)

기본적으로 AI가 호스트에서 직접 명령을 실행할 수 있습니다. 보안이 우려된다면:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "docker"
      }
    }
  }
}

Docker 샌드박스 안에서만 명령이 실행되도록 제한합니다. 특히 그룹 채팅용 세션은 샌드박스 격리를 강력히 권장합니다.

---

활용 사례

코딩 어시스턴트

Discord에서 "@Clawdbot 타입스크립트로 FizzBuzz 코드를 작성해줘"라고 물으면, GPT-4 수준의 코딩 지식으로 코드 블록 형태의 답변을 제공합니다.

리서치 도우미

"AI 에이전트 프레임워크들에 대해 조사해줘"라고 요청하면, 내장 브라우저로 자료를 조사하고 LangChain, Semantic Kernel 등의 장단점을 비교 요약해줍니다.

파일 관리 및 요약

긴 문서나 PDF를 업로드하면 중요 내용을 추출하고, OCR로 이미지/PDF 텍스트도 인식합니다.

명령 실행 자동화

• /backup: 백업 스크립트 실행
• /shutdown 18:00: 오후 6시 종료 예약
• /status: 토큰 사용량, 모델 상태 확인

멀티채널 활용

외부에서는 WhatsApp으로, 집에서는 Discord로 이어서 대화 가능합니다. 터미널 선호자는 clawdbot tui 명령으로 텍스트 UI도 사용할 수 있습니다.

---

커뮤니티 팁

Reddit과 커뮤니티에서 공유된 실제 사용자 조언들입니다:

로컬 LLM 활용

Ollama로 LLaMA 계열 모델을 구동하거나 LlamaGate로 오픈소스 모델을 연결하면 무료로 강력한 AI를 사용할 수 있습니다. 다만 고사양 GPU가 필요하고 속도가 느릴 수 있습니다.

보안 설정 필수

• DM 페어링 정책: 모르는 사람은 페어링 코드 요구
• Allowlist: 허용된 사용자만 명령 가능
• Sandbox 모드: "agents": {"defaults": {"sandbox": {"mode": "docker"}}} 설정으로 명령 실행 격리

공식 Security 가이드를 꼭 읽어보세요.

24시간 운영

DigitalOcean 등 클라우드나 라즈베리 파이 같은 저전력 기기에 설치하면 항상 켜둘 수 있습니다.

커뮤니티 지원

문제 발생 시 공식 Discord 서버 "Friends of the Crustacean"에서 개발자와 사용자들의 도움을 받을 수 있습니다.

---

장단점 정리

장점

항목 설명

완전한 소유권	로컬 저장, 서비스 종료 걱정 없음
폭넓은 연동	거의 모든 채팅앱 지원
확장성	오픈소스로 자유로운 커스터마이즈
강력한 AI	GPT-4, Claude, 오픈소스 LLM 모두 지원
능동적 알림	스케줄 기반 자동화
멀티모달	텍스트, 음성, 이미지 지원
활발한 개발	1-2주 간격 업데이트

단점

항목 설명

설정 난이도	터미널, Node.js, API 설정 필요
운영 부담	24시간 서버/PC 또는 클라우드 필요
보안 주의	강력한 권한으로 인한 위험성
단일 사용자	멀티유저 솔루션 아님
UI 미흡	설정은 JSON 편집이나 터미널 필요

---

누구에게 추천하나?

추천 대상

• 파워유저/개발자: 다양한 서비스를 통합 관리하고 싶은 분
• 프라이버시 중시: 클라우드 AI가 걱정되거나 사내 보안 규정이 있는 분
• 커스터마이징 매니아: 나만의 스킬을 개발하고 싶은 분
• LLM 실험가: 여러 모델을 비교하며 테스트하고 싶은 분

비추천 대상

• 명령줄 사용이 부담스러운 일반 사용자
• 바로 사용 가능한 간편 AI를 원하는 분
• 기업/팀 단위 협업용 솔루션을 찾는 분

---

마무리

Clawdbot은 "내가 꿈꾸던 개인 AI 비서를 직접 운영해본다"는 경험을 제공합니다. 초기 세팅에 노력이 들지만, 일단 자리잡으면 24시간 나만을 위해 일하는 든든한 조력자가 됩니다.

공식 문서와 GitHub를 참고하면 더 깊이 있는 정보를 얻을 수 있습니다. Clawdbot 유저들의 인사말로 마무리합니다.

EXFOLIATE! 🦞

---

참고 자료

• GitHub: https://github.com/clawdbot/clawdbot
• 공식 사이트: https://clawd.bot
• 커뮤니티: Discord "Friends of the Crustacean"