# 채널 시스템 개요

> Clawdbot은 13개 이상의 메신저 플랫폼을 통합합니다.

---

## 📱 지원 채널

| 채널 | 라이브러리 | 위치 | 연결 방식 | 기능 |
| --- | --- | --- | --- | --- |
| **WhatsApp** | Baileys | `/src/whatsapp/` | 웹 소켓 | 개인 DM, 그룹 채팅, 미디어 |
| **Telegram** | grammY | `/src/telegram/` | Bot API | DM, 그룹, 봇 명령어, 리플 |
| **Slack** | Bolt | `/src/slack/` | Bot API | 워크스페이스, DM, 채팅, 슬래시 |
| **Discord** | discord.js | `/src/discord/` | Bot API | 서버, 채널, DM, 리액션 |
| **Google Chat** | Chat API | `/src/googlechat/` | OAuth | 스페이스, DM, 미디어 |
| **Signal** | signal-cli RPC | `/src/signal/` | RPC | DM, 그룹, 미디어 |
| **iMessage** | imsg RPC | `/src/imessage/` | RPC (BlueBubbles) | DM, 그룹, 미디어 |
| **BlueBubbles** | WebSocket | `/extensions/bluebubbles/` | WebSocket | iMessage 통합 (macOS) |
| **Microsoft Teams** | Bot Framework | `/extensions/msteams/` | Bot API | 팀, 채널, DM |
| **Matrix** | Client API | `/extensions/matrix/` | Client API | 룸, DM, 미디어 |
| **Zalo** | Bot SDK | `/extensions/zalo/` | Bot API | DM, 그룹, 미디어 |
| **Zalo Personal** | Client API | `/extensions/zalouser/` | Client API | 개인 계정 |
| **Nextcloud Talk** | Spreed | `/extensions/nextcloud-talk/` | OAuth | 채팅, DM, 미디어 |
| **WebChat** | HTTP API | `/src/web/` | REST API | HTTP 요청으로 채팅 |

---

## 🎨 채널 아키텍처

### 공통 인터페이스

모든 채널이 다음 인터페이스를 구현해야 합니다:

```javascript
// 채널 공통 인터페이스
interface ChannelAdapter {
  // 연결 관리
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  isConnected(): boolean;

  // 메시지 처리
  send(recipient: string, message: Message): Promise<void>;
  onMessage(handler: (msg: InboundMessage) => void): void;

  // 프레즌스
  onPresence(handler: (presence: Presence) => void): void;

  // 기타
  typingIndicator(recipient: string, typing: boolean): void;
}
```

### 메시지 포맷

```javascript
// 공통 메시지 포맷
interface Message {
  text?: string;
  attachments?: Attachment[];
  mentions?: string[];
  replyTo?: MessageId;
  metadata?: Record<string, unknown>;
}

interface Attachment {
  type: 'image' | 'video' | 'audio' | 'file';
  url: string;
  filename?: string;
  mimeType?: string;
}
```

---

## 📱 코어 채널 상세

### 1. WhatsApp (Baileys)

**위치:** `/src/whatsapp/`

**라이브러리:** [Baileys](https://github.com/WhiskeySockets/Baileys)

**기능:**

- ✅ QR 코드 기반 연결

- ✅ 개인 DM 및 그룹 채팅

- ✅ 미디어 전송/수신 (이미지, 비디오, 오디오, 문서)

- ✅ 타이핑 인디케이터

- ✅ 리액션 (👍, ❤️ 등)

- ✅ 멘션 및 리플

**설정 예시:**

```javascript
{
  channels: {
    whatsapp: {
      enabled: true,
      allowFrom: ["+1234567890", "*"],  // "*": 모든 연결 허용
      dmPolicy: "pairing",  // 또는 "open"
      groupPolicy: {
        mode: "mention",  // 또는 "always"
        mentions: ["clawdbot", "@clawdbot"]
      }
    }
  }
}
```

**사용 예시:**

```javascript
# WhatsApp 로그인
clawdbot channels login whatsapp

# QR 코드 가져오기
clawdbot channels login whatsapp --qr-import

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

### 2. Telegram (grammY)

**위치:** `/src/telegram/`

**라이브러리:** [grammY](https://grammy.dev/)

**기능:**

- ✅ Bot API 기반 연결

- ✅ DM 및 그룹 채팅

- ✅ 봇 명령어 (`/start`, `/help` 등)

- ✅ 리플 및 리플 태깅

- ✅ 인라인 키보드

- ✅ 웹훅 및 쿼리

**설정 예시:**

```javascript
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456:ABCDEF1234...",
      groupPolicy: {
        mode: "mention",  // 또는 "always"
        mentions: ["clawdbot_bot", "@clawdbot_bot"]
      }
    }
  }
}
```

**사용 예시:**

```javascript
# Telegram Bot 설정
clawdbot channels login telegram

# 메시지 전송
clawdbot send --to telegram:@username --message "테스트"
```

### 3. Slack (Bolt)

**위치:** `/src/slack/`

**라이브러리:** [@slack/bolt](https://slack.dev/bolt-js)

**기능:**

- ✅ Bot API 기반 연결

- ✅ 워크스페이스 및 채널

- ✅ DM 및 채팅

- ✅ 슬래시 및 블럭 기능

- ✅ 멘션 및 리액션

- ✅ 모달 및 홈탭

**설정 예시:**

```javascript
{
  channels: {
    slack: {
      enabled: true,
      token: "xoxb-1234567890-ABCDEF...",
      dm: {
        policy: "open",  // 또는 "pairing"
        allowFrom: ["U1234567890", "*"]  // "*": 모든 DM 허용
      }
    }
  }
}
```

### 4. Discord (discord.js)

**위치:** `/src/discord/`

**라이브러리:** [discord.js](https://discord.js.org/)

**기능:**

- ✅ Bot API 기반 연결

- ✅ 서버 및 채널

- ✅ DM 및 그룹 채팅

- ✅ 리액션 및 멘션

- ✅ 슬래시 및 커맨드

- ✅ 음성 연결 (선택적)

**설정 예시:**

```javascript
{
  channels: {
    discord: {
      enabled: true,
      token: "MTIyNzE1234...",
      dm: {
        policy: "open",
        allowFrom: ["1234567890123456789", "*"]
      }
    }
  }
}
```

---

## 🔄 그룹 메시지 처리

### 멘션 모드 (Mention Mode)

**동작:** 멘션된 경우에만 응답

**설정:**

```javascript
{
  channels: {
    telegram: {
      groupPolicy: {
        mode: "mention",
        mentions: ["clawdbot_bot", "@clawdbot_bot"]
      }
    }
  }
}
```

**사용 예시:**

```javascript
# 그룹 채팅
User1: 이 데이터를 분석해줘
User2: @clawdbot_bot 이 데이터를 분석해줘

# Clawdbot 응답 (멘션된 경우에만)
Clawdbot: 데이터를 분석하겠습니다...
```

### 항상 모드 (Always Mode)

**동작:** 모든 메시지에 응답

**설정:**

```javascript
{
  channels: {
    telegram: {
      groupPolicy: {
        mode: "always"
      }
    }
  }
}
```

### 리플 태깅

**동작:** 특정 키워드로 답변 리플을 그룹에 전송

**설정:**

```javascript
{
  channels: {
    telegram: {
      replyTag: "[clawdbot]"
    }
  }
}
```

**사용 예시:**

```javascript
# 그룹 채팅
User1: 이 코드를 리뷰해줘

# DM으로 응답
Clawdbot: 리뷰 결과를 DM으로 전송합니다.

# 그룹에 리플 태그 포함
User1: [clawdbot] 코드 리뷰 완료했습니다.
```

---

## 🔗 메시지 라우팅

### 라우팅 결정 요소

1. **채널 식별자**: `whatsapp:+1234567890`, `telegram:@username`, `discord:server:123456789`

2. **계정/피어 식별자**: 채널 내의 고유 ID

3. **세션 바인딩**: 채널/계정 → 워크스페이스 맵핑

**예시:**

```javascript
{
  agents: {
    bindings: {
      // 채널:계정 → 워크스페이스
      "whatsapp:+1234567890": "main",
      "whatsapp:+9876543210": "personal",
      "telegram:@clawdbot_bot": "main",
      "discord:server:123456789": "work",
      "slack:workspace:U1234567890": "main"
    }
  }
}
```

### 라우팅 흐름

```javascript
인바운드 메시지
    │
    ▼
메시징 채널 (WhatsApp, Telegram, ...)
    │
    │ 1. 채널 식별자 추출
    ▼
Gateway (메시지 라우팅)
    │
    │ 2. 바인딩 검색
    │    - agents.bindings[채널:계정]
    ▼
세션 결정
    │
    │ 3. 세션 생성/검색
    ▼
Pi Agent (실행)
```

---

## 🛠 확장 채널

### 채널 어댑터 개발

새로운 채널을 추가하려면 다음 인터페이스를 구현하세요:

```javascript
import type { ChannelAdapter } from './channel-adapter.ts';

// 채널 구현
export class MyChannel implements ChannelAdapter {
  async connect(): Promise<void> {
    // 연결 로직
  }

  async send(recipient: string, message: Message): Promise<void> {
    // 메시지 전송 로직
  }

  onMessage(handler: (msg: InboundMessage) => void): void {
    // 메시지 수신 핸들러 등록
  }

  // ... 기타 메서드
}
```

**자세한 가이드:** [채널 어댑터 예시](https://../examples/channel-adapter.md)

---

## 🔍 상태 확인

```javascript
# 채널 상태 확인
clawdbot status --channels

# 채널 탐색
clawdbot status --probe

# JSON 출력
clawdbot status --json
```

**예시 출력:**

```javascript
{
  "channels": {
    "whatsapp": {
      "status": "connected",
      "username": "+1234567890",
      "uptime": "5h 23m"
    },
    "telegram": {
      "status": "connected",
      "username": "@clawdbot_bot",
      "uptime": "2h 15m"
    },
    "slack": {
      "status": "disconnected",
      "error": "token_expired"
    }
  }
}
```

---

## 🔗 관련 문서

- [WhatsApp 상세](https://whatsapp.md)

- [Telegram 상세](https://telegram.md)

- [Slack 상세](https://slack.md)

- [Discord 상세](https://discord.md)

- [기타 채널](https://others.md)

- [채널 어댑터 개발](https://../examples/channel-adapter.md)

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