Claude Code Channels 살펴보기: Telegram·Discord로 세션에 이벤트 푸시하기

CI가 터졌습니다. Slack 알림을 보고 터미널로 달려가 Claude Code를 열고, 로그를 붙여넣고, 수정을 요청합니다. 익숙한 루틴이지만, 이 과정에서 사람이 중계자 역할을 하고 있습니다. 알림을 확인하고, 컨텍스트를 전달하고, 세션을 여는 건 전부 수동입니다.

Channels는 이 중계 과정을 없앱니다. Telegram 메시지, Discord 알림, CI 웹훅 같은 외부 이벤트가 실행 중인 Claude Code 세션에 직접 도달하고, Claude가 즉시 반응합니다. 이 글에서는 Research Preview로 공개된 Channels의 개념, 설정 방법, 보안 모델, 그리고 활용 사례를 살펴보겠습니다.

Channels란?

Channels는 MCP(Model Context Protocol) 서버가 외부 시스템의 이벤트를 Claude Code 세션으로 푸시하는 기능입니다. 기존에는 사용자가 터미널에서 직접 프롬프트를 입력해야 Claude가 동작했지만, Channels를 통하면 Telegram DM, Discord 메시지, 모니터링 경고 같은 외부 신호가 프롬프트 역할을 합니다.

핵심 구조는 단순합니다.

단방향(One-way): 외부 이벤트 → Claude 세션 (알림 수신, 자동 처리)
양방향(Two-way): 외부 이벤트 → Claude 세션 → 외부 플랫폼 회신 (대화형)

Claude Code가 “요청을 기다리는 도구”에서 “이벤트에 반응하는 에이전트”로 진화하는 셈입니다.

동작 흐름

아래는 Telegram을 예로 든 양방향 Channels의 메시지 흐름입니다.

sequenceDiagram
    participant U as 사용자 (Telegram)
    participant B as Telegram Bot<br/>(MCP 서버)
    participant C as Claude Code 세션

    U->>B: "CI 실패 로그 분석해줘"
    B->>B: Allowlist 확인
    B->>C: MCP Notification 전송<br/>(content + meta)
    C->>C: 컨텍스트 분석 & 작업 수행
    C->>B: reply 도구 호출<br/>(chat_id, 분석 결과)
    B->>U: "원인: 타입 에러, PR #42 수정 완료"

사용자가 Telegram 봇에 메시지를 보냅니다
MCP 서버가 allowlist를 확인한 뒤, 승인된 사용자의 메시지만 Claude Code 세션에 전달합니다
Claude가 메시지를 분석하고 작업을 수행합니다
양방향 채널이면 reply 도구를 호출해 결과를 Telegram으로 회신합니다

시작하기

요구사항

Claude Code v2.1.80+ (claude update로 업데이트)
Bun 설치 필수 — 각 채널 플러그인이 Bun 런타임을 사용합니다 (bun --version으로 확인)
claude.ai 로그인 필수 (/login) — API 키는 미지원
Research Preview 단계이므로 프로토콜이 변경될 수 있습니다

Channels를 사용하려면 세션 시작 시 --channels 플래그로 사용할 채널을 명시적으로 지정해야 합니다. .mcp.json에 MCP 서버가 등록되어 있더라도, --channels에 이름이 없으면 메시지를 푸시할 수 없습니다.

참고 Channels는 현재 Research Preview입니다. 플래그 문법이나 프로토콜이 변경될 수 있으니, 프로덕션 워크플로우에 적용하기 전에 공식 문서를 확인하세요.

지원 채널

BotFather로 봇을 만들고 플러그인을 설치합니다.

# 1. BotFather에서 /newbot으로 봇 생성 → 토큰 획득

# 2. 플러그인 설치
/plugin install telegram@claude-plugins-official

# 3. 봇 토큰 구성
/telegram:configure <YOUR_BOT_TOKEN>

# 4. Channels 모드로 실행
claude --channels plugin:telegram@claude-plugins-official

실행 후 Telegram에서 봇에 메시지를 보내면 페어링 코드가 반환됩니다. 이 코드로 사용자를 등록합니다.

# 5. 페어링 코드로 사용자 등록
/telegram:access pair <code>

# 6. allowlist 정책 활성화
/telegram:access policy allowlist

이후부터 해당 사용자의 메시지가 Claude Code 세션으로 전달됩니다.

Discord

Discord Developer Portal에서 봇을 생성하고 서버에 초대합니다. **“Message Content Intent”**를 반드시 활성화해야 합니다.

# 1. Discord Developer Portal → Bot → "Message Content Intent" 활성화
# 2. OAuth2 > URL Generator에서 bot 스코프 + 권한 설정
#    (View Channels, Send Messages, Send Messages in Threads,
#     Read Message History, Attach Files, Add Reactions)

# 3. 플러그인 설치
/plugin install discord@claude-plugins-official

# 4. 봇 토큰 구성
/discord:configure <YOUR_BOT_TOKEN>

# 5. Channels 모드로 실행
claude --channels plugin:discord@claude-plugins-official

# 6. 페어링 (Telegram과 동일한 흐름)
/discord:access pair <code>
/discord:access policy allowlist

Fakechat (테스트용)

로컬에서 Channels 동작을 빠르게 확인하고 싶다면 fakechat을 사용합니다. 외부 서비스 설정이 필요 없습니다.

# 플러그인 설치 & 실행
/plugin install fakechat@claude-plugins-official
claude --channels plugin:fakechat@claude-plugins-official

# http://localhost:8787 에서 메시지 전송 가능 (인증 불필요)

Tip 처음 Channels를 시험해본다면 fakechat으로 시작하세요. 외부 서비스 설정 없이 로컬에서 메시지 흐름을 바로 확인할 수 있습니다.

보안 모델

Channels는 외부에서 Claude 세션으로 들어오는 통로이므로, 보안이 핵심입니다. 세 가지 레이어로 접근을 제어합니다.

Sender Allowlist

승인된 사용자만 메시지를 보낼 수 있습니다. allowlist에 없는 사용자의 메시지는 조용히 무시(silence drop)됩니다. Claude에게 도달하지도 않습니다.

Pairing Flow

allowlist에 사용자를 추가하는 과정입니다.

사용자가 봇에 메시지를 보냅니다
봇이 페어링 코드를 반환합니다
Claude Code 세션에서 해당 코드를 승인합니다
사용자의 ID가 allowlist에 추가됩니다

이 과정을 거치지 않으면 아무도 세션에 메시지를 보낼 수 없습니다.

Enterprise 제어

플랜에 따라 Channels 활성화 방식이 다릅니다.

플랜	기본 상태	활성화 방법
Pro / Max (조직 없음)	사용 가능	`--channels` 플래그로 opt-in
Team / Enterprise	비활성화	관리자가 `channelsEnabled: true` 설정 필요

Team/Enterprise 관리자는 claude.ai → Admin settings → Claude Code → Channels에서 조직 전체의 Channels 사용을 제어할 수 있습니다.

주의 Enterprise 환경에서는 관리자가 명시적으로 활성화하지 않으면 Channels를 사용할 수 없습니다. 도입 전에 보안 팀과 협의하세요.

커스텀 채널 만들기

Telegram, Discord 외에 Slack, 웹훅, 자체 모니터링 시스템 등 원하는 소스를 연결하고 싶다면 커스텀 채널을 빌드할 수 있습니다.

기본 요구사항

MCP SDK (@modelcontextprotocol/sdk)
Node.js 호환 런타임 (Node, Bun, Deno)
stdio 연결 (표준 입출력)

핵심 설정

MCP 서버의 capabilities에 채널 리스너를 등록합니다.

{
  "capabilities": {
    "experimental": {
      "claude/channel": {}
    },
    "tools": {}
  }
}

claude/channel이 채널 리스너 등록을 의미하고, tools는 양방향 채널(reply 도구)에 필요합니다.

이벤트 푸시와 Reply

핵심은 세 단계입니다. capability 선언, 이벤트 전송, 그리고 (양방향이라면) reply 도구 정의입니다.

// 1. Capability 선언
const server = new Server({
  capabilities: {
    experimental: { "claude/channel": {} },
    tools: {}, // 양방향 채널만 필요
  },
});

// 2. 이벤트 푸시
await server.notification({
  method: "notifications/claude/channel",
  params: {
    content: "CI 빌드 실패: main 브랜치 #1234",
    meta: { severity: "error", source: "github-actions" },
  },
});

// 3. stdio 연결
await server.connect(new StdioServerTransport());

양방향 채널이라면 Claude가 호출할 reply 도구를 MCP 표준 도구로 정의합니다.

{
  "name": "reply",
  "inputSchema": {
    "type": "object",
    "properties": {
      "chat_id": { "type": "string" },
      "text": { "type": "string" }
    },
    "required": ["chat_id", "text"]
  }
}

예시: 웹훅 리시버

외부 CI 시스템의 POST 요청을 받아 Claude 세션에 전달하는 간단한 예시입니다.

Bun.serve({
  port: 8788,
  hostname: "127.0.0.1",
  async fetch(req) {
    const body = await req.text();
    await server.notification({
      method: "notifications/claude/channel",
      params: {
        content: body,
        meta: {
          path: new URL(req.url).pathname,
          method: req.method,
        },
      },
    });
    return new Response("ok");
  },
});

이렇게 만든 채널은 --dangerously-load-development-channels 플래그로 테스트합니다.

# 커스텀 서버
claude --dangerously-load-development-channels server:webhook

# 개발 중인 플러그인
claude --dangerously-load-development-channels plugin:yourplugin@marketplace

Tip 커스텀 채널 빌드에 대한 자세한 내용은 Channels Reference를 참고하세요.

항목	Channels	Remote Control	Scheduled Tasks
용도	외부 이벤트 수신 & 반응	어디서나 세션 제어	정기 실행 (폴링)
트리거	메시지 푸시	폰/웹 UI	타이머/시간
실행 조건	세션 열려있음	세션 열려있음	데스크톱 앱 켜짐
예시	Telegram DM → CI 실패 자동 수정	소파에서 빌드 모니터링	매일 9시 보안 스캔

활용 사례

단방향: 알림 기반 자동화

CI/CD 실패 자동 대응: GitHub Actions 웹훅 → Claude가 로그 분석 → 수정 커밋 생성
모니터링 경고 처리: Grafana 알림 → Claude가 로그 분석 → Slack에 요약 통보
PR 리뷰 트리거: 새 PR 웹훅 → Claude가 코드 리뷰 자동 수행

양방향: 대화형 에이전트

Telegram/Discord 코딩 비서: “로그인 화면 UI 개선해줘” → Claude가 작업 후 결과 회신
팀 채팅 브리지: 여러 플랫폼에서 자연어로 Claude에 작업 요청
인시던트 대응: 장애 알림 수신 → 자동 분석 → 결과를 채팅방에 공유

현재 제한사항

Research Preview 단계인 만큼 몇 가지 제약이 있습니다.

claude.ai 로그인 필수: API 키로는 사용할 수 없습니다
세션 유지 필요: 항상-켜짐(always-on) 모드가 없어서, 터미널이나 백그라운드 프로세스로 세션을 열어둬야 합니다
프로토콜 변경 가능: 플래그 문법이나 MCP 인터페이스가 바뀔 수 있습니다
Team/Enterprise: 관리자가 명시적으로 활성화해야 사용 가능합니다

마무리

Channels는 Claude Code를 “요청을 기다리는 도구”에서 **“이벤트에 반응하는 에이전트”**로 바꿔주는 기능입니다. 핵심을 정리하면:

MCP 기반: 표준 프로토콜 위에 동작하므로 커스텀 채널 확장이 자유롭습니다
보안 우선: Allowlist + Pairing Flow로 승인된 사용자만 접근합니다
단방향/양방향: 알림만 받을 수도, 대화형 봇으로 쓸 수도 있습니다

아직 Research Preview 단계이지만, Telegram이나 Discord 봇을 붙여 CI 알림에 자동 대응하는 것만으로도 상당한 시간을 절약할 수 있습니다. fakechat으로 먼저 흐름을 체험해보고, 실제 워크플로우에 적용해보세요.

Claude Code Channels 살펴보기: Telegram·Discord로 세션에 이벤트 푸시하기

Channels란?

동작 흐름

시작하기

요구사항

지원 채널

Telegram

Discord

Fakechat (테스트용)

보안 모델

Sender Allowlist

Pairing Flow

Enterprise 제어

커스텀 채널 만들기

기본 요구사항

핵심 설정

이벤트 푸시와 Reply

예시: 웹훅 리시버

관련 기능 비교

활용 사례

단방향: 알림 기반 자동화

양방향: 대화형 에이전트

현재 제한사항

마무리

참고 자료