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. 봇 생성이 매우 간단함
Telegram에서는 'BotFather'라는 공식 봇에게 메시지를 보내는 것만으로 단 몇 분 만에 새로운 봇을 만들 수 있습니다. 개발자 포털에 로그인하여 애플리케이션을 생성하는 등의 복잡한 절차가 필요 없어 부담 없이 시도해 볼 수 있다는 점이 매력적입니다.
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 봇 생성하기
먼저 Telegram 측에서 봇을 준비합니다.
- Telegram 앱을 엽니다. 처음 사용하는 경우 전화번호 인증 등 초기 설정을 완료해 주세요.
- 화면 하단의 검색창(돋보기 아이콘)을 탭하고 "BotFather"를 입력합니다. 검색 결과에 파란색 체크 표시가 있는 "BotFather"가 나타나면 이를 탭하여 채팅 화면을 엽니다. 검색이 되지 않는다면 브라우저에서 https://t.me/BotFather에 접속하여 직접 BotFather 채팅을 열 수 있습니다.
- BotFather와의 채팅을 열었다면 Start 버튼을 클릭하고
/newbot메시지를 보냅니다.
- 봇의 '표시 이름(Name)'을 물어보므로 원하는 이름을 입력합니다 (예:
My Claude Bot).
- 다음으로 '사용자 이름(Username)'을 물어봅니다. 이는 반드시
bot으로 끝나야 합니다 (예:my_claude_code_bot).
- 생성이 완료되면 **봇 토큰(Bot Token)**이 표시됩니다.
110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw와 같은 긴 문자열입니다. 이를 잘 적어두세요.
주의: 봇 토큰은 비밀 정보입니다. 타인에게 공유하거나 공개 리포지토리에 커밋하지 마세요.
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: 봇 토큰 설정하기
Step 1에서 받은 봇 토큰을 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 플러그인이 자동으로 서브 프로세스로 실행되어 봇으로 오는 메시지를 폴링(주기적으로 확인)하기 시작합니다.
Step 5: 계정 페어링하기
보안을 위해 먼저 자신의 Telegram 계정과 Claude Code 세션을 연결(페어링)하는 작업이 필요합니다.
- Telegram 앱에서 Step 1에서 만든 봇을 마지막 메시지에 적힌 링크를 통해 열고 '시작(OK)'을 탭합니다.
- 봇에게 아무 메시지나 보냅니다 (예: "hello" 등 무엇이든 상관없습니다).
- 봇이 페어링 코드를 답장으로 보내줍니다.
봇이 반응하지 않는다면 Claude Code가
--channels플래그와 함께 실행 중인지 확인하세요. 채널이 활성화된 세션이 돌아가고 있지 않으면 봇은 응답할 수 없습니다.
- Claude Code 터미널로 돌아와 아래 명령어로 페어링을 완료합니다.
<code>부분은 봇에게 받은 코드로 바꿉니다.
/telegram:access pair <code>
- 마지막으로 액세스 정책을 설정하여 자신 이외의 사용자로부터 오는 메시지를 차단합니다.
/telegram:access policy allowlist
이제 자신의 Telegram 계정만 Claude Code에 메시지를 보낼 수 있는 상태가 되었습니다.
사용해 보기!
설정이 완료되었으니 바로 사용해 봅시다. Telegram 앱을 열어 봇에게 메시지를 보냅니다.
현재 워킹 디렉토리에 있는 파일들을 알려줘
그러면 현재 세션의 워킹 디렉토리 경로를 Telegram으로 답변해 줄 것입니다.
메시지가 Claude Code 세션에 전달되면, Claude는 이를 바탕으로 파일을 읽거나 명령어를 실행합니다. 처리 결과는 Telegram 채팅방에 답장 형식으로 도착합니다.
터미널 쪽에서는 수신한 메시지와 답장을 위한 도구 호출("sent"라는 확인 표시)이 나타납니다. 실제 답장 텍스트는 Telegram 쪽에 표시되는 구조입니다.
보안에 대해 알아두어야 할 점
Channels를 사용하는 데 있어 보안 측면에서 몇 가지 짚고 넘어가야 할 포인트가 있습니다.
발신자 허용 목록(Allowlist)
Telegram 채널 플러그인은 페어링된 계정의 메시지만 수신합니다. 허용 목록에 없는 발신자의 메시지는 무시됩니다. 이를 통해 제삼자가 봇을 통해 Claude Code에 부정한 지시를 내리는 것(프롬프트 인젝션)을 방지합니다.
세션 단위 활성화
.mcp.json에 서버가 등록되어 있다고 해서 메시지가 전달되는 것은 아닙니다. --channels 플래그로 명시적으로 활성화한 세션에서만 Claude Code Channels가 작동합니다.
권한 프롬프트 주의사항
Claude Code가 파일 편집이나 명령어 실행 등 권한이 필요한 작업을 수행하려 하면 터미널에 확인 프롬프트가 표시됩니다. 외출 중에 메시지를 보낸 경우, 이 프롬프트 때문에 처리가 일시 중지될 수 있습니다.
완전히 무인으로 동작시키고 싶다면 --dangerously-skip-permissions 플래그가 있지만, 이름 그대로 위험을 수반하는 옵션입니다. 신뢰할 수 있는 환경에서만 사용하세요.
작동하지 않을 때의 체크리스트
문제가 발생한다면 다음 사항을 확인해 보세요.
- Claude Code 버전: v2.1.80 이상인가요?
- 인증 방식: claude.ai 계정으로 로그인했나요? (API 키 인증으로는 Channels를 사용할 수 없습니다)
- Bun 설치:
bun --version으로 버전이 표시되나요? --channels플래그: Claude Code를 실행할 때 플래그를 붙였나요?- 페어링: 봇에게 메시지를 보내고 받은 코드로
/telegram:access pair를 실행했나요?
해결되지 않는다면 먼저 Claude Code에게 직접 물어보세요.
요약
Claude Code Channels와 Telegram을 조합하면 터미널에서 떨어져 있어도 Claude Code에 지시를 보낼 수 있는 환경을 구축할 수 있습니다. 설정 단계를 다시 한번 정리해 보겠습니다.
- BotFather에서 Telegram 봇을 생성하고 토큰 획득
- Claude Code에서 Telegram 플러그인 설치
/telegram:configure로 토큰 설정--channels플래그와 함께 Claude Code 재시작- 봇에게 메시지를 보내 페어링 완료
단 이 몇 단계만으로 스마트폰에서 Claude Code를 조작할 수 있게 됩니다.
Channels는 아직 리서치 프리뷰 단계이므로 향후 플래그 사양이나 프로토콜이 변경될 가능성이 있습니다. 최신 정보는 공식 문서를 확인해 주세요.
피드백이나 버그 보고는 Claude Code의 GitHub 리포지토리에서 받고 있다고 합니다. 관심 있는 분들은 꼭 한번 시도해 보세요!
