2026 Hermes Agent 설치 가이드: macOS / Linux / VPS 원클릭 배포 + Telegram 24/7 Gateway

Hermes Agent는 Nous Research가 유지보수하며 MIT 라이선스로 공개되어 있습니다. 공식 문서는 hermes-agent.nousresearch.com에서 확인할 수 있습니다. 일회성 CLI 도구와 달리 장기 실행 게이트웨이 프로세스로 설계되었습니다. Telegram 메시지, 터미널 TUI, Tool Calling, 하위 Agent 스케줄링, Skill Markdown 자기 증류가 동일 코어를 공유합니다. 2026년 6월 기준 활성 버전은 v0.15.x이며, 설치 스크립트가 런타임 의존성을 자동 처리하므로 pyenv와 nvm을 수동으로 맞출 필요가 없습니다.

설치 성공의 기준은 hermes --version 출력이 아닙니다. 모델 Provider가 동작하고, hermes doctor가 전부 녹색이거나 허용 가능한 경고만 남으며, 최소 하나의 채팅 게이트웨이(본문은 Telegram 기준)가 메시지를 주고받고, SSH 종료 후에도 launchd 또는 systemd가 프로세스를 다시 띄우는지입니다. 기억이 왜 영속 호스트를 요구하는지는 아키텍처 선정 글을 먼저 읽으면 이해가 빠릅니다. 본문은 「바이너리를 띄우고 Telegram에 연결」하는 데 집중합니다.

선택 기능으로 Hermes는 MCP를 통해 외부 도구 서버(파일시스템, 브라우저, 데이터베이스 등)를 마운트할 수 있습니다. 다만 프로덕션 최소 구성은 보통 「게이트웨이 + 모델 API + 로컬 SQLite / Markdown 기억 경로」입니다. Skill 자기 진화는 작업 종료 후 유효한 절차를 Skill 라이브러리에 기록하므로 별도 플러그인이 필요 없습니다. 설치 후 수백 MB 디스크를 예약하는 이유이기도 합니다.

커뮤니티 Issue에서 가장 흔한 실패는 컴파일 오류가 아니라 환경 파편화와 호스트 프로필 불일치입니다. 아래 표는 설치 단계에서 자주 막히는 지점을 모았습니다. 대조하면 트러블슈팅 시간을 절반 가까이 줄일 수 있습니다.

• 런타임 버전 드리프트: 시스템 기본 Python 3.9나 Node 16은 uv 해석 실패로 이어집니다. 공식 스크립트 목표는 Python 3.11+와 Node 22이며, Homebrew와 시스템 Python을 섞을 때 PATH 순서 오류가 특히 흔합니다.
• 게이트웨이와 CLI 혼동: 노트북에서 TUI만 통과한 뒤 뚜껑을 닫으면 Telegram Bot이 즉시 오프라인이 됩니다. 「설치가 깨졌다」고 느끼지만 실제로는 데몬 프로세스 부재인 경우가 많습니다.
• 모델 Key와 네트워크: hermes model이 가리키는 OpenRouter / Nous Portal / OpenAI 호환 엔드포인트가 방화벽에 막히면 401 대신 「Agent 무반응」처럼 보입니다.
• 디스크와 권한: Docker에 영속 볼륨이 없거나 /tmp가 비워지는 VPS에서는 state.db와 Skill 디렉터리가 재시작마다 초기화되어 30일 실측의 「기억이 오히려 줄어드는」 현상과 일치합니다.
• OpenClaw 스택과 병행: 팀이 OpenClaw + Ollama 로컬 Agent를 검토 중이라면 Hermes는 「다중 플랫폼 게이트웨이 + 폐루프 Skill」에 더 가깝습니다. 동일 호스트에 둘 다 올릴 수 있지만 사용자와 포트를 분리해 11434나 게이트웨이 리스닝 포트 충돌을 피해야 합니다.

결론은 단순합니다. 설치 Runbook에는 호스트 선정이 포함되어야 합니다. MacBook은 개발·디버깅에 적합하고, Telegram 24/7 프로덕션 게이트웨이는 항상 온라인이며 디스크가 감사 가능한 노드에 두는 편이 낫습니다. 이것이 아래에서 NUKCLOUD Mac Mini M4 클라우드 임대를 권하는 이유입니다.

아래 단계는 macOS 14+, Ubuntu 22.04+, NUKCLOUD 클라우드 Mac에서 검증되었습니다. Linux VPS 경로도 동일하며, 데몬 유닛만 systemd로 바꿉니다(후술).

1. 01
   호스트와 SSH 준비: 클라우드 Mac을 쓸 경우 주문 페이지에서 16GB+ 인스턴스를 고르고 콘솔에서 SSH를 받습니다. macOS / 배포판 마이너 버전을 고정하고 전용 Unix 사용자(예: hermes)를 만듭니다. root로 게이트웨이를 장기 실행하지 마세요.
2. 02
   공식 원클릭 설치 실행: 로그인 후 아래 curl 스크립트를 실행합니다. Hermes 배포판 다운로드, uv 가상환경, Python 3.11·Node 22 툴체인 설치까지 처리합니다. 완료 후 Shell을 다시 열거나 설치기가 안내한 profile 조각을 source합니다.
3. 03
   CLI 검증: hermes --version으로 v0.15.x를 확인하고 hermes doctor를 실행해 빨간 항목을 수정합니다. 흔한 원인은 API Key 누락, state.db 디렉터리 쓰기 불가, Node 모듈 미링크입니다.
4. 04
   대화형 setup: hermes setup이 기본 모델 Provider, 기억 파일 경로, TUI 환경을 안내합니다. 프로덕션에서는 MEMORY.md와 Skill 디렉터리를 영속 Home 하위에 두고 /tmp는 피하세요.
5. 05
   로컬 스모크: hermes tui로 Tool Calling 대화 한 라운드를 돌려 모델 응답과 디스크 쓰기를 확인합니다. hermes model list / hermes model set으로 OpenRouter 등 200+ 모델 엔드포인트를 전환할 수 있습니다.
6. 06
   버전 고정과 백업: 현재 release tag를 기록하고 ~/.hermes(또는 setup 지정 경로)를 tarball로 첫 백업합니다. 프로덕션 게이트웨이는 staging 없이 main 브랜치를 추적하지 마세요.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
exec $SHELL -l
hermes --version
hermes doctor
hermes setup
hermes tui

설치 직후 첫 과제는 모델 경로를 안정화하는 것입니다. hermes model 하위 명령(또는 setup이 쓴 설정 파일)으로 Provider를 지정합니다. 흔한 선택은 OpenRouter API Key, Nous Portal, 자체 OpenAI 호환 게이트웨이입니다. 모델을 바꿔도 기억 파일은 자동 이전되지 않으므로 Provider를 크게 바꾸기 전 state.db와 Markdown 기억을 백업하세요.

MCP(선택): 설정에 MCP Server 목록을 선언하면 Hermes가 파일 탐색, Git, 데이터베이스 등을 Tool로 Agent 루프에 주입합니다. 최소 프로덕션은 MCP 없이 시작하고 게이트웨이가 안정된 뒤 추가해도 됩니다. MCP 프로세스 하나당 메모리는 대략 100–300 MB 늘어나며 16GB 클라우드 Mac에서는 여전히 관리 가능한 수준입니다.

Skill 자기 진화: 복잡한 작업이 끝나면 Hermes가 재사용 가능한 절차를 Markdown Skill 파일로 증류합니다(한 Skill 약 2,200자 상한, 중복 제거 포함). 별도 「훈련 스크립트」가 필요 없습니다. 게이트웨이가 계속 온라인이고 디스크가 영속이면 Skill 라이브러리는 수 주 안에 한 자릿수에서 수십 개로 성장합니다. 이는 3층 메모리 아키텍처 두 번째 층과 직접 대응합니다.

• 저장소 인기: GitHub Star 약 17.4만(2026년 6월, 페이지 실시간 수 기준), MIT 라이선스, 수백 명 기여자.
• 런타임 스택: 설치기가 Python 3.11, Node 22, uv를 묶어 Python 3.9 함정을 피합니다.
• 모델 폭: OpenRouter 등으로 200+ 모델 전환 가능. 로컬 Metal 추론은 macOS 호스트가 필요하며 Linux VPS 순수 API 경로와 다릅니다.

Telegram은 Hermes 커뮤니티에서 가장 많이 쓰는 프로덕션 채널입니다. 휴대폰에서 메시지를 보내면 게이트웨이 프로세스가 Agent 코어로 전달하고 Bot API로 답이 돌아옵니다. 설정 진입점은 hermes gateway setup(또는 문서의 동등 대화형 흐름)이며, BotFather Token, Webhook / 롱폴링 모드, 리스닝 포트, 로그 경로를 입력합니다.

macOS — launchd: ~/Library/LaunchAgents/에 plist를 만들고 ProgramArguments를 hermes gateway start(또는 문서상 현행 하위 명령)로 지정합니다. KeepAlive를 true로, StandardOutPath / StandardErrorPath를 로테이션 로그로 연결합니다. 로드: launchctl load ~/Library/LaunchAgents/com.hermes.gateway.plist. NUKCLOUD 클라우드 Mac과 자가 Mini 경로가 동일합니다.

Linux — systemd: /etc/systemd/system/hermes-gateway.service에 Unit을 작성합니다. User=hermes, ExecStart=/home/hermes/.local/bin/hermes gateway start, Restart=always. 이후 systemctl enable --now hermes-gateway. VPS에서는 Telegram API로의 아웃바운드 443을 반드시 확인하세요.

1. 01
   @BotFather에서 Bot을 만들고 Token을 복사합니다. Git에 커밋하지 말고 chmod 600 로컬 env 파일에 기록하세요.
2. 02
   hermes gateway setup을 실행해 Telegram을 선택하고 Token을 붙여넣은 뒤 Webhook 또는 polling 설정을 마칩니다.
3. 03
   포그라운드에서 hermes gateway start를 돌리고 휴대폰으로 Bot에 /start를 보내 왕복 지연과 Tool 호출 로그를 확인합니다.
4. 04
   launchd plist 또는 systemd unit을 작성합니다. 관리 TUI는 SSH 터널만 사용하고 관리 포트를 공인망에 노출하지 마세요.
5. 05
   장애를 시뮬레이션해 게이트웨이 프로세스를 kill하고 30초 안에 자동 기동되는지, state.db와 Skill 디렉터리가 그대로인지 확인합니다.
6. 06
   로그 로테이션과 디스크 알림을 설정합니다. Telegram 채널이 72시간 안정된 뒤 팀을 초대하세요.

hermes gateway setup
hermes gateway start
hermes gateway status

동일 설치 명령도 호스트마다 운영 마찰이 크게 다릅니다. 아래 표는 「어디에 먼저 설치할지」 단계에서 선택을 돕습니다.

설치·게이트웨이 단계 흔한 오류는 아래 표로 빠르게 좁힐 수 있습니다.

Hermes + 선택적 로컬 Metal 추론을 한 호스트에 두려면 Linux VPS로는 macOS를 대체할 수 없습니다. Telegram 24/7이 필요한데 가정 브로드밴드를 걸기 싫다면 5달러 VPS의 초과판매와 긴 요약 지연이 사용자 모델이 「똑똑해진 직후」 다운타임 비용을 키웁니다. 감사 가능한 디스크, 고정 SSH 경계, Agent 유휴 시간에 Xcode CI까지 같은 테넌트에 두려는 팀에게는 NUKCLOUD 다리전 클라우드 Mac Mini M4가 「노트북 + 저가 VPS」보다 안정적인 프로덕션 평면인 경우가 많습니다. 가격 페이지에서 시간 단위 파일럿 후 자가 Mini 구매 여부를 결정하세요.