설치 가이드

Clawdbot을 다양한 환경에 설치하는 방법

📋 목록

전제 조건

NPM 설치

🔧 전제 조건

필수 요구사항

요구사항	최소 버전	권장 버전
Node.js	22.12.0	최신 LTS
pnpm	10.23.0	최신 버전
운영체제	macOS 12+, Linux, Windows (WSL2)	최신 버전
메모리	2GB	4GB 이상
디스크 공간	500MB	2GB 이상
Docker (선택적)	20.10+	최신 버전

설치 확인

# Node.js 버전 확인
node --version
# v22.12.0 이상 필요

# pnpm 설치 확인
pnpm --version
# 10.23.0 이상 필요

# npm 설치 확인
npm --version
# 9.0.0 이상 필요

# Docker 설치 확인 (선택적)
docker --version
# 20.10+ 이상 권장

운영체제별 사전 준비

macOS:

# Xcode Command Line Tools 설치
xcode-select --install

# Homebrew 업데이트
brew update
brew upgrade node

# 방화벽 (테스트용)
sudo pfctl -d

Linux:

# 시스템 업데이트
sudo apt update && sudo apt upgrade -y

# 필수 패키지 설치
sudo apt install -y build-essential curl git

# 방화벽 (테스트용)
sudo ufw disable

Windows (WSL2):

# Windows Terminal에서
# wsl --update
# wsl --set-default-version Ubuntu

# Node.js 설치
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

📦 NPM 설치 (권장)

방법 1: 글로벌 설치

# 최신 버전 설치
npm install -g clawdbot@latest

# 또는 pnpm 사용
pnpm add -g clawdbot@latest

# 설치 확인
clawdbot --version

방법 2: 안정 버전 설치

# 특정 버전 설치
npm install -g clawdbot@2026.1.25

# 버전 확인
clawdbot --version

방법 3: 개발 채널 설치

# 베타 채널 설치
npm install -g clawdbot@beta

# 또는 dev 채널
npm install -g clawdbot@dev

설치 경로

플랫폼	설치 경로
macOS	/usr/local/lib/node_modules/clawdbot
Linux	/usr/local/lib/node_modules/clawdbot
Windows	%APPDATA%\npm\node_modules\clawdbot

PATH 확인

# PATH에 포함되어 있는가 확인
which clawdbot

# PATH 확인
echo $PATH

# PATH 추가 (필요시)
# macOS/Linux
export PATH="$HOME/.npm-global/bin:$PATH"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc

# Windows (PowerShell)
$env:PATH += "$env:APPDATA\npm"

🐳 Docker 설치

방법 1: Docker Image 사용

# Docker 이미지 풍
docker pull clawdbot/clawdbot:latest

# 컨테이너 실행
docker run -d \
  --name clawdbot \
  -p 18789:18789 \
  -p 18793:18793 \
  -v ~/.clawdbot:/root/.clawdbot \
  -v ~/clawd:/root/clawd \
  clawdbot/clawdbot:latest

# 로그 확인
docker logs -f clawdbot

# 컨테이너 중지
docker stop clawdbot

# 컨테이너 삭제
docker rm clawdbot

방법 2: Docker Compose 사용

# docker-compose.yml
version: '3.8'

services:
  clawdbot:
    image: clawdbot/clawdbot:latest
    container_name: clawdbot
    ports:
      - "18789:18789"
      - "18793:18793"
    volumes:
      - ~/.clawdbot:/root/.clawdbot
      - ~/clawd:/root/clawd
    restart: unless-stopped
    environment:
      - NODE_ENV=production

# 실행
docker-compose up -d

# 로그 확인
docker-compose logs -f

# 중지
docker-compose down

방법 3: 개발 Docker 빌드

# 이미지 빌드
docker build -t clawdbot:dev .

# 실행
docker run -d \
  --name clawdbot-dev \
  -p 18789:18789 \
  -v $(pwd):/workspace \
  clawdbot:dev

Docker 네트워크

설정	설명
host 모드	호스트 네트워크 사용 (기본)
bridge 모드	Docker 브리지 네트워크 사용
host-network	호스트 네트워크 모드 (Tailscale 등)

# 호스트 네트워크 사용
docker run -d \
  --network host \
  --name clawdbot \
  clawdbot/clawdbot:latest

🔨 소스 빌드

단계 1: 리포지토리 클론

# 리포지토리 클론
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

# 또는 포크
git clone https://github.com/your-username/clawdbot.git
cd clawdbot

단계 2: 의존성 설치

# pnpm 사용 (권장)
pnpm install

# 또는 npm 사용
npm install

# 또는 bun 사용 (빠름)
bun install

단계 3: UI 빌드 (최초 1회)

# UI 빌드
pnpm ui:build

# 또는
npm run ui:build

단계 4: TypeScript 빌드

# TypeScript 컴파일
pnpm build

# 또는
npm run build

# 빌드 확인
ls -la dist/

단계 5: 개발 모드 실행

# 개발 모드로 실행
pnpm dev

# 또는
npm run dev

# Gateway만 실행 (자동 리로드)
pnpm gateway:watch

단계 6: 전역 링크 (선택적)

# 전역 링크 생성
pnpm link

# 사용
clawdbot --version

🔄 백그라운드 서비스

macOS (launchd)

# launchd 서비스 설치
clawdbot onboard --install-daemon

# 또는 수동 설치
sudo cp scripts/com.clawdbot.gateway.plist \
  ~/Library/LaunchAgents/com.clawdbot.gateway.plist

# 서비스 로드
launchctl load ~/Library/LaunchAgents/com.clawdbot.gateway.plist

# 서비스 시작
launchctl start com.clawdbot.gateway

# 상태 확인
launchctl list | grep clawdbot

# 로그 확인
tail -f ~/Library/Logs/clawdbot-gateway.log

# 서비스 중지
launchctl stop com.clawdbot.gateway

# 서비스 언로드
launchctl unload ~/Library/LaunchAgents/com.clawdbot.gateway.plist

launchd 플리스트 예시:

<!-- com.clawdbot.gateway.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.clawdbot.gateway</string>

  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/clawdbot</string>
    <string>gateway</string>
  </array>

  <key>RunAtLoad</key>
  <true/>

  <key>KeepAlive</key>
  <true/>

  <key>StandardOutPath</key>
  <string>~/Library/Logs/clawdbot-gateway.log</string>

  <key>StandardErrorPath</key>
  <string>~/Library/Logs/clawdbot-gateway-error.log</string>
</dict>
</plist>

Linux (systemd)

# systemd 서비스 설치
clawdbot onboard --install-daemon

# 또는 수동 설치
sudo cp scripts/clawdbot-gateway.service \
  /etc/systemd/user/clawdbot-gateway.service

# 서비스 리로드
systemctl --user daemon-reload

# 서비스 활성화
systemctl --user enable clawdbot-gateway.service

# 서비스 시작
systemctl --user start clawdbot-gateway.service

# 상태 확인
systemctl --user status clawdbot-gateway.service

# 로그 확인
journalctl --user -u clawdbot-gateway -f

# 서비스 중지
systemctl --user stop clawdbot-gateway.service

# 서비스 비활성화
systemctl --user disable clawdbot-gateway.service

systemd 서비스 예시:

# clawdbot-gateway.service
[Unit]
Description=Clawdbot Gateway
After=network.target

[Service]
Type=simple
User=%i
ExecStart=/usr/local/bin/clawdbot gateway
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Windows (Scheduled Task)

# PowerShell (관리자 권한)
# 스케줄된 작업 생성

$action = New-ScheduledTaskAction `
  -Execute "C:\Program Files\nodejs\clawdbot.cmd" `
  -Argument "gateway"

$trigger = New-ScheduledTaskTrigger `
  -AtLogon `
  -User $env:USERNAME

Register-ScheduledTask `
  -TaskName "Clawdbot Gateway" `
  -Action $action `
  -Trigger $trigger `
  -RunLevel Highest `
  -Force

🔄 업데이트

버전 확인

# 현재 버전 확인
clawdbot --version

# 최신 버전 확인
npm view clawdbot version

# 또는
curl -s https://registry.npmjs.org/clawdbot | jq -r .version

업데이트 방법 1: NPM

# 전역 패키지 업데이트
npm update -g clawdbot@latest

# 또는 pnpm 사용
pnpm update -g clawdbot@latest

# 확인
clawdbot --version

업데이트 방법 2: 소스에서

# 최신 코드 풍
git pull origin main

# 의존성 업데이트
pnpm install

# 빌드
pnpm build

# 재시작
# 백그라운드 서비스 자동 재시작됨

업데이트 방법 3: Docker

# Docker 이미지 업데이트
docker pull clawdbot/clawdbot:latest

# 컨테이너 중지
docker stop clawdbot

# 컨테이너 삭제
docker rm clawdbot

# 재시작 (새 컨테이너)
docker run -d \
  --name clawdbot \
  -p 18789:18789 \
  -v ~/.clawdbot:/root/.clawdbot \
  -v ~/clawd:/root/clawd \
  clawdbot/clawdbot:latest

🗑 제거

NPM 제거

# 전역 패키지 제거
npm uninstall -g clawdbot

# 또는 pnpm 사용
pnpm remove -g clawdbot

# 확인
which clawdbot
# => 찾을 수 없음

완전 제거

# 1. 백그라운드 서비스 중지
clawdbot gateway stop

# 2. 서비스 제거
launchctl unload ~/Library/LaunchAgents/com.clawdbot.gateway.plist  # macOS
systemctl --user disable --now clawdbot-gateway.service  # Linux

# 3. 데이터 삭제
rm -rf ~/.clawdbot
rm -rf ~/clawd

# 4. 전역 패키지 제거
npm uninstall -g clawdbot

# 5. Docker 제거 (사용했던 경우)
docker stop clawdbot
docker rm clawdbot
docker rmi clawdbot/clawdbot:latest

🔍 설치 후 체크리스트

Gateway가 정상적으로 시작되는가?

clawdbot status로 상태 확인 가능한가?

clawdbot --version으로 버전 확인 가능한가?

백그라운드 서비스가 자동 시작되는가?

로그 파일이 생성되고 있는가?

포트 18789이 열려 있는가?

설치 확인 명령어

# 상태 확인
clawdbot status

# Gateway만 상태
clawdbot status --gateway

# 채널 상태
clawdbot status --channels

# 에이전트 상태
clawdbot status --agent

# 진단
clawdbot doctor

🎯 다음 단계

설치 후 다음 단계를 진행하세요:

온보딩 실행: clawdbot onboard

채널 로그인: clawdbot channels login <channel>

에이전트 설정: clawdbot config set agent.model <model>

첫 메시지 전송: clawdbot send --to <recipient> --message "Hello!"

상태 확인: clawdbot status

🔗 관련 문서

•

•

•

•