# 설치 가이드

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

---

## 📋 목록

1. [전제 조건](https://#%EC%A0%84%EC%A0%9C-%EC%A1%B0%EA%B1%B4)

2. [NPM 설치](https://#npm-%EC%84%A4%EC%B9%98)

3. [Docker 설치](https://#docker-%EC%84%A4%EC%B9%98)

4. [소스 빌드](https://#%EC%86%8C%EC%8A%A4-%EB%B9%8C%EB%93%9C)

5. [백그라운드 서비스](https://#%EB%B0%B1%EA%B7%B8%EB%9D%BC%EC%9A%B4%EB%93%9C-%EC%84%9C%EB%B9%84%EC%8A%A4)

6. [업데이트](https://#%EC%97%85%EB%8D%B0%EC%9D%B4%ED%8A%B8)

7. [제거](https://#%EC%A0%9C%EA%B1%B0)

---

## 🔧 전제 조건

### 필수 요구사항

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

### 설치 확인

```javascript
# 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:**

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

# Homebrew 업데이트
brew update
brew upgrade node

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

**Linux:**

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

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

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

**Windows (WSL2):**

```javascript
# 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: 글로벌 설치

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

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

# 설치 확인
clawdbot --version
```

### 방법 2: 안정 버전 설치

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

# 버전 확인
clawdbot --version
```

### 방법 3: 개발 채널 설치

```javascript
# 베타 채널 설치
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 확인

```javascript
# 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 사용

```javascript
# 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 사용

```javascript
# 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
```

```javascript
# 실행
docker-compose up -d

# 로그 확인
docker-compose logs -f

# 중지
docker-compose down
```

### 방법 3: 개발 Docker 빌드

```javascript
# 이미지 빌드
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 등) |

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

---

## 🔨 소스 빌드

### 단계 1: 리포지토리 클론

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

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

### 단계 2: 의존성 설치

```javascript
# pnpm 사용 (권장)
pnpm install

# 또는 npm 사용
npm install

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

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

```javascript
# UI 빌드
pnpm ui:build

# 또는
npm run ui:build
```

### 단계 4: TypeScript 빌드

```javascript
# TypeScript 컴파일
pnpm build

# 또는
npm run build

# 빌드 확인
ls -la dist/
```

### 단계 5: 개발 모드 실행

```javascript
# 개발 모드로 실행
pnpm dev

# 또는
npm run dev

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

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

```javascript
# 전역 링크 생성
pnpm link

# 사용
clawdbot --version
```

---

## 🔄 백그라운드 서비스

### macOS (launchd)

```javascript
# 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 플리스트 예시:**

```javascript
<!-- 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)

```javascript
# 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 서비스 예시:**

```javascript
# 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)

```javascript
# 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
```

---

## 🔄 업데이트

### 버전 확인

```javascript
# 현재 버전 확인
clawdbot --version

# 최신 버전 확인
npm view clawdbot version

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

### 업데이트 방법 1: NPM

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

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

# 확인
clawdbot --version
```

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

```javascript
# 최신 코드 풍
git pull origin main

# 의존성 업데이트
pnpm install

# 빌드
pnpm build

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

### 업데이트 방법 3: Docker

```javascript
# 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 제거

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

# 또는 pnpm 사용
pnpm remove -g clawdbot

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

### 완전 제거

```javascript
# 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이 열려 있는가?

### 설치 확인 명령어

```javascript
# 상태 확인
clawdbot status

# Gateway만 상태
clawdbot status --gateway

# 채널 상태
clawdbot status --channels

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

# 진단
clawdbot doctor
```

---

## 🎯 다음 단계

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

1. **온보딩 실행**: `clawdbot onboard`

2. **채널 로그인**: `clawdbot channels login <channel>`

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

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

5. **상태 확인**: `clawdbot status`

---

## 🔗 관련 문서

- [빠른 시작](https://../overview/quickstart.md)

- [백그라운드 서비스](https://background-service.md)

- [Docker 배포](https://docker.md)

- [문제 해결](https://../usage/troubleshooting.md)

For the site tree, see the [root Markdown](https://slashpage.com/techkwon.md).