🤖 헤르메스(Hermes) 에이전트를 텔레그램과 연결하면, 컴퓨터 앞에 앉아있지 않아도 휴대폰으로 메시지를 보내 AI에게 작업을 시키고, 예약된 작업 결과도 텔레그램으로 받아볼 수 있습니다. 아래 순서를 그대로 따라 하면 됩니다.
Index
시작하기 전에 준비할 것
- 헤르메스(Hermes Agent)가 이미 설치되어 실행 중이어야 합니다 (PC, Mac, 또는 NAS의 Docker 컨테이너 등 설치 방식은 무관합니다).
- 텔레그램 계정 (스마트폰 앱 또는 PC 앱 모두 가능)
- 넉넉하게 5~10분 정도의 시간
💡 헤르메스가 PC에 직접 설치되어 있든, NAS의 Docker 컨테이너로 돌아가고 있든 아래 절차는 동일합니다. Docker로 설치했다면 컨테이너 터미널에서 같은 명령어를 입력하면 됩니다.
1단계. 텔레그램에서 봇 만들기
- 텔레그램 앱을 열고 검색창에 @BotFather를 입력해 대화방을 엽니다. (텔레그램이 공식으로 제공하는 '봇을 만들어주는 봇'입니다.)
/newbot명령을 보냅니다.- 봇의 표시 이름을 정합니다. (예: "헤르메스 비서" — 자유롭게 지어도 됩니다.)
- 봇의 아이디(username)를 정합니다. 이 아이디는 전체 텔레그램에서 유일해야 하고, 반드시
bot으로 끝나야 합니다. (예:my_hermes_bot) - BotFather가 아래와 같은 형태의 토큰을 답장으로 보내줍니다.
123456789:ABCdefGHIjklMNOpqrSTUvwxYZ⚠️ 이 토큰은 봇의 비밀번호와 같습니다. 절대 다른 사람과 공유하거나 공개된 곳에 올리지 마세요. 만약 유출됐다면 BotFather에게 /revoke를 보내 즉시 무효화할 수 있습니다.
2단계. 봇 토큰을 안전하게 복사해두기
방금 받은 토큰 전체를 복사해서 메모장 같은 곳에 잠시 보관해둡니다. 다음 단계에서 바로 사용합니다.
3단계. 헤르메스에 토큰 연결하기
두 가지 방법 중 편한 것을 고르면 됩니다.
방법 A. 대화형 설정 (초보자 추천)
헤르메스가 설치된 터미널(또는 Docker 컨테이너 터미널)에서 아래 명령을 입력합니다.
hermes gateway setup목록이 나오면 Telegram을 선택하고, 안내에 따라 방금 받은 토큰을 붙여넣습니다. 헤르메스가 설정 파일을 자동으로 만들어줍니다.
방법 B. 설정 파일에 직접 입력하기
헤르메스의 .env 설정 파일(보통 ~/.hermes/.env)을 열어 아래 줄을 추가합니다.
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ- 등호(=) 앞뒤에 띄어쓰기를 넣지 않습니다.
- 토큰 값에 따옴표를 씌우지 않습니다.
4단계. 게이트웨이 실행하기
설정이 끝났으면 게이트웨이(연결 프로그램)를 실행합니다.
hermes gateway몇 초 안에 봇이 온라인 상태가 됩니다. 이미 게이트웨이가 실행 중이었다면 hermes gateway restart로 재시작하세요.
5단계. 텔레그램에서 실제로 말 걸어보기
- 텔레그램에서 방금 만든 봇 이름(아이디)을 검색해 대화방을 엽니다.
/start를 보냅니다.- 처음 대화하면 헤르메스가 "아직 모르는 사용자예요" 같은 안내와 함께 페어링 코드를 보여줄 수 있습니다. 이 경우 헤르메스 터미널에서 아래처럼 승인해줍니다.
hermes pairing approve telegram CODE - 이제 봇에게 아무 메시지나 보내보세요. 답장이 오면 연결 성공입니다 🎉
6단계. 홈 채널 지정하기 (선택이지만 추천)
지금 대화 중인 채팅방에서 아래 명령을 보내면, 예약된 작업(아침 브리핑, 크론 작업 결과 등)이 이 채팅방으로 자동 전송됩니다.
/sethome그룹 채팅에서도 헤르메스를 쓰고 싶다면
텔레그램 봇은 기본적으로 프라이버시 모드가 켜져 있어서, 그룹방에서는 /로 시작하는 명령이나 봇에게 답장(reply)한 메시지만 볼 수 있습니다.
모든 메시지를 보게 하려면:
- @BotFather에게
/mybots를 보냅니다. - 내 봇을 선택합니다.
- Bot Settings → Group Privacy → Turn off를 선택합니다.
⚠️ 설정을 바꾼 뒤에는 봇을 그룹에서 내보냈다가 다시 추가해야 적용됩니다. 텔레그램이 봇이 그룹에 들어온 시점의 설정을 캐싱하기 때문입니다.
자주 발생하는 문제 해결하기
| 증상 | 원인 / 해결 방법 |
|---|---|
| 봇이 답장을 안 함 | .env에 토큰이 정확히 들어있는지 확인하고, hermes gateway status로 게이트웨이가 켜져 있는지 확인 |
| "아직 모르는 사용자예요"가 반복됨 | 페어링 코드를 승인하지 않은 상태입니다. hermes pairing approve telegram CODE를 실행하세요 |
| 토큰을 입력했는데 인식이 안 됨 | 토큰이 중간에 잘렸을 수 있습니다. .env 파일을 다시 열어 토큰 전체가 한 줄에 온전히 들어있는지 확인 |
| 그룹방에서 봇이 아무 반응이 없음 | 프라이버시 모드가 켜져 있는 상태입니다. 위 그룹 채팅 설정을 참고하세요 |
| 게이트웨이가 세션 안에서 재시작이 안 됨 | 새 터미널 창을 열어 hermes gateway restart를 실행하세요 |
마무리
이제 컴퓨터 앞에 없어도 텔레그램으로 헤르메스에게 말을 걸고, 예약된 작업 결과도 받아볼 수 있습니다. 다음 편에서는 음성 메시지로 명령하기, 매일 아침 브리핑 예약하기 같은 활용법을 다뤄볼 수 있습니다.
관련 글
- 시놀로지 나스(Docker)로 헤르메스 설치·연결하는 방법
- 헤르메스에서 로컬 AI(로컬 LLM) 연결하는 방법
댓글