Claude Code Channels 완벽 가이드 - 텔레그램, 디스코드, 웹훅으로 AI 코딩 세션에 이벤트 푸시하기

Claude Code v2.1.80부터 도입된 Channels는 터미널 앞에 앉아 있지 않아도 외부 이벤트에 Claude가 반응할 수 있게 해주는 기능입니다. CI 빌드 실패, 텔레그램 메시지, 디스코드 DM, 웹훅 알림 등을 Claude Code 세션에 푸시하면, Claude가 자동으로 파일을 읽고 코드를 수정하고 응답합니다. 이 글에서는 Channels의 개념부터 텔레그램/디스코드 설정, 커스텀 채널 구축, 그리고 관련 기능인 Remote Control과 스케줄 작업까지 한눈에 정리합니다.

Channels란 무엇인가?

Channel은 MCP(Model Context Protocol) 서버로, 외부 시스템의 이벤트를 실행 중인 Claude Code 세션에 푸시합니다. 이벤트는 세션이 열려 있는 동안에만 도착하며, 양방향 채널의 경우 Claude가 같은 채널을 통해 답장을 보낼 수도 있습니다.

빠른 시작 - fakechat 데모

실제 플랫폼 연결 전에 localhost에서 채널 동작을 체험할 수 있는 공식 데모입니다.

1단계: 플러그인 설치

/plugin install fakechat@claude-plugins-official

마켓플레이스가 없다면 먼저 /plugin marketplace add anthropics/claude-plugins-official을 실행합니다.

2단계: 채널 활성화 후 재시작

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

여러 플러그인을 동시에 활성화하려면 공백으로 구분합니다.

3단계: 메시지 보내기

브라우저에서 http://localhost:8787을 열고 메시지를 입력합니다. 메시지는 channel source="fakechat"/ 태그로 Claude Code 세션에 도착하고, Claude가 작업 후 결과를 채팅 UI에 표시합니다.

텔레그램 채널 설정

1. 봇 생성 — 텔레그램에서 BotFather를 열고 /newbot 명령으로 봇을 생성합니다. 표시 이름과 bot으로 끝나는 유저네임을 지정하고, 발급받은 토큰을 복사합니다.
2. 플러그인 설치

   /plugin install telegram@claude-plugins-official

3. 토큰 설정

   /telegram:configure <토큰>

   토큰은 .claude/channels/telegram/.env에 저장됩니다. 셸 환경변수 TELEGRAM_BOT_TOKEN으로도 설정 가능합니다.

4. 채널 활성화 후 재시작

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

5. 계정 페어링 — 텔레그램에서 봇에 아무 메시지를 보내면 페어링 코드가 돌아옵니다. Claude Code에서 승인 후 접근 정책을 설정합니다.

   /telegram:access pair <코드>
   /telegram:access policy allowlist

디스코드 채널 설정

1. 봇 생성 — Discord Developer Portal에서 New Application → Bot 섹션에서 토큰을 발급받습니다.
2. Message Content Intent 활성화 — Bot 설정의 Privileged Gateway Intents에서 Message Content Intent를 켭니다.
3. 서버에 봇 초대 — OAuth2 → URL Generator에서 bot 스코프를 선택하고 다음 권한을 활성화합니다: View Channels, Send Messages, Send Messages in Threads, Read Message History, Attach Files, Add Reactions.
4. 플러그인 설치 및 토큰 설정

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

5. 채널 활성화 후 재시작

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

6. 계정 페어링 — 봇에 DM을 보내고 페어링 코드를 승인합니다.

   /discord:access pair <코드>
   /discord:access policy allowlist

보안 모델

모든 승인된 채널 플러그인은 발신자 허용 목록(allowlist)을 유지합니다. 허용 목록에 없는 ID의 메시지는 자동으로 폐기됩니다.

• 페어링 기반 인증 — 봇에 메시지 → 페어링 코드 수신 → Claude Code에서 승인 → 발신자 ID가 허용 목록에 추가
• 세션별 활성화 — --channels 플래그로 명시적으로 활성화한 서버만 메시지를 수신
• 조직 정책 — Team/Enterprise에서는 channelsEnabled 설정으로 전체 가용성 제어
• 발신자 ID 게이팅 — 채팅방 ID가 아닌 개별 발신자 ID로 검증 (그룹 채팅에서 허용되지 않은 사용자의 주입 방지)

커스텀 채널 구축하기

텔레그램이나 디스코드 외에 CI/CD, 모니터링 시스템 등 자체 채널을 직접 구축할 수 있습니다. 핵심 요구사항은 @modelcontextprotocol/sdk 패키지와 Node.js 호환 런타임(Bun, Node, Deno)뿐입니다.

채널 서버의 3가지 필수 요소

1. claude/channel 캐패빌리티 선언 — Claude Code가 알림 리스너를 등록
2. notifications/claude/channel 이벤트 발송 — 외부 이벤트를 Claude에 전달
3. stdio 트랜스포트 연결 — Claude Code가 서브프로세스로 채널 서버를 실행

웹훅 수신기 예제 (단방향)

mkdir webhook-channel && cd webhook-channel
bun add @modelcontextprotocol/sdk

webhook.ts 파일 하나로 완성됩니다:

#!/usr/bin/env bun
import { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

const mcp = new Server(
  { name: 'webhook', version: '0.0.1' },
  {
    capabilities: { experimental: { 'claude/channel': {} } },
    instructions: 'Events from the webhook channel arrive as <channel source="webhook">.',
  },
)

await mcp.connect(new StdioServerTransport())

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

.mcp.json에 서버를 등록하고 개발 플래그로 테스트합니다:

// .mcp.json
{ "mcpServers": { "webhook": { "command": "bun", "args": ["./webhook.ts"] } } }

// 실행
claude --dangerously-load-development-channels server:webhook

다른 터미널에서 curl로 웹훅을 시뮬레이션합니다:

curl -X POST localhost:8788 -d "build failed on main: https://ci.example.com/run/1234"

양방향 채널 만들기 (reply 도구 추가)

채팅 브릿지처럼 Claude가 답장을 보내야 하는 경우, MCP 표준 도구를 추가합니다:

1. Server 생성자의 capabilities에 tools: {} 추가
2. ListToolsRequestSchema와 CallToolRequestSchema 핸들러 등록
3. instructions에 reply 도구 사용법 명시

알림 포맷

플랜별 기본 동작

Team/Enterprise 관리자는 claude.ai → Admin settings → Claude Code → Channels에서 활성화하거나 managed settings에서 channelsEnabled를 true로 설정합니다.

Remote Control - 모바일에서 세션 이어가기

Channels가 외부 이벤트를 세션에 밀어넣는 것이라면, Remote Control은 실행 중인 로컬 세션을 다른 기기에서 직접 제어하는 기능입니다.

시작 방법

# 서버 모드 (전용 원격 서버)
claude remote-control

# 인터랙티브 세션 + 원격 제어
claude --remote-control

# 기존 세션에서 활성화
/remote-control

시작하면 세션 URL이 표시되며, 스페이스바로 QR 코드를 토글할 수 있습니다. claude.ai/code 또는 Claude 모바일 앱에서 세션에 접속합니다.

주요 특징

• 로컬 실행 유지 — 파일시스템, MCP 서버, 프로젝트 설정이 모두 로컬에서 작동
• 멀티 디바이스 동기화 — 터미널, 브라우저, 모바일에서 동시에 메시지 전송 가능
• 자동 재연결 — 노트북 슬립이나 네트워크 끊김 시 자동 복구
• 아웃바운드 전용 — 인바운드 포트를 열지 않으며, 모든 트래픽은 TLS를 통해 Anthropic API 경유

서버 모드 주요 옵션

스케줄 작업 - /loop와 cron

Channels가 이벤트를 받아서 반응하는 방식이라면, 스케줄 작업은 주기적으로 폴링하는 방식입니다.

/loop 사용법

# 5분마다 배포 상태 확인
/loop 5m 배포 완료됐는지 확인하고 결과 알려줘

# 다른 명령어를 주기적으로 실행
/loop 20m /review-pr 1234

# 기본 10분 간격
/loop 빌드 상태 확인해줘

일회성 리마인더

오후 3시에 릴리스 브랜치 push하라고 알려줘
45분 후에 통합 테스트 통과했는지 확인해줘

인터벌 문법

단위: s(초), m(분), h(시간), d(일). 초 단위는 분 단위로 올림 처리됩니다.

작업 관리

# 자연어로 관리
예약된 작업 목록 보여줘
배포 확인 작업 취소해줘

주요 제약사항

• 세션 범위 — 터미널을 닫거나 Claude Code를 종료하면 모든 작업이 사라짐
• 3일 자동 만료 — 반복 작업은 생성 후 3일이 지나면 자동 삭제
• 미실행 건 미보충 — Claude가 바쁜 동안 놓친 실행은 1회만 보충
• 로컬 타임존 — 모든 시간은 로컬 시간대 기준으로 해석

CLAUDE_CODE_DISABLE_CRON=1 환경변수로 스케줄러 전체를 비활성화할 수 있습니다.

Channels vs Remote Control vs 스케줄 작업 비교