Hermes 릴레이 — 인스턴스 연결하기 | Easy Understand Hermes Agent

Hermes Relay — 인스턴스 연결하기

Hermes Relay를 다시 전화를 걸어주는 공중전화라고 생각해 보세요. 집 주소를 알려줄 필요 없이 한 번만 전화를 걸어 두면, 상대방은 그 동일한 회선을 통해 언제든지 나에게 연락할 수 있습니다.

Hermes Relay란 무엇인가?

Hermes Relay는 Hermes Agent 게이트웨이를 위한 커넥터 시스템입니다. 이 시스템을 사용하면 게이트웨이가 Discord, Telegram, Slack 같은 메시징 플랫폼과 대화할 수 있습니다. 봇 토큰이나 비밀번호를 전혀 보관하지 않고도 말이죠.

대신, 별도의 서비스(커넥터)가 해당 자격 증명을 보유합니다. 게이트웨이는 단일 보안 WebSocket 연결을 통해 커넥터로 전화를 걸기만 하면 되고, 이후 모든 메시지는 그 하나의 열린 회선을 통해 양방향으로 흐릅니다.

왜 유용한가?

핵심 장점을 쉽게 설명하면 다음과 같습니다.

개방 포트가 필요 없습니다. 게이트웨이는 홈 라우터나 클라우드 방화벽 뒤에서도 정상 작동합니다. 외부로 나가는 연결만 만들기 때문에 인터넷에 아무것도 노출할 필요가 없습니다.
봇 비밀 정보가 내 머신에 없습니다. 커넥터가 모든 플랫폼 토큰을 보관합니다. 게이트웨이를 도난당해도 공격자는 쓸모없는 것을 얻게 될 뿐입니다.
하나의 게이트웨이, 여러 플랫폼. 커넥터는 연결되는 순간 게이트웨이에게 자신이 할 수 있는 일(메시지 길이, 마크다운, 편집, 스레드 등)을 알려줍니다. 하드코딩된 규칙이 없으니 그냥 적응할 뿐입니다.

언제 사용하나요? 봇을 직접 운영하고 있다면 Relay를 건너뛰고 네이티브 어댑터(Telegram, Discord)를 사용하세요. Relay는 공유 또는 호스팅 커넥터가 플랫폼 측을 관리하는 환경을 위한 것입니다. 멀티테넌트 호스팅이나 내 머신에 토큰을 두고 싶지 않을 때 적합합니다.

게이트웨이 등록 방법

등록은 일회성 설정입니다. 명령어 하나만 실행하면 나머지는 Hermes가 처리합니다.

먼저 등록 토큰(커넥터 제공자가 발급)이 있는지 확인하세요. 그런 다음 실행합니다:

hermes gateway enroll \
  --token <enrollment-token> \
  --connector-url wss://connector.example.com/relay

단계별로 어떤 일이 일어나는지 설명합니다:

Hermes는 기존 로그인(~/.hermes/auth.json)을 확인하여 소속 조직을 증명합니다.
자체 ID 공급자(에어갭 또는 자체 호스팅 환경)를 설정한 경우, 그 대신 사용합니다.
등록 토큰을 TLS를 통해 커넥터의 /relay/enroll 엔드포인트로 전송합니다.
커넥터는 토큰이 유효하고, 일회용이며, 테넌트와 일치하는지 확인합니다.
그런 다음 게이트웨이별 비밀 키와 전달 키를 발급하여 한 번만 반환합니다.
Hermes는 이를 ~/.hermes/.env에 저장합니다:

GATEWAY_RELAY_ID
GATEWAY_RELAY_SECRET
GATEWAY_RELAY_DELIVERY_KEY

끝입니다. 이제 게이트웨이가 “등록”되었으며 필요할 때마다 커넥터로 전화를 걸 수 있습니다.

다음 단계는?

등록이 완료되면 게이트웨이는 다음을 수행합니다:

제공한 커넥터 URL로 전화를 겁니다
기능 설명자(프런트 플랫폼이 할 수 있는 일)를 수신합니다
동일한 소켓을 통해 정규화된 메시지와 작업을 주고받습니다

인바운드 포트도, 추가 자격 증명도, 플랫폼별 코드도 필요 없습니다.

요약 및 실용 팁

요약: Hermes Relay는 플랫폼 자격 증명을 소유하거나 포트를 개방하지 않고도 게이트웨이를 메시징 플랫폼에 연결하는 깔끔한 방법입니다. 공유 호스팅, NAT 환경, 또는 메인 머신에 비밀 정보를 두고 싶지 않은 모든 환경에 적합합니다.

실용 팁: 등록 토큰은 항상 일회용이고 수명이 짧은 것으로 유지하세요. 자격 증명을 교체해야 한다면 새 토큰으로 등록 명령을 다시 실행하기만 하면 됩니다. 그리고 업데이트하기 전에 .env 파일에서 이전 GATEWAY_RELAY_SECRET을 삭제하는 것을 잊지 마세요. 작은 위생 습관이 큰 차이를 만듭니다.