채널 시스템 개요

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 요청으로 채팅

🎨 채널 아키텍처

공통 인터페이스

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

// 채널 공통 인터페이스
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;
}

메시지 포맷

// 공통 메시지 포맷
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

기능:

•

✅ QR 코드 기반 연결

•

✅ 개인 DM 및 그룹 채팅

•

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

•

✅ 타이핑 인디케이터

•

✅ 리액션 (👍, ❤️ 등)

•

✅ 멘션 및 리플

설정 예시:

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

사용 예시:

# WhatsApp 로그인
clawdbot channels login whatsapp

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

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

2. Telegram (grammY)

위치: /src/telegram/

라이브러리: grammY

기능:

•

✅ Bot API 기반 연결

•

✅ DM 및 그룹 채팅

•

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

•

✅ 리플 및 리플 태깅

•

✅ 인라인 키보드

•

✅ 웹훅 및 쿼리

설정 예시:

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

사용 예시:

# Telegram Bot 설정
clawdbot channels login telegram

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

3. Slack (Bolt)

위치: /src/slack/

라이브러리: @slack/bolt

기능:

•

✅ Bot API 기반 연결

•

✅ 워크스페이스 및 채널

•

✅ DM 및 채팅

•

✅ 슬래시 및 블럭 기능

•

✅ 멘션 및 리액션

•

✅ 모달 및 홈탭

설정 예시:

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

4. Discord (discord.js)

위치: /src/discord/

라이브러리: discord.js

기능:

•

✅ Bot API 기반 연결

•

✅ 서버 및 채널

•

✅ DM 및 그룹 채팅

•

✅ 리액션 및 멘션

•

✅ 슬래시 및 커맨드

•

✅ 음성 연결 (선택적)

설정 예시:

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

🔄 그룹 메시지 처리

멘션 모드 (Mention Mode)

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

설정:

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

사용 예시:

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

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

항상 모드 (Always Mode)

동작: 모든 메시지에 응답

설정:

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

리플 태깅

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

설정:

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

사용 예시:

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

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

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

🔗 메시지 라우팅

라우팅 결정 요소

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

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

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

예시:

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

라우팅 흐름

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

🛠 확장 채널

채널 어댑터 개발

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

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 {
    // 메시지 수신 핸들러 등록
  }

  // ... 기타 메서드
}

자세한 가이드: 채널 어댑터 예시

🔍 상태 확인

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

# 채널 탐색
clawdbot status --probe

# JSON 출력
clawdbot status --json

예시 출력:

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

🔗 관련 문서

•

•

•

•

•

•