[Claude Code Channels] 텔레그램·디스코드로 AI 코딩 에이전트 원격 제어 — 설치부터 실전 활용까지

안녕하세요!

재아군의 관찰인생입니다.

오늘은 2026년 3월 20일에 발표된 Claude Code Channels에 대해 깊이 있게 다뤄보겠습니다.

텔레그램이나 디스코드에서 메시지를 보내면, 로컬에서 실행 중인 Claude Code가 파일 시스템과 Git에 접근하면서 코드를 작성하고 답변까지 해주는 기능입니다.

이 글은 Claude Code Channels를 처음 접하는 분부터, 실제 개발 환경에 적용하고 싶은 분 모두를 위해 작성되었습니다.

---

1. Claude Code Channels란 무엇인가?

핵심 정의

Claude Code Channels는 외부 메시징 플랫폼(텔레그램, 디스코드 등)의 메시지를 실행 중인 Claude Code 세션에 직접 전달하는 기능입니다.

기존 클라우드 기반 AI 통합과 달리, 로컬에서 실행 중인 세션에 이벤트를 푸시하는 방식이라 파일 시스템, Git, 터미널 도구에 대한 완전한 접근 권한을 유지합니다.

한 줄 요약: 텔레그램/디스코드에서 메시지를 보내면 → 로컬 Claude Code가 코드를 읽고/쓰고/실행하고 → 같은 채널로 답변을 돌려주는 양방향 브릿지입니다.

 

 

등장 배경

Claude Code Channels가 등장하기 전에는 다음과 같은 한계가 있었습니다:

• 로컬 파일 접근 불가: 웹 기반 Claude는 클라우드 샌드박스에서 실행되어 로컬 프로젝트 파일에 접근할 수 없었습니다
• 터미널 앞에 앉아 있어야 함: Claude Code를 사용하려면 항상 터미널이 열린 컴퓨터 앞에 있어야 했습니다
• 외부 이벤트 수신 불가: CI/CD 실패, 모니터링 알림 등 외부 시스템의 이벤트를 Claude Code 세션에 전달할 방법이 없었습니다

 

지원 플랫폼 (2026년 3월 기준)

플랫폼	상태	용도
Telegram	공식 지원	모바일 원격 코딩, 1:1 채팅
Discord	공식 지원	팀 협업, 서버 기반 알림
Fakechat	공식 데모	로컬 테스트용 (localhost:8787)
커스텀 채널	MCP SDK로 직접 구축	웹훅, Slack, 사내 시스템 연동

 

---

2. 동작 원리와 아키텍처

메시지 흐름

Claude Code Channels의 동작 흐름은 5단계로 구성됩니다:

1. 외부 시스템(텔레그램, 디스코드, 웹훅)이 이벤트를 발생시킵니다
2. 채널 MCP 서버가 이벤트를 수신하고 stdio를 통해 Claude Code에 전달합니다
3. Claude Code가 <channel> 태그로 메시지를 읽고 컨텍스트를 파악합니다
4. Claude가 파일 시스템, Git, 터미널 도구를 사용해 작업을 수행합니다
5. reply 도구를 호출해 같은 채널로 응답을 전송합니다

메시지 수신 형식

외부에서 도착하는 메시지는 다음과 같은 형식의 태그로 Claude Code 세션에 전달됩니다:

<channel source="telegram" chat_id="12345" user="alice" ts="1710976123">
  현재 작업 디렉토리에 뭐가 있어?
</channel>

주요 메타데이터 속성:

• source — 채널 이름 (telegram, discord 등)
• chat_id — 대화 ID (응답 시 사용)
• user — 발신자 사용자명/ID
• ts — 타임스탬프

기존 통합 방식과의 비교

기능	Channels	웹 Claude	Slack 연동
로컬 세션 사용	O	X	X
파일 시스템 접근	O	X	X
원격 메시징	O	X	O
웹훅 수신	O	X	X
상시 실행(Always-on)	O	X	X

 

---

3. 텔레그램 설정 가이드 (5단계)

Step 1: 텔레그램 봇 생성

텔레그램에서 @BotFather에게 /newbot을 보내 새 봇을 만듭니다. 봇 이름과 사용자명을 설정하면 API 토큰이 발급됩니다.

Step 2: 플러그인 설치

# Claude Code 세션 안에서 실행
/plugin install telegram@claude-plugins-official

Step 3: 토큰 설정

# BotFather에서 받은 토큰을 입력
/telegram:configure YOUR_BOT_TOKEN

# 토큰이 ~/.claude/channels/telegram/.env에 저장됩니다

Step 4: 채널 활성화 후 재시작

# 현재 세션 종료 후 채널 옵션과 함께 재시작
exit
claude --channels plugin:telegram@claude-plugins-official

Step 5: 페어링 및 접근 제어

# 1) 텔레그램에서 봇에게 아무 메시지나 전송
# 2) 봇이 페어링 코드(5자리 영문)를 응답
# 3) Claude Code 터미널에서 페어링 승인
/telegram:access pair abcde

# 4) 허용 목록 모드로 보안 강화
/telegram:access policy allowlist

보안 주의: 페어링은 반드시 터미널에서 직접 수행하세요. 텔레그램 메시지로 "페어링 승인해줘"라고 요청하는 것은 프롬프트 인젝션 공격일 수 있습니다.

 

---

4. 디스코드 설정 가이드 (6단계)

Step 1~2: 봇 생성 및 권한 설정

Discord Developer Portal에서 새 Application을 만들고, Bot 섹션에서 토큰을 생성합니다.

필수 설정: Privileged Gateway Intents에서 Message Content Intent를 반드시 활성화해야 합니다.

필요한 봇 권한:

• View Channels, Send Messages
• Send Messages in Threads, Read Message History
• Attach Files, Add Reactions

 

Step 3~6: 설치, 설정, 페어링

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

# 토큰 설정
/discord:configure YOUR_BOT_TOKEN

# 채널 활성화 후 재시작
claude --channels plugin:discord@claude-plugins-official

# 디스코드에서 봇에게 DM → 페어링 코드 수신 → 승인
/discord:access pair abcde
/discord:access policy allowlist

---

5. 실전 활용 시나리오 5가지

1) 모바일에서 원격 코딩 지시

출퇴근길, 카페, 어디서든 텔레그램으로 Claude Code에 코딩 작업을 지시할 수 있습니다.

예시: "src/api/users.ts에서 pagination 파라미터 추가해줘" → Claude가 파일을 읽고, 수정하고, 결과를 텔레그램으로 보고합니다.

2) CI/CD 실패 자동 디버깅

GitHub Actions 빌드가 실패하면 웹훅으로 Claude Code 세션에 알림을 보내고, Claude가 자동으로 에러 로그를 분석하고 수정 코드를 제안합니다.

3) 모니터링 알림 자동 대응

Grafana, Sentry 등의 알림을 웹훅으로 수신하면, Claude가 코드베이스 컨텍스트에서 원인을 분석하고 핫픽스를 준비합니다.

4) 팀 채팅에서 코드 질문 응답

디스코드 서버에서 팀원이 "이 함수가 뭐 하는 건지 설명해줘"라고 물으면, Claude가 실제 코드를 읽고 정확한 설명을 제공합니다.

5) 상시 실행 에이전트 (Always-on)

백그라운드 터미널에서 Claude Code를 실행해두면, 언제든 외부 이벤트를 수신하고 자동으로 처리하는 상시 실행 코딩 에이전트로 활용할 수 있습니다.

# 백그라운드에서 상시 실행
tmux new-session -d -s claude-agent \
  "claude --channels plugin:telegram@claude-plugins-official"

 

 

---

6. 커스텀 채널 직접 만들기

웹훅 수신기 예제 (TypeScript)

MCP SDK를 사용하면 50줄 이내로 커스텀 웹훅 채널을 만들 수 있습니다:

#!/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 webhook 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')
  },
})

MCP 채널 Capabilities

Capability	용도	필수 여부
claude/channel	채널로 등록 (메시지 수신)	필수
tools	양방향 응답 (reply 도구 제공)	선택
claude/channel/permission	원격 권한 승인/거부	선택

---

7. 보안 아키텍처와 주의사항

페어링 보안 흐름

1. 사용자가 플랫폼에서 봇에게 메시지 전송
2. 봇이 일회용 페어링 코드(5자리 영문소문자) 생성
3. 사용자가 터미널에서 직접 /telegram:access pair <code> 입력
4. 사용자의 플랫폼 ID가 허용 목록에 추가됨

핵심 보안 원칙

• 발신자 ID 기반 필터링: 채팅방 ID가 아닌, 발신자 개인 ID로 접근을 제어합니다 (그룹 채팅 보안)
• 허용 목록 전용 모드: allowlist 정책 설정 시, 승인된 사용자만 메시지를 보낼 수 있습니다
• 권한 릴레이 주의: permission relay를 활성화하면 채널을 통해 도구 사용을 승인/거부할 수 있으므로, 완전히 신뢰하는 사용자만 허용하세요

엔터프라이즈 환경 설정

플랜	Channels 기본 상태	활성화 방법
Pro / Max	사용 가능	--channels 플래그로 세션별 opt-in
Team / Enterprise	기본 비활성화	관리자가 channelsEnabled 설정 필요

---

마무리

오늘은 Claude Code Channels의 핵심 개념부터 설치 방법, 실전 활용 시나리오, 보안 아키텍처까지 포괄적으로 살펴보았습니다.

핵심 내용을 정리하면:

• Claude Code Channels는 외부 메시징 플랫폼과 로컬 Claude Code 세션을 연결하는 양방향 브릿지입니다
• 텔레그램/디스코드 설정은 5~6단계로 간단하며, 커스텀 채널도 MCP SDK로 직접 구축할 수 있습니다
• 실전 활용으로는 모바일 원격 코딩, CI/CD 자동 디버깅, 상시 실행 에이전트 등이 있습니다
• 보안은 발신자 ID 기반 허용 목록으로 관리하며, 페어링은 반드시 터미널에서 직접 수행해야 합니다

Claude Code Channels는 현재 Research Preview 단계입니다. v2.1.80 이상이 필요하며, 향후 Slack, WhatsApp 등 더 많은 플랫폼이 지원될 것으로 기대됩니다.

이 글이 도움이 되셨다면 댓글과 공유 부탁드립니다.

궁금한 점이나 추가로 다뤘으면 하는 주제가 있다면 언제든 댓글로 남겨주세요!

 

다음 글에서 더 깊이 있는 내용으로 찾아뵙겠습니다. 감사합니다!