텔레그램 봇 개발 일지 #1 — Claude Code를 텔레그램으로 부리기

결론부터

텔레그램 봇 하나로 Claude Code를 호출할 수 있게 만들었다. 화이트리스트 기반 1인 운영 — BotFather 토큰과 본인 user ID만 넣으면, 어디서든 채팅으로 작업이 돌아간다.

왜 시작했나

데스크톱 Claude Code는 키보드 앞에 앉아 있어야 한다. 출퇴근길이나 외출 중에 떠오르는 짧은 작업, 빌드 결과 확인, 간단한 커밋 같은 걸 모바일에서 처리하고 싶었다.

기존 대안은 모두 어딘가 무거웠다:

• Claude 모바일 앱은 코드 실행과 파일 수정이 안 된다
• SSH + tmux는 모바일 키보드로 명령 치는 게 번거롭다
• 웹 기반 IDE는 인증·세션 유지가 부담스럽다

텔레그램 봇이라면 이미 모바일에 항상 떠 있고, 슬래시 명령·토픽 분리로 멀티 프로젝트 관리까지 자연스럽다.

1일차에 한 일

골자는 세 덩이다.

봇 골격

python-telegram-bot v21로 polling 봇을 띄우고 /start, /whoami 같은 기본 명령을 붙였다. TELEGRAM_ALLOWED_USER_IDS 환경변수로 화이트리스트만 응답하도록 막았다.

ALLOWED = {int(x) for x in os.environ["TELEGRAM_ALLOWED_USER_IDS"].split(",")}
 
async def gate(update, _):
    if update.effective_user.id not in ALLOWED:
        return  # silently ignore

비-화이트리스트 멤버는 조용히 무시한다. 그룹에 다른 사람이 있어도 안전하다.

Claude Code 호출

claude-agent-sdk(Python)로 메시지 텍스트를 그대로 Claude에 넘기고, 응답을 텔레그램으로 다시 보낸다. permission mode는 default로 시작 — 인라인 Allow/Deny 버튼이 도구 호출 전에 한 번씩 끼어들어 안전 검증을 해준다.

라이브 메시지

긴 응답을 한 메시지에 editMessage로 점진적으로 덮어쓰는 방식이 가장 깔끔했다. 텔레그램 rate limit과 메시지당 4096자 제약 때문에 throttle과 분할이 필요했고, 도구 호출 라인은 최근 N줄만 보여줘 가독성을 잡았다.

다음 편 예고

2일차에는 음성 입력(Whisper), 이미지 첨부 처리, 그리고 MCP 서버 통합(Playwright, blog)을 다룬다.