Hermes Agent 설치 메뉴얼

Hermes Agent 설치 메뉴얼

Gemma 4 + Ollama + Telegram 봇 + Firecrawl 셀프호스팅 완전 가이드
마지막 업데이트: 2026년 4월

---

1. 사전 준비사항

하드웨어 요구사항

구성	최소 사양	권장 사양	비고
RAM	16GB	24GB 이상	Gemma 4 26B 기준
VRAM	8GB	20GB 이상	GPU 가속 시
저장공간	50GB	100GB 이상	모델 + 컨테이너
CPU	4 코어	8 코어 이상	M 시리즈 또는 Ryzen/Intel

Mac 사용자 참고:

• M3/M4 MacBook Pro (16-24GB 통합 메모리) → Gemma 4 26B MoE 또는 Qwen 3.5 27B 실행 가능
• Mac Studio M4 Ultra (64GB+) → 모든 모델 variant 동시 실행 가능

소프트웨어 요구사항

• OS: macOS, Linux, WSL2 (Windows)
• Git: git --version 으로 확인
• Docker: Firecrawl 셀프호스팅용
• Node.js: v22+ (Hermes가 자동 설치)
• Python: 3.11+ (Hermes가 자동 설치)

💡 참고: Hermes 원클릭 인스톨러가 Git 외 모든 의존성을 자동으로 설치해줘.

---

2. 단계별 설치 명령어

2.1 Hermes Agent 설치

# 원클릭 인스톨러 실행 (Linux/macOS/WSL2)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 셸 리로드
source ~/.bashrc   # Bash 사용자
# 또는
source ~/.zshrc    # Zsh 사용자

# 설치 확인
hermes version
hermes doctor

2.2 수동 설치 (선택사항)

# 1. 저장소 클론
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 2. uv 설치 및 가상환경 생성
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv venv --python 3.11

# 3. 의존성 설치
export VIRTUAL_ENV="$(pwd)/venv"
uv pip install -e ".[all]"

# 4. Node.js 의존성 (브라우저 자동화/WhatsApp 용)
npm install

# 5. 설정 디렉토리 생성
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

# 6. PATH에 추가
mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

---

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 모델 다운로드

# 엣지 모델 (~8GB VRAM)
ollama pull gemma4:e4b

# **추천**: MoE 스위트스팟 (~20GB VRAM)
ollama pull gemma4:26b

# 최대 품질 (~24GB VRAM)
ollama pull gemma4:31b

# 대안: Qwen 3.5 (코딩 특화)
ollama pull qwen3.5:9b      # ~8GB
ollama pull qwen3.5:27b     # ~20GB (추천)
ollama pull qwen3.5:35b-a3b # ~12GB (MoE)

# 설치된 모델 확인
ollama list

3.3 Hermes에 Ollama 연결

# 모델 설정 위저드 실행
hermes model

# 다음 단계 선택:
# 1. "More providers…" 또는 "Custom endpoint" 선택
# 2. API Base URL: `http://127.0.0.1:11434/v1`
# 3. API Key: 비워둠 (없어도 됨)
# 4. 자동 감지된 모델에서 `gemma4:26b` 또는 `qwen3.5:27b` 선택

⚠️ 중요: Hermes는 최소 64K 토큰 컨텍스트가 필요해.
Ollama가 자동 감지하지만, 문제 발생 시 명시적으로 설정:

ollama run gemma4:26b --ctx-size 65536

3.4 config.yaml 직접 설정 (선택사항)

~/.hermes/config.yaml

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

---

4. Hermes Agent 설정

4.1 초기 설정 위저드

# 전체 설정 위저드 실행
hermes setup

# 또는 개별 설정:
hermes model   # LLM 제공자/모델 선택
hermes tools   # 활성화할 도구 설정
hermes config check  # 설정 검증

4.2 API 키 설정 (선택사항)

# ~/.hermes/.env 파일 편집
nano ~/.hermes/.env

# 내용 추가:
# ===== 필수 (로컬 Ollama 사용 시 생략 가능) =====
# 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-your-key-here

4.3 채팅 시작

# 클래식 CLI
hermes

# 현대적 TUI (추천)
hermes --tui

# 세션 재개
hermes --continue
# 또는
hermes -c

4.4 주요 슬래시 명령어

명령어	설명
/help	모든 명령어 표시
/tools	사용 가능한 도구 목록
/model	모델 변경
/save	대화 저장
/voice on	음성 모드 활성화
/skills	스킬 관리
/stop	실행 중인 에이전트 중지

---

5. Telegram 봇 연동

5.1 Telegram Bot Token 발급

1. Telegram에서 @BotFather 검색
2. /newbot 명령어 입력
3. 봇 이름 설정 (예: MyHermesBot)
4. 봇 username 설정 (예: my_hermes_bot)
5. API Token 복사 (예: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

5.2 Hermes Gateway 설정

# 게이트웨이 설정 위저드
hermes gateway setup

# Telegram 선택 → 토큰 입력
# Allowed Users 설정 (보안을 위해 권장):
# TELEGRAM_ALLOWED_USERS=123456789,987654321
# (자신의 Telegram User ID, @userinfobot에서 확인 가능)

5.3 수동 설정

# ~/.hermes/.env에 추가
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_ALLOWED_USERS=123456789

# 또는 CLI로 설정
hermes config set TELEGRAM_BOT_TOKEN 123456789:ABCdefGHIjklMNOpqrsTUVwxyz
hermes config set TELEGRAM_ALLOWED_USERS 123456789

5.4 게이트웨이 실행

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

# 백그라운드 서비스로 설치 (macOS)
hermes gateway install
hermes gateway start
hermes gateway status

# 백그라운드 서비스로 설치 (Linux systemd)
hermes gateway install
hermes gateway start
journalctl --user -u hermes-gateway -f  # 로그 확인

# 서비스 중지/재시작
hermes gateway stop
hermes gateway restart

5.5 Telegram에서 채팅 명령어

명령어	설명
/new	새 대화 시작
/model	모델 변경
/reset	대화 초기화
/stop	실행 중지
/approve	위험한 명령 승인
/deny	명령 거부
/status	세션 정보
/help	도움말

5.6 DM 페어링 (대체 인증 방식)

# 허용목록 대신 1회성 페어링 코드 사용
# 봇이 미지 사용자에게 코드 발급 (예: XKGH5N7P)
# 관리자가 승인:
hermes pairing approve telegram XKGH5N7P

# 기타 명령어:
hermes pairing list          # 대기/승인된 사용자 목록
hermes pairing revoke telegram 123456789  # 접근 권한 제거

---

6. Firecrawl 셀프호스팅

Hermes Agent의 웹 검색/스크래핑 기능을 위해 Firecrawl을 셀프호스팅하면 API 비용 없이 무제한 사용 가능.

6.1 Docker Compose로 설치

# 작업 디렉토리 생성
mkdir -p ~/firecrawl-selfhost
cd ~/firecrawl-selfhost

# docker-compose.yml 생성
cat > docker-compose.yml << 'EOF'
version: '3.8'

services:
  firecrawl-api:
    image: ghcr.io/mendableai/firecrawl:latest
    ports:
      - "3002:3002"
    environment:
      - PORT=3002
      - HOST=0.0.0.0
      - REDIS_URL=redis://redis:6379
      - REDIS_RATE_LIMIT_URL=redis://redis:6379
      - PLAYWRIGHT_MICROSERVICE_URL=http://playwright-service:3000/scrape
      - USE_DB_AUTHENTICATION=false
      - BULL_AUTH_KEY=CHANGEME_ME
    depends_on:
      - redis
      - playwright-service

  playwright-service:
    image: ghcr.io/mendableai/firecrawl-playwright:latest
    ports:
      - "3000:3000"
    environment:
      - PORT=3000

  redis:
    image: redis:alpine
    ports:
      - "6379:6379"
    command: redis-server
EOF

# .env 파일 생성 (선택사항)
cat > .env << 'EOF'
# ===== Required =====
PORT=3002
HOST=0.0.0.0
USE_DB_AUTHENTICATION=false

# ===== Optional: AI 기능 (Ollama 연동) =====
# OLLAMA_BASE_URL=http://host.docker.internal:11434/api
# MODEL_NAME=gemma4:26b

# ===== Optional: Proxy =====
# PROXY_SERVER=http://your-proxy:port
# PROXY_USERNAME=
# PROXY_PASSWORD=

# ===== Admin UI =====
BULL_AUTH_KEY=CHANGEME_ME

# ===== Redis =====
REDIS_URL=redis://redis:6379
REDIS_RATE_LIMIT_URL=redis://redis:6379
EOF

6.2 Firecrawl 실행

# 컨테이너 빌드 및 시작
docker compose build
docker compose up -d

# 상태 확인
docker compose ps

# 로그 확인
docker compose logs -f firecrawl-api

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

# Bull Queue Admin UI 접속
# http://localhost:3002/admin/CHANGEME_ME/queues

6.3 Hermes에 Firecrawl 연결

# ~/.hermes/.env에 추가
FIRECRAWL_BASE_URL=http://localhost:3002
# API 키는 셀프호스팅 시 불필요
# FIRECRAWL_API_KEY=

# 또는 CLI로 설정
hermes config set FIRECRAWL_BASE_URL http://localhost:3002

6.4 macOS Docker 네트워크 문제 해결

macOS에서 host.docker.internal를 사용하려면:

11434/api

# docker-compose.yml의 OLLAMA_BASE_URL 수정:
# 또는 명시적 네트워크 설정:
docker run --add-host=host.docker.internal:host-gateway ...

---

7. 문제 해결 / 팁

7.1 Hermes Agent

문제	해결 방법
hermes: command not found	source ~/.zshrc 또는 PATH 확인 (echo $PATH)
API 키가 설정되지 않음	hermes model 실행 또는 hermes config set OPENROUTER_API_KEY your_key
모델이 감지되지 않음	Ollama 서버 확인 (ollama list), 컨텍스트 크기 설정 (--ctx-size 65536)
게이트웨이가 시작되지 않음	hermes gateway status, journalctl --user -u hermes-gateway -f
Telegram 봇이 응답하지 않음	토큰 확인, TELEGRAM_ALLOWED_USERS에 자신의 ID 추가

7.2 Ollama

문제	해결 방법
모델 다운로드 실패	네트워크 확인, ollama serve 재시작
VRAM 부족	더 작은 모델 사용 (e.g., gemma4:e4b, qwen3.5:9b)
느린 추론	GPU 오프로딩 확인, 양자화 모델 사용 (Q4_K_M)
컨텍스트 오류	--ctx-size 65536 명시적 설정

7.3 Firecrawl

문제	해결 방법
컨테이너가 시작되지 않음	docker compose logs 확인, .env 변수 검증
Redis 연결 오류	REDIS_URL이 redis://redis:6379로 설정되었는지 확인
API 응답 없음	포트 3002 사용 중인지 확인 (lsof -i :3002)
Supabase 오류 로그	self-hosting에서는 정상 (기능 제한 없음)

7.4 성능 최적화 팁

1. 모델 선택 가이드:

• 일반 작업: Gemma 4 26B MoE (빠름, 신뢰성 높은 함수 호출)
• 코딩 작업: Qwen 3.5 27B (SWE-bench 72.4점)
• 저사양: Gemma 4 E4B 또는 Qwen 3.5 9B

2. 멀티모델 라우팅:

# 프로필 생성
hermes profile create general --model gemma4:26b
hermes profile create coder --model qwen3.5:27b

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

3. 메모리 관리:

• Hermes는 4계층 메모리 시스템 사용 (Working/Session/Long-term/Skill)
• 정기적으로 /compress로 컨텍스트 정리
• ~/.hermes/memories/에서 장기 메모리 확인

4. 스킬 설치:

# 스킬 검색
hermes skills search kubernetes
hermes skills search react --source skills-sh

# 스킬 설치
hermes skills install openai/skills/k8s
hermes skills install official/security/1password

5. 자동화 (Cron):

# Telegram에서:
# "매일 오전 9시에 Hacker News AI 뉴스를 요약해서 보내줘"

# Hermes가 자동으로 cron 작업 생성
# 게이트웨이가 60초마다 체크하여 실행

7.5 보안 권장사항

1. 게이트웨이 허용목록 설정:

   TELEGRAM_ALLOWED_USERS=123456789
   DISCORD_ALLOWED_USERS=123456789012345678

2. BULL_AUTH_KEY 변경:

   BULL_AUTH_KEY=$(openssl rand -hex 16)

3. Docker 샌드박스 사용:

   hermes config set terminal.backend docker

4. SSH 격리 (원격 서버):

   hermes config set terminal.backend ssh

---

8. 다음 단계

추가 리소스

• 공식 문서: https://hermes-agent.nousresearch.com/docs/
• GitHub: https://github.com/NousResearch/hermes-agent
• Discord: https://discord.gg/hermes-agent
• Firecrawl 문서: https://docs.firecrawl.dev/

추천 설정

# 1. 음성 모드 활성화 (CLI 마이크 입력)
pip install "hermes-agent[voice]"
hermes
/voice on

# 2. MCP 서버 연결 (VS Code 등)
pip install -e '.[acp]'
hermes acp

# 3. 백업 설정
cp ~/.hermes/config.yaml ~/.hermes/config.yaml.backup
cp -r ~/.hermes/skills ~/.hermes/skills.backup

# 4. 로그 확인
tail -f ~/.hermes/logs/gateway.log

---

9. 빠른 참조

# Hermes 시작
hermes              # CLI
hermes --tui        # TUI (추천)
hermes gateway      # 게이트웨이 (포그라운드)

# 게이트웨이 관리 (macOS)
hermes gateway install
hermes gateway start
hermes gateway status
hermes gateway stop

# 모델 변경
hermes model
/model              # 세션 내에서

# 설정 확인
hermes doctor
hermes status
hermes config check

# Firecrawl 상태
docker compose ps
curl http://localhost:3002/health

# Ollama 상태
ollama list
ollama ps

---

---

⚠️ 주의: 이 메뉴얼은 참고용이며, 실제 설치는 아직 진행하지 않았습니다. 설치 전 메뉴얼을 확인하고 직접 진행하세요.

설치 상태: ❌ 미설치