2026년 Hermes Agent Mac
최신 설치 체크리스트: 주말 작업 전에 준비할 것
2026년 M 시리즈 Mac에 Hermes Agent를 처음 설치할 때, 가장 아픈 순간은 설치 명령 자체가 아니라 런타임 불일치, API 키 누락, 권한 팝업 방치, 터미널을 닫으면 Gateway가 멈추는 경우입니다. 「설치 성공」과 「장기 안정 운용」은 별개입니다. 이 체크리스트는 첫 curl 이전부터 launchd 상시 실행·24시간 관찰까지 공식 문서에 맞춰 정리해, 주말 설치를 검증 가능하고 복구 가능하며 지속 가능한 흐름으로 만듭니다. (2026-05-23 확인)
가볍게 체험만 하려면 공식 Quickstart만 따라도 됩니다. Mac에서 Hermes를 오래 쓰려면, 설치 스크립트를 실행하기 전에 아래 항목부터 확인하세요.
1설치 전: 하드웨어·시스템·백업
| 확인 항목 | 권장 기준 | 검증 방법 |
|---|---|---|
| 칩 / OS | Apple Silicon 또는 Intel Mac, Xcode Command Line Tools 포함 macOS | uname -m, sw_vers |
| 메모리 / 디스크 | RAM 16GB 이상 권장, Skills 캐시 포함 5GB 이상 여유 | 활성 상태 보기 / df -h ~ |
| 네트워크 | GitHub raw 및 선택한 LLM API 엔드포인트 접근 가능 | curl -I https://github.com |
| 계정 | 로컬 관리자(PATH, 전체 디스크 접근 등 설정용) | 시스템 설정 → 사용자 및 그룹 |
| 백업 | Time Machine 또는 ~/.hermes 스냅샷 |
복원 연습 1회 |
2의존성 준비: 사전 필수는 Git뿐
Installation 문서에 따르면, 한 줄 설치 스크립트가 uv, Python 3.11, Node.js v22, ripgrep, ffmpeg를 자동으로 구성합니다. Homebrew Python/Node를 미리 깔 필요는 없습니다. Git만 확인하세요:
- →Git:
git --version으로 버전 출력 확인. 설치 중이 아니라 시작 전에 Xcode CLT를 준비하세요. - →셸: 기본 zsh 사용. 설치 후
source ~/.zshrc로 PATH를 갱신하세요. - →Nix(선택): Nix 사용자는 Nix 설정 가이드를 따르고, curl 설치와 중복하지 마세요.
3계정·시크릿 준비
설치 과정에서 LLM provider를 설정합니다. 키를 미리 준비하면 중간에 멈추지 않습니다:
- →OpenRouter, Anthropic, OpenAI 등 지원 provider의 API 키 최소 1개.
- →시크릿은
~/.hermes/.env에 저장하고chmod 600 ~/.hermes/.env실행. - →프로젝트 Git에 키를 커밋하지 말 것.
TELEGRAM_ALLOWED_USERS등 allowlist 사용,GATEWAY_ALLOW_ALL_USERS=true는 피하세요.
approvals.mode: manual)을 유지하세요. 프로덕션에서 YOLO 모드는 켜지 말고, 가능하면 docker 터미널 백엔드로 격리하세요.
4안전한 작업 공간 만들기
공식 per-user 레이아웃: 코드는 ~/.hermes/hermes-agent/, 데이터는 ~/.hermes/(config, logs, pairing, sandboxes).
- →에이전트 작업 공간은 전용 하위 디렉터리로—홈 전체를 넘기지 마세요.
- →로그:
~/.hermes/logs/(Gateway는gateway.log기록). - →커스텀 경로: 설치 스크립트 실행 전
HERMES_INSTALL_DIR=...설정(공식 문서 참고).
5설치 및 첫 실행 검증
설치(최소 가동):
이후 source ~/.zshrc → hermes 또는 hermes setup → hermes model.
첫 실행 검증:
- ✓
which hermes→~/.local/bin/hermes - ✓
hermes doctor에 블로킹 항목 없음(API 키 누락 시hermes model안내) - ✓실제 프롬프트를 보내 모델 응답·도구 호출 확인
- ✓파일·터미널 도구 사용 시 시스템 설정에서 전체 디스크 접근 등 필요 권한 부여
6상시 실행: launchd로 유지
터미널에서 hermes만 실행하면 현재 세션에만 존재합니다. 메시징 Gateway는 데몬화가 필요합니다:
- 1CLI가 안정되면
hermes gateway setup(Telegram, Discord, Slack 등은 공식 Messaging 문서 지원 목록 확인) - 2
hermes gateway install→ plist:~/Library/LaunchAgents/ai.hermes.gateway.plist - 3
hermes gateway start→hermes gateway status - 4로그:
tail -f ~/.hermes/logs/gateway.log - 5이후 Homebrew/nvm 도구를 추가했다면
hermes gateway install을 다시 실행해 plist PATH 갱신
7복구: 설치 실패 시 확인 순서
| 증상 | 먼저 확인 |
|---|---|
hermes: command not found |
셸 PATH → source ~/.zshrc |
| API 호출 실패 | hermes model / hermes config check |
| Gateway 기동 안 됨 | hermes gateway status, 로그, 플랫폼 토큰·allowlist |
| 재부팅 후 서비스 사라짐 | 포그라운드 hermes gateway만 실행하고 gateway install을 안 했는지 |
| WhatsApp에서 node/ffmpeg 없음 | hermes gateway install 재실행으로 plist PATH 갱신 |
| 업데이트 후 설정 깨짐 | hermes config migrate, hermes update |
824시간 관찰 체크리스트
- ①Mac 재부팅 →
hermes gateway status가 running인지 - ②네트워크 5분 차단 후 복구 시 Gateway가 자동 복구되는지, 수동 start가 필요한지
- ③
~/.hermes/logs/에 오류 스택이 없는지 spot-check - ④LLM 과금 확인—도구 루프로 비용 급증 방지
- ⑤위험 명령 1회 의도적으로 실행해 승인 흐름이 살아 있는지
924/7 Agent에는 Mac mini가 더 잘 맞습니다
Hermes Gateway, BlueBubbles 브리지, 로컬 툴체인은 모두 안정적인 macOS 호스트를 전제로 합니다. Mac mini M4는 Apple Silicon 통합 메모리와 약 4W급 대기 전력으로, 가정·소규모 팀의 조용한 Agent 노드에 적합합니다. WSL 없이 Unix, Homebrew, Docker, launchd가 네이티브로 갖춰지고, Gatekeeper·FileVault가 장기 노출면을 줄입니다. 같은 가격대 Windows 호스트보다 크래시율이 낮아 무인 Gateway 운용에 유리합니다.
주말에 설치해 다음 주부터 상시 온라인 Agent 호스트로 쓰려면, Mac mini M4는 가성비 좋은 출발점입니다. 지금 호스트를 마련해 Hermes를 장기 운용에 맞는 하드웨어에서 돌려 보세요.
- ①설치 전: 하드웨어·네트워크·백업
- ②설치: 한 줄 스크립트 +
hermes doctor - ③첫 실행: 모델·대화·권한
- ④상시 실행:
gateway install+ launchd - ⑤복구: PATH → API → gateway → 로그