본문으로 건너뛰기

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까지 도달함

앞으로 비슷한 세팅을 할 때는 화면만 보고 “안 됐다”고 판단하지 않고, 아래 순서로 확인하면 좋겠다고 느꼈습니다.

  1. Dashboard는 켜둔 채로 둔다.

  2. 새 터미널에서 Gateway 상태를 확인한다.

  3. PID와 LastExitStatus를 본다.

  4. Telegram 봇에 /start, hello를 보낸다.

  5. tail -f ~/.hermes/logs/gateway.log로 실제 메시지 유입 여부를 확인한다.

  6. 필요하면 ~/.hermes/config.yaml에서 Telegram 설정 저장 여부를 확인한다.

결국 이번 사례의 결론은 단순했습니다.

“Hermes가 안 된 게 아니라, 어디까지 된 상태인지 확인하는 기준이 필요했다.”

터미널, 대시보드, Gateway, Telegram 봇이 각각 다른 역할을 한다는 걸 이해하고 나니 문제를 훨씬 차분하게 좁혀갈 수 있었습니다.

도움 받은 글

  • Hermes Agent 공식 GitHub 저장소

  • Hermes Dashboard와 Gateway 실행 구조 관련 문서

  • Hermes Telegram 연동 튜토리얼 자료

1

함께 이야기해요 1

로그인하고 댓글을 남겨 주세요

댕댕이멍멍 프로필 이미지
댕댕이멍멍2026.05.27

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

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기