2026 Hermes Agent 완벽 설치·설정 가이드: 초보 실전 튜토리얼로 0부터 끝까지

2. 자주 겪는 문제

1. 제한: 튜토리얼이 「실행됨」에서 멈춤. 터미널 환영 메시지 ≠ 모델 연결·파일 도구·게이트웨이 수신. Hermes가 진짜 쓰이려면 환경·모델·권한·로그·저위험 사례 검수가 함께 되어야 합니다.
2. 숨은 비용: 키·경로 분산. API Key가 메모에만 있고 config.yaml과 .env가 어긋나거나 작업 공간이 전체 홈을 가리키면 SSH 키·프로덕션 저장소를 건드릴 수 있습니다.
3. 안정성·감사: 설치 후 로그 위치를 잊음. 문제 시 무작정 재설치하면 ~/.hermes/logs/errors.log 단서가 사라지고, 백업 없이 업그레이드하면 설정 롤백이 어렵습니다.

3. 설치 전 준비: Mac·환경 체크리스트

목적: 설치 중간에 네트워크·Git·디스크 부족을 발견하지 않기.통과 기준: 아래 항목을 모두 체크한 뒤 설치 스크립트 실행.

• 시스템: macOS 12+(Intel·Apple Silicon 모두; Apple Silicon은 로컬 추론에 유리하나 클라우드 모델은 provider 문서 기준).
• Git: 공식 git 설치기의 유일한 필수 선행은 Git(git --version ≥ 2.30 권장). 없으면 Xcode CLT 또는 brew install git.
• 네트워크: GitHub raw(설치 스크립트)와 선택한 LLM provider API 접근 가능; 회사 프록시는 HTTPS_PROXY 사전 설정.
• 디스크: 공식 설치는 Python 3.11, Node.js v22, ripgrep, ffmpeg·저장소를 받습니다. ≥ 2GB 여유 권장(Skills 캐시 시 1.5–3GB, 당시 문서 기준).
• 권한: 개인 사용자 설치는 sudo 불필요; root 모드로 설치했다면 데이터가 /root/.hermes에 있을 수 있습니다.
• 백업: 기존 ~/.hermes가 있으면 cp -a ~/.hermes ~/.hermes.bak-$(date +%F).
• 테스트 디렉터리: 격리 작업 공간 생성(아래 ~/hermes-lab). 첫 실전을 ~/Documents·프로덕션 git·키 디렉터리에 두지 마세요.

# 설치 전 빠른 자가 점검(전체 복사 실행)
git --version
sw_vers
df -h ~
mkdir -p ~/hermes-lab/{inbox,outbox,archive}
echo "Hermes lab sample: Q2 planning notes." > ~/hermes-lab/inbox/sample.txt

실패 시 먼저: Git errors → CLT/홈brew; low disk → clear Downloads or use another volume; network timeout → switch network or mirror—do not reinstall three times without knowing why.

4. 공식 방식으로 Hermes Agent 설치

목적: Nous Research 유지보수 설치 경로로 Python·Node·CLI를 자동 처리. 출처: 공식 Installation 문서(게시 전 버전·플래그 재확인).

4.1 권장: Git 원라인 설치(main 추적)

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

설치기가 uv, Python 3.11, Node.js v22, ripgrep, ffmpeg, 저장소 클론, venv 생성, hermes PATH 추가를 처리합니다. 일반 per-user 레이아웃:

• 코드: ~/.hermes/hermes-agent/
• 데이터·설정: ~/.hermes/(HERMES_HOME으로 덮어쓰기 가능)
• CLI: ~/.local/bin/hermes

4.2 대안: pip 설치(이미 Python 3.11+ 필요)

pip install hermes-agent
hermes postinstall   # 선택: Node·브라우저·ripgrep·ffmpeg + setup

PyPI는 태그 릴리스를 따릅니다. bleeding edge는 위 git 스크립트를 권장합니다. hermes update 동작은 설치 방식마다 다릅니다—hermes doctor 표시를 기준으로 하세요.

4.3 설치 후 필수 3단계

source ~/.zshrc          # 또는 새 터미널 창
hermes version           # 버전을 메모해 두면 나중에 트러블슈팅에 유리
hermes doctor            # 누락 자동 진단; --fix로 수정 시도

통과 기준: which hermes가 ~/.local/bin/hermes를 가리킴; hermes doctor에 차단 FAIL 없음. 실패 시: 설치 로그 마지막 20줄 → PATH → 시스템 Python으로 저장소 내 hermes를 직접 실행했는지(venv 런처 사용).

주의: 실패 직후 ~/.hermes 삭제·재설치하지 마세요—터미널 출력과 hermes doctor를 먼저 저장해야 네트워크·권한 문제를 구분할 수 있습니다.

5. 모델·API Key 설정

목적: Hermes가 선택한 LLM provider를 호출하게 함.통과 기준: 비대화형 스모크에 합리적 응답; hermes auth list 또는 .env에 항목이 있고 shell history에 평문 Key가 남지 않음.

5.1 대화형 설정(첫 설치 권장)

hermes setup          # 전체 마법사: 모델·도구·게이트웨이 등
# 또는 단계별:
hermes model          # provider·기본 모델 선택
hermes tools          # 필요한 도구 세트 활성화

5.2 환경 변수·설정 파일

주 설정은 보통 ~/.hermes/config.yaml; 비밀은 ~/.hermes/.env(hermes config path, hermes config env-path로 실제 경로 확인). 예시(변수명은 provider 최신 문서 기준—만료된 이름 복사 금지):

# 예: OpenRouter(본인 key로 교체; git 커밋 금지)
hermes config set OPENROUTER_API_KEY "sk-or-v1-xxxxxxxx"

# 또는 .env 직접 편집(chmod 600 ~/.hermes/.env)
echo 'OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx' >> ~/.hermes/.env

경계 안내: 모델 가격·API 한도·지역 가용·개인정보 정책은 provider마다 변합니다—프로덕션 전 최신 약관을 확인하세요. 이 글은 특정 모델명에 고정하지 않습니다.

6. 작업 디렉터리·권한·로그

목적: 설치 후 추적·제한·롤백 가능하게.원칙: 최소 권한—먼저 테스트 디렉터리만 허용, 이후 실제 프로젝트를 점진적으로 개방.

• 작업 공간: config.yaml 또는 세션에 ~/hermes-lab; 해당 디렉터리에 AGENTS.md로 허용 도구·경계 기술(공식 Context Files 문서 참고).
• macOS 권한: 터미널/파일 도구가 전체 디스크 접근을 요청할 수 있음—첫 검수 단계에서는 테스트 디렉터리에 필요한 권한만 부여.
• 로그 디렉터리: 기본 ~/.hermes/logs/(agent.log, errors.log, gateway.log). hermes logs list, hermes logs errors --since 30m로 확인.
• 키 보안: chmod 600 ~/.hermes/.env; 백업 zip을 동기화 폴더에 두지 않음; Agent가 ~/.ssh·결제·프로덕션 kubeconfig를 읽지 않게.
• 백그라운드 실행(선택): Telegram/Discord 게이트웨이는 hermes gateway setup·hermes gateway install; 장기 운영은 Hermes 장기 유지보수 가이드를 참고하세요.

통과 기준: Agent에 「~/hermes-lab만 읽고 쓰기」라고 한 뒤, 홈 테스트 경로 밖 접근은 거부되거나 로그에 감사 기록이 남음.

7. 첫 실행 검수: 7단계 런북

아래 7단계는 「설정 완료」를 「실전 가용」까지 밀어 올립니다—그대로 실행하고 출력·로그 스니펫을 보관하세요.

1. 진단: hermes doctor --fix → 미처리 FAIL 없음.
2. 모델 ping: hermes chat -q "Reply with exactly: HERMES_OK" → 응답에 HERMES_OK 포함.
3. 파일 읽기: Agent가 ~/hermes-lab/inbox/sample.txt를 읽고 첫 문장을 되풀이.
4. 파일 쓰기: ~/hermes-lab/outbox/ping.txt 작성 → cat으로 확인.
5. 로그: hermes logs errors --since 10m → 신규 ERROR 없음(또는 알려진 무시 항목 문서화).
6. 터미널 종료: 창을 닫고 새 터미널에서 2단계 반복 → PATH가 현재 세션에만 유효한지 배제.
7. 선택 재부팅: Mac 재부팅 후 2단계 재실행(게이트웨이 설치 시 hermes gateway status 추가).

참고 임계값(개인 검수, 공식 SLA 아님): 스모크 응답 < 60s; 10분 내 errors.log 미설명 ERROR 0건; 테스트 쓰기 후 ls -la ~/hermes-lab/outbox에 신규 파일.

8. 첫 실전 사례: 요약+할 일+롤백 가능 출력

시나리오: 테스트 디렉터리에서 샘플을 읽고 한국어 요약·할 일 3개를 Markdown으로 저장, 롤백 복사본 유지. 설치 결과(CLI)·설정 결과(모델)·실제 workflow(읽기→추론→쓰기→로그)를 함께 검증합니다.

# 1. 입력 준비(3절에서 이미 만들었으면 생략)
cat > ~/hermes-lab/inbox/weekly-notes.txt <<'EOF'
이번 주: Hermes 설치 문서 초안 완료.
후속: OpenRouter 예산 알림 설정; 다음 주 Telegram gateway 검토.
위험: API Key를 git에 커밋하지 말 것.
EOF

# 2. 대화형 세션 시작(또는 복합 지시 한 줄)
hermes
# 세션에서 전송(예시 프롬프트):
# 「~/hermes-lab 디렉터리만 사용. inbox/weekly-notes.txt를 읽고,
#   150자 이내 한국어 요약과 할 일 3개를 작성해
#   outbox/summary-and-todos.md에 저장하고,
#   원본을 archive/weekly-notes.bak으로 복사」

# 3. 비대화형 검수
ls -la ~/hermes-lab/outbox/summary-and-todos.md
ls -la ~/hermes-lab/archive/
hermes logs agent -n 30 --since 15m

통과 기준:

• summary-and-todos.md 원본과 일치하는 요약·할 일 3개 포함.
• archive/ diff 가능한 백업 보관.
• 로그에 tool call 기록; provider 청구/대시보드에 이번 호출 반영(비용 확인).

롤백: rm ~/hermes-lab/outbox/summary-and-todos.md && cp ~/hermes-lab/archive/weekly-notes.bak ~/hermes-lab/inbox/weekly-notes.txt. 실패 시 먼저: 모델이 파일을 다 못 읽음 → outbox 권한 거부 → errors.log의 tool 오류.

9. 트러블슈팅: 층별로 좁히기, 맹목적 재설치 금지

게시 전 사실 체크리스트(유지보수자): 공식 install.sh URL, 최소 macOS, 기본 디렉터리명, CLI 하위 명령, provider 환경 변수명, 로그 경로—변경 시 문서를 먼저 갱신. 독자는 오류 시 hermes doctor → errors.log → 그다음 재설치 순서만 기억하면 됩니다.

10. 다음 단계: 테스트 디렉터리에서 실제 workflow로

검수 통과 후 아래 순으로 확장—프로덕션 저장소·결제 시스템에 바로 연결하지 마세요:

1. 실제 사이드 프로젝트 디렉터리 하나를 허용 목록에 추가; ~/.ssh와 전역 * 읽기/쓰기는 계속 차단.
2. hermes cron으로 일일 저위험 작업(예: Downloads 목록—여전히 테스트 디렉터리 범위).
3. 메시징 게이트웨이 하나(Telegram/Discord)를 페어링 모드로 설정해 낯선 사람 차단(공식 Security 문서).
4. 주간 hermes backup --quick 리듬을 만든 뒤 장기 유지보수 가이드로 업그레이드·롤백 연습.