채널 (Channels)

공식 문서: https://code.claude.com/docs/ko/channels

채널이란?

채널(Channels)은 외부 메시징 시스템(텔레그램, 디스코드, iMessage 등)에서 실행 중인 Claude Code 세션으로 메시지를 보내고, Claude의 응답을 다시 받을 수 있는 양방향 브릿지(Bridge, 다리 역할) 기능입니다.

예를 들어, 텔레그램에서 "빌드 상태 확인해줘"라고 메시지를 보내면, 로컬에서 실행 중인 Claude Code가 빌드 상태를 확인한 뒤 텔레그램으로 답변을 보냅니다.

연구 프리뷰

이 기능은 현재 연구 프리뷰(Research Preview) 단계입니다. 문법이나 프로토콜이 변경될 수 있습니다.

채널 연동 구조

채널 연동 구조 — Claude Desktop 중심 양방향 브릿지

✈️

봇 토큰

🎮

Discord

봇 DM

💬

iMessage

macOS 메시지

메시지 →

← 응답

🤖

Claude Desktop

MCP 채널 브릿지

로컬 실행

메시지 →

← 응답

🧪

Fakechat

테스트용 UI

⚙️

커스텀 채널

웹훅 직접 구현

🔗

CI/CD 봇

빌드 알림 연동

모든 채널은 MCP claude/channel capability 기반 | 세션이 열려 있을 때만 수신 가능

스케줄과의 차이

구분	채널	스케줄(/loop)
방식	푸시(Push) 기반 — 이벤트 발생 시 즉시 도착	폴링(Poll) 기반 — 주기적으로 확인
트리거	외부 메시지/알림	시간 간격
용도	메시지 대화, 알림 반응	상태 확인, 반복 작업
응답	외부 플랫폼으로 답변 전송	터미널에 결과 표시

지원 채널

채널	설명	필요한 것
텔레그램(Telegram)	텔레그램 봇을 통해 대화	봇 토큰 (BotFather)
디스코드(Discord)	디스코드 봇의 DM으로 대화	봇 토큰 (Developer Portal)
iMessage	macOS의 메시지 앱으로 대화	macOS + 전체 디스크 접근 권한
Fakechat (데모)	테스트용 로컬 웹 UI	없음 (개발용)
커스텀	직접 웹훅 수신기 구현	개발 필요

요구사항

Claude Code v2.1.80 이상
claude.ai 로그인 (API 키나 Console 토큰 불가)
Bun 설치 (사전 빌드된 플러그인 실행용)
Team/Enterprise: 관리자가 channelsEnabled 설정 활성화 필요

MCP 푸시 메시지 (`claude/channel`)

채널은 내부적으로 MCP(Model Context Protocol)의 claude/channel capability를 사용합니다. MCP 서버가 이 capability를 구현하면 외부에서 세션 안으로 메시지를 푸시할 수 있습니다.

동작 구조

외부 메시징 플랫폼 (텔레그램, 디스코드 등)
       │
       ▼
  MCP 서버 (채널 플러그인)
       │  claude/channel capability
       ▼
  Claude Code 세션 ──→ 응답 생성 ──→ MCP 서버 ──→ 외부 플랫폼

플러그인이 채널 제공자가 되는 과정

플러그인이 MCP 서버로 등록될 때 claude/channel capability를 선언
Claude Code가 --channels 플래그로 해당 플러그인을 로드
플러그인이 외부 메시지를 수신하면 MCP 프로토콜을 통해 세션에 전달
세션이 응답을 생성하면 플러그인이 다시 외부 플랫폼으로 전송

커스텀 채널 개발

공식 플러그인(telegram, discord, imessage, fakechat) 외에 직접 MCP 서버를 구현하여 커스텀 채널을 만들 수 있습니다. fakechat 플러그인의 소스 코드를 참고하면 구조를 이해하기 쉽습니다.

텔레그램 설정

1단계: 봇 생성

텔레그램에서 @BotFather에게 메시지를 보내 봇을 생성합니다:

/newbot
# 봇 이름과 사용자명을 입력하면 토큰이 발급됩니다

2단계: 플러그인 설치 및 설정

# Claude Code 세션에서
/plugin install telegram@claude-plugins-official
/telegram:configure <봇_토큰>

3단계: 채널과 함께 시작

세션을 종료한 후 채널을 활성화하여 다시 시작합니다:

claude --channels plugin:telegram@claude-plugins-official

4단계: 페어링

텔레그램에서 봇에게 아무 메시지를 보냅니다
터미널에 나타나는 페어링 코드를 확인합니다
Claude Code에서 페어링합니다:

/telegram:access pair <페어링_코드>

접근을 허용 목록(Allowlist)으로 잠급니다:

/telegram:access policy allowlist

디스코드 설정

1단계: 봇 생성

Discord Developer Portal에서 앱 생성
Bot 섹션에서 Message Content Intent 활성화
서버에 봇 초대 (적절한 권한 부여)

2단계: 플러그인 설치 및 설정

/plugin install discord@claude-plugins-official
/discord:configure <봇_토큰>

3단계: 채널과 함께 시작

claude --channels plugin:discord@claude-plugins-official

4단계: 페어링

디스코드에서 봇에게 DM을 보냅니다
페어링 코드를 확인하고 Claude Code에서 실행:

/discord:access pair <페어링_코드>
/discord:access policy allowlist

iMessage 설정

1단계: 권한 설정

macOS 시스템 설정 > 개인 정보 보호 및 보안 > 전체 디스크 접근에서 터미널 앱에 권한을 부여합니다.

2단계: 플러그인 설치

/plugin install imessage@claude-plugins-official

3단계: 채널과 함께 시작

claude --channels plugin:imessage@claude-plugins-official

4단계: 사용

자신에게 iMessage를 보내면 Claude가 자동으로 응답합니다. 다른 연락처를 허용하려면:

/imessage:access allow +821012345678

멀티 채널 설정

여러 채널을 동시에 사용할 수 있습니다. --channels 플래그에 쉼표로 구분하여 여러 플러그인을 지정합니다:

# 텔레그램 + 디스코드 동시 사용
claude --channels plugin:telegram@claude-plugins-official,plugin:discord@claude-plugins-official

멀티 채널 활용 시나리오

조합	활용 사례
텔레그램 + 디스코드	개인 알림은 텔레그램, 팀 Q&A는 디스코드
iMessage + 텔레그램	Mac에서는 iMessage, 외출 시 텔레그램
텔레그램 + Fakechat	프로덕션 텔레그램 + 디버깅용 Fakechat

멀티 채널 주의사항

모든 채널에서 수신된 메시지가 같은 세션에서 처리됩니다
한 채널에서 온 메시지를 처리하는 동안 다른 채널의 메시지는 **대기열(Queue)**에 쌓입니다
채널 수가 많아지면 응답 지연이 발생할 수 있습니다

실전 활용: CI/CD 알림 봇 구성

텔레그램으로 빌드 실패 알림을 받고, Claude가 자동으로 원인을 분석하는 워크플로우입니다.

전체 구성

GitHub Actions (빌드 실패)
       │
       ▼
텔레그램 봇 ──→ Claude Code 세션 ──→ 로그 분석 + 수정 제안
       │                                      │
       ▼                                      ▼
📱 텔레그램으로 결과 수신            자동 커밋 + PR 생성

설정 순서

1. 텔레그램 봇 설정 (위의 텔레그램 설정 참고)

2. GitHub Actions에서 빌드 실패 시 텔레그램 알림 전송

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test
      - name: 빌드 실패 시 텔레그램 알림
        if: failure()
        run: |
          curl -s -X POST "https://api.telegram.org/bot${{ secrets.TELEGRAM_BOT_TOKEN }}/sendMessage" \
            -d chat_id=${{ secrets.TELEGRAM_CHAT_ID }} \
            -d text="빌드 실패: ${{ github.repository }}@${{ github.sha }}%0A브랜치: ${{ github.ref_name }}%0A로그: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"

3. Claude Code 세션을 채널과 함께 시작

claude --channels plugin:telegram@claude-plugins-official \
  --dangerously-skip-permissions

4. 시스템 프롬프트 설정 (.claude/CLAUDE.md)

## CI/CD 알림 봇 역할
- 텔레그램에서 빌드 실패 알림이 오면:
  1. GitHub Actions 로그를 확인
  2. 실패 원인을 분석
  3. 수정 가능하면 코드를 수정하고 PR 생성
  4. 결과를 텔레그램으로 보고

실전 활용: 팀 디스코드 봇으로 코드 질문 받기

팀원들이 디스코드에서 코드 관련 질문을 하면 Claude가 프로젝트 컨텍스트를 바탕으로 답변합니다.

설정 순서

1. 디스코드 봇 생성 및 서버 초대 (위의 디스코드 설정 참고)

2. 팀원 허용 목록 등록

# 각 팀원을 페어링
/discord:access pair <팀원1_페어링_코드>
/discord:access pair <팀원2_페어링_코드>

# allowlist 정책 적용
/discord:access policy allowlist

3. 프로젝트 루트에서 채널 시작

cd /path/to/project
claude --channels plugin:discord@claude-plugins-official

4. 팀원 사용 예시 (디스코드 DM)

팀원: "UserService의 캐시 전략이 어떻게 되어 있어?"
Claude: "UserService는 Redis 기반 캐시를 사용합니다. 
        src/services/UserService.ts:45에서 TTL 300초로 설정되어 있고,
        캐시 키 패턴은 `user:{id}` 형태입니다..."

팀원: "getUser 함수에서 null 체크가 빠진 것 같아. 수정해줘"
Claude: "확인했습니다. src/services/UserService.ts:52에서 
        user가 null일 때 처리가 없었습니다. 수정하고 PR을 생성했습니다.
        PR #87: https://github.com/team/project/pull/87"

비용 고려사항

채널을 통해 들어오는 메시지는 일반 Claude Code 세션과 동일하게 토큰을 소비합니다.

항목	비용 영향
수신 메시지당	메시지 길이 + 프로젝트 컨텍스트 크기에 비례
응답 생성	일반 Claude Code 응답과 동일
도구 사용	파일 읽기, 명령 실행 등 추가 토큰 소비
세션 유지	세션 자체는 비용 없음 (메시지 처리 시에만)

비용 절감 팁

불필요한 알림은 외부 플랫폼에서 필터링한 후 전달
자주 묻는 질문은 .claude/CLAUDE.md에 정리하여 컨텍스트 크기 절감
대량 알림이 예상되면 스케줄(/loop)로 일괄 처리하는 것이 더 효율적

Rate Limiting (속도 제한)

채널을 통한 메시지에는 암묵적인 속도 제한이 적용됩니다:

제한 유형	동작
메시지 큐잉	메시지 처리 중 새 메시지가 오면 대기열에 추가
순차 처리	한 번에 하나의 메시지만 처리 (병렬 처리 없음)
권한 프롬프트 차단	권한 승인이 필요하면 세션이 일시 중단
API Rate Limit	Claude API 자체의 분당/시간당 토큰 제한 적용

무인 운영 시 Rate Limit

--dangerously-skip-permissions 없이 실행하면 권한 프롬프트에서 세션이 멈춥니다. 무인 운영 시에는 이 플래그를 사용하거나 .claude/settings.json에서 필요한 도구를 미리 허용하세요.

보안 모델

보안 장치	설명
허용 목록(Allowlist)	승인된 사용자만 메시지 전송 가능
페어링 과정	텔레그램/디스코드는 코드 기반 본인 확인
iMessage 보호	기본적으로 자기 자신에게만 보낸 메시지만 처리
조직 제어	Team/Enterprise에서 `allowedChannelPlugins` 설정으로 관리

다른 원격 기능과 비교

항목	채널	원격 제어	디스패치
방향	외부 → Claude 세션	웹/모바일 → 로컬 세션	모바일 → 데스크탑
트리거	외부 메시지	사용자 직접 조작	작업 요청
플랫폼	텔레그램, 디스코드 등	claude.ai/code	Claude 모바일 앱
양방향	응답 전송	실시간 대화	결과 알림

Channels vs 다른 외부 연결 방법 비교

Claude에 외부에서 연결하는 방법이 여러 가지 있습니다. 핵심 차이를 정리하면 다음과 같습니다.

기능	트리거	방향	핵심 차이
Channels	외부 메시지 수신	양방향 (메시지↔Claude)	메시징 앱에서 Claude와 대화
Dispatch	사용자가 폰에서 직접 요청	단방향 (요청→실행)	작업을 맡기고 결과만 받기
Schedule	시간 기반 자동 실행	단방향 (시간→실행)	반복 작업 자동화
Remote Control	사용자가 브라우저에서 접속	양방향 (세션 공유)	기존 세션을 다른 기기에서 이어보기
MCP Push	서버 이벤트 발생	단방향 (서버→Claude)	외부 시스템 변경 시 자동 반응

한 줄 비유로 기억하기

Channels = 메시징 앱이 Claude의 '입'과 '귀'가 되는 것. Dispatch = 명령만 전달하는 '전보'. Remote Control = 화면을 공유하는 '원격 데스크탑'.

연계 기능

🔗 채널과 함께 사용하면 강력한 기능들

📤 디스패치(Dispatch)

채널이 외부 메시징 플랫폼을 통해 작업을 전달한다면, 디스패치는 Claude 모바일 앱에서 직접 작업을 지시합니다. 두 기능을 조합하면 다양한 경로로 Claude에게 작업을 보낼 수 있습니다.

디스패치 문서 보기 →

⏰ 스케줄(Schedule)

채널이 이벤트 발생 즉시 반응하는 푸시 방식이라면, 스케줄은 시간 간격으로 반복 실행하는 폴링 방식입니다. 긴급 알림에는 채널을, 정기 점검에는 스케줄을 함께 운영하세요.

스케줄 문서 보기 →

🔌 MCP

채널은 MCP의 claude/channel capability를 활용합니다. MCP 서버를 직접 구현하면 슬랙, 위챗 등 공식 지원하지 않는 플랫폼도 커스텀 채널로 연결할 수 있습니다.

MCP 문서 보기 →

장점, 단점과 한계점

장점

외부 메시징 통합: 텔레그램, 디스코드, iMessage 등 기존에 사용하던 메시징 플랫폼에서 직접 Claude Code 세션과 소통할 수 있습니다
양방향 대화: 외부에서 메시지를 보내면 Claude가 처리하고 결과를 같은 플랫폼으로 되돌려 보내는 완전한 양방향 브릿지를 제공합니다
팀 채널 활용: 디스코드 서버에서 팀원들이 프로젝트 컨텍스트를 기반으로 코드 질문을 하고 즉시 답변받을 수 있습니다
알림 자동화: CI/CD 파이프라인과 연동하여 빌드 실패 시 자동으로 원인 분석 및 수정 제안을 받을 수 있습니다

단점과 한계점

연구 프리뷰 단계: 아직 정식 기능이 아니므로 문법이나 프로토콜이 향후 변경될 수 있습니다
Bun 필수 설치: 플러그인 실행에 Bun 런타임이 필요하며, 기존에 Node.js만 사용하던 환경에서는 추가 설치가 필요합니다
세션 열려있을 때만 수신: Claude Code 세션이 종료되면 메시지를 받을 수 없어, 항상 켜진 상태를 유지해야 합니다
보안 설정 복잡: 페어링 코드 인증, 허용 목록 관리, 접근 정책 설정 등 초기 보안 구성에 여러 단계가 필요합니다
무인 운영 시 위험 플래그 필요: --dangerously-skip-permissions 없이는 권한 프롬프트에서 세션이 멈추므로, 무인 운영에 보안 트레이드오프가 있습니다

활용 팁

항상 켜진 상태가 필요하면 클라우드 세션과 병행하거나, 스케줄로 주기적 배치 처리를 고려하세요. 보안을 유지하면서 무인 운영하려면 .claude/settings.json에서 필요한 도구만 선별적으로 허용하는 것이 --dangerously-skip-permissions보다 안전합니다.

제한사항

세션이 열려 있을 때만 이벤트를 수신합니다
권한 프롬프트가 나타나면 세션이 일시 중단됩니다
무인 운영 시 --dangerously-skip-permissions 플래그가 필요합니다
항상 켜진 상태가 필요하면 클라우드 세션이나 스케줄을 고려하세요

Fakechat (테스트용)

Fakechat은 채널 기능을 로컬에서 테스트하기 위한 데모 채널입니다. 실제 메시징 플랫폼 없이 채널의 동작을 확인할 수 있습니다.

# Fakechat 플러그인 설치
/plugin install fakechat@claude-plugins-official

# Fakechat과 함께 세션 시작
claude --channels plugin:fakechat@claude-plugins-official

로컬 웹 UI가 열리며, 브라우저에서 메시지를 보내 Claude의 응답을 확인할 수 있습니다. 실제 채널 설정 전에 워크플로우를 테스트하는 데 유용합니다.

문제 해결

문제	원인	해결
봇이 메시지에 응답하지 않음	페어링 미완료	페어링 코드 재확인, `/채널:access pair <코드>` 재실행
"Not in allowlist" 에러	허용 목록에 미등록	`/채널:access allow <사용자ID>` 실행
Bun 설치 오류	Bun 미설치	`curl -fsSL https://bun.sh/install \| bash` 실행
채널이 갑자기 끊김	세션 종료 또는 권한 프롬프트	세션 상태 확인, 권한 승인 후 재시작
iMessage가 작동하지 않음	전체 디스크 접근 권한 없음	시스템 설정 > 전체 디스크 접근에서 터미널 허용
여러 사용자가 동시 접근	허용 목록으로 관리 안 함	`policy allowlist`로 접근 제한
멀티 채널 응답 지연	메시지 큐잉으로 순차 처리	채널 수를 줄이거나 별도 세션으로 분리
API Rate Limit 에러	단시간 대량 메시지	외부에서 메시지 빈도 조절, 배치 처리 고려

페어링 과정 상세 (텔레그램 예시)

📱 텔레그램에서 봇에게 "안녕" 메시지 전송
    │
    ▼
🖥️ Claude Code 터미널에 페어링 코드 표시 (예: ABC123)
    │
    ▼
🖥️ /telegram:access pair ABC123 입력
    │
    ▼
페어링 성공 → 이제 텔레그램에서 Claude와 대화 가능
    │
    ▼
🔒 /telegram:access policy allowlist 로 보안 잠금

다음 단계

클라우드 세션 - 클라우드에서 항상 실행
원격 제어 - 웹/모바일에서 세션 제어
기능 비교 - 모든 원격/자동화 기능 한눈에 비교

채널이란?​

채널 연동 구조​

스케줄과의 차이​

지원 채널​

요구사항​

MCP 푸시 메시지 (claude/channel)​

동작 구조​

플러그인이 채널 제공자가 되는 과정​

텔레그램 설정​

1단계: 봇 생성​

2단계: 플러그인 설치 및 설정​

3단계: 채널과 함께 시작​

4단계: 페어링​

디스코드 설정​

1단계: 봇 생성​

2단계: 플러그인 설치 및 설정​

3단계: 채널과 함께 시작​

4단계: 페어링​

iMessage 설정​

1단계: 권한 설정​

2단계: 플러그인 설치​

3단계: 채널과 함께 시작​

4단계: 사용​

멀티 채널 설정​

멀티 채널 활용 시나리오​

실전 활용: CI/CD 알림 봇 구성​

전체 구성​

설정 순서​

실전 활용: 팀 디스코드 봇으로 코드 질문 받기​

설정 순서​

비용 고려사항​

Rate Limiting (속도 제한)​

보안 모델​

다른 원격 기능과 비교​

Channels vs 다른 외부 연결 방법 비교​

연계 기능​

장점, 단점과 한계점​

장점​

단점과 한계점​

제한사항​

Fakechat (테스트용)​

문제 해결​

페어링 과정 상세 (텔레그램 예시)​

다음 단계​

채널이란?

채널 연동 구조

스케줄과의 차이

지원 채널

요구사항

MCP 푸시 메시지 (`claude/channel`)

동작 구조

플러그인이 채널 제공자가 되는 과정

텔레그램 설정

1단계: 봇 생성

2단계: 플러그인 설치 및 설정

3단계: 채널과 함께 시작

4단계: 페어링

디스코드 설정

1단계: 봇 생성

2단계: 플러그인 설치 및 설정

3단계: 채널과 함께 시작

4단계: 페어링

iMessage 설정

1단계: 권한 설정

2단계: 플러그인 설치

3단계: 채널과 함께 시작

4단계: 사용

멀티 채널 설정

멀티 채널 활용 시나리오

실전 활용: CI/CD 알림 봇 구성

전체 구성

설정 순서

실전 활용: 팀 디스코드 봇으로 코드 질문 받기

설정 순서

비용 고려사항

Rate Limiting (속도 제한)

보안 모델

다른 원격 기능과 비교

Channels vs 다른 외부 연결 방법 비교

연계 기능

장점, 단점과 한계점

장점

단점과 한계점

제한사항

Fakechat (테스트용)

문제 해결

페어링 과정 상세 (텔레그램 예시)

다음 단계