에르메스 에이전트 Hermes Agent 설치부터 Telegram 연동까지 5단계 완벽 가이드

클로드 코드(Claude Code)나 Codex 같은 터미널 AI 에이전트가 주목받고 있지만, 특정 모델에 종속되지 않으면서 Hermes Agent 설치 한 번으로 200개 이상의 LLM을 자유롭게 전환할 수 있는 오픈소스 에이전트가 등장했다. Nous Research가 만든 Hermes Agent는 사용할수록 스스로 스킬을 만들고 개선하는 자기 학습 루프를 내장한 유일한 에이전트다.

이 글에서는 Hermes Agent를 설치하고, 원하는 LLM 프로바이더를 연결한 뒤, Telegram 봇으로 연동해서 스마트폰에서도 에이전트와 대화하는 전체 과정을 5단계로 정리한다.

Hermes Agent란? — 자기 학습형 오픈소스 AI 에이전트

Hermes Agent는 Nous Research가 개발한 MIT 라이선스 오픈소스 AI 에이전트다. GitHub 스타 8,700개 이상을 기록하며 빠르게 성장 중이다. Claude Code나 Cursor 같은 도구와 비슷한 터미널 기반 인터페이스를 제공하지만, 근본적으로 다른 철학을 가지고 있다.

핵심 특징 요약

• 자기 학습 루프: 복잡한 작업을 수행한 뒤 자동으로 스킬(skill)을 생성하고, 다음 사용 시 스스로 개선한다. 세션 간 메모리를 유지하며 사용자 모델링까지 수행한다.
• 모델 자유: OpenRouter(200+ 모델), OpenAI, Anthropic, Nous Portal, z.ai, Kimi, MiniMax, Ollama 등 어떤 LLM이든 hermes model 한 줄로 전환 가능하다.
• 멀티 플랫폼 접속: CLI뿐 아니라 Telegram, Discord, Slack, WhatsApp, Signal에서 동일 에이전트와 대화할 수 있다.
• 저비용 운영: 저사양 Linux 서버에서도 돌릴 수 있고, Modal이나 Daytona 같은 서버리스 백엔드를 사용하면 유휴 시 비용이 거의 없다.
• Cron 스케줄링: 자연어로 “매일 아침 9시에 AI 뉴스 요약해서 텔레그램으로 보내줘” 같은 자동화가 가능하다.

Claude Code와의 차이점

Claude Code는 Anthropic 모델 전용이지만, Hermes Agent는 프로바이더 잠김(lock-in)이 없다. 또한 메시징 게이트웨이를 통해 노트북을 열지 않고도 스마트폰에서 서버 작업을 지시할 수 있다는 점이 실전에서 큰 차이를 만든다.

Hermes Agent 설치 방법 — 1분 원라인 설치

Hermes Agent 설치는 놀라울 정도로 간단하다. Linux, macOS, WSL2 환경에서 아래 한 줄이면 Python, Node.js, 의존성, hermes 커맨드까지 전부 자동 설정된다.

설치 명령어

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

설치가 완료되면 셸을 리로드한다.

source ~/.bashrc    # zsh 사용자는 source ~/.zshrc

시스템 요구사항

• 운영체제: Linux, macOS, WSL2 (Windows 네이티브 미지원)
• 필수 의존성: git만 있으면 된다. 나머지는 인스톨러가 처리.
• Python: 인스톨러가 자동 설치 (3.11 권장)
• Node.js: 인스톨러가 자동 설치

Windows 사용자 참고: 반드시 WSL2를 먼저 설치한 뒤 WSL2 터미널 안에서 위 명령을 실행해야 한다. PowerShell이나 CMD에서는 동작하지 않는다.

설치 확인

hermes              # 대화형 CLI 실행
hermes doctor       # 설치 상태 진단

hermes 입력 시 웰컴 배너와 함께 현재 모델, 사용 가능한 도구, 스킬 목록이 표시되면 설치 성공이다.

LLM 프로바이더 설정 — 원하는 모델 연결하기

Hermes Agent 설치 직후에는 LLM 프로바이더를 선택해야 한다. 인스톨러가 자동으로 안내하지만, 나중에 바꾸고 싶을 때는 아래 명령을 사용한다.

셋업 위자드 실행

hermes setup        # 전체 설정 한 번에 (권장)
hermes model        # 모델/프로바이더만 변경

주요 프로바이더 비교

• OpenRouter: API 키 하나로 200+ 모델 접근. 가장 범용적. OPENROUTER_API_KEY 설정.
• Anthropic: Claude 모델 직접 사용. Claude Code 인증 또는 API 키 방식.
• OpenAI: GPT 시리즈 및 Codex 모델. OAuth 디바이스 코드 인증.
• Nous Portal: 구독 기반, OAuth 로그인으로 제로 설정.
• 커스텀 엔드포인트: vLLM, SGLang, Ollama 등 자체 호스팅 모델. Base URL + API 키 입력.

프로바이더는 언제든 hermes model로 전환할 수 있다. 코드 변경 없이 모델만 바꾸면 되므로, 작업 성격에 따라 빠른 모델과 정확한 모델을 오가며 사용하는 전략이 가능하다.

Telegram 봇 연동 — 어디서든 에이전트와 대화

Hermes Agent의 킬러 기능 중 하나가 메시징 게이트웨이다. 특히 Telegram 연동을 설정하면 노트북을 열지 않고도 스마트폰에서 서버의 에이전트에게 작업을 지시할 수 있다.

Step 1: BotFather에서 봇 생성

1. Telegram에서 @BotFather를 검색하고 대화를 시작한다.
2. /newbot 명령을 전송한다.
3. 봇의 표시 이름을 입력한다 (예: “My Hermes Agent”).
4. 봇의 유저네임을 입력한다. 반드시 bot으로 끝나야 한다 (예: my_hermes_bot).
5. BotFather가 API 토큰을 발급한다. 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ 형태의 문자열이다.

보안 주의: 봇 토큰은 절대 외부에 공개하면 안 된다. 토큰이 유출되면 BotFather에서 /revoke 명령으로 즉시 폐기하고 재발급받아야 한다.

Step 2: 내 Telegram User ID 확인

Telegram에서 @userinfobot에게 아무 메시지나 보내면 숫자형 User ID를 알려준다. 이 숫자를 기록해둔다. 유저네임이 아니라 123456789 같은 숫자 ID가 필요하다.

Step 3: Hermes에 Telegram 연결

방법 A — 인터랙티브 위자드 (권장)

hermes gateway setup

Telegram을 선택한 뒤 봇 토큰과 허용할 User ID를 입력하면 자동으로 설정 파일이 생성된다.

방법 B — 수동 설정

~/.hermes/.env 파일에 아래 내용을 추가한다.

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=내_유저_ID

여러 사용자를 허용하려면 쉼표로 구분한다: TELEGRAM_ALLOWED_USERS=111111,222222

Step 4: 게이트웨이 실행 및 테스트

hermes gateway

몇 초 내에 봇이 온라인으로 뜬다. Telegram에서 봇에게 메시지를 보내서 응답이 오는지 확인한다.

Telegram 주요 명령어

• /new — 새 대화 시작
• /model provider:model — 모델 변경
• /stop — 현재 작업 중단
• /compress — 컨텍스트 압축
• /sethome — 현재 채팅을 홈 채널로 설정 (Cron 결과 전달용)
• /voice on — 음성 응답 활성화

음성 메모를 보내면 자동으로 STT(음성→텍스트) 변환되어 처리된다. faster-whisper를 설치하면 로컬에서 무료로 음성 인식을 사용할 수 있다.

백그라운드 서비스 등록 및 실전 운영 팁

개인 노트북에서만 쓸 거라면 hermes gateway로 포그라운드 실행해도 충분하다. 하지만 서버에 올려서 24시간 운영하려면 systemd 서비스로 등록하는 게 안정적이다.

systemd 서비스 등록 (Linux)

hermes gateway install          # systemd 유저 서비스 설치
hermes gateway start             # 서비스 시작
sudo loginctl enable-linger $USER  # 로그아웃 후에도 유지

상태 확인과 로그는 아래 명령으로 본다.

hermes gateway status                       # 서비스 상태 확인
journalctl --user -u hermes-gateway -f      # 실시간 로그

부팅 시 자동 시작 (헤드리스 서버)

sudo hermes gateway install --system    # 시스템 레벨 서비스 설치
sudo hermes gateway start --system      # 시작

서버 재부팅 후에도 게이트웨이가 자동으로 올라오므로 별도 관리가 필요 없다.

실전 운영 팁

• Docker 격리: hermes config set terminal.backend docker로 터미널 명령을 Docker 컨테이너 안에서 실행하면 보안이 강화된다.
• Cron 자동화: Telegram에서 “매일 아침 9시에 서버 상태 점검해서 보내줘”라고 말하면 에이전트가 Cron 작업을 설정한다.
• 업데이트: hermes update 한 줄로 최신 버전 업데이트. Telegram에서 /update 명령으로도 가능하다.
• MCP 서버 연동: ~/.hermes/config.yaml에 MCP 서버를 추가하면 GitHub, 데이터베이스 등 외부 도구와 연결된다.

보안 팁: TELEGRAM_ALLOWED_USERS를 반드시 설정해야 한다. 미설정 시 기본적으로 모든 사용자가 차단되지만, 실수로 GATEWAY_ALLOW_ALL_USERS=true를 켜면 누구나 서버 터미널에 접근할 수 있다.

Hermes Agent에 대한 더 자세한 내용은 공식 문서에서 확인할 수 있다.

Hermes Agent GitHub 리포지토리: https://github.com/NousResearch/hermes-agent