🪽 Hermes 04. 텔레그램 연결과 게이트웨이 운영

Hermes를 설치한 다음 체감 가치가 가장 빨리 올라가는 지점은 Telegram 연결이다. 터미널 앞에 앉아 있을 때만 쓰는 에이전트와, 휴대폰에서 바로 부를 수 있는 에이전트는 완전히 다르게 느껴진다. 특히 메모, 질문, 음성 입력, 백그라운드 작업 결과 확인까지 한 채널로 묶이면 사용 빈도가 급격히 올라간다.

다만 여기서 가장 많이 꼬이는 부분도 비슷하다. BotFather 설정, 허용 사용자, privacy mode, gateway 서비스 실행이 한 번에 섞이기 때문이다. 이 글은 Hermes 공식 문서를 기준으로, 개인용 Telegram 연결을 가장 덜 꼬이게 만드는 순서로 정리한다.

안내: 이 글은 Hermes 공식 문서와 공식 저장소를 바탕으로 정리했고, 구조화와 문장 정리에 생성형 AI를 보조적으로 활용했습니다.

이번 글의 목표

이 글을 끝내면 아래 다섯 가지가 되어 있어야 한다.

Telegram 봇이 만들어져 있다
Hermes gateway가 Telegram과 연결돼 있다
내 계정만 봇을 호출할 수 있게 제한돼 있다
DM에서 기본 대화와 명령이 정상 동작한다
필요하면 그룹에서도 안전하게 쓸 준비가 되어 있다

flowchart LR
A[BotFather에서 봇 생성] --> B[내 Telegram ID 확인]
B --> C[Hermes gateway 설정]
C --> D[허용 사용자 제한]
D --> E[DM에서 첫 테스트]
E --> F[그룹/자동화 확장]

왜 설치 다음 편이 Telegram인가

Hermes 공식 Messaging Gateway 문서는 gateway를 단일 백그라운드 프로세스로 설명한다. 이 프로세스 하나가 Telegram, Discord, Slack 같은 채널 연결과 세션 저장, 크론 실행, 음성 메시지 전달까지 함께 맡는다. 즉, Telegram 연결은 단순 채팅 연동이 아니라 Hermes를 일상 운영 도구로 바꾸는 진입점이다.

Messaging Gateway: https://hermes-agent.nousresearch.com/docs/user-guide/messaging

처음부터 Discord, WhatsApp, 그룹 토픽, 웹훅까지 넓히기보다, Telegram DM 하나를 먼저 안정화하는 편이 훨씬 낫다. 문제가 생겨도 원인을 분리하기 쉽기 때문이다.

1. BotFather에서 먼저 끝내야 하는 것

Telegram 봇은 @BotFather에서 만든다. 공식 Telegram 설정 문서는 /newbot으로 봇을 만들고 토큰을 받는 흐름을 가장 먼저 안내한다.

기본 순서는 간단하다.

@BotFather에 /newbot 전송
표시 이름 설정
...bot으로 끝나는 사용자명 설정
발급된 토큰 보관

토큰은 사실상 봇의 열쇠다. 유출되면 다른 사람이 내 봇을 제어할 수 있으니, 공식 문서도 토큰 노출 시 즉시 /revoke로 폐기하라고 안내한다.

Telegram Setup: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram

같이 해두면 좋은 BotFather 설정

BotFather에서 아래 네 가지를 같이 손보면 첫인상이 좋아진다.

/setdescription : 봇 설명 문구
/setabouttext : 프로필 짧은 소개
/setuserpic : 봇 아바타
/setcommands : 기본 명령 메뉴

처음에는 아래 정도면 충분하다.

help - Show help information
new - Start a new conversation
sethome - Set this chat as the home channel
status - Show session info

이 단계는 필수는 아니지만, 나중에 모바일에서 / 메뉴를 눌렀을 때 훨씬 덜 헤맨다.

2. 내 Telegram ID를 먼저 확인해야 하는 이유

Hermes는 Telegram 사용자명을 기준으로 허용하지 않는다. 숫자 user ID를 기준으로 접근을 통제한다. 그래서 연결 전에 내 ID를 먼저 알아두는 게 좋다.

공식 문서는 @userinfobot이나 @get_id_bot으로 user ID를 확인하는 방법을 안내한다. 여기서 받은 숫자가 나중에 TELEGRAM_ALLOWED_USERS에 들어간다.

이걸 먼저 해두면 “봇은 살아 있는데 왜 내 말을 안 듣지?” 같은 초반 혼란을 많이 줄일 수 있다.

3. 개인용이라면 allowlist부터 잡는 게 가장 안전하다

Hermes 보안 문서와 Messaging Gateway 문서는 둘 다 같은 원칙을 강조한다. 기본값은 deny다. 허용 사용자나 pairing이 없으면, 인증되지 않은 사용자는 막힌다. 터미널 도구를 쓸 수 있는 봇이라면 이 기본값이 맞다.

Security: https://hermes-agent.nousresearch.com/docs/user-guide/security
Messaging Gateway: https://hermes-agent.nousresearch.com/docs/user-guide/messaging

가장 단순하고 안전한 개인용 설정은 아래 두 줄이다.

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

이 방식의 장점은 분명하다.

누가 쓸 수 있는지 명확하다
불특정 사용자 DM을 걱정할 필요가 없다
pairing 승인 과정을 당장 배우지 않아도 된다

pairing은 언제 쓰면 좋은가

Hermes는 DM pairing도 지원한다. 모르는 사용자가 봇에 DM을 보내면 일회용 코드가 나오고, 소유자가 CLI에서 승인하는 방식이다.

hermes pairing approve telegram XKGH5N7P

이 방식은 팀원 몇 명에게 점진적으로 열어 줄 때 유용하다. 하지만 처음 연결하는 1인 개인 세팅이라면 allowlist가 더 빠르고 덜 헷갈린다.

4. 설정은 wizard가 가장 덜 꼬인다

Telegram 연결은 수동으로도 되지만, 공식 문서는 hermes gateway setup을 가장 쉬운 경로로 제시한다.

hermes gateway setup

이 wizard는 플랫폼 선택, 봇 토큰, 허용 사용자 설정, gateway 재시작 여부까지 한 흐름으로 묶어 준다. 처음에는 이 경로가 제일 낫다.

Messaging Gateway Quick Setup: https://hermes-agent.nousresearch.com/docs/user-guide/messaging
Telegram Setup: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram

수동 설정이 더 나은 경우

이미 ~/.hermes/.env와 config.yaml을 직접 관리하고 있거나, 여러 머신에서 같은 설정을 복제할 생각이라면 수동 설정도 괜찮다. 이때 규칙은 단순하다.

비밀값은 ~/.hermes/.env
일반 설정은 ~/.hermes/config.yaml
Configuration: https://hermes-agent.nousresearch.com/docs/user-guide/configuration

5. 게이트웨이는 foreground보다 서비스로 굴리는 편이 편하다

가볍게 테스트만 할 때는 foreground 실행도 가능하다.

hermes gateway

하지만 실제로 계속 쓸 거라면 공식 문서대로 서비스 설치 후 시작하는 편이 낫다.

hermes gateway install
hermes gateway start
hermes gateway status

Linux는 systemd user service, macOS는 launchd agent로 설치된다. 즉, 터미널 창을 계속 열어두지 않아도 된다.

Service Management: https://hermes-agent.nousresearch.com/docs/user-guide/messaging

언제 foreground가 좋나

지금 막 연결 확인만 할 때
로그를 바로 보고 싶을 때
환경 변수나 토큰 입력이 맞는지 첫 점검할 때

언제 서비스가 좋나

일상적으로 계속 쓰려 할 때
크론 결과를 Telegram으로 받고 싶을 때
노트북 재부팅 후에도 쉽게 복구하고 싶을 때

미니 사례로 보면 차이가 분명하다. 테스트 단계에서 hermes gateway로 1분 안에 DM 확인까지 가고, 정상 동작이 확인되면 곧바로 install → start로 전환하는 방식이 가장 안정적이다.

6. 첫 연결 뒤 바로 확인할 체크리스트

Telegram DM에서 봇에게 메시지를 보내고, 아래 순서대로 확인하면 된다.

1) 일반 대화

봇에게 짧은 메시지를 하나 보낸다. 응답이 오면 최소 연결은 성공이다.

2) 기본 명령

아래 명령 네 개는 꼭 눌러보는 편이 좋다.

/help
/status
/new
/sethome

공식 Messaging 문서에 따르면 /new 또는 /reset은 새 대화를 시작하고, /status는 세션 상태를 보여주며, /sethome은 이 채팅을 홈 채널로 지정한다. 홈 채널로 지정해 두면 크론 결과나 백그라운드 작업 완료 메시지가 여기로 돌아오기 쉽다.

3) 음성 입력

Telegram 문서는 음성 메시지 전사를 기본 기능 중 하나로 소개한다. 따라서 가능하면 짧은 음성 하나를 보내 보고, 텍스트로 잘 들어오는지 확인하는 게 좋다.

4) 세션 리셋 감각

/new를 눌렀을 때 새 대화처럼 초기화되는지 확인한다. 나중에 컨텍스트가 무거워질 때 이 감각이 꽤 중요하다.

7. 그룹에 넣을 거면 privacy mode와 mention 규칙을 같이 봐야 한다

Telegram에서 그룹 운영이 꼬이는 가장 큰 이유는 privacy mode다. 공식 Telegram 설정 문서가 이걸 아예 “가장 흔한 혼란 지점”이라고 짚는다.

기본적으로 privacy mode가 켜져 있으면 봇은 그룹에서 아래 정도만 본다.

슬래시 명령
봇 메시지에 대한 답글
일부 서비스 메시지

반대로 privacy mode를 끄면 그룹 메시지를 더 넓게 받는다. 또는 봇을 그룹 admin으로 올려도 전체 메시지 접근이 가능하다.

Telegram Setup, Privacy Mode: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram

하지만 여기서 바로 전체 반응형으로 열어 두는 건 추천하지 않는다. 개인 생산성용 봇이라면 먼저 require_mention으로 시작하는 편이 훨씬 안전하다.

telegram:
  require_mention: true

공식 문서는 여기에 mention_patterns, ignored_threads까지 더해 세밀하게 반응 범위를 조절할 수 있다고 설명한다. 즉, 그룹에서 너무 수다스럽게 굴지 않게 만들 수 있다.

미니 사례 1, 나만 쓰는 개인 그룹

나 혼자 쓰는 실험용 그룹이라면 이 구성이 무난하다.

privacy mode는 꺼 두거나 admin 승격
TELEGRAM_ALLOWED_USERS는 내 ID만
telegram.require_mention: true

이렇게 하면 그룹에 메시지가 많아도, 내가 멘션하거나 명령을 쓸 때만 반응한다. 봇이 대화 흐름을 어지럽힐 가능성이 줄어든다.

미니 사례 2, 작은 팀 그룹

팀에서 같이 쓸 생각이라면 allowlist를 2~3명으로 좁게 시작하고, 자유 응답보다 멘션 기반으로 운영하는 편이 낫다. 처음부터 전원 개방으로 가면 누가 호출했는지, 누가 승인권자인지, 어디까지 허용해야 하는지가 금방 흐려진다.

8. 홈 채널과 백그라운드 작업을 묶으면 체감이 올라간다

Hermes는 /sethome으로 현재 채팅을 home channel로 지정할 수 있다. 공식 문서 기준으로 크론 결과와 일부 자동 결과는 이 홈 채널로 돌아간다.

이게 왜 중요하냐면, Telegram 연결의 진짜 가치는 “대화”보다 알림과 결과 회수에 있을 때가 많기 때문이다.

예를 들어 이런 흐름이 가능해진다.

모바일에서 아이디어 한 줄 전송
데스크톱에서 Hermes가 이어서 정리
백그라운드 작업 완료 메시지를 Telegram으로 수신
다시 모바일에서 후속 질문

메모리 루프나 Obsidian 연동은 다음 단계지만, 홈 채널을 먼저 잡아두면 나중 확장이 훨씬 자연스럽다.

9. 항상 켜둘 서버가 아니라면 polling으로 시작하면 된다

Telegram 문서에 따르면 기본 연결 방식은 polling이다. 로컬 머신이나 항상 켜져 있는 장비에서는 이 방식이 가장 단순하다. 반면 Fly.io나 Railway 같은 슬립 기반 클라우드에서는 webhook이 더 효율적이다.

TELEGRAM_WEBHOOK_URL=https://my-app.example.com/telegram
TELEGRAM_WEBHOOK_SECRET=...

처음에는 굳이 webhook부터 갈 필요가 없다. 개인용 데스크톱, 노트북, 홈서버라면 polling이 이해하기 쉽고 디버깅도 단순하다. webhook은 “계속 켜둘 수 없는 클라우드 배포”가 필요해질 때 넘어가면 된다.

Telegram Webhook Mode: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram

10. 텔레그램 연결에서 가장 자주 막히는 원인

실전에서 많이 막히는 원인은 대체로 네 가지다.

1) 토큰은 맞는데 응답이 없다

대부분 gateway가 안 떠 있거나, foreground 테스트 후 창을 닫았기 때문이다. 이럴 땐 hermes gateway status부터 보는 편이 빠르다.

2) 봇은 보이는데 내 메시지를 무시한다

TELEGRAM_ALLOWED_USERS에 넣은 숫자가 틀렸을 가능성이 크다. username이 아니라 numeric user ID인지 다시 봐야 한다.

3) 그룹에서는 명령만 되고 일반 메시지는 안 된다

privacy mode 영향일 가능성이 높다. 그룹 사용 목적이라면 BotFather의 Group Privacy 설정과, 봇 재초대를 같이 확인해야 한다.

4) 말이 너무 많거나 너무 자주 끼어든다

telegram.require_mention: true와 ignored_threads를 먼저 검토하는 편이 좋다. 그룹 운영은 기능보다 반응 범위 설계가 더 중요할 때가 많다.

11. 보안 기준은 여기까지는 꼭 지키는 게 좋다

Hermes 보안 문서를 기준으로 보면 Telegram 연결 시 최소 기준은 이 정도다.

GATEWAY_ALLOW_ALL_USERS=true는 웬만하면 쓰지 않기
개인용이면 TELEGRAM_ALLOWED_USERS로 시작하기
위험 명령 승인 모드는 기본 manual 유지하기
처음부터 YOLO 모드로 열지 않기
항상 켜둘 환경이면 local보다 Docker 같은 격리 백엔드도 검토하기
Security Overview: https://hermes-agent.nousresearch.com/docs/user-guide/security
Configuration, Terminal Backend: https://hermes-agent.nousresearch.com/docs/user-guide/configuration

특히 Hermes는 terminal 도구를 포함한 강한 권한을 가질 수 있다. 그래서 “편하게 다 열기”보다, 내가 통제할 수 있는 범위만 먼저 열기가 맞다.

여기까지 했으면 다음 단계는 두 갈래다

이제 갈림길은 분명하다.

1) 메모리와 지식 쪽으로 확장

Telegram에서 들어온 질문과 아이디어를 llm-wiki, Obsidian 같은 지식 계층으로 붙이고 싶다면, 다음부터는 입력 루프와 저장 위치 설계가 핵심이다.

2) 모바일 입력 효율 쪽으로 확장

Gboard 음성 입력, Telegram 음성 메시지, 짧은 프롬프트 습관을 붙이고 싶다면, 입력 마찰을 줄이는 루틴 설계가 핵심이다.

Hermes를 오래 쓰게 만드는 건 결국 설치가 아니라 자주 부를 수 있는 채널과 기록이 남는 구조다. Telegram 연결은 그 첫 번째 문턱이다.

일하는 ai

탐색기