실습할 때 Hermes App을 다운 받아서 하는 걸로 안내되어 있었는데 저는 맨땅에 헤딩하겠다고 무작정 git hub에서 hermes를 받아서 깔았습니다. 그 전에 cursor, VPS, claude console, telegram 연동해서 bot에서 뭔가를 받아보고 있긴 했어요. (어떻게 했는지 하나도 기억안남)
여러가지 문제가 있었는데 claude에 문제가 생길때마다 스크린샷 캡쳐해서 해결했구요. 결국은 PC에서 못돌리고 VPS로 우회해서 연동한다음, rclone으로 VPS와 PC를 연결했습니다. soul과 user md는 VPS에 올라가 있네요.
코딩은 클로드, 터미널은 cursor, 파워셀, cmd를 이용했습니다. (클로드가 시키는대로 해서 머가 어딘지는 몰라요)
Hermes Agent × Telegram 연동 트러블슈팅 사례
환경: Windows 11 PC + Contabo VPS (Ubuntu 24.04) / Anthropic API (Claude Opus 4-7) / Telegram Bot 소요시간: 약 2시간 작성일: 2026.07.21
전체 요약
비개발자(Python 초보)가 Hermes Agent를 Telegram으로 연동하는 과정에서 겪은 5가지 문제와 해결 과정을 기록한다. 핵심 교훈은 "에러 메시지를 정확히 읽고, 한 번에 하나씩 해결하라"는 것이다.
문제 1. API Key 인증 실패 (HTTP 401)
증상
Hermes 실행 시
API call failed: AuthenticationError [HTTP 401]API key is invalid메시지 반복
원인
.env파일에 API key가 2개 중복 저장되어 있었음이전 무효 키와 새 키가 동시에 존재 → Hermes가 잘못된 키를 참조
해결
bash
# .env 파일 직접 열기
notepad $env:LOCALAPPDATA\hermes\.env
# 이전 키 줄 삭제, 새 키 1줄만 남기고 저장교훈: hermes config set을 여러 번 실행하면 키가 중복 추가될 수 있다. 설정 후 .env 파일을 직접 열어 확인하는 습관이 필요하다.
문제 2. Telegram Bot Token 노출 → 토큰 무효화
증상
Gateway 로그에
The token was rejected by the servercurl 테스트 시
401: Unauthorized
원인
디버깅 과정에서 curl 명령에 포함된 Bot Token이 채팅 화면(스크린샷)에 노출
보안을 위해 BotFather에서
/revoke로 토큰 재발급 → 이전 토큰 무효화Hermes Gateway에는 이전 토큰이 그대로 남아있었음
해결
bash
# BotFather에서 /revoke → 새 토큰 발급
# Hermes에 새 토큰 등록
hermes gateway setup
# → Telegram 선택 → reconf → 새 토큰 입력교훈: API key, Bot Token 등 인증 정보는 스크린샷에 포함되지 않도록 주의. 노출 시 즉시 재발급하고, 관련된 모든 시스템의 토큰을 교체해야 한다.
문제 3. Telegram Gateway 네트워크 연결 실패 (PC)
증상
hermes gateway run실행 시Connecting to Telegram (attempt 1/8)...에서 무한 대기Primary api.telegram.org connection failed; trying fallback IPsPrimary api.telegram.org path unreachable; using sticky fallback IP
원인
한국 ISP 환경에서 Telegram의 장기 WebSocket 연결이 불안정
단순 HTTPS 요청(curl)은 통과되지만, Gateway가 사용하는 상시 연결은 방화벽/ISP에서 차단 또는 불안정 처리
같은 이유로
curl https://api.telegram.org는 성공하지만 Gateway 연결은 실패
해결
PC에서의 직접 연결을 포기하고, 해외 VPS(Contabo)에서 Gateway를 운영하는 방식으로 전환
교훈: Telegram API의 단순 요청(polling)과 장기 연결(WebSocket)은 네트워크에서 다르게 처리된다. 한국 환경에서 Gateway 상시 연결이 안 되면 해외 VPS가 현실적 해결책이다.
문제 4. PC ↔ VPS Gateway 충돌
증상
VPS에서 Gateway 실행 시
Telegram polling conflict (1/5) — previous session still held openterminated by other getUpdates request; make sure that only one bot instance is running
원인
PC와 VPS에서 동시에 같은 Bot Token으로 Gateway를 실행
Telegram은 하나의 Bot Token에 대해 하나의 polling 세션만 허용
해결
powershell
# PC에서 Gateway 중지
hermes gateway stopbash
# VPS에서 Gateway 재시작
hermes gateway restart교훈: 하나의 Bot Token으로는 한 곳에서만 Gateway를 실행해야 한다. PC는 수업 실습용(Desktop 앱), VPS는 Telegram 봇 상시 운영용으로 역할을 분리한다.
문제 5. VPS에 Hermes 미설치 + 설치 URL 오류
증상
VPS에서
hermes --version→Command 'hermes' not foundcurl -fsSL https://hermes-ai.net/install.sh | bash→404 Not Found
원인
VPS는 새 서버이므로 Hermes가 설치되어 있지 않음
설치 URL이 변경되어 이전 URL이 무효
해결
bash
# 공식 설치 URL
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
# Full setup 선택 (Anthropic API key 직접 입력 방식)
# System service로 설치 (VPS 재부팅 시 자동 시작)교훈: 오픈소스 프로젝트의 설치 URL은 변경될 수 있다. 공식 GitHub 저장소(NousResearch/hermes-agent)에서 최신 설치 방법을 확인한다.
최종 아키텍처
[사용자] ←→ [Telegram] ←→ [VPS: Hermes Gateway] ←→ [Anthropic API]
(24시간 상시 운영)
[PC: Hermes Desktop] ←→ [Anthropic API]
(수업 실습용, 필요시 사용)비개발자를 위한 체크리스트
Anthropic Console에서 API key 발급 + 크레딧 충전
BotFather에서 Telegram Bot 생성 + Token 발급
VPS에 Hermes 설치 (
Full setup→Local→System service)API key 등록:
hermes config set ANTHROPIC_API_KEY "키"Gateway 설정:
hermes gateway setup→ Telegram 선택 → Token + 숫자ID 입력Gateway 시작:
hermes gateway restartPC의 Gateway는 반드시 중지 (Token 충돌 방지)
Telegram에서 봇에게 메시지 보내 응답 확인
