2026-05-28 렌탈 Mac mini M4에서 Hermes Agent Telegram 게이트웨이 (서울 · HK / JP / KR / SG / US)

SSH로 iOS 앱을 빌드하는 동일한 Mac mini M4에서 Hermes Agent를 Telegram 봇으로 실행할 수 있습니다. 게이트웨이(hermes gateway)가 BotFather 토큰을 보관하고 숫자 사용자 ID 허용 목록을 적용해 채팅을 Hermes 도구 루프로 전달합니다. 노트북을 항상 켜 두지 않아도 모바일에서 CI 수정 승인이나 아키텍처 질문이 가능합니다.

Modal/Daytona serverless 터미널·near-idle 구성은 Hermes Serverless Modal/Daytona 가이드 참고.

빌더 Mac에서 Telegram을 쓰는 이유

Telegram은 헤드리스 리스에 적합합니다. 게이트웨이는 기본적으로 아웃바운드 long polling을 사용해 Mac이 Telegram API로 HTTPS를 시작하므로, 공유 빌더에서 인바운드 포트를 열 필요가 없습니다(공개 HTTPS가 필요한 webhook 모드와 대비).

리스 호스트에서 Hermes를 Telegram에 연결하는 일반적인 이유:

• 온콜 대응—GitHub Actions나 xcodebuild가 야간에 실패할 때 모바일에서 응답하고 agent가 NVMe 로그를 읽습니다.
• 관심사 분리—OpenClaw로 저장소 자동화, Hermes로 개인/운영 채팅. 두 게이트웨이 프로세스(RAM·토큰 격리)를 수용할 때만 병행하세요.
• OpenClaw 메시징에서 마이그레이션—상류 README의 hermes claw migrate. 16 GB 호스트에서 두 게이트웨이를 동시에 돌리기 전 Hermes vs OpenClaw vs OpenHuman 선정 매트릭스를 확인하세요.

Apple Mac mini 사양은 16–24 GB 통합 메모리입니다. Xcode 병렬 테스트 전에 hermes gateway와 모델 작업 집합에 약 1–2 GB를 확보하세요. 서울 노드를 포함한 HK/JP/KR/SG/US 출구는 Telegram 폴링을 안정적으로 지원합니다. bot 토큰을 git에 커밋하지 마세요.

Telegram 게이트웨이 구성

Hermes는 CLI 채팅(hermes TUI)과 메시징(hermes gateway)을 분리합니다. Telegram 설정은 ~/.hermes/.env(또는 마법사 출력)에 기록되고, 로그는 ~/.hermes/logs/gateway.log, macOS에서는 선택적 launchd 서비스입니다.

데이터 흐름(폴링 모드):

1. Telegram에서 bot에 메시지를 보냅니다.
2. 게이트웨이가 Telegram Bot API(아웃바운드 poll)로 업데이트를 수신합니다.
3. Hermes agent가 구성된 터미널 backend(로컬, Docker, 동일 호스트 SSH)에서 도구를 실행합니다.
4. 응답 텍스트(및 선택적 MEDIA:/path 첨부)가 게이트웨이를 통해 Telegram으로 돌아갑니다.

중요한 보안 기본값: 상류는 @사용자명이 아닌 TELEGRAM_ALLOWED_USERS의 숫자 사용자 ID를 사용합니다. bot 토큰 보유자는 bot을 가장할 수 있습니다—API 키처럼 취급하고 유출 시 BotFather /revoke로 교체하세요.

공식: Hermes Telegram 문서(BotFather, 프라이버시 모드, webhook).

BotFather 및 액세스 제어

bot 생성

1. @BotFather 열기 → /newbot.
2. 표시 이름(예: Builder Hermes)과 bot으로 끝나는 사용자 이름 설정.
3. 123456789:ABCdefGHIjklMNOpqrs… 형식 토큰 복사—비밀번호 관리자에 저장, git에는 넣지 않음.

사용자 ID 허용 목록 추가

@userinfobot에 메시지해 숫자 ID(예: 123456789)를 받습니다. TELEGRAM_ALLOWED_USERS 설정 시 Hermes는 모르는 사용자를 거부합니다.

공유 리스 호스트의 선택적 강화:

• 단일 사용자 허용 목록만—도구 범위를 이해하기 전 와일드카드「팀」ID 사용 금지.
• 환경별 bot(스테이징 vs 프로덕션 리스)—스테이징 토큰 유출이 프로덕션 workspace에 영향 주지 않도록.
• DM 동작 검증 전 그룹 액세스 비활성.

Telegram용 Hermes 구성

대화형(권장)

hermes setup # 신규 설치 시 먼저 모델 제공자 구성 hermes gateway setup # Telegram 선택 → 토큰 붙여넣기 → 허용 사용자 ID

수동 편집 ~/.hermes/.env

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ TELEGRAM_ALLOWED_USERS=123456789 # 선택적 팀: TELEGRAM_ALLOWED_USERS=111111111,222222222

파일 권한이 600인지, 신뢰하지 않는 dotfile 동기화 대상에 포함되지 않았는지 확인.

포그라운드 스모크 테스트:

hermes gateway

Telegram에서 hello를 내면 수초 내 응답이 와야 합니다. launchd 설치 전 Ctrl+C로 중지.

Mac mini M4 헤드리스 배포 8단계

1. Hermes 설치 — 리스 사용자 계정(root 아님)에서 공식 install.sh 실행.
2. hermes setup 실행 — 모델 제공자 구성; hermes doctor 오류 없음 확인.
3. BotFather 토큰 생성 — 숫자 사용자 ID도 확보(위 섹션).
4. hermes gateway setup 실행 — Telegram 선택; ~/.hermes/.env에 토큰·허용 목록 확인.
5. 포그라운드 테스트 — hermes gateway로 bot에 메시지, 무해한 도구(예: agent pwd) 실행; Ctrl+C 중지.
6. 서비스 설치 — hermes gateway install 후 hermes gateway start(macOS launchd).
7. 데몬용 환경 영속화 — ~/.hermes/.env API 키가 launchd에서 읽히는지(설치와 동일 사용자) 확인; 백그라운드만 실패 시 OpenClaw launchd PATH 안내 참고.
8. 모니터링 — hermes gateway status, tail -f ~/.hermes/logs/gateway.log, 설정 변경 후 Telegram /new로 이상 세션 리셋.

인용 가능한 운영 규칙:하나의 게이트웨이 프로세스가 여러 플랫폼(Telegram, Discord, Slack 등)을 서비스할 수 있습니다—채팅 앱마다 별도 데몬이 필요하지 않습니다.

launchd와 SSH 전용 리스

macOS 리스에서 hermes gateway install은 사용자 수준 launchd 작업을 등록합니다—본 블로그의 OpenClaw openclaw onboard --install-daemon 패턴과 유사합니다.

hermes gateway install hermes gateway start hermes gateway status tail -f ~/.hermes/logs/gateway.log

SSH 연결 해제 후에도 install을 실행한 동일 Unix 사용자에서 게이트웨이가 유지되어야 합니다. 중지되면 다음을 확인:

• launchctl list | grep -i hermes
• 로그의 TELEGRAM_BOT_TOKEN / 인증 오류
• 리스 정책이 로그아웃 시 장시간 사용자 agent를 종료하는지(전용 M4는 드묾, 공유 shell은 흔함)

Docker backend 참고: terminal.backend: docker이면 MEDIA:/path로 보내는 파일은 게이트웨이가 읽는 호스트 경로에 있어야 합니다(컨테이너 내부만으로는 불가). 상류 telegram.md에 따라 호스트에서 보이는 볼륨을 마운트하세요.

그룹 채팅(선택)

Telegram 프라이버시 모드는 기본 ON—그룹에서 bot은 보통 /commands, bot에 대한 답장, 관리자에게 보이는 트래픽만 봅니다. 컨텍스트를 넓히려면 BotFather에서 프라이버시 끄기(Bot Settings → Group Privacy → Turn off) 후 각 그룹에서 bot을 제거 후 재추가하거나 그룹 관리자로 승격.

「관찰만 하고 @ 없이는 답하지 않음」에는 상류의 TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES와 허용 chat ID가 있습니다—telegram.md 그룹 장을 먼저 읽으세요.

문제 해결

증상: bot 무응답(폴링 침묵)

증상: 401 Unauthorized 또는 Conflict: terminated by other getUpdates

• 401: 잘못되었거나 취소된 TELEGRAM_BOT_TOKEN.
• Conflict: 동일 bot을 두 프로세스가 폴링—중복 포그라운드 hermes gateway 또는 동일 토큰의 두 번째 호스트 중지.

hermes gateway stop pkill -f "hermes gateway" 2>/dev/null || true hermes gateway start

증상: 포그라운드는 됨, launchd에서는 실패

• launchd는 최소 환경—~/.hermes/.env 읽기 가능·제공자 키 존재 확인.
• SSH와 launchctl print gui/$(id -u)의 PATH 비교(macOS); 플러그인이 shell 호출 시 Node 등 경로 정렬.

증상: 그룹에서 /commands만 보임

• BotFather 프라이버시 모드가 여전히 ON—끄거나 bot을 관리자로; 그룹에 bot 재추가.

자주 묻는 질문