Claude Code Channels で Telegram から Claude とやり取りしよう！ステップバイステップ設定ガイド→Claude Code Channels에서 Telegram으로 Claude와 대화하자！단계별 설정 가이드

터미널 앞에 없어도 스마트폰에서 Claude Code에 메시지를 보낼 수 있다면 편리하지 않을까요? 저도 그런 환경을 목표로 직접 Discord와 연동하는 환경을 만들어보긴 했지만, 그다지 만족스러운 결과는 아니었습니다. 하지만 얼마 전(2026년 3월 21일)에 리서치 프리뷰로 공개된 Claude Code Channels를 사용하면 그것을 간단하게 실현할 수 있습니다!

이 글에서는 채팅 앱 Telegram을 사용해 Claude Code Channels를 설정하는 방법을 처음부터 알기 쉽게 설명합니다.

Claude Code Channels란

Claude Code Channels는 외부에서 오는 알림이나 메시지를 실행 중인 Claude Code 세션에 실시간으로 전달하는 仕組みです. 기술적으로는 MCP(Model Context Protocol) 서버로 동작하며, Claude Code의 서브프로세스로 실행됩니다.

예를 들어, 이런 사용 방법이 가능합니다.

• 채팅 연동: Telegram이나 Discord에서 메시지를 보내면, 로컬에서 실행 중인 Claude Code가 그것을 받아서 작업해줍니다
• Webhook 연동: CI/CD 결과나 모니터링 알림을 Claude Code에 직접 전달하여 자동으로 대응하게 합니다

단방향(알림만 보내기)과 양방향(Claude가 답장도 하기) 모두 지원합니다. 채팅 앱과의 연동에서는 스마트폰으로 메시지를 보내고, Claude가 작업한 결과를 그 채팅으로 돌려보내주는 양방향 소통이 가능합니다.

왜 Telegram을 선택했는가

리서치 프리뷰 단계에서는 채팅 앱으로 Telegram과 Discord가 공식 지원됩니다. 이번에는 Telegram을 선택했습니다. 그 이유를 몇 가지 들어보겠습니다.

1. Bot 생성이 매우 간단

Telegram에서는 「BotFather」라는 공식 Bot에 메시지를 보내는 것만으로 몇 분 안에 새로운 Bot을 만들 수 있습니다. 개발자 포털에 로그인해서 애플리케이션을 생성하는 등의 절차가 필요 없어서 부담 없이 시도해볼 수 있다는 것이 매력입니다.

2. 스마트폰 조작과 궁합이 최고

Telegram은 모바일 앱 동작이 가볍고, 어디서든 빠르게 메시지를 보낼 수 있습니다. 외출 중에 문득 「저 파일 내용을 확인하고 싶다」「테스트를 돌려두고 싶다」고 생각했을 때, 주머니 속 스마트폰에서 Claude Code에 지시를 내릴 수 있다는 것은 큰 장점입니다.

3. 설정 절차가 간단

Discord의 경우 Developer Portal에서 애플리케이션을 생성하고, Message Content Intent를 활성화하고, 권한을 세세하게 설정하고, 서버에 초대하는 등 단계가 많아지기 쉽습니다. Telegram이라면 BotFather에서 토큰을 발급받는 것만으로 준비가 완료되므로, Channels의 동작을 빠르게 체험할 수 있습니다.

4. Claude Code 전용으로 분리할 수 있다

저는 그때까지 Telegram을 설치조차 하지 않았기 때문에, 오히려 그것이 유리하게 작용했습니다. 다른 용도의 알림이 오지 않아서, Telegram을 열면 Claude Code 알림만 있는 완전한 전용 채널로 사용할 수 있습니다.

그럼 실제로 설정해봅시다!

사전 조건

설정을 시작하기 전에 다음 준비가 완료되어 있는지 확인하세요.

• Claude Code v2.1.80 이상이 설치되어 있을 것
• claude.ai 계정으로 로그인되어 있을 것 (Console이나 API 키 인증은 미지원입니다)
• Bun이 설치되어 있을 것 (플러그인 실행에 필요합니다)
• Telegram 계정을 가지고 있을 것
• Team / Enterprise 플랜의 경우, 조직 관리자가 Channels를 활성화했을 것

Bun이 아직 없는 분은 다음 명령어로 간단하게 설치할 수 있습니다.

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

설치 완료 후 바로 bun --version을 실행하면 command not found가 될 수 있습니다. 이는 설치 프로그램이 ~/.zshrc에 경로를 추가해주지만, 현재 셸에는 아직 반영되지 않았기 때문입니다. 다음 중 하나를 실행하면 사용할 수 있게 됩니다.

# 방법1: 현재 셸을 재시작한다 (설치 프로그램 안내에도 표시됩니다)
exec /bin/zsh

# 방법2: .zshrc를 수동으로 다시 읽어들인다
source ~/.zshrc

경로가 설정되면 버전을 확인해봅시다.

bun --version

Step 1: Telegram Bot 생성하기

먼저 Telegram 측에서 Bot을 준비합니다.

1. Telegram 앱을 엽니다. 처음 사용하는 경우 전화번호 인증 등의 초기 설정을 완료하세요.
2. 화면 하단의 검색 바(돋보기 아이콘)를 탭하고 「BotFather」를 입력합니다. 검색 결과에 파란색 체크 마크가 붙은 「BotFather」가 표시되면 그것을 탭하여 채팅 화면을 엽니다. 검색에서 찾을 수 없는 경우 브라우저에서 https://t.me/BotFather에 접속하면 BotFather 채팅을 직접 열 수 있습니다.
3. BotFather와의 채팅을 열었으면 Start 버튼을 클릭하고 /newbot이라고 메시지를 전송합니다.
4. Bot의 「표시 이름」을 물어보면 원하는 이름을 입력합니다 (예: My Claude Bot).
5. 다음으로 「사용자 이름」을 물어봅니다. 이것은 bot으로 끝나야 합니다 (예: my_claude_code_bot).
6. 생성이 완료되면 Bot 토큰이 표시됩니다. 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw와 같은 긴 문자열입니다. 이것을 메모해두세요.

주의: Bot 토큰은 비밀 정보입니다. 타인과 공유하거나 공개 저장소에 커밋하지 마세요.

Step 2: Telegram 플러그인 설치하기

다음으로 Claude Code 세션 내에서 Telegram 채널 플러그인을 설치합니다.

Claude Code를 실행하고 다음 명령어를 실행하세요.

/plugin install telegram@claude-plugins-official

만약 「플러그인을 찾을 수 없다」는 오류가 나오면 먼저 마켓플레이스를 등록해야 합니다.

/plugin marketplace add anthropics/claude-plugins-official

마켓플레이스를 추가했으면 다시 한번 설치 명령어를 실행해보세요.

설치가 완료되면 한 번 /exit으로 세션을 종료하고 다시 들어갑시다. /reload-plugins로는 /telegram 명령어를 사용할 수 없게 되었습니다.

Step 3: Bot 토큰 설정하기

Step 1에서 취득한 Bot 토큰을 Claude Code에 등록합니다. 다음 명령어로 설정하세요. <token> 부분을 실제 토큰으로 교체합니다.

/telegram:configure <token>

토큰은 ~/.claude/channels/telegram/.env에 저장됩니다. 셸의 환경 변수 TELEGRAM_BOT_TOKEN으로 설정해두는 방법도 괜찮다고 합니다.

토큰을 반영하기 위해 다시 /exit으로 세션을 종료합니다.

Step 4: Channels를 활성화하고 Claude Code 재시작하기

토큰 설정이 완료되면 Claude Code를 종료하고 --channels 플래그를 붙여 재시작합니다. 이 플래그가 Telegram 플러그인을 활성화하는 스위치가 됩니다. 참고로 저는 --dangerously-skip-permissions를 붙이지만, 그것에 대해서는 본인의 판단에 맡깁니다.

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

실행하면 Telegram 플러그인이 자동으로 서브프로세스로 실행되어 Bot에 오는 메시지를 폴링(정기적으로 확인)하기 시작합니다.

Step 5: 계정 페어링하기

보안을 위해 처음에 자신의 Telegram 계정과 Claude Code 세션을 연결(페어링)하는 작업이 필요합니다.

1. Telegram 앱에서 Step 1에서 생성한 Bot을 마지막 메시지에 적혀 있는 링크에서 열고 OK를 탭합니다.
2. Bot에 아무 메시지나 보냅니다 (「hello」등 무엇이든 OK입니다)
   <img data-mt-asset-id="80" src="https://tinybeans.net/assets/images/claude_code_telegram_14_trimmed.webp" width="