중추 신경계 비유
대부분의 사람들은 AI 어시스턴트를 독립형 두뇌—처리하고 응답하는 단일 개체로 생각합니다. clawbot은 다릅니다: 생물학적 신경계처럼 설계되었습니다. 뇌(AI 모델)는 근육을 직접 제어하지 않습니다. 신호는 신경(채널)을 통해 이동하고, 척수(Gateway)에서 처리되고, 운동 뉴런(시스템 도구)을 통해 실행됩니다.
이 분산 아키텍처는 clawbot이 WhatsApp을 동시에 듣고, Telegram을 통해 응답하고, 셸 명령을 실행하고, 메모리를 업데이트할 수 있는 이유입니다—모두 병렬로. 전통적인 모놀리식 AI는 모든 기능이 긴밀하게 결합되어 있기 때문에 이것을 할 수 없습니다. clawbot의 모듈식 설계는 각 구성 요소를 잘 정의된 프로토콜을 통해 통신하는 독립적인 서비스로 취급합니다.
clawbot 시스템 아키텍처
구성 요소 심층 분석: 각 부분의 기능
🌐 Gateway: 중앙 사령부
Gateway는 clawbot의 심장입니다—절대 잠들지 않는 지속적인 Node.js 프로세스입니다. 각 채널에서 직접 AI를 실행하는 대신 전용 서비스를 사용하는 이유는 무엇입니까? 세 가지 중요한 이유:
- 통합 상태: 모든 채널의 대화 기록에 대한 단일 진실 소스
- 리소스 효율성: 15개 이상의 별도 연결 대신 AI API에 대한 하나의 연결
- 장애 격리: WhatsApp이 충돌하면 Telegram이 계속 작동합니다—채널은 교체 가능한 플러그인입니다
Gateway는 HTTP가 아닌 WebSocket을 통해 통신합니다. 왜 그럴까요? HTTP는 클라이언트가 "업데이트가 있나요?"를 계속 물어야 합니다(폴링). WebSocket은 지속적인 양방향 연결을 유지합니다—Gateway는 준비되는 즉시 채널에 메시지를 푸시할 수 있어 실시간 스트리밍 응답을 가능하게 합니다.
💬 채널: 감각 인터페이스
채널은 메시징 플랫폼 프로토콜과 Gateway의 통합 메시지 형식 간에 변환하는 독립적인 프로세스입니다. 프로토콜 어댑터로 생각하세요—WhatsApp은 Baileys를 말하고, Telegram은 Bot API를 말하지만, 둘 다 동일한 JSON 구조로 Gateway에 메시지를 제공합니다.
이 추상화는 강력합니다: 새로운 메시징 플랫폼을 추가하려면 전체 시스템을 수정하는 것이 아니라 하나의 채널 플러그인을 작성하면 됩니다. 각 채널은 샌드박스화되어 있습니다—충돌하면 Gateway가 다른 채널에 영향을 주지 않고 자동으로 재연결을 시도합니다.
🧠 AI 모델 라우터: 인텔리전스 백본
clawbot은 단일 AI 제공업체에 종속되지 않습니다. 모델 라우터는 동적 제공업체 선택을 구현합니다: 복잡한 추론을 위해 Claude를 선택하고, 창의적 작업을 위해 GPT-4를 선택하거나, 프라이버시가 중요한 작업을 위해 로컬 Ollama를 선택하세요—모두 동일한 대화 내에서.
이것은 기술적으로 어떻게 작동합니까? 각 AI 제공업체는 표준화된 인터페이스를 가지고 있습니다(OpenAI Completion API 패턴을 따름). 라우터는 구성된 모든 제공업체에 대한 연결 풀을 유지하고, 구성된 기본 설정에 따라 요청을 라우팅하며, 제공업체를 사용할 수 없는 경우 자동 장애 조치를 처리합니다.
고급: 사용자 정의 모델 라우팅 로직
~/.clawbot/clawbot.json에서 사용자 정의 라우팅 규칙을 구성할 수 있습니다:
- 코딩 작업을 Claude로 라우팅(프로그래밍에 더 나음)
- 창의적 글쓰기를 GPT-4로 라우팅(더 상상력이 풍부함)
- 민감한 데이터 처리를 로컬 Ollama로 라우팅(외부 전송 없음)
- 기본 제공업체가 실패하면 보조 제공업체로 자동 장애 조치
💾 지속적 메모리: 대화 상태 관리
요청 간에 모든 것을 잊어버리는 무상태 AI API와 달리, clawbot은 ~/.clawbot/conversations/에
Markdown 파일로 저장된 지속적인 대화 기록을 유지합니다. 각 대화는 메시지, 도구 실행 및 AI 응답의
완전한 로그입니다.
데이터베이스 대신 Markdown을 사용하는 이유는 무엇입니까? 세 가지 이유:
- 사람이 읽을 수 있음: AI 대화를 grep, 검색 및 버전 제어할 수 있습니다
- 이식 가능: 폴더를 복사하여 전체 대화 기록 이동
- AI 친화적: AI 모델은 컨텍스트 검색을 위해 Markdown 형식을 기본적으로 이해할 수 있습니다
Gateway는 컨텍스트 윈도우를 자동으로 관리합니다—대화가 모델의 토큰 제한을 초과하면 중요한 컨텍스트를 보존하면서 오래된 메시지를 지능적으로 요약합니다. 이를 통해 저하 없이 몇 주에 걸친 대화가 가능합니다.
⚙️ 실행 엔진: 안전한 시스템 제어
이것은 clawbot을 챗봇과 구별하는 것입니다: 진정한 작업 실행. AI가 셸 명령이 필요하다고 결정하면 실행 엔진은 여러 보호 계층을 통해 안전하게 처리합니다:
- 샌드박싱: 명령은 제한된 파일 시스템 액세스로 제한된 환경에서 실행됩니다
- 권한 게이트: 명령 패턴에 대한 사용자 구성 가능한 허용 목록/거부 목록
- 확인 프롬프트: 파괴적인 작업에는 명시적인 사용자 승인이 필요합니다
- 감사 로깅: 실행된 모든 명령은 타임스탬프, 사용자 및 결과와 함께 기록됩니다
- 시간 초과 보호: 명령은 구성 가능한 기간 후 자동으로 종료됩니다
🔌 스킬 시스템: 확장 가능한 기능
스킬은 clawbot의 플러그인 시스템입니다—AI에게 새로운 기능을 가르치는 SKILL.md 파일이 포함된 폴더입니다.
Markdown 파일이 어떻게 기능을 확장합니까? AI는 스킬 정의를 읽고 다음을 학습합니다:
- 스킬이 무엇을 하고 언제 사용하는지
- 어떤 매개변수를 허용하는지
- 트리거하는 예제 명령
- 예상 동작 및 에지 케이스
스킬에는 셸 스크립트, Node.js 모듈 또는 API 통합 코드가 포함될 수 있습니다. AI는 구조화된 함수 호출을 통해 이러한 도구를 호출하고, 결과를 받고, 응답에 통합합니다. 이것이 clawbot이 스마트 홈을 제어하고, 클라우드 인프라를 관리하거나, 독점 내부 시스템과 통합할 수 있는 방법입니다—누구나 스킬을 작성할 수 있습니다.
기술 스택: clawbot을 구동하는 것
런타임: Node.js 22+
실시간 통신을 위한 뛰어난 비동기 I/O 성능을 갖춘 최신 JavaScript 런타임. WebSocket, HTTP/2 및 워커 스레드에 대한 네이티브 지원으로 병렬 작업 실행이 가능합니다.
언어: TypeScript
타입 안전 개발은 전체 범주의 버그를 방지합니다. WebSocket 메시지, AI 응답 및 구성에 대한 강력한 타이핑은 견고한 오류 처리를 보장합니다.
통신: WebSocket 프로토콜
Gateway와 모든 클라이언트 간의 양방향 지속적 연결. 실시간 메시지 스트리밍, 즉각적인 알림 및 AI 응답에 대한 서브초 대기 시간을 가능하게 합니다.
저장소: 파일 기반 상태
Markdown으로 저장된 대화, JSON으로 구성, 구조화된 폴더로 스킬. 데이터베이스 종속성 없음—더 간단한 배포, 더 쉬운 백업, grep 친화적 디버깅.
WhatsApp: Baileys 라이브러리
역설계된 WhatsApp Web 프로토콜 구현. 브라우저가 사용하는 것과 동일한 프로토콜을 사용하여 지속적인 연결 유지— 비공식 API 또는 전화번호 공유 없음.
Telegram: grammY 프레임워크
TypeScript 지원이 포함된 공식 Telegram Bot API 래퍼. 유연한 배포를 위한 롱 폴링 및 웹훅 지원, 파일 업로드, 인라인 키보드 및 전체 봇 기능.
AI 통합: 제공업체 추상화
Anthropic Claude, OpenAI GPT-4, Ollama 로컬 모델 및 Google Gemini를 지원하는 통합 인터페이스. 원활한 제공업체 전환을 위한 다양한 API 형식 간 자동 변환.
보안: 샌드박스 실행
셸 명령은 구성 가능한 권한으로 제한된 환경에서 실행됩니다. 사용자 정의 신뢰 경계는 우발적인 시스템 손상이나 무단 작업을 방지합니다.
메시지 흐름: 시스템을 통한 요청 추적
WhatsApp을 통해 "2시간 후에 엄마에게 전화하도록 알려줘"라고 보내면 어떻게 되는지 추적해 봅시다.
{"from": "user", "text": "Remind...", "channel": "whatsapp"}schedule_reminder(time="+2h", message="엄마에게 전화") 호출이 19단계 안무는 2초 이내에 발생합니다. 분산 아키텍처를 통해 각 구성 요소가 독립적으로 작동할 수 있습니다—WhatsApp 채널은 Claude에 대해 모르고, Claude는 WhatsApp에 대해 모르지만, Gateway의 오케스트레이션을 통해 원활하게 조율됩니다.
이 아키텍처가 중요한 이유
대부분의 AI 어시스턴트는 모놀리식입니다—모든 로직이 하나의 애플리케이션에 있고, 특정 플랫폼에 긴밀하게 결합되어 있습니다. clawbot의 분산 설계는 전통적인 아키텍처에서는 불가능한 기능을 가능하게 합니다:
- 핫 스왑 가능 구성 요소: 채널을 다시 시작하지 않고 AI 모델을 업그레이드합니다. Gateway를 건드리지 않고 WhatsApp을 Telegram으로 교체합니다.
- 수평 확장: 여러 채널 인스턴스를 다른 머신에서 실행하고, 모두 하나의 Gateway에 연결합니다.
- 장애 허용: 한 채널이 충돌하면 다른 채널이 계속 작동합니다. Gateway가 다시 시작하면 채널이 자동으로 재연결됩니다.
- 다중 테넌시: 하나의 Gateway가 격리된 대화 공간으로 여러 사용자에게 서비스를 제공할 수 있습니다—가족 배포에 완벽합니다.
- 확장성: 커뮤니티 구성원은 핵심 코드에 액세스하지 않고도 새로운 채널, 스킬 또는 도구를 구축할 수 있습니다.
아키텍처를 통한 보안
분산 설계는 유연성에 관한 것만이 아닙니다—보안 경계입니다. 채널은 제한된 권한으로 별도의 프로세스에서 실행됩니다. 채널이 손상되면 공격자는 전체 시스템이 아닌 해당 메시징 플랫폼에만 액세스할 수 있습니다. Gateway는 인증을 적용하고, 실행 엔진은 시스템 명령이 실행되기 전에 추가 샌드박싱을 적용합니다.
기술적 결정 및 트레이드오프
HTTP REST 대신 WebSocket을 사용하는 이유는 무엇입니까?
HTTP는 요청-응답입니다: 클라이언트가 묻고 서버가 답합니다. AI 응답은 종종 5-15초가 걸립니다. WebSocket이 없으면 폴링(낭비) 또는 롱 폴링(복잡)이 필요합니다. WebSocket은 스트리밍 응답을 가능하게 합니다—AI는 생성하는 순간 단어를 보내기 시작하여 즉각적인 응답성의 인식을 만듭니다.
데이터베이스 대신 파일 저장소를 사용하는 이유는 무엇입니까?
데이터베이스는 배포 복잡성을 추가합니다—설치, 구성, 백업 전략. 개인 AI(1-10명 사용자)의 경우 파일은 이식 가능하고, 검사 가능하며, 버전 제어 가능하면서 충분한 성능을 제공합니다. 대화 기록을 grep하거나, Dropbox로 백업하거나, Git으로 변경 사항을 추적할 수 있습니다.
Python/Go/Rust 대신 Node.js를 사용하는 이유는 무엇입니까?
Node.js는 I/O 바운드 작업(실시간 통신, API 호출)에 탁월합니다. JavaScript의 async/await 모델은 AI 워크플로에 자연스럽게 매핑됩니다(요청 보내기, 응답 대기, 결과 처리). npm 생태계는 모든 메시징 플랫폼에 대한 성숙한 라이브러리를 제공합니다. TypeScript는 개발 속도를 희생하지 않고 안전성을 추가합니다.