2026. 4. 28.

클로드 코드(Claude Code) Channels 기능으로 텔레그램 연동하는 방법 완벽 가이드

클로드 코드(Claude Code)를 사용하다 보면 한 가지 불편한 점이 있습니다. 바로 터미널 앞에 계속 붙어 있어야 한다는 것입니다. 긴 작업을 시켜 놓고 외출하거나, 잠시 자리를 비울 때 작업 진행 상황을 확인하기 어렵습니다.

이 문제를 해결하기 위해 Anthropic은 Channels 기능을 리서치 프리뷰로 공개했습니다. Channels를 활용하면 텔레그램, 디스코드, iMessage 같은 메신저 앱에서 클로드 코드 세션과 직접 대화할 수 있습니다.

이 글에서는 그중에서도 가장 많이 사용되는 텔레그램 연동 방법을 처음부터 끝까지 자세히 다루겠습니다.

Channels 기능이란?

공식 문서에 따르면, Channels는 MCP(Model Context Protocol) 서버를 통해 외부 이벤트를 실행 중인 클로드 코드 세션으로 푸시하는 기능입니다.

핵심 특징을 정리하면 다음과 같습니다.

  • 양방향 통신이 가능합니다. 클로드가 이벤트를 읽고 같은 채널을 통해 답장합니다.
  • 이벤트는 세션이 열려 있을 때만 도착합니다. 따라서 항상 켜 두려면 백그라운드 프로세스나 영구 터미널에서 실행해야 합니다.
  • 플러그인 형태로 설치합니다. 사용자가 직접 자신의 자격 증명으로 설정하는 구조입니다.

리서치 프리뷰에는 텔레그램, 디스코드, iMessage가 포함되어 있습니다.

다른 기능과의 차이점

클로드 코드에는 외부 시스템과 연결되는 여러 기능이 있는데, 각 기능의 역할이 다릅니다.

  • Claude Code on the web: GitHub에서 복제된 새로운 클라우드 샌드박스에서 작업을 실행합니다.
  • Claude in Slack: Slack 채널이나 스레드에서 @Claude 멘션으로 웹 세션을 생성합니다.
  • 표준 MCP 서버: 클로드가 작업 중에 쿼리하는 방식이며, 세션으로 무엇이 푸시되지는 않습니다.
  • Remote Control: claude.ai나 모바일 앱에서 로컬 세션을 조작합니다.

Channels는 외부 소스에서 발생한 이벤트를 이미 실행 중인 로컬 세션으로 푸시한다는 점에서 위 기능들과 차이가 있습니다.

알아두면 좋은 동작 방식

공식 문서에 따르면, 클로드가 채널을 통해 답장할 때 터미널에서는 인바운드 메시지는 볼 수 있지만 답장 텍스트는 보이지 않습니다. 터미널에는 도구 호출과 확인 메시지(예: "sent")만 표시되고, 실제 답장 내용은 텔레그램 같은 외부 플랫폼에서 확인할 수 있습니다.

또한 실제 메신저를 연동하기 전에 플로우를 먼저 체험해 보고 싶다면, 공식적으로 제공되는 fakechat 데모 채널이 있습니다. 이 데모는 localhost에서 채팅 UI를 실행해 외부 서비스 없이 채널 흐름을 체험할 수 있게 해 줍니다.

텔레그램 연동을 위한 사전 준비물

본격적인 연동에 앞서 다음 사항들이 필요합니다.

1. 클로드 코드 v2.1.80 이상

Channels 기능은 클로드 코드 v2.1.80 이상에서만 동작합니다. 터미널에서 다음 명령어로 버전을 확인할 수 있습니다.

claude --version

2. claude.ai 로그인 계정

Channels 기능은 claude.ai 계정 로그인이 필수입니다. 공식 문서에 따르면 콘솔이나 API 키 인증 방식은 지원되지 않습니다.

3. Bun 런타임

텔레그램 플러그인의 MCP 서버는 Bun 런타임에서 실행됩니다. 다음 명령어로 설치할 수 있습니다.

curl -fsSL https://bun.sh/install | bash

Bun 공식 사이트에서도 자세한 설치 방법을 확인할 수 있습니다. 설치 후 bun --version 명령어로 정상 설치 여부를 점검하시기 바랍니다.

4. 텔레그램 앱과 BotFather 접근

텔레그램 앱이 설치되어 있어야 하고, BotFather로 봇을 생성해야 합니다.

5. Team/Enterprise 사용자의 경우

Team 또는 Enterprise 조직 사용자라면 관리자가 Channels 기능을 명시적으로 활성화해야 합니다. 관리자는 claude.ai → Admin settings → Claude Code → Channels 메뉴에서 설정할 수 있습니다.

Pro와 Max 사용자는 별도의 조직 설정 없이 바로 사용할 수 있습니다.

텔레그램 연동 단계별 설정 방법

이제 본격적으로 연동을 시작하겠습니다. 총 6단계로 진행됩니다.

1단계: BotFather로 텔레그램 봇 생성

먼저 텔레그램에서 @BotFather를 검색하여 채팅을 엽니다. BotFather는 텔레그램 공식 봇 관리 봇입니다.

채팅창에 다음 명령어를 입력합니다.

/newbot

BotFather가 두 가지 정보를 요청합니다.

  • 이름(Name): 채팅 헤더에 표시되는 이름이며, 공백을 포함할 수 있습니다.
  • 사용자명(Username): bot으로 끝나는 고유 핸들이어야 합니다 (예: my_assistant_bot). 이 값이 봇의 링크가 됩니다 (예: t.me/my_assistant_bot).

설정을 완료하면 BotFather가 다음과 같은 형식의 토큰을 반환합니다.

123456789:AAHfiqksKZ8...

주의사항: 토큰은 앞의 숫자와 콜론(:)을 포함한 전체 문자열을 복사해야 합니다. 이 토큰은 봇에 대한 모든 권한을 가지므로 절대 외부에 노출되어서는 안 됩니다.

2단계: 클로드 코드에 플러그인 설치

터미널에서 claude 명령어로 클로드 코드 세션을 시작합니다. 그다음 세션 안에서 다음 명령어를 입력합니다.

/plugin install telegram@claude-plugins-official

만약 "플러그인을 마켓플레이스에서 찾을 수 없다"는 메시지가 나타나면, 마켓플레이스가 누락되었거나 오래된 것일 수 있습니다. 다음 명령어로 새로 고치거나 추가합니다.

/plugin marketplace update claude-plugins-official

또는 처음 추가하는 경우라면 다음 명령어를 사용합니다.

/plugin marketplace add anthropics/claude-plugins-official

설치 후에는 /reload-plugins 명령어로 플러그인의 configure 명령어를 활성화해야 합니다.

3단계: 봇 토큰 설정

1단계에서 BotFather로부터 받은 토큰을 다음 명령어로 등록합니다.

/telegram:configure 123456789:AAHfiqksKZ8...

이 명령어를 실행하면 토큰이 ~/.claude/channels/telegram/.env 파일에 저장됩니다. 직접 파일을 편집하거나, 셸 환경변수에 TELEGRAM_BOT_TOKEN을 설정해도 됩니다. 두 곳 모두 설정된 경우 셸 환경변수가 우선 적용됩니다.

참고: 한 컴퓨터에서 여러 봇을 운영하려면(다른 토큰, 별도 허용 목록) TELEGRAM_STATE_DIR 환경변수를 인스턴스마다 다른 디렉토리로 지정하면 됩니다.

4단계: Channels 플래그로 클로드 코드 재시작

기존 세션을 종료하고 다음 명령어로 클로드 코드를 다시 실행합니다.

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

이 플래그가 있어야 텔레그램 플러그인이 활성화되어 봇 메시지를 폴링하기 시작합니다. 이 플래그 없이는 채널이 연결되지 않습니다.

5단계: 계정 페어링

이제 텔레그램 앱에서 본인이 만든 봇을 찾아 아무 메시지나 전송합니다. 봇이 6자리 페어링 코드로 응답합니다.

만약 봇이 응답하지 않는다면, 클로드 코드가 --channels 플래그와 함께 실행 중인지 확인하시기 바랍니다.

클로드 코드 세션으로 돌아와서 다음 명령어를 입력합니다.

/telegram:access pair <받은_6자리_코드>

이 단계가 완료되면 다음 메시지부터 봇이 클로드 코드 어시스턴트로 연결됩니다.

6단계: 접근 제한 설정

페어링은 사용자 ID를 캡처하기 위한 단계입니다. 한 번 페어링된 후에는 보안을 위해 허용 목록(allowlist) 모드로 전환하는 것이 좋습니다. 그렇지 않으면 모르는 사람이 봇에 메시지를 보냈을 때 페어링 코드를 받을 수 있습니다.

다음 명령어로 정책을 변경합니다.

/telegram:access policy allowlist

이로써 본인 계정에서만 메시지를 보낼 수 있게 됩니다.

텔레그램 봇이 사용할 수 있는 기능

공식 GitHub 저장소에 따르면, 어시스턴트에게 노출되는 도구는 세 가지입니다.

  • reply: 채팅에 메시지를 전송합니다. chat_id와 text를 받으며, reply_to(메시지 ID)로 네이티브 스레딩이 가능하고 files(절대 경로)로 첨부 파일을 보낼 수 있습니다. 이미지(.jpg/.png/.gif/.webp)는 인라인 미리보기와 함께 사진으로 전송되고, 그 외 파일 형식은 문서로 전송됩니다. 파일당 최대 50MB이며, 텍스트는 자동으로 분할됩니다.
  • react: 메시지 ID에 이모지 반응을 추가합니다. 텔레그램이 정한 고정 이모지 화이트리스트만 허용됩니다 (👍 👎 ❤ 🔥 👀 등).
  • edit_message: 봇이 이전에 보낸 메시지를 편집합니다. "작업 중…"에서 결과로 진행 상황을 업데이트할 때 유용합니다. 봇이 직접 보낸 메시지에만 적용됩니다.

수신된 메시지에는 자동으로 입력 표시기가 켜집니다. 어시스턴트가 응답을 작성하는 동안 텔레그램에서 "봇이름이 입력 중…" 표시가 나타납니다.

사진과 파일 처리 방식

수신된 사진은 ~/.claude/channels/telegram/inbox/ 경로에 다운로드되며, 로컬 경로가 <channel> 알림에 포함되어 어시스턴트가 Read 도구로 읽을 수 있습니다.

주의할 점: 텔레그램은 사진을 압축합니다. 원본 파일이 필요하다면 사진 대신 문서로 전송해야 합니다 (길게 누르기 → 파일로 보내기).

알아두면 좋은 제한사항

1. 메시지 히스토리 API 부재

텔레그램의 Bot API는 메시지 히스토리와 검색 기능을 모두 제공하지 않습니다. 봇은 메시지가 도착하는 시점에만 볼 수 있으며, fetch_messages 도구는 존재하지 않습니다. 어시스턴트가 이전 컨텍스트가 필요한 경우 사용자에게 붙여넣기나 요약을 요청합니다.

이는 과거 메시지의 첨부 파일도 마찬가지여서, 사진은 도착하는 즉시 다운로드됩니다.

2. 세션이 켜져 있어야 동작

세션이 종료되면 채널도 오프라인이 됩니다. 봇이 오프라인일 때 보낸 메시지는 텔레그램에서는 그대로 유실됩니다 (디스코드는 fetch_messages로 봇이 다시 온라인이 될 때까지 큐에 보관됩니다).

3. 권한 프롬프트 처리

작업 중 클로드가 권한 승인을 요청하면 세션은 사용자가 터미널에서 승인할 때까지 일시 중지됩니다. 외부에서 작업을 처리하려면 --dangerously-skip-permissions 플래그를 사용할 수 있지만, 본인이 신뢰하는 환경에서만 사용해야 합니다.

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

이 플래그는 보안상 위험을 감수하고 모든 권한 프롬프트를 건너뜁니다.

보안 고려사항

공식 보안 문서에서 강조하는 핵심은 다음과 같습니다.

  • 모든 승인된 채널 플러그인은 발신자 허용 목록을 유지합니다. 추가된 ID만 메시지를 푸시할 수 있고, 그 외에는 자동으로 무시됩니다.
  • --channels 플래그로 세션마다 활성화할 서버를 제어합니다.
  • .mcp.json에 등록된 것만으로는 부족하며, --channels에 명시적으로 지정되어야 합니다.

봇 토큰은 봇에 대한 전체 권한을 부여하는 자격 증명이므로, 절대 GitHub 등 공개 저장소에 올리거나 타인과 공유해서는 안 됩니다.

활용 사례

공식 문서에서 소개하는 Channels의 주요 활용 패턴은 두 가지입니다.

  • 채팅 브릿지(Chat bridge): 폰에서 텔레그램으로 클로드에게 질문을 보내면, 작업은 사용자 컴퓨터에서 실제 파일을 대상으로 실행되고 답변은 같은 텔레그램 채팅으로 돌아옵니다.
  • 웹훅 수신기(Webhook receiver): CI, 에러 트래커, 배포 파이프라인 등 외부 서비스의 웹훅을 클로드가 이미 파일을 열어 두고 디버깅 중인 세션으로 전달할 수 있습니다.

핵심은 모바일 환경에서도 AI를 통해 데스크톱의 파일과 도구에 접근할 수 있다는 점입니다.

자주 발생하는 문제와 해결법

봇이 응답하지 않는 경우

가장 흔한 원인은 클로드 코드 세션이 --channels 플래그 없이 실행 중이거나, 아예 종료되어 있는 경우입니다. 세션 상태를 다시 확인하시기 바랍니다.

플러그인을 찾을 수 없다는 메시지

마켓플레이스가 추가되지 않았거나 오래된 경우입니다. 위에서 안내한 /plugin marketplace update 또는 /plugin marketplace add 명령어로 해결할 수 있습니다.

권한 프롬프트로 세션이 멈추는 경우

장시간 자리를 비울 때 흔히 겪는 문제입니다. 신뢰할 수 있는 환경이라면 --dangerously-skip-permissions 플래그 사용을 검토해 볼 수 있습니다.

마치며

클로드 코드의 Channels 기능은 아직 리서치 프리뷰 단계이므로 공식 문서에 따르면 --channels 플래그 문법과 프로토콜이 사용자 피드백에 따라 변경될 수 있습니다. 문제나 의견은 Claude Code GitHub 저장소로 보고할 수 있습니다.

이 기능을 활용하면 책상 앞에 앉아 있을 때만 가능했던 개발 작업을, 외출 중이나 이동 중에도 텔레그램 채팅으로 처리할 수 있습니다. 모바일 환경에서 AI를 통해 데스크톱 도구와 파일에 접근할 수 있다는 점이 가장 큰 장점입니다.

다음 단계로 아래 기능들을 함께 살펴보면 더 강력한 워크플로우를 구성할 수 있습니다.