Clawdbot은 사용자의 개인 기기에서 실행되는 로컬 우선(local-first) AI 비서로, 다양한 커뮤니케이션 채널을 통해 상호작용하며 개인화된 경험을 제공한다. 이 프로젝트는 MIT 라이선스하에 오픈 소스로 개발되었으며, clawd.bot 웹사이트를 통해 접근 가능하다.

핵심 목적 및 기능:
Clawdbot의 주요 목적은 사용자가 WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, Microsoft Teams, WebChat 등과 같은 기존 메시징 플랫폼 및 BlueBubbles, Matrix, Zalo, Zalo Personal 같은 확장 채널을 통해 AI 어시스턴트와 직접 소통할 수 있도록 하는 것이다. 핵심 기능으로는 macOS/iOS/Android에서의 음성 듣기 및 말하기 기능, 실시간으로 제어 가능한 Canvas 렌더링, 그리고 Browser, Canvas, Nodes, Cron, sessions, Discord/Slack actions과 같은 일급(first-class) 도구 통합이 있다. 개인 사용자에게 최적화된 로컬, 빠르고 항상 켜져 있는(always-on) 어시스턴트 경험을 목표로 한다.

주요 방법론 및 아키텍처:
Clawdbot의 아키텍처는 Gateway를 중심으로 구축되며, 이는 sessions, channels, tools, events를 위한 단일 control plane 역할을 한다.

1. Gateway:
   • WebSocket 기반의 네트워크를 통해 client, tools, events를 제어하는 ws://127.0.0.1:18789에서 실행되는 중심 허브이다.
   • CLI surface(gateway, agent, send, wizard, doctor)를 제공하여 시스템 관리 및 상호작용을 가능하게 한다.
   • Pi agent runtime은 RPC mode로 동작하며 tool streaming과 block streaming을 지원한다.
   • Session model은 main 채팅 외에 group isolation, activation modes, queue modes, reply-back 기능을 포함하여 다양한 대화 시나리오를 지원한다.
   • Media pipeline은 images, audio, video 처리, transcription hooks, size caps, temp file lifecycle 관리를 담당한다.
   • Tailscale Serve/Funnel 통합을 통해 Gateway dashboard 및 WebSocket에 대한 안전한 원격 접근을 제공한다. gateway.tailscale.mode 설정을 통해 off, serve, funnel 모드를 선택할 수 있다.
   • Browser control 기능은 clawd-관리 Chrome/Chromium 인스턴스를 통해 CDP(Chrome DevTools Protocol) 제어를 가능하게 하여 snapshots, actions, uploads, profiles 등을 수행한다.
   • Canvas 및 A2UI는 에이전트 주도(agent-driven)의 시각적 작업 공간을 제공하며, A2UI를 host한다.
   • Voice Wake 및 Talk Mode는 ElevenLabs와 연동하여 always-on speech 및 continuous conversation 기능을 제공한다.
   • Nodes는 Canvas, camera snap/clip, screen record, location.get, notifications와 같은 장치별 액션을 수행하며, macOS에서는 system.run 및 system.notify도 지원한다.

2. 보안 모델:
   • 기본적으로 tools는 Gateway host에서 실행되어 main session의 경우 에이전트가 호스트 시스템에 대한 전체 접근 권한을 가진다.
   • Group/channel 안전을 위해 agents.defaults.sandbox.mode: "non-main" 설정을 통해 비-main 세션(groups/channels)을 세션별 Docker sandboxes 내에서 실행할 수 있다. 이 경우 bash는 Docker container 내에서 실행된다.
   • sandbox defaults는 bash, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn을 allowlist하고, browser, canvas, nodes, cron, discord, gateway를 denylist한다.
   • 인바운드 DM(Direct Message)은 기본적으로 $dmPolicy="pairing"$으로 설정되어 알 수 없는 발신자에게 pairing code를 전송하고 메시지 처리를 중단한다. 명시적인 승인($clawdbot pairing approve <channel> <code>$)이 필요하다. 공용 DM($dmPolicy="open"$)을 허용하려면 allowlist에 *를 포함해야 한다.

3. 채널 통합:
   • WhatsApp (Baileys), Telegram (grammY), Slack (Bolt), Discord (discord.js), Signal (signal-cli), iMessage (imsg), BlueBubbles, Microsoft Teams, Matrix, Zalo, Zalo Personal, WebChat 등 다양한 메시징 플랫폼 API를 통해 연동된다. 각 채널은 allowlist, group policy, token 등의 전용 설정을 가진다.

4. 도구 및 자동화:
   • Browser: clawd-관리 Chrome/Chromium을 통한 웹 브라우징 및 상호작용.
   • Canvas: A2UI를 사용한 시각적 작업 공간.
   • Nodes: 카메라, 화면 녹화, 위치 정보, 시스템 명령어(system.run, system.notify) 등 장치별 기능 접근.
   • Cron + wakeups: 스케줄링된 작업.
   • Webhooks: 외부 서비스 트리거.
   • Gmail Pub/Sub: 이메일 이벤트 트리거.
   • Skills platform: bundled, managed, workspace skills를 지원하며 install gating과 UI를 포함한다. ClawdHub를 통해 skill registry를 제공하여 에이전트가 필요에 따라 skills를 검색하고 설치할 수 있다.

5. 에이전트 워크스페이스 및 스킬:
   • Workspace root는 기본적으로 ~/clawd이며 agents.defaults.workspace를 통해 구성 가능하다.
   • AGENTS.md, SOUL.md, TOOLS.md와 같은 프롬프트 파일이 주입되어 에이전트의 동작과 기능을 정의한다.
   • Skills는 ~/clawd/skills/<skill>/SKILL.md 경로에 위치하며, ClawdHub를 통해 관리될 수 있다.

6. 에이전트 간(Agent to Agent) 통신:
   • sessions_list: 활성 세션 및 메타데이터 검색.
   • sessions_history: 특정 세션의 transcript logs 가져오기.
   • sessions_send: 다른 세션으로 메시지 전송.

설치 및 배포:
Clawdbot은 npm install -g clawdbot@latest 명령어를 통해 전역적으로 설치할 수 있으며, clawdbot onboard 명령어로 gateway, workspace, channels, skills 설정을 위한 CLI wizard를 실행하는 것이 권장된다. macOS, Linux, Windows(WSL2 권장)에서 작동하며 npm, pnpm, bun을 지원한다. Docker 및 Nix 기반 설치도 가능하다.

CLI 명령어:

• clawdbot onboard --install-daemon: 게이트웨이 데몬 설치 및 설정 마법사 실행.
• clawdbot gateway --port 18789 --verbose: 특정 포트에서 게이트웨이 시작.
• clawdbot message send --to +1234567890 --message "Hello from Clawdbot": 메시지 전송.
• clawdbot agent --message "Ship checklist" --thinking high: 어시스턴트와 상호작용.

이 프로젝트는 $Node.js >= 22$ 런타임을 필요로 하며, Anthropic의 Claude Pro/Max 모델(특히 Opus 4.5)을 long-context strength 및 prompt-injection resistance 측면에서 강력히 권장한다.