curl 원클릭 · hermes doctor · 모델·Gateway · 플랫폼 비교 · 6단계 Runbook
2026년 Nous Research Hermes Agent(GitHub 약 17.4만 Star)를 돌리려다 PATH, API Key, Telegram 무응답에 막히셨나요? 본 글은 완벽 설치 경로를 제공합니다: 공식 curl | bash로 Python 3.11 / Node 22 자동 설치, hermes doctor 12항목 점검, hermes setup으로 모델과 Gateway 설정, Telegram 7×24까지 연결합니다. 환경 요구, 호스트 비교, 6단계 Runbook, 흔한 오류 표를 포함하며, 프로덕션 상시 구동에는 Mac Mini M4 월 대여를 권장하는 이유도 설명합니다.
Hermes Agent(Nous Research, MIT)는 2026년 GitHub에서 가장 주목받는 오픈소스 자기 진화 AI 에이전트 중 하나입니다. 한 유형의 작업을 완료하면 재사용 가능한 Skill을 자동 생성하며, 커뮤니티 기준 동종 작업 token이 약 38% 감소합니다. Gateway로 Telegram / Discord / Slack 등 20+ 플랫폼에 연결하고 MCP와 Claude / OpenRouter / Ollama 등 다중 백엔드를 지원합니다. OpenClaw, LangGraph와의 차이는 세션 간 지속 메모리(SESSION → MEMORY.md → USER.md)와 네이티브 Skill 자동 생성이며, 공식 스크립트는 $5급 VPS나 Mac에서도 동작합니다——다만 프로덕션 7×24와 macOS 브라우저 Skill은 호스트 선택이 중요합니다.
본 글은 개념이 아니라 설치 단계 5대 문제를 해결합니다: hermes: command not found, API Key 미설정, 업그레이드 후 설정 드리프트, Telegram 그룹 무응답, 「로컬 PC 덮으면 Gateway 끊김」 상시 구동 문제. 설치 후 메모리 아키텍처를 보려면 3계층 메모리와 7×24 실측을 참고하세요.
| 환경 항목 | 최소 요구 | 권장(프로덕션 Gateway) |
|---|---|---|
| OS | macOS 12+ / Ubuntu 20.04+ / WSL2 | macOS 14+(Apple Silicon) 또는 Ubuntu 24.04 LTS |
| Python / Node | 스크립트가 3.11 / 22 자동 설치 | 수동 설치 불필요, hermes doctor 기준 |
| 메모리 | 4 GB(Gateway + 클라우드 API만) | 16 GB+; 로컬 모델은 32 GB UMA 권장 |
| 디스크 | 약 1.5 GB(Skills 캐시 포함) | 20 GB SSD+, FTS5·로그 증가 여유 |
| 네트워크 | GitHub raw + LLM API 접근 | 안정적 저지연, IM webhook 유리 |
Python/Node를 먼저 설치해야 한다고 생각:공식 install.sh가 uv로 Python 3.11, Node 22, ripgrep, ffmpeg 설치. sudo 불필요.
설치 후 Shell source 안 함:PATH 미갱신으로 command not found. source ~/.zshrc 또는 새 터미널.
hermes doctor 건너뜀:12항목 점검으로 API Key, ffmpeg, PATH 사전 발견. 맹 실행보다 1시간 절약.
헤드리스에서 브라우저 의존 활성:VPS는 --skip-browser 추가, Camoufox 의존 실패 방지.
로컬 POC를 프로덕션으로:MacBook 슬립 시 Gateway 중단, Skill 복리 불가. 7×24는 전용 호스트 필요.
같은 curl | bash도 호스트에 따라 uptime, IO, macOS 네이티브 경로가 달라집니다. 설치 성공 ≠ Gateway와 Skill 복리 7×24 운영——아래 표는 「Hermes 설치 후」 프로덕션 체감을 정리한 것입니다(커뮤니티·IDC 실측 구간).
| 플랫폼 | 7×24 가용성 | Skill 복리 | 월 비용 체감 | 적합 시나리오 |
|---|---|---|---|---|
| 개인 MacBook | ≈ 60%(덮으면 중단) | 잦은 중단 | ₩0 하드웨어 + 높은 불안 | POC / 로컬 CLI만 |
| 라즈베리 파이 4B 8GB | ≈ 88% | I/O 병목, 장작업 타임아웃 | 하드웨어 일회성 | 취미용, 프로덕션 Gateway 비권장 |
| x86 VPS 4GB | ≈ 99.5% | 안정, macOS Skill 없음 | 종량 과금 | 순 API + Telegram, 브라우저 자동화 불필요 |
| Mac Mini M4 월 대여 | IDC SLA, 30일급 100% | UMA + launchd 상시, Skill 누적 | 고정 월 대여 | Telegram 7×24 + Camoufox / 로컬 Ollama |
설치는 10분;7×24 호스트 선택이 Skill 복리인지 매번 처음부터인지를 결정합니다.
M4 통합 메모리는 Gateway(커뮤니티 기준 상시 약 4.2 GB), 브라우저 자동화, SQLite WAL이 주소 공간을 공유합니다. launchd는 macOS에서 공식 테스트 경로에 가깝습니다. 단기 검증은 1개월 대여로 Telegram·Skill 곡선 확인 후 구매 결정——30일 체험기 참고.
다음은 macOS / Linux / WSL2 공통입니다. 헤드리스 VPS는 1단계에 --skip-browser 추가. 데이터·설정 기본 경로 ~/.hermes/, 업그레이드 전 백업하세요.
원클릭 설치:공식 스크립트 실행 후 ✅ Hermes Agent installed at ~/.hermes 대기, source ~/.zshrc(Linux는 ~/.bashrc).
헬스 체크:hermes doctor로 Python, Node, ripgrep, ffmpeg, PATH 확인. hermes --version v0.14+.
모델 설정:hermes setup 또는 hermes model; OpenRouter / Anthropic / Nous Portal 등을 ~/.hermes/.env에.
CLI 스모크:hermes 대화형 실행, 도구 호출 작업(예: 「현재 디렉터리 파일 수 세기」)으로 API 확인.
Telegram:BotFather로 Bot 생성 → hermes gateway setup에서 Telegram 선택, Token과 TELEGRAM_ALLOWED_USERS 입력. 그룹은 프라이버시 끄고 Bot 재초대.
7×24 상시:hermes gateway install && hermes gateway start; Linux는 sudo hermes gateway install --system, macOS는 launchd 사용자 서비스.
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash source ~/.zshrc hermes doctor hermes setup hermes gateway setup hermes gateway install hermes gateway start hermes gateway status
API Key 수동 입력: hermes config set OPENROUTER_API_KEY sk-or-xxxx 또는 ~/.hermes/.env에 추가. 업그레이드 후 설정 누락 시 hermes config check && hermes config migrate 실행.
다음 증상은 「스크립트 성공 후 서비스 불가」 단계에서 흔합니다——표 순서대로 제거하고, 모델 변경·디렉터리 이전·Gateway 재설치를 동시에 하지 마세요.
| 오류 / 현상 | 흔한 원인 | 조치 |
|---|---|---|
| hermes: command not found | PATH 미갱신 | source ~/.zshrc 또는 새 터미널 |
| API key not set | LLM 미설정 | hermes model 또는 ~/.hermes/.env |
| Missing config after update | 버전 업그레이드 설정 드리프트 | hermes config check && hermes config migrate |
| ModuleNotFoundError: dotenv | 시스템 Python 오사용 | ~/.hermes/hermes-agent/venv/bin/hermes 사용 |
| Telegram 그룹 무응답 | Bot 프라이버시 모드 | BotFather에서 Group Privacy 끄고 재초대 |
Hermes는 임의 MCP Server(GitHub, DB, 브라우저 등)를 ~/.hermes/config.yaml의 mcp_servers에 선언합니다. 헤드리스 OAuth는 hermes mcp login + SSH 터널. 프로덕션은 단일 채널 안정 후 MCP를 쌓아 로그 이분법으로 원인 분리.
팁: Windows도 PowerShell 설치 스크립트가 있으나 Dashboard /chat 터미널은 WSL2 의존.WSL2 + Linux 경로를 권장하며 본 Runbook과 동일합니다.
~/.hermes/hermes-agent/, 전역 명령은 PATH에 기록.hermes doctor 약 12항목(Python 3.11, Node 22, ripgrep, ffmpeg, API Key 등).노트북·가정 NAS로 설치 검증은 가능하지만, 슬립·VPS IO·macOS 브라우저 Skill 부재로 Telegram 7×24 체감이 약해집니다. 라즈베리 파이는 로컬 8B·장작업에 약합니다. Hermes를 「상주 동료」로 쓰는 팀에는 Mac Mini M4 월 대여가 uptime, UMA, launchd를 예측 가능 OpEx로 묶어 재설치보다 시간을 절약합니다.
본 Runbook 완료 후 프로덕션 7×24 노드가 필요하면 VpsMesh Mac Mini M4 클라우드 대여: SSH 인도, 리소스 패널, 해지 전 ~/.hermes/ 전체 백업. 요금 Mac Mini M4 대여 요금, 배포 문의 고객 센터, 주문 주문 페이지.
주의: 주말에 호스트 교체, Hermes 메이저 업그레이드, Telegram 화이트리스트 변경을 동시에 하지 마세요——원인 분리 불가. 먼저 hermes gateway status 24h 안정 후 모델·MCP 변경.
아닙니다. 공식 install.sh가 uv로 Python 3.11, Node.js 22, ripgrep, ffmpeg를 설치하며 저장소는 ~/.hermes/hermes-agent/입니다. source ~/.zshrc 후 hermes doctor로 12항목 확인.
기본프라이버시 모드에서는 그룹이 / 명령만 응답. BotFather → Bot Settings → Group Privacy Turn off, Bot 내보낸 뒤 재초대. TELEGRAM_ALLOWED_USERS에 숫자 ID 포함, hermes gateway status 실행 중 확인.