Telegram Bot과 Hermes Gateway 연결하기

Telegram bot을 연결하면 늘 들고 다니는 기기에서 Hermes를 사용할 수 있습니다. 동시에 agent entry point가 network에 열립니다. 안전한 설정에는 두 가지 credential check가 필요합니다. Bot token을 가지고 있는지, 요청자의 numeric Telegram user ID가 허용됐는지를 각각 확인합니다.

BotFather 또는 Dashboard의 QR flow로 bot을 만듭니다.
Token은 active Hermes profile의 secret environment에만 저장합니다.
Username이 아니라 numeric user ID를 allowlist에 넣습니다.
Gateway를 시작하기 전에 local diagnostic을 실행합니다.

1. Bot을 만들고 token 보호하기

Telegram에서 인증된 @BotFather 계정을 열고 /newbot을 보냅니다. Display name과 bot으로 끝나는 고유 username을 정하면 BotFather가 Bot API token을 돌려줍니다. Token을 가진 사람은 누구나 bot을 제어할 수 있습니다. 노출됐다면 BotFather에서 revoke한 뒤 다시 발급하세요.

Dashboard와 Desktop app에도 QR 기반 설정이 있습니다. Manual path는 각 trust boundary를 눈으로 확인할 수 있다는 장점이 있습니다.

실제 token을 article, issue, shell history, repository에 붙여 넣지 마세요. 이 chapter fixture에는 variable name만 있습니다.

cp .env.example .env

복사한 파일은 local에서 채웁니다. Commit되는 template의 두 값은 비어 있습니다.

2. Numeric user allowlist 사용하기

Hermes는 numeric Telegram user ID로 sender를 승인합니다. @alice 같은 username은 바뀔 수 있고, Hermes가 요구하는 identifier도 아닙니다. 신뢰할 수 있는 Telegram ID bot이나 QR setup flow로 numeric ID를 구한 뒤 TELEGRAM_ALLOWED_USERS에 넣으세요. 여러 ID는 comma로 구분합니다.

최소 environment 형태는 다음과 같습니다.

TELEGRAM_BOT_TOKEN=
TELEGRAM_ALLOWED_USERS=

일반 Gateway setting은 Hermes configuration에, secret은 profile의 .env에 둡니다. Profile을 사용한다면 하나의 global home directory를 가정하지 말고 대상 profile을 명확히 선택하세요.

3. Secret-safe diagnostic 실행하기

예제 diagnostic은 지정한 environment file을 읽고 현재 hermes gateway --help command inventory를 검사합니다. Telegram에는 접속하지 않습니다.

python3 gateway_diagnostic.py --env-file .env --json

통과한 report는 TELEGRAM_BOT_TOKEN, TELEGRAM_ALLOWED_USERS라는 이름과 allowlist entry count, run, setup, status command를 보여 줍니다. Variable value나 numeric ID는 출력하지 않습니다. 잘못된 token 형태나 username 기반 allowlist는 network action 전에 실패합니다.

이 check가 보장하는 것은 local readiness입니다. Bot ownership은 보장하지 않습니다. Token validity는 실제 Telegram connection을 통해서만 확인할 수 있습니다.

4. Gateway 설정하고 시작하기

Interactive setup을 사용하면 Hermes가 올바른 위치에 setting을 씁니다.

hermes gateway setup
hermes gateway status
hermes gateway run

hermes gateway run은 terminal에 붙어 있어 첫 connection을 볼 때 편합니다. 계속 켜 둘 machine에서는 운영체제 service를 의도적으로 설치하고 시작합니다.

hermes gateway install
hermes gateway start
hermes gateway status

Service installation은 host state를 바꿉니다. 시작 뒤 status와 local log를 확인하세요. Credential과 private path를 지우지 않은 raw log는 공개하지 않습니다.

5. Connection acceptance check 마치기

Allowlist에 든 account에서 bot으로 짧은 message를 보냅니다. 다음 관찰을 모두 만족해야 합니다.

Gateway가 계속 실행 중입니다.
의도한 numeric user의 inbound message를 받습니다.
Hermes가 같은 chat으로 response를 돌려줍니다.
Allowlist 밖 account에는 agent access가 열리지 않습니다.
Gateway diagnostic이 token을 노출하지 않습니다.

마지막 교환에는 실제 token과 network access가 필요합니다. Repository test는 성공한 Telegram response를 꾸며 내지 않습니다. Local preflight contract만 증명합니다.

6. Group과 delivery를 의도적으로 다루기

Telegram privacy mode는 기본으로 켜져 있습니다. Group에서 bot은 보통 command, bot message에 대한 reply, service message, admin 권한으로 볼 수 있는 message를 받습니다. 일반 group traffic이 필요하면 BotFather privacy setting과 Hermes chat allowlist를 함께 검토하세요. 더 많이 볼 수 있다고 해서 더 넓게 답하도록 허용할 필요는 없습니다.

/sethome으로 chat을 home channel로 정할 수 있고, 예약 결과에 explicit delivery target을 쓸 수도 있습니다. 먼저 direct message를 테스트하세요. Single-user path가 안정된 뒤 group, topic, Cron delivery를 추가합니다.

Webhook mode는 inbound wakeup이 필요한 public HTTPS deployment용입니다. Webhook secret과 public endpoint가 threat model에 추가됩니다. Local always-on installation은 default long polling을 유지할 수 있습니다.

7. Token 없이 테스트하고 문제 찾기

Fixture suite를 실행합니다.

python3 -m unittest discover -s tests -v

Test는 fake command inventory와 합성 token-shaped text를 주입한 뒤 stdout과 stderr에 값이 나오지 않는지 검사합니다. 사용자의 Hermes home을 읽지 않고 BotFather나 Telegram Bot API에도 접속하지 않습니다.

Gateway가 시작되지만 답하지 않는다면 numeric allowlist, active profile, Gateway status, group privacy behavior 순으로 확인하세요. Token이 유출됐다면 진행하기 전에 재발급해야 합니다. 10편에서는 하나의 Gateway process를 벗어나 isolated Git worktree에서 parallel subagent를 운영합니다.

[Hermes Agent 실전 09] Telegram Bot과 Hermes Gateway 연결하기