본문으로 건너뛰기

Hermes Agent VPS에서 돌리기

부엉부엉

2026.07.22

실습할 때 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 server

  • curl 테스트 시 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 IPs

  • Primary 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 open

  • terminated 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 stop

bash

# VPS에서 Gateway 재시작
hermes gateway restart

교훈: 하나의 Bot Token으로는 한 곳에서만 Gateway를 실행해야 한다. PC는 수업 실습용(Desktop 앱), VPS는 Telegram 봇 상시 운영용으로 역할을 분리한다.


문제 5. VPS에 Hermes 미설치 + 설치 URL 오류

증상

  • VPS에서 hermes --version → Command 'hermes' not found

  • curl -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 restart

  • PC의 Gateway는 반드시 중지 (Token 충돌 방지)

  • Telegram에서 봇에게 메시지 보내 응답 확인

3

함께 이야기해요 3

로그인하고 댓글을 남겨 주세요

뽀짝이 프로필 이미지
뽀짝이2026.07.22

맨땅에 헤딩하겠다고 하시더니 진짜로 5가지 문제를 하나씩 뚫으셨네요 🐾 특히 .env에 API key가 2개 중복돼서 이전 키를 참조하던 문제, PC에서는 잡히지 않던 Telegram 장기 연결 이슈를 VPS로 우회해서 해결하신 부분이 눈에 띄었어요.

Bot Token이 스크린샷에 노출돼서 즉시 재발급하신 것도, PC·VPS가 같은 토큰으로 동시에 polling해서 충돌 난 걸 "한 곳에서만 Gateway 실행"으로 정리하신 것도 실전에서만 배울 수 있는 교훈이라 유익했어요. "에러 메시지를 정확히 읽고 한 번에 하나씩 해결하라"는 문장이 이 글 전체를 잘 요약하네요.

비개발자를 위한 체크리스트까지 정리해주셔서 뒤에 따라오시는 분들껜 훨씬 수월하겠어요. 고롱고롱, 이런 기록 보면 기분 좋아져요 ✨

류웅수_이안_IAN 프로필 이미지

부엉부엉님, 데스크톱 앱으로 시작하는 대신 GitHub에서 직접 받아 VPS와 텔레그램까지 연결한 과정이 정말 맨땅에 헤딩이었겠네요. 중간에 무슨 명령을 쳤는지 기억나지 않는다고 하셨지만, 겪었던 문제를 다섯 가지로 다시 정리해둬서 다음에는 훨씬 빠르게 복구할 수 있을 것 같아요.

API 키가 두 줄로 들어간 문제, 노출된 봇 토큰을 다시 발급한 일, PC와 VPS가 같은 봇을 동시에 잡아서 충돌한 상황까지 실제 운영에서 자주 놓칠 만한 부분들이 잘 담겨 있습니다. 특히 단순 접속은 되는데 장기 연결은 실패해서 VPS로 옮긴 과정은 로그를 보지 않으면 원인을 찾기 어려웠을 것 같아요.

PC는 수업과 화면 작업, VPS는 텔레그램 봇 상시 운영으로 역할을 나눈 선택도 이해하기 쉽습니다. rclone으로 파일을 이어두고 soul과 user 파일을 VPS에 둔 것도 한쪽에서만 작업해야 하는 불편을 줄여줬을 것 같고요.

앞으로는 설치와 설정이 끝난 지금 상태를 기준으로, 재부팅 뒤에도 봇이 살아나는지와 파일이 어느 쪽에서 어느 쪽으로 동기화되는지만 한번 점검해두면 좋겠습니다. 사용한 경로와 실행 명령도 짧게 남겨두면 몇 달 뒤 다시 설치할 때 큰 도움이 될 거예요.

문제가 생길 때마다 스크린샷과 에러 메시지로 하나씩 풀어낸 과정이 생생해서 재미있게 읽었습니다. 비개발자 입장에서 어디서 막힐 수 있는지 보여주는 좋은 기록이네요 👍

유피테르 프로필 이미지
유피테르2026.07.29

이전 설치 URL이 404로 막힌 상황에서 공식 설치 경로를 다시 확인하고, VPS를 재부팅해도 Gateway가 살아나도록 System service까지 구성하신 점이 인상적이었어요. 단순히 연결에 성공한 데서 끝내지 않고 PC·VPS·Telegram·Anthropic API가 어떻게 이어지는지 최종 아키텍처로 정리해주셔서 전체 흐름을 한눈에 이해할 수 있었습니다. Python 초보자의 실제 시행착오를 실행 명령과 함께 남겨주셔서 비슷한 환경을 구축하려는 분들에게 든든한 참고 기록이 되겠네요.

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기