대상: GitHub에서 Hermes Agent가 약 17.5만 Stars에 근접했지만 「명령을 찾을 수 없음 / Telegram 무응답 / 업그레이드 후 설정 유실」에 막힌 개발자입니다. macOS·Linux·WSL2에서 v0.15.x를 당일 가동하고 Telegram 24/7을 붙이는 것이 목표입니다.제공 내용: 복사 가능한 원클릭 설치, hermes doctor 검수, 모델·Gateway 설정, 오류 대조표, 상시 호스트 비교입니다.구성: 설치 함정 → 환경 표 → 8단계 Runbook → 지표 → 플랫폼 매트릭스 → 마무리·FAQ. 아키텍처는 3층 메모리 글, 30일 실측은 체험기를 참고하십시오.
2026년 5월 말 Nous Research는 v0.15.2를 배포했으며 pip install hermes-agent와 curl | bash를 모두 지원합니다. Stars는 빠르게 변하지만, 실제 첫 시간에 겪는 마찰은 포럼 글에서 자주 생략됩니다. 재설치 전에 아래 체크리스트를 확인하십시오.
~/.zshrc에 hermes를 추가했어도 source 없이는 command not found가 납니다. 설치 실패로 오인하는 가장 흔한 케이스입니다.python3 -m hermes는 dotenv 등이 빠질 수 있습니다. 지원 진입점은 ~/.hermes/hermes-agent/venv/bin/hermes입니다.hermes setup·hermes model 없이는 API key not set로 즉시 종료됩니다.hermes gateway 장기 프로세스가 필요합니다. 일회성 hermes 대화만으로는 휴대폰에 메시지가 오지 않습니다.hermes config check && hermes config migrate가 선행되어야 Missing config after update를 피할 수 있습니다.OpenClaw와 한 줄 비교하면, OpenClaw는 멀티 채널 Gateway와 npm/Docker Compose 운영에 강하고, Hermes는 MEMORY.md·USER.md, 태스크 후 Skill 축적, MCP에 최적화되어 있습니다. 본문은 설치 레인에 머물며, 개념·하드웨어는 위 두 Hermes 시리즈 글을 링크합니다.
팀 평가 시 세 질문을 분리하십시오. OS 기선 설치 가능 여부, 보안팀이 승인한 LLM 연결 여부, 주말·야간 Gateway 생존 여부입니다. 본 Runbook은 전자를 한 오후에 검증합니다. 셋째가 MACCOME이 호스팅 비교표를 함께 게시하는 이유입니다.
공식 설치 스크립트는 Python 3.11(uv), Node.js 22, ripgrep, ffmpeg를 번들합니다. 사용자 책임은 git, GitHub raw·LLM 벤더 HTTPS, Skills·세션 SQLite용 디스크입니다. 브라우저 자동화가 없는 헤드리스 Linux는 --skip-browser로 Camoufox 부담을 줄이십시오.
원격 Mac 노드는 로컬과 동일합니다. SSH 접속 후 같은 명령을 붙여넣고, 검증 후 launchd 또는 systemd로 Gateway를 상시화합니다. 클라우드 라우팅 모델에는 API 리전 RTT가 CPU보다 중요합니다. 브라우저 Skill과 다중 Gateway가 한 대에 있으면 통합 메모리가 유리합니다.
WSL2는 Hermes 트리를 WSL ext4에 두고 /mnt/c에 두지 마십시오. DrvFS에서는 file watcher와 SQLite WAL이 불안정합니다. Gateway 야간 검증 시 Windows 절전을 끄십시오. 한계를 넘으면 ~/.hermes tarball로 Linux VPS 또는 대여 Mac에 이전할 수 있습니다.
| 항목 | 최소 | 권장(프로덕션 Gateway) |
|---|---|---|
| OS | macOS 12+, Ubuntu 20.04+, WSL2 | macOS 14+(Apple Silicon) / Ubuntu 24.04 LTS |
| RAM | 4 GB(클라우드 API + Gateway만) | 16 GB(브라우저 자동화 + 다중 Skill 캐시) |
| 디스크 | 약 1.5 GB(기본 Skills 포함) | 20 GB SSD(로그 + SQLite WAL) |
| 네트워크 | GitHub raw 접근 | 안정·저지연 LLM API egress |
| Windows | PowerShell 네이티브(얼리 베타) | WSL2 + Linux 원클릭 스크립트(가장 안정) |
헤드리스 서버: 브라우저 자동화가 필요 없으면 설치 시 --skip-browser를 추가해 디스크·RAM을 절약하십시오.
macOS·Linux·WSL2에서 동일합니다. 각 게이트를 검증한 뒤 다음 단계로 진행하십시오. hermes doctor를 건너뛰면 대개 더 오래 걸립니다.
~/.hermes 설치 메시지가 출력됩니다.source ~/.zshrc 또는 새 탭을 엽니다.hermes doctor가 Python·Node·PATH·API 키 등을 점검합니다. hermes --version은 v0.15.x여야 합니다.hermes setup, 기존 키는 hermes model 또는 ~/.hermes/.env에 기록합니다.hermes로 현재 디렉터리 목록 등 가벼운 도구 호출을 확인합니다.@BotFather에서 /newbot, Token 보관, @userinfobot으로 숫자 ID 확인합니다.hermes gateway setup에서 Telegram 선택, 또는 TELEGRAM_BOT_TOKEN·TELEGRAM_ALLOWED_USERS를 수동 설정합니다.hermes gateway, 프로덕션은 hermes gateway install && hermes gateway start입니다.8단계에서 「설치됨」이 「운영 중」이 됩니다. 포그라운드 Gateway는 SSH 종료 시 끊기므로 tmux가 필요할 수 있습니다. macOS 사용자 서비스는 올바르게 설치하면 로그아웃 후에도 유지됩니다. 그룹 테스트 전 DM으로 토큰·allow-list를 먼저 검증하십시오.
일상 도구 호출·다중 모델 실험에는 OpenRouter가 가장 빠릅니다. Claude 표준화 팀은 Anthropic API/OAuth를 hermes model에 연결합니다. Nous Portal은 hermes setup --portal로 시험할 수 있습니다. 프라이버시 워크플로는 Ollama Base URL을 동일 마법사에 넣습니다. v0.15의 Grok·x_search는 hermes tools에서 필요한 것만 켜 context를 줄이십시오.
Telegram: Token을 git에 올리지 마십시오. TELEGRAM_ALLOWED_USERS는 @핸들이 아니라 숫자 ID만 허용합니다. dev/stage/prod는 봇·Token을 분리해 staging 프롬프트가 production ~/.hermes를 오염시키지 않게 하십시오.
# 공식 원클릭 설치 (macOS / Linux / WSL2) curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash # 헤드리스 서버 (선택) # curl -fsSL .../install.sh | bash -s -- --skip-browser source ~/.zshrc hermes doctor hermes setup # Telegram Gateway (대화형 마법사) hermes gateway setup hermes gateway install hermes gateway start hermes gateway status
# Linux 시스템 Gateway (부팅 자동 시작, root 필요) sudo hermes gateway install --system sudo hermes gateway start --system journalctl -u hermes-gateway -f
Stars는 관심도이지 개인 Gateway 준비도가 아닙니다. 경영 보고에는 38% 절감과 Gateway 가동률·Telegram 응답 지연을 함께 제시하십시오. 내부 링크: 30일 보고, 아키텍처 글.
첫 주 지원 시 아래 표를 우선 확인하십시오. 해당 없으면 hermes doctor 출력과 Gateway 로그를 캡처한 뒤 Issue를 여십시오.
| 증상 | 원인 | 조치 |
|---|---|---|
hermes: command not found |
PATH 미로드 | source ~/.zshrc 또는 새 터미널; which hermes 확인 |
API key not set |
LLM 미설정 | hermes model 또는 ~/.hermes/.env |
Missing config after update |
마이그레이션 미완 | hermes config check && hermes config migrate |
No module named 'dotenv' |
잘못된 Python | ~/.hermes venv의 hermes 사용 |
| Telegram 그룹 무응답 | Group Privacy / 멤버십 | BotFather에서 프라이버시 해제 후 봇 재초대 |
| Gateway 즉시 종료 | Token·ID 오류 | TELEGRAM_ALLOWED_USERS는 숫자만 |
| LLM 연결 거부 | Proxy·지역 차단 | curl로 API 테스트; 회사 Proxy 우회 진단 |
| Skills 권한 거부 | sudo 설치 후 소유자 | chown -R $USER ~/.hermes |
| 브라우저 도구 멈춤 | 헤드리스 Camoufox 없음 | --skip-browser 없이 재설치 또는 도구 비활성 |
| venv 중복 | pip+curl 혼용 | 한 경로만 선택, 다른 트리 삭제 |
| WSL2 야간 Gateway 중단 | Windows 절전 | 절전 해제; 전용 Linux/Mac 노드 권장 |
| SQLite WAL 디스크 급증 | 장기 세션 | ~/.hermes 백업 후 오래된 session 정리 |
설치 통과는 바이너리 실행을 증명합니다. Telegram 프로덕션과 Skill 복리는 호스트 가용성을 증명합니다. 개인 MacBook은 1~5단계에 적합하고, 8단계가 출장·슬립·OS 업데이트를 견디려면 부적합합니다. VPS는 가동률을 주지만 macOS 네이티브 설치·Camoufox Skill 경로가 없을 수 있습니다. 라즈베리 파이는 Gateway는 되나 장시간 에이전트 작업에서 I/O·열 한계가 납니다. MACCOME Mac mini M4 대여는 실제 macOS·데이터센터 전력·본문과 동일한 launchd 패턴의 교집합입니다.
대여 vs 구매 TCO에는 전기·냉각·고정 IP·물리 보안·macOS 업데이트 on-call 시간을 MSRP와 함께 넣으십시오. 파일럿 후에도 구매할 수 있으나, 많은 팀은 프로덕션 Gateway를 대여에 두고 노트북은 SSH 클라이언트만 씁니다.
| 플랫폼 | 24/7 가용성 | Skill 복리 | 적합 |
|---|---|---|---|
| 개인 MacBook | 덮개 닫으면 중단(약 60%) | 루프 자주 끊김 | POC·당일 디버깅 |
| x86 VPS 4GB | 공급자 정상 시 ~99.5% | 안정하나 macOS 경로 없음 | Linux 전용·Camoufox 불필요 |
| 라즈베리 파이 4B 8GB | 취미 환경 ~88% | I/O 병목·장시간 타임아웃 | 실험용, 프로덕션 비권장 |
| Mac mini M4 대여 | 데이터센터 30일 온라인 목표 | launchd + 통합 메모리 | Telegram 프로덕션 + macOS Skill |
본문 8단계를 따르면 API 키가 이미 승인된 조직에서는 30~60분 안에 Hermes CLI와 Telegram Gateway 첫 응답에 도달하는 경우가 많습니다. 이후 실패는 재설치보다 운영 이슈—노트북 슬립, Token 교체 후 Gateway 미재시작, 브라우저 Skill 로드 시 RAM 부족—인 경우가 많습니다.
대안별 약점도 분명합니다. (a) 노트북은 24/7을 보장하지 못합니다. (b) 소형 x86 VPS는 macOS curl | bash·Camoufox 워크플로가 없습니다. (c) Mac mini 구매는 Capex·가정용 회선·물리 보안을 팀에 이전합니다.
Hermes가 반복 업무를 줄였고 예측 가능한 월 비용·수분 내 SSH 인계·호스트 이전 전 ~/.hermes/ tarball이 필요하다면 MACCOME 전용 Mac mini M4가 일반적인 프로덕션 형태입니다. 아키텍처 글, 30일 실측을 읽은 뒤 Mac mini 대여 요금에서 리전을 선택하십시오.
FAQ
Hermes Agent와 OpenClaw를 같은 Mac에 둘 수 있나요?
가능합니다. ~/.hermes와 ~/.openclaw를 분리하고 RAM·디스크를 모니터링하십시오. 24/7 Hermes Gateway는 매일 덮는 노트북보다 MACCOME 대여 노드를 권장합니다.
v0.15를 pip로 설치할 수 있나요?
예: pip install hermes-agent && hermes. 첫 기동에 hermes doctor를 실행하십시오. pip와 git 설치 스크립트 중 하나만 선택해 venv 이중화를 피하십시오.
Gateway 로그는 어디서 보나요?
포그라운드는 터미널, systemd는 journalctl -u hermes-gateway -f, macOS는 hermes gateway status입니다. 상세 운영은 고객 센터를 참고하십시오.
호스트 변경 전 Hermes 데이터를 어떻게 이전하나요?
~/.hermes/ 전체(Skills, memories, session SQLite)를 아카이브해 새 머신에 복원한 뒤 Gateway를 시작하십시오. MACCOME은 반납 전 자체 삭제를 지원하며, 이전 절차는 고객 센터에 있습니다.