헤르메스 에이전트 설치부터 텔레그램 연결까지

이론은 끝났다. 지금부터 손을 움직여보자.

이 글은 2026년 6월 기준으로 작성됐다. 설치 스크립트와 명령어는 버전에 따라 달라질 수 있으니, 막히는 부분이 있으면 공식 GitHub 레포지토리를 참고하자.

시작 전 준비물 체크리스트

설치에 앞서 아래 항목을 먼저 확인한다. 다 갖춰져 있다면 바로 다음 섹션으로 넘어가도 좋다.

항목	Windows	macOS / Linux
운영체제	Windows 10/11 + WSL2	macOS 12+, Ubuntu 20.04+
터미널	WSL2 터미널	기본 터미널
AI 모델 API 키	OpenRouter 또는 OpenAI, Anthropic 중 하나	동일
(선택) 텔레그램 봇 토큰	BotFather로 발급	동일

API 키가 없다면: OpenRouter에서 가입하면 다양한 모델을 하나의 키로 사용할 수 있다. 헤르메스 공식 문서에서도 OpenRouter를 기본으로 추천한다.

로컬 모델을 원한다면: Ollama를 설치하면 API 비용 없이 운용 가능하다. 단, 성능은 모델 품질에 따라 달라진다.

단계별 설치 가이드

1단계: WSL2 설치 (Windows 사용자만)

macOS 또는 Linux 사용자는 이 단계를 건너뛴다.

PowerShell을 관리자 권한으로 열고 아래 명령어를 실행한다.

wsl --install

설치 완료 후 PC를 재시작한다. 재시작 후 자동으로 Ubuntu 설정이 시작되면, 사용자 이름과 비밀번호를 입력하면 된다. 여기서 설정한 비밀번호는 나중에 sudo 명령어 실행 시 필요하니 기억해두자.

설치가 완료됐는지 확인:

wsl --version

2단계: 헤르메스 에이전트 설치

WSL2 터미널(또는 macOS/Linux 터미널)에서 아래 명령어를 실행한다. 공식 설치 스크립트가 필요한 모든 의존성을 자동으로 처리해 준다.

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

설치가 끝나면 반드시 쉘을 새로고침한다.

source ~/.bashrc
# zsh를 사용한다면:
source ~/.zshrc

설치가 제대로 됐는지 확인:

hermes --version

버전 정보가 출력되면 설치 성공이다.

3단계: 초기 설정 (hermes setup)

hermes setup

이 명령어를 실행하면 대화형 설정 마법사가 시작된다. 순서대로 입력한다.

AI 모델 제공자 선택 — OpenRouter, OpenAI, Anthropic, Ollama 중 선택
API 키 입력 — 선택한 제공자의 API 키를 붙여넣는다
기본 모델 선택 — 추천: anthropic/claude-3.5-sonnet (성능과 비용 균형 우수)
에이전트 이름 설정 — 원하는 이름을 입력한다 (나중에 SOUL.md에서 변경 가능)
작업 디렉토리 설정 — 에이전트가 파일 작업을 수행할 기본 경로

설정이 완료되면 ~/.hermes/ 디렉토리에 설정 파일이 생성된다. SOUL.md와 MEMORY.md도 이 디렉토리 안에 있다.

4단계: 첫 실행 테스트

설치가 완료됐다면 바로 실행해보자.

hermes

프롬프트가 뜨면 간단한 명령을 입력해보자.

> 현재 날짜와 시간을 알려줘
> 내 홈 디렉토리의 파일 목록을 보여줘

응답이 정상적으로 오면 설치 완료다.

텔레그램 봇 연결하기

헤르메스의 진가는 텔레그램과 연결했을 때 드러난다. 스마트폰으로 어디서든 명령을 내리고 결과를 받을 수 있다.

텔레그램 봇 토큰 발급:

텔레그램에서 @BotFather를 검색해 대화를 시작한다.
/newbot 명령어를 입력한다.
봇 이름과 사용자 이름을 설정한다. (사용자 이름은 bot으로 끝나야 한다)
발급된 HTTP API 토큰을 복사해둔다. (예: 7123456789:AAHxxxxxxxxxxxxxxxx)

헤르메스에 텔레그램 연결:

hermes gateway add telegram

명령 실행 후 토큰 입력 프롬프트가 나오면 복사해둔 토큰을 붙여넣는다.

연결 확인:

hermes gateway list

telegram: active 상태가 보이면 성공이다.

이제 텔레그램에서 봇과 대화하면 헤르메스 에이전트가 응답한다. 서버가 켜져 있는 동안 24시간 언제든 명령을 받는다.

자주 발생하는 오류와 해결법

설치 과정에서 막히는 경우가 있다. 자주 발생하는 오류와 해결법을 정리했다.

오류: command not found: hermes

쉘을 새로고침하지 않았을 때 발생한다.

source ~/.bashrc

그래도 안 된다면 터미널을 완전히 닫고 다시 열어보자.

오류: curl: (6) Could not resolve host

네트워크 문제 또는 WSL2의 DNS 설정 오류다.

echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

입력 후 다시 설치 명령어를 실행한다.

오류: API 키 인증 실패

API 키를 잘못 입력했거나 만료됐을 때 발생한다. 아래 명령으로 API 키를 재설정한다.

hermes setup --reset-api

텔레그램 봇이 응답하지 않음

헤르메스가 실행 중인지 확인한다. 텔레그램 게이트웨이는 에이전트가 실행 중일 때만 동작한다.

hermes status
hermes start  # 실행 중이 아니라면

24시간 상시 실행을 원한다면 systemd 서비스로 등록하거나, nohup 또는 tmux를 활용하자.

자주 묻는 질문 (FAQ)

Q. Ollama로 로컬 모델을 연결하면 성능 차이가 크나? A. 로컬 모델은 API 비용이 없다는 장점이 있지만, Claude나 GPT-4 급 성능을 내려면 고사양 GPU가 필요하다. 8GB VRAM 이하의 환경이라면 API 모델이 더 현실적이다.

Q. VPS(클라우드 서버)에 설치하면 어떤 장점이 있나? A. 로컬 PC가 꺼져 있어도 에이전트가 계속 실행된다. 월 5달러 수준의 저가 VPS(DigitalOcean, Hetzner 등)로도 충분히 운용 가능하다. 24시간 자동화가 목표라면 VPS 설치를 강력히 권장한다.

Q. 에이전트를 여러 개 운용할 수 있나? A. 가능하다. 헤르메스는 여러 인스턴스를 독립적으로 실행할 수 있다. 업무용 에이전트와 개인용 에이전트를 분리해서 운용하는 방식도 유효하다.

📝 정리

이번 글에서 다룬 핵심 내용:

[x] WSL2(Windows), curl 스크립트로 설치, hermes setup으로 초기 설정 완료
[x] hermes gateway add telegram으로 텔레그램 봇 연결 가능
[x] 자주 발생하는 오류(command not found, DNS 오류, API 인증 실패)와 해결법
[x] 24시간 운용을 원한다면 VPS 환경에 설치를 권장

헤르메스 에이전트 완전정복 시리즈는 여기까지다. 개념부터 원리, 설치까지 — 이제 직접 써먹을 일만 남았다. 처음 설치하고 텔레그램으로 첫 명령을 내리는 순간, "이게 진짜 AI 에이전트구나" 하는 느낌을 받게 될 것이다.