canine89 ClaudeClaw - Claude Code Channels 텔레그램 연동 가이드
Claude Code의 Channels 기능을 사용하여 텔레그램에서 직접 Claude에게 작업을 지시할 수 있도록 연동하는 설치 가이드 스킬입니다.
Channels란? Anthropic의 MCP(Model Context Protocol)를 활용하여, 텔레그램 같은 메신저 앱을 실행 중인 내 PC의 Claude Code 세션과 양방향으로 연결해 주는 기능입니다. 컴퓨터 앞을 떠나 이동 중에도 휴대폰 메신저를 통해 Claude에게 코딩 작업을 지시하고, 결과를 실시간으로 받아볼 수 있습니다.
사전 준비물
| 준비물 | 설명 |
|---|---|
| Claude Code CLI | 시스템에 설치 완료 상태여야 합니다 |
| 유료 플랜 | Claude Pro, Team 등 유료 플랜에 로그인되어 있어야 합니다 |
| Bun 런타임 | 텔레그램 플러그인 서버가 Bun에서 동작합니다 (아래 설치 방법 참고) |
| 텔레그램 앱 | 모바일 또는 데스크톱 앱 |
| 텔레그램 계정 | 봇 생성을 위해 필요합니다 |
Bun 설치 (아직 설치하지 않은 경우)
macOS / Linux:
curl -fsSL https://bun.sh/install | bash
설치 후 터미널을 새로 열거나 아래 명령어로 환경변수를 적용합니다:
source ~/.bashrc # bash 사용자
source ~/.zshrc # zsh 사용자 (macOS 기본)
Windows (PowerShell 관리자 권한):
powershell -c "irm bun.sh/install.ps1 | iex"
Windows에서는 PowerShell을 관리자 권한으로 실행한 뒤 위 명령어를 입력하세요. 설치 후 PowerShell을 새로 열어야
bun명령어가 인식됩니다.
설치 확인 (모든 OS 공통):
bun --version
버전 번호가 출력되면 정상 설치된 것입니다.
1단계: 텔레그램 봇 생성 및 토큰 발급
먼저 텔레그램에서 봇을 만들고 API 토큰을 발급받습니다.
1-1. BotFather에서 봇 만들기
- 텔레그램 앱을 열고 검색창에 @BotFather를 검색합니다.
- BotFather 채팅에서 Start 버튼을 누릅니다.
/newbot명령어를 입력합니다.- 봇의 표시 이름(예:
My Claude Bot)을 입력합니다. - 봇의 사용자명(예:
my_claude_helper_bot)을 입력합니다.- 반드시
bot으로 끝나야 합니다.
- 반드시
1-2. API 토큰 복사
봇 생성이 완료되면 BotFather가 다음과 같은 메시지를 보냅니다:
Use this token to access the HTTP API:
123456789:AAH_이런형식의_긴_문자열
이 토큰을 복사해 둡니다.
주의: API 토큰은 비밀번호와 같습니다. 절대 다른 사람에게 공유하지 마세요.
2단계: 텔레그램 플러그인 설치
2-1. Claude Code 실행
macOS / Linux:
claude
Windows (PowerShell 또는 명령 프롬프트):
claude
팁: 설치 과정에서 매번 승인을 누르기 번거롭다면
claude --dangerously-skip-permissions로 실행할 수 있습니다. 설치가 끝나면 일반 모드로 다시 실행하세요.
2-2. 플러그인 설치
Claude Code 프롬프트에 아래 명령어를 입력합니다:
/plugin install telegram@claude-plugins-official
- 설치 범위(scope)를 물으면 project 또는 user 중 원하는 범위를 선택합니다.
user: 모든 프로젝트에서 사용 가능 (추천)project: 현재 프로젝트에서만 사용
- 아직 프리뷰(Preview) 기능이므로 일부 불안정할 수 있습니다.
플러그인을 찾을 수 없다는 에러가 나올 때:
/plugin marketplace update claude-plugins-official을 먼저 실행하여 목록을 갱신한 뒤 다시 시도하세요.
3단계: 토큰 설정
1단계에서 BotFather로부터 발급받은 텔레그램 토큰을 Claude Code에 등록합니다.
/telegram:configure <발급받은_토큰>
예시:
/telegram:configure 123456789:AAH_이런형식의_긴_문자열
엔터를 눌러 설정을 적용합니다.
4단계: Channels 플래그로 재시작
이 단계가 매우 중요합니다.
--channels플래그 없이 실행하면 텔레그램 연동이 동작하지 않습니다.
현재 실행 중인 Claude Code 세션을 종료합니다:
exit
그런 다음, --channels 플래그를 추가하여 다시 실행합니다:
macOS / Linux:
claude --channels plugin:telegram@claude-plugins-official
Windows (PowerShell):
claude --channels plugin:telegram@claude-plugins-official
터미널에 채널 수신 관련 메시지가 표시되면 정상입니다.
메시지가 안 나오면: 2단계의 플러그인 설치가 제대로 되었는지 확인하세요. Claude Code를 완전히 종료 후 다시 시도해 보세요.
5단계: 기기 페어링 (Pairing)
5-1. 텔레그램에서 봇 시작
- 텔레그램 앱으로 돌아갑니다.
- 1단계에서 만든 봇을 검색합니다 (설정한 사용자명으로).
- Start 버튼을 누르거나
/start를 입력합니다.
5-2. 페어링 코드 확인
봇이 6자리 페어링 코드를 답장으로 보냅니다.
페어링 코드가 안 오면:
- 4단계의
--channels플래그 실행이 정상적으로 되었는지 확인하세요.- 봇에게
/start를 다시 입력해 보세요.- BotFather에서 토큰이 맞는지 확인하세요.
5-3. Claude Code에서 페어링 완료
Claude Code 프롬프트로 돌아와서 아래 명령어로 기기를 연결합니다:
/telegram:access pair <6자리_페어링_코드>
예시:
/telegram:access pair 482951
승인(Yes) 프롬프트가 나오면 Yes를 선택합니다.
6단계: 보안 설정 (Allowlist)
반드시 수행하세요! 초기 페어링 모드에서는 봇 주소를 아는 누구나 메시지를 보낼 수 있습니다. 본인만 사용할 수 있도록 접근 정책을 변경해야 합니다.
Claude Code 프롬프트에 아래 명령어를 입력합니다:
/telegram:access policy allowlist
승인(Yes)을 누르면:
- 허용 목록(Allowlist)에 등록된 본인만 소통 가능
- 타인의 접근이 완전히 차단됩니다
왜 필요한가요? Allowlist 없이는 누구나 봇을 통해 Claude에 접근할 수 있어 보안 위험이 있습니다.
7단계: 연동 테스트
7-1. 간단한 메시지 테스트
텔레그램 봇 채팅창에 입력합니다:
Hi Claude
Claude Code 터미널에 메시지가 표시되고 응답이 오면 연동 성공입니다!
7-2. 작업 명령 테스트
텔레그램에서 실제 작업 명령을 보내봅니다:
현재 디렉토리에 index.html 파일 만들어줘
Claude Code가 요청을 수신하고 작업을 수행한 뒤, 텔레그램으로 결과를 돌려보내는 것을 확인합니다.
문제 해결 (트러블슈팅)
| 증상 | 해결 방법 |
|---|---|
bun: command not found |
Bun 설치 후 터미널을 새로 열었는지 확인. Windows는 PowerShell 재시작 |
| 플러그인 설치 실패 | 인터넷 연결 확인. /plugin marketplace update claude-plugins-official 실행 후 재시도 |
--channels 실행 후 채널 메시지가 안 나옴 |
플러그인이 정상 설치되었는지 확인. Claude Code 완전 종료 후 재시작 |
| 텔레그램 봇에서 페어링 코드가 안 옴 | 봇에 /start 다시 입력. BotFather에서 토큰이 맞는지 확인. --channels 플래그로 실행했는지 확인 |
/telegram:access pair 실패 |
코드를 정확히 입력했는지 확인. 시간이 지나면 코드가 만료될 수 있으니 /start로 새 코드를 받으세요 |
| 페어링 후에도 메시지가 안 옴 | Claude Code 재시작 시 반드시 --channels plugin:telegram@claude-plugins-official 플래그를 포함했는지 확인 |
| API 토큰 오류 | BotFather에서 /token 명령으로 토큰 재확인. /telegram:configure로 다시 설정 |
| Windows에서 Claude Code가 실행 안 됨 | Node.js 및 npm이 설치되어 있는지 확인. PowerShell 관리자 권한으로 실행 |
Windows 사용자 참고 사항
- 터미널 선택: PowerShell 또는 Windows Terminal 사용을 권장합니다. 기본 명령 프롬프트(cmd)도 가능하지만, PowerShell이 더 안정적입니다.
- 경로 구분자: Windows에서는 파일 경로에
\(백슬래시)를 사용하지만, Claude Code 내 명령어에서는/를 사용해도 무방합니다. - 방화벽: Windows Defender 방화벽이 연결을 차단할 수 있습니다. Claude Code나 Bun이 네트워크 접근을 요청하면 허용을 선택하세요.
- 백그라운드 실행: 텔레그램 연동을 유지하려면 Claude Code 터미널 창을 열어 둔 채로 유지해야 합니다. 터미널을 닫으면 연결이 끊어집니다.
참고: 전체 명령어 요약 (Quick Reference)
# 0. Bun 설치 (macOS/Linux)
curl -fsSL https://bun.sh/install | bash
# 0. Bun 설치 (Windows PowerShell 관리자 권한)
# powershell -c "irm bun.sh/install.ps1 | iex"
# 1. Claude Code 실행
claude
# 2. 텔레그램 플러그인 설치
/plugin install telegram@claude-plugins-official
# 3. API 토큰 설정 (BotFather에서 발급받은 토큰)
/telegram:configure YOUR_BOT_TOKEN
# 4. Claude Code 종료 후 --channels 플래그로 재시작
exit
claude --channels plugin:telegram@claude-plugins-official
# 5. 텔레그램 봇에서 받은 6자리 페어링 코드로 연결
/telegram:access pair YOUR_6DIGIT_CODE
# 6. 보안 설정 (Allowlist)
/telegram:access policy allowlist
추가 활용
- 커스텀 채널 확장: Anthropic의 'Build your own channel' 문서를 참고하면 텔레그램 외에도 자체 서비스(SaaS 등)에서 Claude 세션에 프롬프트를 직접 보내는 구조를 만들 수 있습니다.
- Discord 연동: 디스코드 개발자 포털(Developer Portal)에서 봇을 생성하고 토큰을 발급받은 뒤, 비슷한 과정으로 플러그인을 연동할 수 있습니다.
- 활용 예시: 슬랙 봇, 디스코드 봇, 자체 웹 대시보드 등에서 Claude Code로 작업 지시 가능