Hermes Messaging Gateway 정리

한 줄 요약

Hermes Messaging Gateway는 Telegram, Discord, Slack, WhatsApp 같은 외부 메시징 플랫폼에서 Hermes Agent와 대화할 수 있게 해주는 백그라운드 게이트웨이라고 보면 된다.

쉽게 말하면 터미널에서만 hermes를 쓰는 것이 아니라, 메신저 앱에서도 Hermes Agent를 호출하고 작업을 시킬 수 있게 해주는 중간 서버 역할을 한다.

사용자 메시지
   ↓
Telegram / Discord / Slack / WhatsApp
   ↓
Hermes Messaging Gateway
   ↓
Hermes Agent
   ↓
응답 반환

Messaging Gateway가 하는 일

여러 메시징 플랫폼 연결

Hermes Messaging Gateway는 여러 플랫폼을 하나의 프로세스에서 연결할 수 있다.

지원 플랫폼은 다음과 같다.

  • Telegram
  • Discord
  • Slack
  • WhatsApp
  • Signal
  • SMS
  • Email
  • Home Assistant
  • Mattermost
  • Matrix
  • DingTalk
  • Feishu / Lark
  • WeCom
  • Weixin
  • BlueBubbles
  • QQ
  • Open WebUI
  • Webhooks

즉 하나의 Hermes Agent를 여러 채널에서 사용할 수 있다.

예를 들면 이런 식이다.

Telegram에서는 개인 비서처럼 사용
Discord에서는 개발 서버 봇처럼 사용
Slack에서는 팀 작업 도우미처럼 사용
Email에서는 비동기 작업 처리용으로 사용
Home Assistant에서는 홈 자동화 제어용으로 사용

세션 관리

Gateway는 플랫폼별, 채팅별 세션을 관리한다.

즉 Telegram에서 나눈 대화와 Discord에서 나눈 대화는 서로 다른 세션으로 관리될 수 있다.

이 구조 덕분에 각 채팅방마다 대화 맥락을 따로 유지할 수 있다.

Telegram DM 세션
Discord 채널 세션
Slack 채널 A 세션
Slack 채널 B 세션

세션은 메시지를 보낼 때마다 이어지고, 특정 조건이 되면 초기화될 수 있다.

cron 작업 실행

Gateway는 단순 메시지 중계만 하는 것이 아니라 cron scheduler도 함께 실행한다.

문서 기준으로 Gateway는 60초마다 due job이 있는지 확인한다.

즉 예약 작업이나 반복 작업을 Hermes Agent와 연결해서 사용할 수 있다.

예를 들면 다음과 같은 작업이 가능하다.

매일 아침 서버 상태 점검
매시간 특정 서비스 health check
정해진 시간에 요약 리포트 생성
주기적으로 파일 정리

음성 메시지 처리

Gateway는 플랫폼에 따라 음성 관련 기능도 처리할 수 있다.

지원 범위는 플랫폼마다 다르지만, 기본적으로 다음과 같은 기능을 기대할 수 있다.

  • 음성 메시지 transcription
  • TTS 음성 응답
  • Discord voice-channel 대화
  • 메시징 플랫폼에서 음성 답변 전달

다만 모든 플랫폼이 동일한 음성 기능을 지원하는 것은 아니다.

전체 아키텍처

기본 흐름

Messaging Gateway의 기본 흐름은 다음과 같다.

Platform Adapter
   ↓
Per-chat Session Store
   ↓
AIAgent
   ↓
Platform Adapter
   ↓
사용자에게 응답

각 플랫폼에는 adapter가 있다.

예를 들어 Telegram에는 Telegram adapter, Discord에는 Discord adapter, Slack에는 Slack adapter가 있다고 보면 된다.

Adapter는 외부 플랫폼에서 들어온 메시지를 받아 Hermes Agent가 이해할 수 있는 형태로 넘기고, Hermes Agent의 응답을 다시 해당 플랫폼으로 돌려보낸다.

플랫폼 Adapter

Platform Adapter는 각 메시징 서비스와 직접 통신하는 부분이다.

역할은 다음과 같다.

  • 메시지 수신
  • 사용자 인증 확인
  • 첨부파일 처리
  • 이미지 처리
  • 음성 메시지 처리
  • typing indicator 표시
  • streaming 응답 업데이트
  • thread 처리
  • reaction 처리

지원 기능은 플랫폼마다 다르다.

예를 들어 Discord와 Slack은 thread, reaction, typing, streaming 같은 기능을 폭넓게 지원하지만, SMS는 기능이 제한적이다.

Session Store

Session Store는 채팅별 대화 상태를 관리한다.

즉 사용자가 이전에 어떤 질문을 했고, Hermes가 어떤 답을 했는지 기억하는 역할을 한다.

세션이 유지되면 다음과 같은 대화가 가능하다.

사용자: 이 서버 로그 분석해줘.
Hermes: 이 로그에서는 kubelet 문제가 보인다.

사용자: 그럼 해결 명령어만 정리해줘.
Hermes: 앞서 분석한 kubelet 문제 기준으로 해결 명령어를 정리하면...

반대로 세션이 초기화되면 이전 대화 맥락 없이 새 대화로 시작한다.

AIAgent 처리

Gateway가 메시지를 받으면 최종적으로 Hermes의 AIAgent로 전달된다.

AIAgent는 다음을 수행할 수 있다.

  • 일반 질의응답
  • 코드 분석
  • 터미널 명령 실행
  • 파일 작업
  • 웹 검색
  • MCP 도구 호출
  • 스킬 실행
  • 백그라운드 작업 실행

중요한 점은 메시징 플랫폼에서도 Hermes의 도구 기능을 사용할 수 있다는 것이다.

따라서 보안 설정을 반드시 신경 써야 한다.

세션 관리

Session Persistence

Gateway 세션은 메시지 사이에서 유지된다.

즉 한 번 질문하고 끝나는 구조가 아니라, 같은 채팅방에서는 이전 대화 맥락을 이어서 사용할 수 있다.

예를 들어 다음과 같은 흐름이 가능하다.

사용자: 이 Docker Compose 파일 분석해줘.
Hermes: redis, api, db 서비스로 구성되어 있다.

사용자: 여기서 db 볼륨만 분리하려면 어떻게 해?
Hermes: 앞서 본 compose 구조 기준으로 db service의 volumes를 이렇게 바꾸면 된다.

이런 맥락 유지는 메시징 환경에서 매우 중요하다.

Reset Policy

세션은 설정된 정책에 따라 초기화될 수 있다.

대표 정책은 다음과 같다.

정책 기본값 의미
Daily 오전 4시 매일 특정 시간에 세션 초기화
Idle 1440분 일정 시간 동안 대화가 없으면 초기화
Both 조합 둘 중 먼저 발생하는 조건으로 초기화

플랫폼별로 reset 정책을 다르게 줄 수도 있다.

설정 파일은 다음 위치를 사용한다.

~/.hermes/gateway.json

예시는 다음과 같다.

{
  "reset_by_platform": {
    "telegram": { "mode": "idle", "idle_minutes": 240 },
    "discord": { "mode": "idle", "idle_minutes": 60 }
  }
}

이렇게 하면 Telegram은 4시간 idle 후 초기화되고, Discord는 1시간 idle 후 초기화된다.

보안 설정

기본 보안 모델

Messaging Gateway는 기본적으로 allowlist에 없는 사용자를 거부한다.

이 기본값은 매우 중요하다.

Hermes Agent는 터미널 실행, 파일 접근, 도구 호출 같은 강력한 기능을 가질 수 있기 때문이다.

즉 아무나 봇에게 DM을 보내서 내 서버 명령을 실행하게 만들면 안 된다.

Allowlist 설정

플랫폼별로 허용할 사용자를 지정할 수 있다.

예시는 다음과 같다.

TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
SIGNAL_ALLOWED_USERS=+155****4567,+155****6543
SMS_ALLOWED_USERS=+155****4567,+155****6543
EMAIL_ALLOWED_USERS=trusted@example.com,colleague@work.com
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c
MATRIX_ALLOWED_USERS=@alice:matrix.org
DINGTALK_ALLOWED_USERS=user-id-1
FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy
WECOM_ALLOWED_USERS=user-id-1,user-id-2

공통 allowlist를 사용할 수도 있다.

GATEWAY_ALLOWED_USERS=123456789,987654321

Allow All 주의

모든 사용자를 허용하는 설정도 있다.

GATEWAY_ALLOW_ALL_USERS=true

하지만 이 설정은 터미널 접근 권한이 있는 봇에서는 권장하지 않는다.

개발 서버, 개인 PC, 운영 서버에 연결된 Hermes라면 반드시 allowlist를 사용하는 게 좋다.

Tool Progress Notification

도구 실행 상태 표시

Hermes가 작업 중 어떤 도구를 실행하는지 메시징 플랫폼에 표시할 수 있다.

설정은 다음 파일에서 한다.

~/.hermes/config.yaml

예시는 다음과 같다.

display:
  tool_progress: all
  tool_progress_command: false

tool_progress는 다음 값을 가질 수 있다.

값 의미
off 도구 진행 상황을 표시하지 않는다
new 새 도구 실행만 표시한다
all 도구 실행 상황을 표시한다
verbose 더 자세히 표시한다

예를 들어 Hermes가 작업하면서 다음과 같은 상태 메시지를 보낼 수 있다.

`ls -la`...
web_search...
web_extract...
execute_code...

언제 켜면 좋은가

Tool Progress Notification은 다음 상황에서 유용하다.

  • Hermes가 멈춘 것처럼 보이는 문제를 줄이고 싶을 때
  • 장시간 작업 중 어떤 명령을 실행하는지 보고 싶을 때
  • 터미널 명령 실행 여부를 확인하고 싶을 때
  • 팀 채널에서 Agent 작업 과정을 투명하게 보여주고 싶을 때

반대로 메시지가 너무 많이 오는 것이 싫다면 off 또는 new로 줄이면 된다.

Background Sessions

개념

Messaging Gateway에서는 /background 명령으로 별도 백그라운드 세션을 실행할 수 있다.

예시는 다음과 같다.

/background Check all servers in the cluster and report any that are down

이 명령을 보내면 Hermes는 별도 Agent instance를 만들어 작업을 수행한다.

사용자는 메인 채팅을 계속 사용할 수 있고, 작업이 끝나면 같은 채팅방으로 결과가 돌아온다.

동작 방식

Background session은 다음 특징을 가진다.

  • 별도 세션으로 실행된다.
  • 현재 채팅 맥락을 자동으로 공유하지 않는다.
  • prompt에 적은 내용만 전달된다.
  • 현재 Gateway 설정의 model, provider, toolset, reasoning 설정을 상속한다.
  • 메인 채팅은 계속 사용할 수 있다.
  • 작업 완료 시 같은 채팅방에 결과가 전달된다.

즉 독립적인 작업 큐처럼 사용할 수 있다.

사용 예시

서버 상태 점검을 백그라운드로 실행할 수 있다.

/background 모든 서비스에 대해 헬스체크를 하고 다운 상태가 있으면 알려줘

긴 빌드 작업을 맡길 수도 있다.

/background staing 환경 빌드하고 배포해

조사 작업도 가능하다.

/background 경쟁사의 제품에 대해 분석을 하고 테이블(표)로 요약해줘

파일 정리 작업도 시킬 수 있다.

/background ~/Downloads 폴더에 있는 사진을 날짜순으로 정리해줘

Background Process Notification

백그라운드 작업 중 장기 실행 프로세스의 상태 알림을 받을 수 있다.

설정 예시는 다음과 같다.

display:
  background_process_notifications: all

사용 가능한 값은 다음과 같다.

값 의미
all 실행 중 출력과 최종 완료 메시지를 모두 받는다
result 최종 완료 메시지만 받는다
error 실패했을 때만 최종 메시지를 받는다
off 프로세스 watcher 메시지를 받지 않는다

환경변수로도 설정할 수 있다.

HERMES_BACKGROUND_NOTIFICATIONS=result

 

메시징 플랫폼별 기능 차이

기능 비교 관점

모든 메시징 플랫폼이 같은 기능을 지원하는 것은 아니다.

비교할 때는 다음 기능을 보면 된다.

기능 의미
Voice TTS 응답 또는 음성 메시지 transcription
Images 이미지 송수신
Files 파일 첨부 송수신
Threads thread 기반 대화
Reactions emoji reaction
Typing 처리 중 typing indicator
Streaming 응답을 점진적으로 업데이트

예를 들어 Telegram, Discord, Slack은 비교적 많은 기능을 지원한다.

SMS는 기능이 매우 제한적이다. ( 문자로 쓸일이 있을까... )

Email은 이미지, 파일, thread에는 강점이 있지만 typing이나 streaming 같은 실시간 기능은 기대하기 어렵다. ( 마찬가지로 이메일로 쓸일이 있을까... )

플랫폼 선택 기준

개인용으로는 Telegram이 간단하다.

팀 채널에서는 Discord나 Slack이 적합하다.

자동화와 시스템 연동은 Webhooks나 Home Assistant가 적합하다. => 단순 작업이면 오픈클로가 훨씬 가볍다.

이메일 기반 비동기 작업은 Email integration을 고려할 수 있다.

정리하면 다음과 같다.

목적 추천 플랫폼
개인 비서처럼 사용 Telegram
개발 커뮤니티 또는 팀 서버 Discord
업무 채널 연동 Slack
모바일 메신저 중심 WhatsApp, Signal
서버 자동화 Webhooks
홈 자동화 Home Assistant
비동기 업무 처리 Email
자체 UI 연동 Open WebUI

 

운영 시 주의할 점

allowlist는 필수로 보는 게 좋다

Gateway는 기본적으로 allowlist에 없는 사용자를 거부한다.

이 기본값을 유지하는 게 좋다.

특히 Hermes가 다음 권한을 가진다면 더더욱 allowlist가 필요하다.

  • 터미널 실행
  • 파일 수정
  • 서버 접속
  • API 호출
  • 배포 명령 실행
  • Home Assistant 제어

GATEWAY_ALLOW_ALL_USERS=true는 테스트 환경이 아니라면 피하는 게 좋다.

user service와 system service를 동시에 쓰지 않는 게 좋다

Linux에서는 user service와 system service를 둘 다 설치할 수 있다.

하지만 둘 다 설치하면 start, stop, status 대상이 모호해질 수 있다.

문서에서도 두 service unit을 동시에 유지하는 것을 피하라고 안내한다.

개발 머신은 user service를 쓰고, 서버는 system service를 쓰는 식으로 하나만 선택하면 된다.

background 작업은 현재 대화 맥락을 자동 공유하지 않는다

/background는 독립 세션으로 실행된다.

따라서 현재 대화에서만 알고 있는 정보를 바탕으로 백그라운드 작업을 시키면 원하는 결과가 나오지 않을 수 있다.

나쁜 예시는 다음과 같다.

/background 아까 말한 서버들 점검해줘

더 좋은 예시는 다음과 같다.

/background Check these servers: node01, node02, node03. Verify SSH, disk usage, kubelet status, and containerd status. Report failures only.

background prompt는 독립적으로 이해할 수 있게 구체적으로 작성하면 된다.

추천 설정 예시

개인 개발자용 보안 중심 설정

개인 개발자가 Telegram으로만 사용한다면 allowlist를 명확히 지정하는 게 좋다.

TELEGRAM_BOT_TOKEN=your-token
TELEGRAM_ALLOWED_USERS=123456789

Gateway는 user service로 실행하면 된다.

hermes gateway install
hermes gateway start
hermes gateway status

로그 확인은 다음처럼 한다.

journalctl --user -u hermes-gateway -f

서버용 system service 설정

VPS나 홈서버에서 계속 실행하려면 system service를 사용할 수 있다.

sudo hermes gateway install --system
sudo hermes gateway start --system
sudo hermes gateway status --system

로그는 다음 명령으로 확인한다.

journalctl -u hermes-gateway -f

서버에서는 반드시 allowlist를 설정하는 게 좋다.

GATEWAY_ALLOWED_USERS=123456789

tool progress 표시 설정

Hermes가 어떤 작업을 하는지 보고 싶으면 다음 설정을 사용할 수 있다.

display:
  tool_progress: all
  tool_progress_command: false

너무 시끄럽다면 다음처럼 줄일 수 있다.

display:
  tool_progress: new

아예 끄려면 다음처럼 하면 된다.

display:
  tool_progress: off

background notification 설정

백그라운드 작업 알림을 최종 결과만 받고 싶다면 다음처럼 설정할 수 있다.

display:
  background_process_notifications: result

환경변수로는 다음과 같이 설정할 수 있다.

HERMES_BACKGROUND_NOTIFICATIONS=result
저작자표시 비영리 변경금지 (새창열림)

'인공지능 > Hermes' 카테고리의 다른 글

[인공지능/Hermes] 헤르메스 메모리 시스템 이해하기  (0) 2026.04.25
[인공지능/Hermes] 헤르메스 리눅스에 설치하기  (0) 2026.04.25
[인공지능/Hermes] 헤르메스란 ( feat. 오픈클로와의 차이 )  (0) 2026.04.15

티스토리툴바