# 🦞 Clawdbot 핵심 가이드

> **버전:** v2026.1.25

---

[GitHub - clawdbot/clawdbot: Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞](https://github.com/clawdbot/clawdbot)

## 📋 목차

1. [Clawdbot이란?](https://#1-clawdbot%EC%9D%B4%EB%9E%80)

2. [빠른 시작](https://#2-%EB%B9%A0%EB%A5%B8-%EC%8B%9C%EC%9E%91)

3. [아키텍처](https://#3-%EC%95%84%ED%82%A4%ED%85%8D%EC%B2%98)

4. [채널 설정](https://#4-%EC%B1%84%EB%84%90-%EC%84%A4%EC%A0%95)

5. [에이전트 설정](https://#5-%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8-%EC%84%A4%EC%A0%95)

6. [도구 사용](https://#6-%EB%8F%84%EA%B5%AC-%EC%82%AC%EC%9A%A9)

7. [보안 설정](https://#7-%EB%B3%B4%EC%95%88-%EC%84%A4%EC%A0%95)

8. [자주 사용 팁](https://#8-%EC%9E%90%EC%A3%BC-%EC%82%AC%EC%9A%A9-%ED%8C%81)

---

## 1. Clawdbot이란?

**Clawdbot**은 여러 메신저에서 사용할 수 있는 개인용 AI 어시스턴트입니다.

### 핵심 특징

- ✅ **로컬 우선**: 모든 데이터가 사용자 장치에 저장

- ✅ **다중 채널**: WhatsApp, Telegram, Slack, Discord 등 13개 이상 지원

- ✅ **단일 제어 평면**: WebSocket Gateway (기본 포트 18789)

- ✅ **다중 에이전트**: 채널/계정별 세션 격리

### 기술 스택

- Node.js 22+

- TypeScript

- Pi Agent Runtime (pi-mono 기반)

- WebSocket 프로토콜

---

## 2. 빠른 시작

### 설치

```javascript
# 글로벌 설치
npm install -g clawdbot@latest

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

### 온보딩

```javascript
# 온보딩 실행 (최초 1회)
clawdbot onboard --install-daemon

# 포함 내용:
# - Gateway 설정
# - 에이전트 설정
# - 채널 로그인
# - 워크스페이스 설정
```

### 첫 사용

```javascript
# Gateway 시작
clawdbot gateway

# 상태 확인
clawdbot status

# 메시지 전송
clawdbot send --to whatsapp:+1234567890 --message "안녕하세요!"
```

---

## 3. 아키텍처

### 구조

```javascript
메시징 채널 → Gateway (WS:18789) → Pi Agent → 도구
     ↓                                    ↓
  제어 평면                         브라우저, Canvas, 노드
```

### 핵심 컴포넌트

1. **Gateway Daemon**: 모든 연결 관리

2. **Pi Agent Runtime**: AI 추론 엔진

3. **메시징 채널**: WhatsApp, Telegram, Slack, Discord 등

4. **도구 시스템**: 브라우저, Canvas, 노드, 크론

---

## 4. 채널 설정

### 채널 목록

| 채널 | 설치 명령 | 기능 |
| --- | --- | --- |
| **WhatsApp** | `channels login whatsapp` | 개인 DM, 그룹, 미디어 |
| **Telegram** | `channels login telegram` | DM, 그룹, 봇 명령어 |
| **Slack** | `channels login slack` | 워크스페이스, DM, 채팅 |
| **Discord** | `channels login discord` | 서버, 채널, DM, 리액션 |
| **Google Chat** | `channels login googlechat` | 스페이스, DM, 미디어 |
| **Signal** | `channels login signal` | DM, 그룹, 미디어 |
| **iMessage** | `channels login imessage` | DM, 그룹, 미디어 (macOS) |

### 그룹 채팅 설정

```javascript
# 멘션 모드 (기본)
clawdbot config set channels.telegram.groupPolicy.mode mention

# 항상 응답
clawdbot config set channels.telegram.groupPolicy.mode always
```

### DM 정책

```javascript
# 페어링 모드 (기본)
clawdbot config set channels.whatsapp.dmPolicy pairing

# 오픈 모드 (모두 허용)
clawdbot config set channels.whatsapp.dmPolicy open
```

---

## 5. 에이전트 설정

### 모델 선택

```javascript
# Anthropic Claude Opus 4.5 (권장 - 긴 컨텍스트)
clawdbot config set agent.model "anthropic/claude-opus-4-5"

# Anthropic Claude Sonnet 4.5 (빠른 응답)
clawdbot config set agent.model "anthropic/claude-sonnet-4-5"

# OpenAI GPT-5.1 (코드 생성)
clawdbot config set agent.model "openai/gpt-5.1"

# Local (Ollama)
clawdbot config set agent.model "ollama/llama3"
```

### 사고 레벨

```javascript
# 높음 (복잡한 작업 권장)
clawdbot config set agent.thinkingLevel high

# 중간 (일반 작업)
clawdbot config set agent.thinkingLevel medium

# 낮음 (빠른 응답)
clawdbot config set agent.thinkingLevel low
```

### 워크스페이스

```javascript
# 기본 워크스페이스
~/clawd/

# 다중 워크스페이스
clawdbot agents add personal --workspace ~/clawd-personal

# 워크스페이스 바인딩
clawdbot config set agents.bindings.whatsapp:+1234567890 personal
```

---

## 6. 도구 사용

### 브라우저 도구

에이전트가 웹 브라우저를 자동화합니다.

```javascript
예시 사용:
"Chrome에서 example.com 열어서 스크린샷 찍아줘"
```

### Canvas/A2UI

에이전트가 HTML/React 캔버스를 생성할 수 있습니다.

```javascript
예시 사용:
"데이터 시각화 차트를 만들어줘"
"요약 대시보드를 생성해줘"
```

### 노드 도구

macOS/iOS/Android 노드에서 하드웨어 기능 제공:

- **camera.snap**: 사진 캡처

- **screen.record**: 화면 녹화

- **location.get**: 현재 위치

```javascript
예시 사용:
"지금 내 위치를 알려줘"
"화면을 녹화해줘"
```

### 크론 & 웹훅

주기적 작업 자동화 및 외부 트리거.

```javascript
예시 사용:
"매일 아침 9시에 일정을 정리해줘"
"API 호출 시 알림을 보내줘"
```

---

## 7. 보안 설정

### DM 페어링 (기본)

새로운 DM 연결자 승인 필요.

```javascript
# 페어링 승인
clawdbot pairing approve whatsapp <code>

# 오픈 모드 변경
clawdbot config set channels.whatsapp.dmPolicy open
```

### 샌드박스

비-main 세션(그룹, 공개 DM)에서 코드 실행 제한.

```javascript
# 샌드박스 모드
clawdbot config set sandbox.mode non-main

# 샌드박스 비활성화
clawdbot config set sandbox.mode none
```

### 인증

```javascript
# 비밀번호 인증
clawdbot config set gateway.auth.mode password

# 토큰 인증
clawdbot config set gateway.auth.mode token
```

---

## 8. 자주 사용 팁

### 빠른 시작 팁

```javascript
# 상태 빠르게 확인
clawdbot status --simple

# 채널만 탐색
clawdbot status --channels

# 로그 실시간 확인
clawdbot logs gateway --follow
```

### 문제 해결 팁

| 문제 | 해결책 |
| --- | --- |
| **Gateway 시작 안 됨** | `lsof -ti:18789`로 충돌 확인 후 종료 |
| **채널 연결 실패** | `~/.clawdbot/credentials/` 삭제 후 재로그인 |
| **메시지 전송 안 됨** | DM 페어링 승인 필요 |
| **응답 없음** | API 키 확인, 모델 확인 |

### 효율 팁

- ✅ **사고 레벨 적절하게 설정**: `low`는 빠른 응답, `high`는 복잡한 작업

- ✅ **세션 컴팩션 사용**: 필요 없는 세션 종료

- ✅ **메모리 관리**: 오래된 세션 정리 (`clawdbot memory compact`)

- ✅ **로그 필터링**: 오류만 확인 (`clawdbot logs gateway | grep error`)

---

## 🔍 빠른 레퍼런스

| 주제 | 명령어 |
| --- | --- |
| **상태 확인** | `clawdbot status` |
| **설정 조회** | `clawdbot config get <key>` |
| **설정 변경** | `clawdbot config set <key> <value>` |
| **채널 로그인** | `clawdbot channels login <channel>` |
| **메시지 전송** | `clawdbot send --to <recipient> --message "<msg>"` |
| **로그 확인** | `clawdbot logs gateway --tail 50` |
| **문제 해결** | `clawdbot doctor` |

---

## 📖 추가 자료

### 공식 문서

- 📖 [메인 문서](https://docs.clawd.bot)

- 🏗 [아키텍처](https://docs.clawd.bot/concepts/architecture)

- 🚪 [채널 가이드](https://docs.clawd.bot/channels)

### 커뮤니티

- 💬 [Discord](https://discord.gg/clawd)

- 🐙 [GitHub](https://github.com/clawdbot/clawdbot)

- 🌐 [웹사이트](https://clawdbot.com)

---

**작성일:** 2026년 1월 26일
**버전:** v2026.1.25

[https://slashpage.com/techkwon/3p4kj92yp8p6vm57q1x8](https://slashpage.com/techkwon/3p4kj92yp8p6vm57q1x8)

[https://slashpage.com/techkwon/n5w9812gkzkqn24kpgze](https://slashpage.com/techkwon/n5w9812gkzkqn24kpgze)

[https://slashpage.com/techkwon/n8pw9x2zegej8mg7yrqv](https://slashpage.com/techkwon/n8pw9x2zegej8mg7yrqv)

[https://slashpage.com/techkwon/93nzyxmdvzvj6mwk6r45](https://slashpage.com/techkwon/93nzyxmdvzvj6mwk6r45)

[https://slashpage.com/techkwon/xjqy1g2v989pym6vd54z](https://slashpage.com/techkwon/xjqy1g2v989pym6vd54z)

[https://slashpage.com/techkwon/ywk9j7297k7y52gpqvnd](https://slashpage.com/techkwon/ywk9j7297k7y52gpqvnd)

[https://slashpage.com/techkwon/qpv5x4277j7vx2kyn3dw](https://slashpage.com/techkwon/qpv5x4277j7vx2kyn3dw)

[https://slashpage.com/techkwon/d367nxm3858w82j98pv1](https://slashpage.com/techkwon/d367nxm3858w82j98pv1)

[https://slashpage.com/techkwon/qrx6zk258e81vmv314y5](https://slashpage.com/techkwon/qrx6zk258e81vmv314y5)

[https://slashpage.com/techkwon/1q3vdn2pxrx112xy49pr](https://slashpage.com/techkwon/1q3vdn2pxrx112xy49pr)

[https://slashpage.com/techkwon/dk58wg2eg9gr92nqevxz](https://slashpage.com/techkwon/dk58wg2eg9gr92nqevxz)

[https://slashpage.com/techkwon/dwy5rvmjp4p6vmp46zn9](https://slashpage.com/techkwon/dwy5rvmjp4p6vmp46zn9)

[https://slashpage.com/techkwon/4z7pvx2ke5e3v2ek8653](https://slashpage.com/techkwon/4z7pvx2ke5e3v2ek8653)

[https://slashpage.com/techkwon/y9e1xp2x58567m7k35vz](https://slashpage.com/techkwon/y9e1xp2x58567m7k35vz)

[https://slashpage.com/techkwon/5r398nmnx6x1pmvwje7y](https://slashpage.com/techkwon/5r398nmnx6x1pmvwje7y)

[https://slashpage.com/techkwon/7vgjr4m1q9q1wmdwpy86](https://slashpage.com/techkwon/7vgjr4m1q9q1wmdwpy86)

[https://slashpage.com/techkwon/36nj8v2wq8qe625ykq9z](https://slashpage.com/techkwon/36nj8v2wq8qe625ykq9z)

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