Hermes Agent 완벽 설치 가이드 (glm-5.1:cloud 상세 버전)

참고 영상: Hermes Agent Full Setup Tutorial: How to Setup Your First AI Agent (Gemma 4)
작성일: 2026-04-19
공식 문서: https://hermes-agent.nousresearch.com

1. 사전 준비사항

하드웨어 요구사항

구성	최소 사양	권장 사양
CPU	4코어 이상	8코어 이상
RAM	8 GB	16 GB 이상
GPU/VRAM	없음 (클라우드 모델 사용 시)	16~24 GB VRAM (로컬 모델용)
저장공간	10 GB 여유	50 GB 이상 여유

로컬 모델별 VRAM 가이드

모델	필요 VRAM	추천 하드웨어
Gemma 4 E4B (~8 GB)	8 GB	MacBook Air M2/M3, 일반 노트북
Gemma 4 26B MoE (~20 GB)	20 GB	MacBook Pro M3/M4 (24GB), RTX 4090
Gemma 4 31B (~24 GB)	24 GB	RTX 4090, Mac Studio
Qwen 3.5 9B (~8 GB)	8 GB	일반 노트북
Qwen 3.5 27B (~20 GB)	20 GB	MacBook Pro M3/M4 (24GB), RTX 4090

소프트웨어 요구사항

항목	버전	비고
Git	최신 안정 버전	설치 전 필요
Python	3.11+	설치 스크립트가 자동 설치
Node.js	v22+	브라우저 자동화/WhatsApp 필요 시
OS	Linux / macOS / WSL2	Windows는 WSL2 필수

참고: 설치 스크립트가 uv, Python 3.11, Node.js v22, ripgrep, ffmpeg 등 의존성을 자동으로 설치합니다. Git만 사전에 준비하면 됩니다.

2. 단계별 설치 명령어

방법 A: 원클릭 설치 (권장)

# Linux / macOS / WSL2 / Android (Termux)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

설치 완료 후 셸 재시작:

source ~/.bashrc   # bash 사용 시
source ~/.zshrc    # zsh 사용 시

방법 B: 수동 설치

# 1. uv 설치
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 저장소 클론 (서브모듈 포함)
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 3. 가상환경 생성 (Python 3.11)
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"

# 4. 의존성 설치 (전체 기능)
uv pip install -e ".[all]"

# 5. 선택: RL 학습 서브모듈
uv pip install -e "./tinker-atropos"

# 6. 선택: Node.js 의존성 (브라우저 자동화/WhatsApp)
npm install

# 7. 설정 디렉토리 생성
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env

# 8. PATH 등록
mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 9. 설치 확인
hermes doctor
hermes version

Windows 사용자

# WSL2 설치 (PowerShell 관리자 권한)
wsl --install

# WSL2 터미널에서 설치
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

3. Ollama 설정 (Gemma 4 모델)

3-1. Ollama 설치

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Ollama 서버 시작
ollama serve

3-2. Gemma 4 모델 다운로드

# 가볍게 시작: E4B (8GB VRAM)
ollama pull gemma4:e4b

# 추천: 26B MoE (20GB VRAM) — 에이전트 용도 최적
ollama pull gemma4:26b

# 최고 품질: 31B Dense (24GB VRAM)
ollama pull gemma4:31b

Hermes 최소 컨텍스트 길이: 64K 토큰. 로컬 모델 실행 시 반드시 확인하세요.

3-3. Ollama 컨텍스트 설정

# Gemma 4 26B를 64K 컨텍스트로 실행
ollama run gemma4:26b

# 또는 컨텍스트 크기 명시적 지정 (Hermes 최소 요구사항)
# Ollama v0.20.0+ 에서는 자동 감지됨

3-4. Hermes에서 Ollama 연결

hermes model

설정 마법사에서:

“More providers…” 선택
“Custom endpoint (enter URL manually)” 선택
API base URL 입력: http://127.0.0.1:11434/v1
API key: 비워두기 (로컬 Ollama는 키 불필요)
자동 감지된 모델 목록에서 gemma4:26b 선택
Context length: 비워두기 (자동 감지) 또는 65536 입력

3-5. 직접 설정 (config.yaml)

model:
  default: gemma4:26b
  provider: custom
  base_url: http://127.0.0.1:11434/v1
  context_length: 65536

3-6. 빠른 시작 (Ollama 통합)

# Ollama에서 직접 Hermes 실행
ollama launch hermes

Ollama가 설치, 모델 선택, 프로바이더 설정을 한 번에 처리합니다.

4. Hermes Agent 설정

4-1. 설정 마법사 실행

# 전체 설정 (권장)
hermes setup

# 또는 개별 설정
hermes model    # LLM 프로바이더/모델 선택
hermes tools    # 도구 활성화/비활성화
hermes gateway setup  # 메시징 플랫폼 연동

4-2. 설정 디렉토리 구조

~/.hermes/
├── config.yaml     # 메인 설정 파일
├── .env            # API 키 및 시크릿
├── auth.json       # OAuth 인증 정보
├── SOUL.md         # 에이전트 정체성
├── memories/       # 장기 메모리
├── skills/         # 자동 생성 스킬
├── cron/           # 예약 작업
├── sessions/       # 세션 데이터
└── logs/           # 로그 파일

4-3. API 키 설정

# .env 파일에 직접 작성
# 최소 하나의 LLM 프로바이더 키 필요

# Ollama (로컬) - 키 불필요
# OpenRouter (클라우드, 추천)
OPENROUTER_API_KEY=sk-or-v1-your-key-here

# 선택: 추가 도구용
FIRECRAWL_API_KEY=fc-your-key       # 웹 검색/스크래핑
FAL_KEY=your-fal-key                 # 이미지 생성 (FLUX)

# 또는 CLI로 설정
hermes config set OPENROUTER_API_KEY sk-or-v1-xxx

4-4. 대화 시작

# 기본 CLI
hermes

# 모던 TUI (추천)
hermes --tui

# 이전 세션 이어서
hermes --continue
# 또는
hermes -c

# 특정 모델로 시작
hermes chat --provider custom --model gemma4:26b

4-5. 주요 슬래시 명령어

명령	설명
`/help`	도움말 표시
`/tools`	사용 가능한 도구 목록
`/model`	모델 전환 (세션 내)
`/compress`	현재 세션 압축
`/save`	대화 저장
`/voice on`	음성 모드 켜기
`/skills`	스킬 관리
`/quit`	종료

4-6. 터미널 백엔드 설정

# 로컬 (기본값)
hermes config set terminal.backend local

# Docker 샌드박스 (권장: 보안)
hermes config set terminal.backend docker

# 원격 서버 SSH
hermes config set terminal.backend ssh

Docker 백엔드 설정 (config.yaml):

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_volumes:
    - "/home/user/projects:/workspace/projects"
  container_cpu: 1
  container_memory: 5120
  container_persistent: true

5. Telegram 봇 연동

5-1. BotFather에서 봇 생성

Telegram에서 @BotFather 검색
/newbot 명령 전송
봇 이름 입력 (예: “Hermes Agent”)
봇 사용자 이름 입력 (예: my_hermes_bot, bot으로 끝나야 함)
BotFather가 제공하는 API 토큰 저장 (형식: 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ)

⚠️ 봇 토큰은 비밀입니다. 유출 시 즉시 /revoke로 재발급하세요.

5-2. 봇 커스터마이징 (선택)

BotFather에서 추가 설정:

명령	용도
`/setdescription`	봇 설명
`/setabouttext`	프로필 짧은 설명
`/setuserpic`	봇 아바타
`/setcommands`	명령 메뉴 (`/help`, `/new`, `/sethome` 추천)
`/setprivacy`	그룹 메시지 접근 권한

5-3. Privacy Mode 설정 (그룹 채팅 시 중요)

@BotFather → /mybots → 봇 선택
Bot Settings → Group Privacy → Turn off

⚠️ Privacy mode 변경 후 봇을 그룹에서 삭제하고 다시 추가해야 반영됩니다.
또는 봇을 그룹 관리자로 승격하면 privacy mode와 무관하게 모든 메시지 수신 가능.

5-4. 사용자 ID 확인

# 방법 1: @userinfobot 에 메시지 보내기
# 방법 2: @get_id_bot 에 메시지 보내기
# 숫자 형태의 ID 획득 (예: 123456789)

5-5. Hermes에 Telegram 설정

방법 A: 대화형 설정 (권장)

hermes gateway setup
# Telegram 선택 → 토큰 입력 → 허용 사용자 ID 입력

방법 B: 수동 설정

~/.hermes/.env 파일에 추가:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789   # 쉼표로 다중 사용자 가능

5-6. 게이트웨이 시작

# 포그라운드 실행 (테스트용)
hermes gateway

# 백그라운드 실행 (운영용)
hermes gateway start

# 상태 확인
hermes gateway status

# WSL2 환경에서는 포그라운드 권장
hermes gateway run

# 또는 tmux 사용
tmux new -s hermes 'hermes gateway run'
# 재접속: tmux attach -t hermes

5-7. Webhook 모드 (클라우드 배포 시)

로컬/항상 켜진 서버 → Long Polling (기본값, 추가 설정 불필요)
클라우드 (Fly.io 등) → Webhook 모드 권장

# ~/.hermes/.env에 추가
TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
TELEGRAM_WEBHOOK_SECRET=$(openssl rand -hex 32)  # 권장
# TELEGRAM_WEBHOOK_PORT=8443  # 선택, 기본 8443

5-8. 그룹 채팅 설정

~/.hermes/config.yaml에 추가:

telegram:
  require_mention: true           # 멘션/명령에만 반응
  mention_patterns:
    - "^\\s*hermes\\b"            # "hermes"로 시작하는 메시지에 반응
  ignored_threads:
    - 31
    - "42"

5-9. 홈 채널 설정

Telegram에서 /sethome 명령으로 현재 채팅을 홈 채널로 설정.
예약 작업(cron) 결과가 이 채널로 전송됩니다.

5-10. 음성 메시지 지원

# 로컬 음성 인식 (faster-whisper, 무료)
pip install "hermes-agent[voice]"

# 또는 API 기반 (더 정확)
# ~/.hermes/.env에 추가:
GROQ_API_KEY=gsk_xxx           # Groq Whisper
VOICE_TOOLS_OPENAI_KEY=sk-xxx  # OpenAI Whisper

TTS (텍스트 → 음성) 설정은 config.yaml:

tts:
  provider: edge-tts    # 무료 (기본), ffmpeg 필요
  # provider: openai   # 고품질, 비용 발생
  # provider: elevenlabs  # 최고 품질, 비용 발생

6. Firecrawl 셀프호스팅

Firecrawl은 Hermes Agent의 웹 검색/스크래핑 도구입니다. 셀프호스팅하면 API 키 비용 없이 로컬에서 실행 가능합니다.

6-1. 사전 요구사항

Docker 및 Docker Compose 설치됨
최소 4GB RAM, 10GB 디스크 여유

6-2. Firecrawl 저장소 클론

git clone https://github.com/firecrawl/firecrawl.git
cd firecrawl

6-3. 환경 변수 설정

cp apps/api/.env.example .env

.env 파일 편집:

# 필수 설정
PORT=3002
HOST=0.0.0.0
USE_DB_AUTHENTICATION=false

# AI 기능 사용 시 (선택)
# OPENAI_API_KEY=sk-xxx

# 실험적: Ollama 로컬 LLM 사용
# OLLAMA_BASE_URL=http://localhost:11434/api
# MODEL_NAME=gemma4:26b
# MODEL_EMBEDDING_NAME=nomic-embed-text

# 큐 관리자 비밀키 (공개 접근 시 변경 필수)
BULL_AUTH_KEY=CHANGEME

# 선택: SearXNG 연동 (검색 API)
# SEARXNG_ENDPOINT=http://your.searxng.server

6-4. Docker Compose로 실행

# 빌드
docker compose build

# 실행
docker compose up -d

# 상태 확인
docker compose ps

# 로그 확인
docker compose logs -f

Firecrawl이 http://localhost:3002 에서 실행됩니다.

6-5. 동작 확인

curl -X POST http://localhost:3002/v2/crawl \
    -H 'Content-Type: application/json' \
    -d '{
      "url": "https://docs.firecrawl.dev"
    }'

6-6. Hermes Agent에 연결

~/.hermes/.env에 추가:

# 셀프호스팅 Firecrawl 사용 시
FIRECRAWL_API_KEY=fc-CHANGEME
FIRECRAWL_API_URL=http://localhost:3002

참고: 셀프호스팅 시 /agent 및 /browser 엔드포인트는 지원되지 않습니다.
기본 fetch 및 Playwright 스크래핑은 정상 작동합니다.

6-7. SearXNG 연동 (선택, 검색 기능 강화)

# Docker로 SearXNG 실행
docker run -d --name searxng \
  -p 8888:8080 \
  -e SEARXNG_BASE_URL=http://localhost:8888/ \
  searxng/searxng

# Firecrawl .env에 추가
# SEARXNG_ENDPOINT=http://localhost:8888

7. 문제 해결 / 팁

설치 관련

문제	해결 방법
`hermes: command not found`	셸 재시작: `source ~/.bashrc` 또는 `source ~/.zshrc`
Python 버전 너무 낮음	`python3 --version` 확인 → 3.11+ 필요. 설치 스크립트가 자동 처리
`uv: command not found`	`curl -LsSf https://astral.sh/uv/install.sh \| sh && source ~/.bashrc`
권한 오류	`sudo` 사용 금지. `~/.local/bin`에 설치됨. 이전 sudo 설치 제거: `sudo rm /usr/local/bin/hermes`
Windows 미지원	WSL2 필수. `wsl --install` 후 WSL 내에서 설치

Ollama / 모델 관련

문제	해결 방법
모델이 감지되지 않음	`ollama list`로 모델 확인. `ollama serve`가 실행 중인지 확인
컨텍스트 길이 부족	`config.yaml`에 `context_length: 65536` 명시. Hermes는 최소 64K 필요
로컬 모델 타임아웃	`.env`에 `HERMES_STREAM_READ_TIMEOUT=1800` 추가. 로컬은 자동으로 1800초로 설정됨
VRAM 부족	더 작은 모델 사용 (gemma4:e4b) 또는 클라우드 프로바이더로 전환
Ollama의 num_ctx 불일치	`ollama run --num_ctx 65536`으로 실행한 경우, Hermes config에도 동일하게 설정 필요

Telegram 관련

문제	해결 방법
봇이 응답하지 않음	`hermes gateway status` 확인. 로그: `cat ~/.hermes/logs/gateway.log \| tail -50`
그룹에서 봇이 메시지를 못 봄	Privacy mode 끄기 → 봇을 그룹에서 제거 후 재추가. 또는 관리자로 승격
메시지 전송 실패	봇 토큰 확인: `hermes gateway setup`. 네트워크/프록시 확인
WSL2에서 게이트웨이 끊김	포그라운드 실행: `hermes gateway run`. tmux 사용 권장
게이트웨이 시작 실패	`pip install "hermes-agent[telegram]"` 확인. 포트 충돌: `lsof -i :8080`

Firecrawl 관련

문제	해결 방법
컨테이너 시작 실패	`docker logs firecrawl` 로그 확인. `.env` 변수 재확인
Redis 연결 오류	Docker Compose에서 Redis 서비스가 실행 중인지 확인
API 응답 없음	`PORT=3002` 확인. 다른 서비스가 같은 포트 사용 중인지 확인
Supabase 경고	무시해도 됨. 인증 없이 스크래핑/크롤링 정상 작동

유용한 명령어

# 진단 실행
hermes doctor

# 현재 설정 확인
hermes config show

# 설정 마이그레이션 (업데이트 후)
hermes config migrate

# 설정 누락 확인
hermes config check

# 최신 버전으로 업데이트
hermes update

# 특정 설정 변경
hermes config set terminal.backend docker
hermes config set model gemma4:26b

# 세션 압축 (컨텍스트 초과 시)
/compress    # Hermes 대화 중에 입력

# 디버그 모드
hermes --debug

프로덕션 배포 팁

Docker 백엔드 사용: hermes config set terminal.backend docker — 명령 실행이 샌드박스 격리
로그 관리: ~/.hermes/logs/ 확인. 시크릿 자동 마스킹됨
자동 시작: systemd 또는 tmux로 hermes gateway run 자동 실행 설정
백업: ~/.hermes/ 디렉토리 정기 백업 (메모리, 스킬, 설정 포함)
멀티 모델 라우팅:

# 일반 태스크용 프로필
hermes profile create general --model gemma4:26b

# 코딩용 프로필
hermes profile create coder --model qwen3.5:27b

# 프로필 실행
hermes --profile general
hermes --profile coder

참고 링크

공식 문서: https://hermes-agent.nousresearch.com
GitHub: https://github.com/NousResearch/hermes-agent
Ollama 연동 가이드: https://docs.ollama.com/integrations/hermes
Firecrawl 셀프호스팅: https://docs.firecrawl.dev/contributing/self-host
Telegram 설정: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram
FAQ: https://hermes-agent.nousresearch.com/docs/reference/faq

💡 2026-04-20 업데이트: MiniCITY 환경에서 Ollama는 맥미니에서 구동됨. WSL2에서 Hermes 사용 시 model.base_url을 맥미니 Tailscale IP로 설정 필요. http://100.96.177.124:11434/v1 (맥미니 Tailscale IP)

[!note] 수정이력 | 2026-04-20 11:01, 미미

Hermes Agent 완벽 설치 가이드 (glm-5.1:cloud 상세 버전)

Hermes Agent 완벽 설치 가이드 (glm-5.1:cloud 상세 버전)

목차

1. 사전 준비사항

하드웨어 요구사항

로컬 모델별 VRAM 가이드

소프트웨어 요구사항

2. 단계별 설치 명령어

방법 A: 원클릭 설치 (권장)

방법 B: 수동 설치

Windows 사용자

3. Ollama 설정 (Gemma 4 모델)

3-1. Ollama 설치

3-2. Gemma 4 모델 다운로드

3-3. Ollama 컨텍스트 설정

3-4. Hermes에서 Ollama 연결

3-5. 직접 설정 (config.yaml)

3-6. 빠른 시작 (Ollama 통합)

4. Hermes Agent 설정

4-1. 설정 마법사 실행

4-2. 설정 디렉토리 구조

4-3. API 키 설정

4-4. 대화 시작

4-5. 주요 슬래시 명령어

4-6. 터미널 백엔드 설정

5. Telegram 봇 연동

5-1. BotFather에서 봇 생성

5-2. 봇 커스터마이징 (선택)

5-3. Privacy Mode 설정 (그룹 채팅 시 중요)

5-4. 사용자 ID 확인

5-5. Hermes에 Telegram 설정

방법 A: 대화형 설정 (권장)

방법 B: 수동 설정

5-6. 게이트웨이 시작

5-7. Webhook 모드 (클라우드 배포 시)

5-8. 그룹 채팅 설정

5-9. 홈 채널 설정

5-10. 음성 메시지 지원

6. Firecrawl 셀프호스팅

6-1. 사전 요구사항

6-2. Firecrawl 저장소 클론

6-3. 환경 변수 설정

6-4. Docker Compose로 실행

6-5. 동작 확인

6-6. Hermes Agent에 연결

6-7. SearXNG 연동 (선택, 검색 기능 강화)

7. 문제 해결 / 팁

설치 관련

Ollama / 모델 관련

Telegram 관련

Firecrawl 관련

유용한 명령어

프로덕션 배포 팁

참고 링크