HappyCapy를 텔레그램에 연결하는 방법: 모든 채팅에서 완전한 AI 에이전트 실행하기
모든 도구, 스킬, 기능을 갖춘 HappyCapy 에이전트를 텔레그램에서 바로 사용해보세요.
대부분의 텔레그램 봇은 질문에 답할 뿐입니다. HappyCapy의 텔레그램 브릿지는 claude --print를 실행합니다 — 메시지를 보낼 때마다 Bash 접근, 파일 작업, 웹 검색, 이미지 생성, 그리고 300,000개 이상의 Skills를 갖춘 완전한 Claude Code 세션이 실행됩니다. 웹사이트를 스크래핑하거나, Python 스크립트를 작성해 실행하거나, 동영상을 생성하도록 요청해 보세요. 실제로 해냅니다. 이것은 챗봇이 아닙니다. 텔레그램 채팅 안에 살고 있는 에이전트입니다.
텔레그램 봇과 다른 이유
텔레그램 봇을 만드는 것은 주말 프로젝트 수준입니다. BotFather에 등록하고, 토큰을 받고, 텔레그램 Bot API를 호출하고, 들어온 메시지를 LLM API에 전달하고, 응답을 반환합니다. 그 결과물은 정교한 자동완성 기계일 뿐입니다. 파일 시스템도 없고, 코드를 실행할 수도 없고, 워크플로우를 트리거할 수도 없습니다. LLM API가 단일 상태 없는(stateless) 응답 안에서 할 수 없는 일은 아무것도 할 수 없습니다.
HappyCapy의 아키텍처는 모든 계층에서 다릅니다. HappyCapy는 Fly.io 위에서 항상 켜져 있는(always-on) Linux 샌드박스로 실행됩니다 — root 접근 권한, Python 3.11, Node.js v24, 영구 파일 저장소를 갖추고 있습니다. 텔레그램 메시지가 도착하면 브릿지는 사용자의 메시지를 입력값으로 claude --print를 호출합니다. 이 호출은 Bash 실행, 파일 읽기/쓰기, 웹 검색, 이미지 생성, 동영상 생성, 그리고 300,000개 이상의 Skills 라이브러리 전체에 대한 완전한 도구 접근 권한을 갖습니다. 에이전트는 새 셸을 열고, 스크립트를 실행하고, 출력을 읽고, 이를 다시 사용자에게 보낼 수 있습니다 — 모두 같은 대화 턴 안에서 이루어집니다.
이 두 접근 방식 사이의 실질적인 격차는 점진적인 수준이 아닙니다. 일반적인 텔레그램 봇은 날씨를 알려줄 수 있습니다. HappyCapy의 텔레그램 봇은 세 개의 API에서 날씨 데이터를 가져오는 코드를 작성하고, 비교하고, 차트를 그리고, PNG로 저장한 뒤 이미지로 전송할 수 있습니다 — 텔레그램을 떠나지 않고 단 하나의 메시지로 말입니다.
| 기능 | 일반 텔레그램 봇 | HappyCapy 텔레그램 봇 |
|---|---|---|
| 질문에 답변 | 가능 | 가능 |
| Bash 명령 실행 | 불가 | 가능 |
| 코드 작성 및 실행 | 불가 | 가능 |
| 영구 파일 접근 | 불가 | 가능 |
| AI 이미지 생성 | 불가 (별도 통합 필요) | 가능, 기본 지원 |
| 동영상 생성 | 불가 | 가능 |
| 웹 스크래핑 | 불가 | 가능 |
| 300,000개 이상의 Skills 접근 | 불가 | 가능 |
| 내 컴퓨터 없이 24/7 작동 | 불가 | 가능 (Fly.io 상시 가동) |
| 사용자별 대화 기록 | 제한적 | 완전하고 영구적 |
실제로 할 수 있는 것들
이 기능 목록은 이론이 아닙니다. 오늘날 사용자들이 실제로 하고 있는 일입니다:
- 봇에게 웹사이트를 스크래핑하고 구조화된 데이터를 표나 JSON으로 반환하도록 요청
- Python 스크립트를 작성하고 샌드박스에서 실행한 뒤 stdout을 반환받기 — IDE가 필요 없음
- 프롬프트로부터 AI 이미지를 생성해 텔레그램 채팅에서 직접 받아보기
- 대화 도중 HappyCapy의 300,000개 이상의 Skills 중 아무거나 실행 — PDF 생성, 스프레드시트 작성, PPTX 슬라이드, 오디오 합성
- 웹을 검색하고, 여러 출처를 읽고, 출처가 포함된 종합 요약을 반환받기
- 파일을 영구 저장소에 생성하고 저장한 뒤, 이후 메시지에서 다시 불러오거나 업데이트하기
- 예약 작업 실행: 에이전트가 매일 아침 스크립트를 실행하고 결과를 메시지로 보내줄 수 있음
- URL이나 API 엔드포인트를 모니터링하고 변화가 있을 때 알림 받기
- 업로드된 문서 처리 — CSV 링크를 붙여넣으면 분석 결과를 받기
- 다섯 개의 서로 다른 도구를 오가며 해야 했을 다단계 워크플로우를 하나로 연결하기
장점
- 항상 켜져 있고, 노트북이 필요 없습니다. 샌드박스는 Fly.io 인프라에서 실행됩니다. 새벽 2시에 휴대폰으로 봇에게 메시지를 보내면 절대 직접 손댈 필요 없는 서버에서 코드가 실행됩니다.
- 모든 것을 위한 단일 인터페이스. Claude를 열고, 코드 에디터를 열고, 브라우저를 열고, 이미지 도구를 여는 대신 — 텔레그램 메시지 하나로 모든 것이 실행됩니다.
- 맥락이 유지됩니다. 대화 기록은 사용자별로 저장됩니다. 3일 전에 물어봤던 것을 다시 설명하지 않고도 참조할 수 있습니다.
- 샌드박스 내 완전한 root 권한. 에이전트는 패키지를 설치하고, 파일을 작성하고, 어떤 유닉스 명령이든 실행할 수 있습니다. 소비자용 챗봇이 부과할 만한 제약이 없습니다.
- 300,000개 이상의 Skills를 즉시 사용 가능. HappyCapy Skill로 패키징된 워크플로우는 문장 하나 거리에 있습니다.
- 공유 가능. 동료나 클라이언트에게 봇 사용자명을 알려주세요. 여러 사용자가 동시에 상호작용할 수 있으며, 각자 독립된 대화 기록을 갖습니다.
- 무료 티어 제공. 텔레그램 브릿지 자체는 기존 HappyCapy 플랜 위에 추가 비용을 발생시키지 않습니다.
실제 사용 사례
사무실에 노트북을 두고 나온 프리랜서 개발자. 커밋을 푸시했는데 배포 로그에서 버그를 발견했고, 이미 문을 나선 상황입니다. 휴대폰으로 봇에게 메시지를 보냅니다: "서버에서 최신 배포 로그를 가져와서 847번째 줄이 무슨 문제인지 알려줘." 30초 후 답을 받습니다. 다시 메시지를 보냅니다: "패치를 작성하고 PR을 열어줘." 완료. 노트북을 열 필요가 없었습니다.
매일 지표를 모니터링하는 소상공인. 매일 아침 다섯 개의 대시보드에 로그인하는 대신, 봇이 예약된 요약 보고서를 실행합니다. 매일 오전 8시: Stripe에서 매출 데이터를, 분석 API에서 방문자 수를, Shopify에서 재고 수준을 가져옵니다. 요약을 정리해 첫 커피를 마시기도 전에 텔레그램 메시지로 보내줍니다. 설정은 봇과의 대화 한 번으로 끝났습니다.
빠른 데이터 추출이 필요한 연구자. 논문을 읽으면서 세 개의 다른 출처에서 데이터셋을 교차 참조하고 싶습니다. 브라우저로 전환해서, 각 출처로 이동하고, CSV를 다운로드하고, 비교를 실행하는 데 20분이 걸립니다. 봇에게 URL과 필요한 내용을 설명하는 메시지를 보내면 2분이면 끝납니다. 봇이 스크래핑하고, 파싱하고, 비교한 뒤 표를 반환합니다.
숙제 도우미를 설정한 부모. 아이들은 이미 텔레그램 계정을 갖고 있습니다. HappyCapy 봇이 가족 그룹에 추가되었습니다. 수학 문제를 단계별로 설명하고, 다이어그램을 생성하고, 연습 문제를 작성하고, 답을 확인할 수 있습니다 — 광고도 없고, 계정 생성도 필요 없고, 소비자용 챗봇 특유의 산만함도 없습니다. 부모는 관리자 토큰을 갖고, 아이들은 집중력을 흐트러뜨리지 않는 도구를 갖게 됩니다.
설정 방법
HappyCapy 계정이 있다면 설정은 5분도 걸리지 않습니다. 과정은 텔레그램의 BotFather에서 시작됩니다: @BotFather에게 메시지를 보내고, /newbot을 실행하고, 이름을 선택하면 봇 토큰을 받게 됩니다 — 7384920156:AAF...와 같은 형식의 문자열입니다. HappyCapy가 대화를 어디로 라우팅해야 하는지 아는 데 필요한 것은 이 토큰뿐입니다.
HappyCapy 내부에서는 텔레그램 스킬이 나머지를 처리합니다. 스킬을 실행하고, 요청 시 봇 토큰을 붙여넣으면 브릿지가 활성화됩니다. 스킬은 샌드박스 안에서 폴링 루프를 시작해 들어오는 텔레그램 메시지를 감지하고, 완전한 도구 접근 권한을 가진 claude --print를 통해 라우팅합니다. 대화 기록은 텔레그램 사용자 ID별로 저장되므로, 봇에게 메시지를 보내는 각 사람은 자신만의 영구 세션을 갖게 됩니다.
설정 스크립트, 환경 변수 문서, 속도 제한 및 사용자 허용 목록에 대한 구성 옵션이 포함된 전체 스킬은 github.com/ndpvt-web/happycapy-telegram에서 확인할 수 있습니다. 시작하기 전에 HappyCapy의 에이전트 아키텍처가 일반적인 챗봇 설정과 왜 다른지 더 깊이 이해하고 싶다면 AI Agent vs Chatbot에서 그 차이를 자세히 다루고 있습니다. 그리고 Fly.io에 의존하는 대신 자체적인 영구 AI 인프라를 운영하는 것을 고려하고 있다면, Mac Mini as AI Server 2026 분석을 먼저 읽어볼 가치가 있습니다.
자주 묻는 질문
봇은 24/7 작동하나요, 아니면 제 컴퓨터가 켜져 있을 때만 작동하나요? 24/7 작동합니다. 샌드박스는 로컬 기기가 아니라 Fly.io 인프라에서 실행됩니다. 텔레그램 스킬을 배포하고 나면, 컴퓨터가 켜져 있거나 인터넷에 연결되어 있지 않아도 계속 살아 있습니다.
봇이 제 HappyCapy 파일과 도구에 접근할 수 있나요? 가능합니다. 봇은 사용자의 HappyCapy 샌드박스 안에서 실행되므로, 저장한 파일, 설치한 스킬, 설정한 환경 변수, 연결한 통합 등 해당 환경의 모든 것에 접근할 수 있습니다. 이것은 다른 인터페이스를 통해 접근하는 사용자 자신의 에이전트입니다.
이것은 무료로 사용할 수 있나요? 텔레그램 브릿지 스킬 자체는 무료입니다. 비용은 샌드박스 컴퓨팅과 AI 모델 사용을 포함하는 HappyCapy 플랜에 따라 결정됩니다. 텔레그램 통합 계층에 대한 추가 요금은 없습니다.
사용자별 대화 기록은 어떻게 작동하나요? 각 텔레그램 사용자 ID는 샌드박스에 저장된 자신만의 대화 스레드를 갖습니다. 사용자 A가 메시지를 보내면 봇은 사용자 A의 기록을 불러와 새 턴을 추가합니다. 사용자 B의 메시지는 완전히 분리되어 있습니다. 기록은 세션 간에도 영구적으로 유지되므로, 일주일 전에 나눈 대화도 명시적으로 삭제하지 않는 한 맥락 안에서 계속 접근 가능합니다.
봇을 사용할 수 있는 사람을 제한할 수 있나요? 가능합니다. 이 스킬은 허용 목록(allowlist) 구성을 지원합니다. 봇과 상호작용할 수 있는 텔레그램 사용자 ID나 사용자명 목록을 지정할 수 있습니다. 허용 목록에 없는 사용자의 메시지는 조용히 무시되거나 사용자 지정 거부 메시지를 반환합니다 — 선택은 자유입니다.
텔레그램이 봇의 속도를 제한하면 어떻게 되나요? 스킬은 지수 백오프(exponential backoff)로 속도 제한을 처리합니다. 텔레그램이 429 응답을 반환하면 브릿지는 일시 정지하고, 필요한 재시도 기간만큼 기다린 뒤 자동으로 재개합니다. 메시지가 유실되지 않습니다. 실제로 속도 제한은 동시 부하가 클 때만 발생하며, 이는 스킬 설정에서 구성할 수 있습니다.
여러 사람이 동시에 봇을 사용할 수 있나요? 가능합니다. 폴링 루프는 메시지를 비동기적으로 처리하며, 각 사용자 세션은 독립적입니다. 한 사용자가 처리되는 동안 다른 사용자를 막는 대기열은 없습니다. 매우 높은 부하 상황에서는 Fly.io에서 샌드박스 인스턴스를 확장해 더 많은 동시 세션을 처리할 수 있습니다 — 이 구성은 스킬 문서에서 다루고 있습니다.
마치며
텔레그램 통합은 그 자체를 위한 기능이 아닙니다 — 이는 사용자와 완전한 기능을 갖춘 AI 에이전트 사이의 마지막 마찰 지점을 제거합니다. HappyCapy 샌드박스는 이미 코드를 실행하고, 미디어를 생성하고, 300,000개 이상의 Skills를 조율합니다. 텔레그램 브릿지는 사용자가 이미 있는 곳에서, 맥락 전환 없이 이 모든 것에 접근할 수 있다는 것을 의미합니다. 원격으로 디버깅하는 새벽 2시에 유용하든, 노트북을 열기 전 아침마다 구조화된 브리핑을 원할 때 유용하든 — 이것은 동일한 에이전트이며, 이제 모든 사람의 주머니 속에서 사용할 수 있습니다.
