Claude Code를 텔레그램 봇에 붙였다 - 설정부터 상시 운영까지
휴대폰에서 내 PC의 Claude Code를 쓰고 싶었다. Anthropic 공식 Channels 기능으로
텔레그램 봇을 연결할 수 있길래 해봤다.
결론부터 말하면 잘 된다. 텔레그램에서 "오늘 뭐 할지 정리해줘" 하고 보내면
PC에서 Claude가 받아서 답장한다. 지금은 PC를 켜면 봇이 자동으로 살 아나도록
등록까지 마쳤다.
처음부터 끝까지, 막혔던 지점까지 포함해서 정리한다. Windows 기준이다.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. 준비물 두 가지
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ 텔레그램 봇 토큰 ]
텔레그램에서 @BotFather 를 검색해 대화를 연다. 텔레그램 공식 봇 관리 봇이다.
1) /newbot 입력
2) 봇 표시 이름 입력 - 아무거나 (예: 내 클로드)
3) 봇 아이디 입력 - 반드시 bot 으로 끝나야 한다 (예: myname_claude_bot)
4) 123456789:AAH... 형태의 토큰이 나온다. 복사해둔다
이 토큰이 봇의 비밀번호다. 노출되면 남이 내 봇을 조종할 수 있으니 주의.
만든 봇은 텔레그램 검색창에 아이디를 넣으면 찾을 수 있다. 대화창을 열면
아래에 START 버튼이 뜨는데, 이걸 눌러야 봇이 내 메시지를 받기 시작한다.
[ Bun 설치 ]
플러그인이 Bun 런타임으로 돌아간다. PowerShell에서 아래를 실행한다.
powershell -c "irm bun.sh/install.ps1|iex"
주의! 설치 후 PowerShell을 완전히 닫고 새로 열어야 인식된다.
bun --version 으로 확인.
(이걸 안 지켜서 나중에 크게 헤맸다. 뒤에 나온다)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2. 설정 순서
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Claude Code 입력창에서 차례로 입력한다.
/plugin install telegram@claude-plugins-official
/reload-plugins
/telegram:configure 복사해둔토큰
설치 범위를 묻거든 user scope 를 고르면 모든 프로젝트에서 쓸 수 있다.
그다음 /exit 로 나가서 옵션을 붙여 다시 켠다.
claude --channels plugin:telegram@claude-plugins-official
이제 텔레그램에서 내 봇에게 아무 메시지나 보내면 페어링이 진행된다.
봇이 6자리 코드를 보내주면 아래로 등록한다.
/telegram:access pair 받은코드
(내 경우엔 세션 안에서 자동 승인되어 코드 입력 없이 Paired! 가 떴다.
두 경로가 다 있는 듯하다)
마지막으로 잠근다.
/telegram:access policy allowlist
이건 꼭 하자. 안 하면 봇 아이디를 아는 사람이 내 PC의 Claude Code에
명령을 보낼 수 있다.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
3. 막혔던 두 지점
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ 실행 옵션을 빼먹었다 ]
플러그인 설치하고 토큰 넣고 재실행했는데 봇이 묵묵부답이었다.
원인은 그냥 claude 만 친 것.
채널은 실행 옵션으로 켜진다. 플러그인이 설치돼 있어도 --channels 를
안 붙이면 아무 일도 일어나지 않는다.
claude --help 에 이 옵션이 안 나와서 더 헷갈렸는데, 리서치 프리뷰라
목록에서 빠져 있을 뿐 정상 작동한다.
[ Bun을 나중에 설치했다 ]
옵션을 붙였는데도 안 됐다. /status 는
Channels: Listening for messages from plugin:telegram...
이라 정상처럼 보였다. 그런데 /mcp 를 열어보니 telegram이 failed.
상세 화면에 Command: bun.
Bun은 분명 설치돼 있었다. 문제는 Claude Code를 켠 뒤에 설치했다는 것.
프로세스는 실행 시점의 환경을 그대로 들고 간다. Reconnect 를 눌러도
소용없다.
PowerShell을 완전히 닫고 새로 열어 bun --version 을 확인한 뒤
재실행하니 바로 connected. 봇에게 인사를 보내니 답장이 왔다.
[ 정리하면 ]
- /status 의 Listening은 "옵션이 먹었다"는 뜻일 뿐 "봇이 작동한다"는
뜻이 아니다. 실제 판정은 /mcp 에서 connected 가 뜨는지로 한다
- 환경변수를 건드렸으면 터미널을 새로 열어라.
오래된 교훈인데 또 당했다
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
4. PC를 켜면 자동으로 뜨게 하기
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
여기서 중요한 제약이 하나 있다. Claude Code 세션이 살아 있는 동안만
봇이 작동한다. 창을 닫으면 봇도 멈춘다.
매번 손으로 켜기 번거로워서 시작프로그램에 등록했다.
[ 메모장으로 하다가 실패했다 ]
.bat 파일을 만들려고 메모장을 썼는데, 그냥 저장하면 claude-bot.bat.txt
가 된다. 파일 형식을 "모든 파일"로 바꿔야 하는데 이걸 놓쳤다.
어디 저장됐는지도 못 찾았다.
[ PowerShell 한 줄로 해결 ]
결국 이 방법이 제일 확실했다. PowerShell에 붙여넣기만 하면 된다.
(아래는 한 줄이다. 줄바꿈 없이 통째로 복사할 것)
Set-Content -Path "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Startup\claude-bot.bat" -Encoding ASCII -Value '@echo off', 'cd /d C:\Users\사용자명', 'powershell -NoExit -Command "claude --channels plugin:telegram@claude-plugins-official"'
C:\Users\사용자명 부분만 본인 경로로 바꾸면 된다.
확인은 아래로 한다.
dir "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Startup"
목록에 claude-bot.bat 이 보이면 완료. 더블클릭해서 Claude Code가
뜨는지 테스트해보자.
참고로 .bat 은 기본적으로 구식 명령 프롬프트(cmd)에서 돌아가는데,
claude 명령어가 인식되지 않는 경우가 있다. 그래서 위 스크립트는
PowerShell을 명시적으로 띄워서 실행하도록 했다.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
5. 상시 운영할 때 주의할 점
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
창을 닫으면 안 된다. 최소화는 괜찮지만 닫기(X)나 /exit 는 봇을 멈춘다.
절전 모드에 들어가면 봇도 잠든다. 상시로 쓰려면 전원 설정에서
절전을 꺼두자.
대기 중에는 토큰을 소모하지 않는다. 메시지가 올 때만 작동하니
켜둬도 부담 없다.
권한 승인 창이 뜨면 세션이 멈춘다. 밖에 있는데 승인 창이 떠 있으면
봇이 답을 안 한다. auto mode를 켜두면 대부분 자동 처리되지만
완전하지는 않다.
진짜 24시간 운영하려면 미니PC나 NAS, 클라우드 VM에 올리는 게 맞다.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
6. 누구에게 좋을까
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
이미 텔레그램에 봇을 여러 개 굴리고 있다면 특히 잘 맞는다.
알림봇, 시세봇, 자동화봇이 있는 사람이라면 거기에 Claude가 하나 더
늘어나는 것뿐이다. 앱을 새로 깔 필요도, 새 창을 띄울 필요도 없다.
이미 하루에 수십 번 여는 앱 안에서 다 해결된다.
파일이나 사진을 그냥 봇에게 던지면 읽어서 정리해주는 것도 편하다.
채팅방이 곧 작업 큐가 된다.
반대로 "내 세션을 휴대폰에서 이어받고 싶다"가 전부라면
Remote Control 이 더 간단하다. 봇 토큰도 Bun도 상시 실행도 필요 없고,
claude.ai/code 나 Claude 모바일 앱에서 바로 이어받으면 된다.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
7. 비용
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Max, Pro 구독으로 로그인해 쓰면 별도 토큰 요금이 붙지 않는다.
텔레그램 봇 자체도 무료다.
다만 웹, 앱, Claude Code가 같은 사용량 한도를 나눠 쓴다.
휴대폰에서 편하게 던지다 보면 평소보다 한도가 빨리 준다.
한도를 넘기면 기다리거나, 상위 플랜으로 올리거나,
usage credits(API 요금 별도 청구)를 켜는 선택지가 있다.
credits는 직접 켜야만 작동하니 모르는 사이에 과금되지는 않는다.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
참고 링크
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Channels 공식 문서
https://code.claude.com/docs/en/channels
Remote Control 공식 문서
https://code.claude.com/docs/en/remote-control
telegram 플러그인 소스
https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram
Channels는 아직 리서치 프리뷰다. 명령어 형식이 바뀔 수 있으니
안 되면 공식 문서를 먼저 확인하자. Discord와 iMessage도 같은 방식으로
지원된다.
