Hermes Agent + Telegram 봇 만들기 — 10분 가이드

🤖 “텔레그램에서 AI한테 얘기하면 답해주는” — 2026년 가장 인기 있는 개인 AI 활용법.

Hermes Agent는 Nous Research가 만든 오픈소스 AI 에이전트 프레임워크예요. 이 가이드에서는 Hermes를 Telegram 봇과 연동해 어디서든 내 AI를 만나는 법을 알려드릴게요.

🎯 무엇을 만들 거예요?

• Telegram에서 /ai 안녕 입력하면 AI가 답장
• 메시지 스트리밍 응답 (타이핑하는 것처럼)
• 멀티모달 (이미지 입력 → 분석)
• 5분마다 자동 뉴스 알림 (보너스)

📋 사전 준비

소요 시간: 10분

STEP 1. Telegram 봇 만들기 (3분)

1-1. BotFather에서 봇 생성

1. Telegram에서 @BotFather 검색
2. /newbot 명령 입력
3. 봇 이름 입력: My AI Assistant
4. username 입력: my_ai_xxx_bot (반드시 “bot”으로 끝나야 함)
5. HTTP API 토큰 받기 (예: 7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx)

토큰은 비밀번호처럼 보관. Git에 절대 커밋 금지.

1-2. 본인 chat_id 알아내기

1. 봇에게 아무 메시지 보내기 (예: /start)
2. 브라우저에서 https://api.telegram.org/bot<TOKEN>/getUpdates 접속
3. JSON 응답에서 chat.id 값 — 이 숫자가 본인 chat_id

STEP 2. Hermes Agent 설치 (3분)

2-1. Python 가상환경

mkdir hermes-bot
cd hermes-bot
python -m venv .venv
source .venv/bin/activate

2-2. 필요한 패키지 설치

pip install python-telegram-bot hermes-agent

2-3. 환경 변수 설정

.env 파일:

TELEGRAM_BOT_TOKEN=7123456789:AAHxxxxxx
ALLOWED_CHAT_IDS=123456789,987654321
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

.env는 .gitignore에 추가 (이미 우리 프로젝트에는 있음).

STEP 3. 봇 코드 (3분)

bot.py:

import os
import logging
from telegram import Update
from telegram.ext import ApplicationBuilder, ContextTypes, CommandHandler
from hermes_agent import Agent

logging.basicConfig(level=logging.INFO)
agent = Agent(
    name="Hermes Bot",
    model="claude-3-7-sonnet",
    api_key=os.getenv("ANTHROPIC_API_KEY") or os.getenv("OPENAI_API_KEY"),
    system_prompt="You are a helpful AI in Telegram. Be concise. Korean when user writes Korean."
)

ALLOWED = set(int(x) for x in os.getenv("ALLOWED_CHAT_IDS", "").split(",") if x)

async def start(update, ctx):
    if update.effective_user.id not in ALLOWED:
        await update.message.reply_text("권한 없음"); return
    await update.message.reply_text("Hermes Agent 준비 완료\\n/ai <질문>")

async def ai(update, ctx):
    if update.effective_user.id not in ALLOWED: return
    query = update.message.text.replace("/ai ", "", 1).strip()
    if not query: return
    msg = await update.message.reply_text("생각 중...")
    response = await agent.run(query)
    for i in range(0, len(response), 4000):
        await ctx.bot.send_message(update.effective_chat.id, response[i:i+4000])
    await msg.delete()

async def clear(update, ctx):
    agent.reset()
    await update.message.reply_text("대화 리셋")

if __name__ == "__main__":
    app = ApplicationBuilder().token(os.getenv("TELEGRAM_BOT_TOKEN")).build()
    app.add_handler(CommandHandler("start", start))
    app.add_handler(CommandHandler("ai", ai))
    app.add_handler(CommandHandler("clear", clear))
    app.run_polling()

STEP 4. 실행 & 테스트 (1분)

python bot.py

Telegram에서:

/ai 오늘 서울 날씨 알려줘      → AI 응답
/ai Python 피보나치 짜줘         → 코드 블록과 응답
/clear                          → 대화 리셋

⚠️ 보안

1. bot token은 절대 git에 커밋 안 함 (이미 .gitignore)
2. ALLOWED_CHAT_IDS 화이트리스트 — 본인만 허용
3. rate limiting — Telegram API limit: 초당 30회
4. prompt injection — 사용자가 “이전 명령 무시” 보낼 수 있음

🐛 트러블슈팅

🚀 다음 단계

• 이미지 입력 — MessageHandler(filters.PHOTO) 추가
• 음성 입력 — Whisper 통합
• 그룹 채팅 — chat_id 화이트리스트 확장
• MCP 통합 — 외부 도구 호출
• Cron 일정 — 매일 아침 뉴스

더 읽을거리

• MCP란 — 예정
• AI 코딩 어시스턴트 비교
• Claude Code CLI 설정 — 예정
• Telegram Bot API 공식

본 가이드의 가격·기능은 2026년 7월 한국 시장 기준 추정치. 공식 문서를 확인하세요.