Hermes Telegram 연동, “멈춘 줄 알았는데 정상”이었던 세팅 확인기
2026.05.24
소개
Hermes Agent를 Telegram과 연동하는 과정에서 가장 헷갈렸던 부분은 터미널이 아무 반응 없이 멈춰 있는 것처럼 보이는 상태였습니다.
처음에는 대시보드를 실행했는데 화면에 에이전트 버전이나 세션 정보가 바로 보이지 않았고, Telegram 봇에 메시지를 보내도 즉시 반응이 없어 보였습니다. 그래서 “이게 정상적으로 세팅된 건가?”, “아직 안 된 건가?”를 구분하기 어려웠습니다.
이번 사례는 Hermes Dashboard와 Gateway를 함께 실행하면서, Telegram 연동이 어디까지 정상이고 어디부터 확인해야 하는지 점검한 기록입니다.
진행 방법
1. Dashboard는 서버처럼 계속 켜두는 구조라는 점 이해하기
처음 실행한 터미널에서는 Hermes Dashboard가 실행 중이었습니다.
hermes dashboard
이 상태에서는 터미널이 입력을 받지 않고 멈춰 있는 것처럼 보입니다. 하지만 실제로는 Dashboard 서버가 계속 실행 중인 상태입니다.
브라우저에서는 아래 주소로 접속합니다.
http://127.0.0.1:9119
여기서 배운 점은 간단했습니다.
Dashboard는 터미널을 점유한다.
그래서 같은 터미널에서
hermes gateway status같은 명령어를 바로 실행할 수 없다.Gateway 관련 명령어는 새 터미널 창을 열어서 실행해야 한다.
2. 새 터미널에서 Gateway 상태 확인하기
Dashboard를 켜둔 상태에서 새 터미널을 열고 Gateway 상태를 확인했습니다.
hermes gateway status
처음에는 Telegram 봇에 메시지를 보냈는데도 Dashboard 쪽에서 LAST UPDATE: 1D AGO처럼 오래된 상태가 보였습니다. 이 경우에는 Telegram 메시지가 Hermes Gateway까지 제대로 들어오지 않는 상태일 수 있습니다.
그래서 Gateway를 다시 시작하거나 교체 실행하는 방식으로 점검했습니다.
hermes gateway stop
hermes gateway start
그래도 반응이 없을 때는 아래 명령어로 강제 교체 실행을 시도했습니다.
hermes gateway run --replace
3. 실제로 Gateway가 살아 있는지 확인하기
다시 상태를 확인했을 때 아래와 같은 결과가 나왔습니다.
Launchd plist: /Users/justice/Library/LaunchAgents/ai.hermes.gateway.plist
✓ Service definition matches the current Hermes install
✓ Gateway service is loaded
{
"StandardOutPath" = "/Users/justice/.hermes/logs/gateway.log";
"LimitLoadToSessionType" = "Aqua";
"StandardErrorPath" = "/Users/justice/.hermes/logs/gateway.error.log";
"Label" = "ai.hermes.gateway";
"OnDemand" = true;
"LastExitStatus" = 0;
"PID" = 17597;
"Program" = "/Users/justice/.hermes/hermes-agent/venv/bin/python";
"ProgramArguments" = (
"/Users/justice/.hermes/hermes-agent/venv/bin/python";
"-m";
"hermes_cli.main";
"gateway";
"run";
"--replace";
);
};
여기서 확인한 핵심은 다음과 같습니다.
✓ Gateway service is loaded→ Gateway 서비스가 로드됨PID = 17597→ 실제 프로세스가 살아 있음LastExitStatus = 0→ 마지막 실행 종료 상태에 에러가 없음ProgramArguments에gateway run --replace가 있음 → Gateway가 교체 실행 모드로 동작 중
즉, Hermes 자체는 정상적으로 떠 있는 상태였습니다.
4. 남은 문제는 Telegram inbound 확인
Gateway가 살아 있는데도 세션이 생기지 않는다면, 남은 문제는 대부분 Telegram 쪽 입력이 Hermes로 들어오는지 여부입니다.
확인해야 할 항목은 다음과 같았습니다.
Telegram에서 내가 메시지를 보내는 대상이 BotFather에서 만든 진짜 봇인지 확인
봇에게
/start를 먼저 보냈는지 확인그 다음
hello같은 테스트 메시지를 보냈는지 확인Dashboard에서
LAST UPDATE가JUST NOW로 바뀌는지 확인SESSIONS 1처럼 세션이 생성되는지 확인
5. 로그로 최종 확인하기
마지막으로 Gateway 로그를 실시간으로 확인했습니다.
tail -f ~/.hermes/logs/gateway.log
이 상태에서 Telegram 봇에 메시지를 보내면 정상적인 경우에는 메시지 수신이나 세션 생성 관련 로그가 찍혀야 합니다.
예상 가능한 정상 흐름은 다음과 같습니다.
Received telegram message
Created session
반대로 문제가 있다면 아래와 같은 단서를 로그에서 찾을 수 있습니다.
Telegram 인증 오류
polling 오류
webhook 관련 오류
config 저장 누락
Telegram gateway 설정 누락
설정 파일도 함께 확인했습니다.
cat ~/.hermes/config.yaml
특히 Telegram 관련 설정이 저장되어 있는지 확인해야 했습니다.
gateways:
telegram:
이 부분이 없다면 hermes gateway setup 과정에서 Telegram 설정이 제대로 저장되지 않았을 가능성이 있습니다.
결과와 배운 점
이번 과정에서 가장 크게 배운 점은 “멈춘 것처럼 보이는 터미널이 항상 실패 상태는 아니다”라는 점이었습니다.
Hermes Dashboard는 웹 UI를 띄우기 위한 서버처럼 동작하기 때문에, 실행 중인 터미널을 계속 점유합니다. 그래서 그 터미널이 조용히 멈춰 있는 것처럼 보여도 실제로는 정상 동작 중일 수 있습니다.
또 하나의 핵심은 Dashboard와 Gateway를 분리해서 봐야 한다는 점입니다.
Dashboard는 브라우저에서 상태를 보는 UI
Gateway는 Telegram 같은 외부 채널과 연결되는 백그라운드 프로세스
둘은 함께 사용할 수 있지만, 같은 프로세스는 아님
이번 상태에서는 다음 단계까지는 정상으로 볼 수 있었습니다.
Hermes 설치 완료
Dashboard 실행 완료
Gateway 서비스 로드 완료
Gateway 프로세스 실행 중
마지막 종료 상태 에러 없음
다만 Telegram 세션이 바로 생기지 않는 경우에는 Gateway 자체보다 Telegram 봇 설정, /start 여부, 봇 username 확인, config 저장 여부, 로그 확인이 더 중요했습니다.
정리하면, 이번 트러블슈팅의 판단 기준은 아래와 같습니다.
Dashboard가 멈춘 것처럼 보임
→ 정상일 수 있음. 웹 서버처럼 실행 중인 상태
Gateway status에서 PID가 있음
→ Gateway 프로세스가 살아 있음
LastExitStatus = 0
→ 마지막 실행에 치명적인 에러 없음
Telegram 메시지를 보내도 LAST UPDATE가 오래됨
→ Telegram inbound 또는 bot 설정 확인 필요
로그에 Received telegram message가 찍힘
→ Telegram 입력이 Gateway까지 도달함
앞으로 비슷한 세팅을 할 때는 화면만 보고 “안 됐다”고 판단하지 않고, 아래 순서로 확인하면 좋겠다고 느꼈습니다.
Dashboard는 켜둔 채로 둔다.
새 터미널에서 Gateway 상태를 확인한다.
PID와 LastExitStatus를 본다.
Telegram 봇에
/start,hello를 보낸다.tail -f ~/.hermes/logs/gateway.log로 실제 메시지 유입 여부를 확인한다.필요하면
~/.hermes/config.yaml에서 Telegram 설정 저장 여부를 확인한다.
결국 이번 사례의 결론은 단순했습니다.
“Hermes가 안 된 게 아니라, 어디까지 된 상태인지 확인하는 기준이 필요했다.”
터미널, 대시보드, Gateway, Telegram 봇이 각각 다른 역할을 한다는 걸 이해하고 나니 문제를 훨씬 차분하게 좁혀갈 수 있었습니다.
도움 받은 글
Hermes Agent 공식 GitHub 저장소
Hermes Dashboard와 Gateway 실행 구조 관련 문서
Hermes Telegram 연동 튜토리얼 자료


Hermes 를 사용하려는 사람들에게는 중요한 포인트가 될 거 같습니다.
저도 참고하겠습니다.
앞으로 Hermes 사용기도 기대하겠습니다.