클로드 코드 텔레그램 봇 설치
지난 시간에 클로드 코드 설치까지 완료했습니다. 그럼 이번 시간에는 텔레그램 연결입니다. 카톡하듯 "이 코드 좀 고쳐줘"라고 보내면, 연구실에 있는 맥미니에서 Claude Code가 알아서 실행하고 결과를 텔레그램으로 돌려주는 구조입니다. 그럼 지금부터 같이 가 보실까요?
이 글은 실제 설치 과정을 그대로 기록한 것입니다. 중간에 헤맨 부분도 숨기지 않았으니, 같은 삽질을 피하시는 데 도움이 되길 바랍니다.
저도 처음에 이 의문이 들었습니다. 어차피 둘 다 사람이 시켜야 하는 건 마찬가지 아닌가? 맞습니다. 차이는 시킨 다음에 일어나는 일에 있습니다.
클로드(claude.ai)에서 "이 CSV 분석해줘"라고 하면, 코드를 화면에 보여줍니다. 제가 그걸 복사하고, 터미널을 열고, 붙여넣고, 실행합니다. 에러가 나면 다시 클로드한테 물어보고, 또 복사하고, 또 붙여넣습니다. 시키는 건 한 번인데, 중간에 사람 손이 계속 끼어드는 구조입니다.
텔레그램 봇의 클로드 코드는 다릅니다. 같은 말을 시키면 알아서 코드를 짜고, 실행하고, 에러가 나면 스스로 고쳐서 다시 돌리고, 최종 결과만 보내줍니다. 거기에 더해 제 맥의 파일에 직접 접근하니까, "projects 폴더에 있는 어제 데이터 다시 돌려줘"가 가능합니다. 폰에서요.
시작하기 전에 맥의 현재 상태를 확인해야 합니다. 터미널을 열고 아래를 실행해 보세요.
python3 --version && node --version && docker --version && git --version
제 결과는 이랬습니다.
Python 3.9.6
v25.8.0
zsh: command not found: docker
Node.js와 Git은 있고, Python은 버전이 낮고(3.11 이상 필요), Docker는 없었습니다. 지난 글에서 Claude Code를 이미 설치해 뒀으니, 그 부분은 넘어갑니다. 아직 설치 전이시라면 이전 글을 참고해 주세요.
이 프로젝트를 돌리려면 Python 3.11 이상이 필요합니다. 처음에는 Docker로 돌리면 맥의 Python 버전과 상관없이 되겠다 싶어서 Docker부터 설치했습니다. 그런데 막상 프로젝트를 받아보니 docker-compose.yml 파일이 없었습니다. Poetry 기반 프로젝트였던 거죠. 결국 Python을 직접 업그레이드하는 방향으로 갔는데, Docker 설치 자체는 나중에 다른 데서 쓸모가 있으니 해두시는 걸 추천합니다.
https://www.docker.com/products/docker-desktop/ 에서 다운로드합니다. 맥 칩 종류를 모르시겠으면 터미널에서 이렇게 확인하세요.
uname -m
arm64가 나오면 Apple Silicon, x86_64가 나오면 Intel 버전을 받으시면 됩니다. 다운받은 .dmg를 열고 Docker를 Applications에 드래그하면 설치 끝입니다.
Docker Desktop을 실행하면 로그인하라는 화면이 나옵니다. 오른쪽 상단의 Skip을 누르세요. 로그인 안 해도 됩니다.
확인은 터미널에서:
docker --version
버전 번호가 나오면 성공입니다.
이 프로젝트는 Python 3.11 이상과 Poetry라는 패키지 관리자가 필요합니다. 지난 글에서 설치했던 Homebrew가 여기서 다시 활약합니다.
brew install python@3.12 poetry
이 한 줄이면 두 개 다 설치됩니다. 설치가 끝나면 Homebrew가 친절하게 경로 안내를 해주는데, 딱히 뭘 더 하지 않아도 됩니다.
텔레그램에서 봇을 만들어야 합니다. 처음엔 뭔가 복잡할 것 같았는데, 의외로 간단합니다.
텔레그램 앱에서 @BotFather를 검색해서 대화를 엽니다
/newbot을 입력합니다
봇 이름을 입력합니다 (예: "My Claude Agent")
봇 유저네임을 입력합니다 (반드시 bot으로 끝나야 합니다)
BotFather가 봇 토큰을 줍니다
토큰은 이런 형태입니다: 7123456789:AAF1234abcd5678efgh-ijklmnop. 숫자, 콜론, 영문숫자 조합 전체가 토큰입니다. 이걸 메모해 두세요. 이 토큰이 있으면 누구나 여러분의 봇을 제어할 수 있으니, 절대 외부에 공개하지 마세요.
그 다음 본인의 텔레그램 유저 ID를 확인합니다. @userinfobot을 검색해서 아무 메시지나 보내면 숫자 ID를 알려줍니다. 이것도 메모해 둡니다.
여기서부터 집중이 필요합니다. 터미널에서 순서대로 실행하세요.
cd ~
git clone https://github.com/RichardAtCT/claude-code-telegram.git
cd claude-code-telegram
cp .env.example .env
Claude Code가 접근할 작업 디렉토리도 만들어 줍니다.
mkdir -p /Users/내맥유저네임/projects
이제 설정 파일을 편집합니다.
nano .env
nano 에디터가 열리면 화살표 키로 이동하면서 아래 항목들을 찾아 값을 넣습니다. Ctrl+W를 누르면 검색이 되니까, 항목 이름을 검색해서 찾으시면 편합니다.
TELEGRAM_BOT_TOKEN=BotFather에서_받은_토큰_전체
TELEGRAM_BOT_USERNAME=봇_유저네임(골뱅이_없이)
APPROVED_DIRECTORY=/Users/내맥유저네임/projects
ALLOWED_USERS=텔레그램_유저_ID_숫자
여기서 제가 한번 헤맸던 부분을 말씀드리겠습니다. APPROVED_DIRECTORY의 기본값이 /path/to/your/projects로 되어 있거든요. 이걸 그대로 두고 실행했더니 "Approved directory does not exist"라는 에러가 나면서 봇이 안 뜹니다. 반드시 실제 존재하는 경로로 바꿔야 합니다.
ALLOWED_USERS도 반드시 채워 넣으세요. 비어 있으면 누구나 봇을 쓸 수 있게 됩니다. 내 맥에서 아무나 코드를 실행할 수 있다는 뜻이니까요.
편집이 끝나면 Ctrl+X를 누릅니다. 저장하겠냐고 물으면 Y, 파일 이름을 확인하라고 하면 그냥 Enter. 처음 보시면 "File name to write: .env"라는 메시지에 당황하실 수 있는데, 그냥 엔터 한 번이면 됩니다.
Docker가 안 되니 직접 실행해야 합니다. 터미널에서 make dev를 치면 되는데, 이 프로젝트는 Poetry라는 패키지 관리자를 씁니다. Step 2에서 이미 설치해 뒀으니 바로 실행하면 됩니다.
make dev
Poetry가 필요한 패키지들을 쭉 설치합니다. 좀 시간이 걸릴 수 있어요. 마지막에 "pre-commit not configured yet"이라는 메시지가 나올 수 있는데, 무시하셔도 됩니다.
설치가 끝났으면 이제 봇을 켜봅니다.
make run
로그가 올라가면서 "Starting bot"이 보이면 성공입니다. 이 터미널 창은 그대로 열어 두세요. 닫으면 봇도 꺼집니다.
자, 텔레그램으로 갑니다. 여기서 제가 또 한 번 헤맸는데요. BotFather한테 메시지를 보냈습니다. 당연히 대답이 없죠. BotFather는 봇을 만들어주는 봇이지, 제 봇이 아닙니다. 본인이 만든 봇의 유저네임을 검색해서 대화를 열어야 합니다.
"hello"라고 보내 봅니다.
대답이 왔습니다. 성공입니다!
기쁨도 잠시, 이 구조의 의미를 짚어봐야 합니다. 텔레그램 메시지가 곧 내 맥의 셸 명령이 될 수 있다는 뜻이거든요. 편리한 만큼 위험할 수도 있습니다.
몇 가지를 반드시 지켜야 합니다.
ALLOWED_USERS에 본인 ID만 등록합니다.
APPROVED_DIRECTORY를 최소한의 작업 폴더로 제한합니다. /, /home, /etc 같은 민감한 경로는 절대 넣지 마세요. 비용 상한도 설정해 두시는 게 좋습니다. .env 파일에 CLAUDE_MAX_COST_PER_USER=5.0 같은 값을 넣으면 됩니다.
참고로 Claude Code 자체에도 보안 이력이 있습니다. 2026년 초에 악성 저장소에서 API 키가 탈취될 수 있는 취약점이 발견되어 수정된 바 있고요. Claude Code를 항상 최신 버전으로 유지하는 것이 중요합니다.
봇이 돌아가고 있으니, 이런 것들을 시켜볼 수 있습니다.
"projects 폴더에 어떤 파일이 있는지 보여줘"
"Python 스크립트 하나 만들어서 실행해줘"
"이 CSV 파일 읽어서 그래프 그려줘"
파일을 텔레그램으로 직접 보내서 분석을 시킬 수도 있습니다.
한 가지 주의하실 점은, Claude Code가 데이터를 "생성"해주는 것과 실제 데이터를 "분석"해주는 것은 전혀 다르다는 겁니다. "알루미늄 합금 인장 데이터 만들어줘"라고 하면 그럴듯한 합성 데이터를 만들어 주긴 하는데, 이건 물리적 상관관계가 보장되지 않는 가짜 데이터입니다. Claude Code의 진짜 가치는 데이터 자체가 아니라, 내가 가진 진짜 데이터를 처리하고 분석하는 코드를 짜고 실행해 주는 데 있습니다.
공개 데이터베이스를 활용하는 것도 가능합니다. Materials Project 같은 곳에서 API 키를 발급받아 "이 API 키로 Al-Zn-Mg-Cu 합금 데이터 가져와줘"라고 시키면, 실제 데이터를 가져와서 엑셀로 정리해 줍니다.
이 오픈소스 프로젝트를 쓰는 방식은 빠르게 시작할 수 있지만, 남이 만든 코드 구조에 종속된다는 단점이 있습니다. 내가 원하는 특정 워크플로우를 넣으려면 남의 코드를 읽고 수정해야 하니까요.
더 자유롭게 쓰고 싶다면 Claude Agent SDK와 python-telegram-bot을 사용해 처음부터 직접 만드는 방법이 있습니다. 초기 개발에 시간이 더 걸리지만, 자기만의 명령어 체계와 권한 구조를 설계할 수 있죠.
저는 일단 이 상태로 써보면서, 한계를 느끼면 직접 구축하는 쪽으로 전환할 생각입니다. 텔레그램 봇은 이미 만들어 놨으니 그건 그대로 쓰면 되고요.
Docker Desktop 설치
Homebrew로 Python 3.12, Poetry 설치
텔레그램에서 @BotFather로 봇 생성, @userinfobot으로 유저 ID 확인
GitHub에서 프로젝트 클론, .env 파일 설정
make dev로 의존성 설치
make run으로 봇 실행
텔레그램에서 본인 봇에게 말 걸기
맥 앞에 앉아 있지 않아도, 폰에서 텔레그램 메시지 하나로 내 컴퓨터에게 일을 시킬 수 있습니다. 이게 가능하다는 걸 아는 것과 실제로 해보는 것 사이에는 꽤 큰 차이가 있었습니다. 다음 글에서는 이걸 실제로 어떻게 활용하고 있는지, 그리고 한계를 느끼고 직접 구축하게 되는 과정을 이야기해 보겠습니다.