2026 Hermes Agent 장기 유지보수 베스트 프랙티스: 업데이트·로그·백업·재시작 복구 완전 가이드
Mac에서 Hermes Agent를 이미 돌리고 있다면, 진짜 관건은 일주일 뒤·한 달 뒤입니다—시스템 업데이트, 만료된 모델 키, 재부팅 후 안 뜬 게이트웨이, 디스크를 채우는 로그. 이 글은 개인·소규모 팀을 위한 백업 가능·추적 가능·복구 가능한 운영 플레이북입니다. 결론부터—장기 안정성은 한 번의 hermes init이 아니라 주기 점검과 업그레이드 검수에서 나옵니다. 의사결정 매트릭스 2종, 백업 체크리스트, 7단계 런북, 건강 임계값, 유지보수 캘린더 포함(2026-05-23 기준 Hermes 공식 CLI).
1. Mac의 Hermes를 소규모 서비스처럼 다루기
2026년 Mac에서 Hermes Agent를 처음 띄운 것은 시작일 뿐입니다. macOS 업데이트, 만료된 모델 API 키, 슬립/웨이크 후 launchd 게이트웨이 미기동, hermes update로 깨진 도구 설정—이것이 상시 AI 에이전트의 실제 비용입니다.
이 Mac이 7×24 어시스턴트 역할(로컬 개발기, 가정용 Mac mini, ZoneMac 같은 원격 물리 노드)이라면 소규모 서비스처럼 관리하세요: 버전 조회(hermes version), 설정 백업(hermes backup), 로그 검색(hermes logs), 롤백 가능 업그레이드(백업 + hermes import), 장애 시 중지(hermes gateway stop / cron 일시 중지). 공식 hermes doctor, hermes status, hermes dashboard를 우선하고, 이 플레이북은 주기와 검수 기준을 덧붙입니다.
2. 자주 겪는 문제 세 가지
- 제약: 무인 ≠ 유지보수 불필요. macOS, Homebrew/pip, Hermes 릴리스 주기는 맞지 않습니다. 검수 없이
hermes update만 돌리면 게이트웨이·cron이 반쯤 업그레이드된 상태로 남을 수 있습니다. - 숨은 비용: PATH·launchd 환경 불일치. 대화형 셸에서는
git·node가 되는데 launchd 게이트웨이는 바이너리를 못 찾아—작업 로그에는 모호한 도구 오류만 남습니다. - 안정성·감사: 백업 없음 = 롤백 포인트 없음. 설정이
~/.hermes/config.yaml,.env, skills, 세션 DB에 흩어져 있고, 채팅에만 키를 두면 순환 시 전체가 끊깁니다.
3. 백업 대상(업데이트 전 체크리스트)
기본 데이터 디렉터리는 HERMES_HOME(보통 ~/.hermes). hermes config path·hermes config env-path로 확인하세요. 프로필마다 home이 다릅니다.
| 구분 | 경로 / 명령 | 롤백 필요도 |
|---|---|---|
| 메인 설정 | config.yaml |
필수 |
| 환경 변수 / API 키 참조 | .env (hermes config env-path) |
필수 |
| 자격 풀 | hermes auth list 뒤 저장소 |
필수 |
| 세션 / 상태 DB | state.db 등(전체 백업에 포함) |
권장 |
| Skills / 작업 템플릿 | skills 디렉터리, hermes cron list |
권장 |
| 게이트웨이 / 페어링 | Telegram/Discord 페어링, webhook 구독 | 아웃바운드 채널 시 필수 |
| 데몬 | hermes gateway install의 launchd plist |
업그레이드 후 재설치가 필요한 경우 많음 |
| 로그(아카이브) | ~/.hermes/logs/ |
장애 분석용, 복구용 아님 |
| Workspace(설정 시) | 프로젝트 workspace, AGENTS.md / SOUL.md |
에이전트 편집 여부에 따름 |
권장 명령: 일상 빠른 스냅샷 hermes backup --quick --label "pre-upgrade"; 대규모 변경 전 hermes backup -o ~/hermes-backups/$(date +%F).zip. 복원은 hermes import. 공식 백업에는 Hermes 코드 저장소 자체는 포함되지 않습니다(git vs pip 롤백 방식이 다름).
4. 환경을 깨지 않고 업그레이드: 주기·매트릭스·7단계 런북
4.1 업데이트 주기: macOS·의존성·Hermes
| 계층 | 권장 빈도 | Hermes와의 관계 |
|---|---|---|
| macOS 마이너 | 커뮤니티 피드백 1–2주 대기 | 업그레이드 후 항상 gateway 재시작 + doctor |
| Homebrew / pip 런타임 | 월 1회 또는 보안 권고 시 | Hermes 업데이트와 겹치지 않게 분산 |
| Hermes Agent | 프로덕션: 월 1회 창; 개인: 2–4주 | 먼저 hermes update --check |
| 모델 공급자 정책 | 벤더 공지에 따름 | OAuth는 hermes auth; API 키는 90일마다 순환 |
자동 업데이트가 안전하다고 가정하지 마세요. git pull이든 pip install --upgrade든 백업 → 업데이트 → 최소 작업 검수 → 롤백 zip 보관 순서를 지키세요. config.yaml에 update.backup: true를 두거나 한 번 hermes update --backup을 실행하세요.
4.2 업그레이드·검수 7단계 런북
- 기준선 기록:
hermes version,hermes dump,hermes gateway status를 변경 티켓에 적습니다. - 백업:
hermes backup --quick --label "pre-$(date +%Y%m%d)"또는 전체 zip. - 사전 점검:
hermes update --check;hermes doctor --fix로 자동 수정 가능 항목 처리. - 업데이트 실행: 유지보수 창에
hermes update --backup(git 설치는 코드 pull·deps 재설치; pip는 PyPI 업그레이드). - 최소 검수:
hermes chat -q "reply OK"; 게이트웨이 사용 시 Telegram/Discord에서 실제 메시지 전송. - 재시작 테스트:
hermes gateway restart; 선택적으로 Mac 재부팅해 launchd 자동 기동 확인. - 실패 시 롤백:
hermes import <backup.zip>, 또는 config/.env 복구 후hermes gateway restart; 설치 방식에 맞게 pip/git 다운그레이드.
| 증상 | 1차 조치 | 검수 기준 |
|---|---|---|
| 업데이트 멈춤 / 재시작 루프 | 게이트웨이 중지; hermes logs errors -f |
doctor 전부 녹색 + chat -q 성공 |
| 업그레이드 후 도구 전부 실패 | hermes tools list; config toolsets 비교 |
핵심 toolset 각 1회 실행 |
| 게이트웨이만 다운, CLI는 정상 | hermes logs gateway --since 1h |
status에 connected |
5. 로그와 건강 점검
5.1 로그 위치와 자주 쓰는 명령
기본 디렉터리: ~/.hermes/logs/(비기본 프로필은 해당 HERMES_HOME/logs/).
agent.log— API 호출, 도구 디스패치, 세션 수명(INFO+)errors.log— WARNING 이상; 장애 시 첫 확인gateway.log— 메시징 플랫폼 연결·webhook
hermes logs list
hermes logs errors --since 30m -n 100
hermes logs gateway -f
hermes logs --level ERROR --since 2h --component tools프레임워크가 agent.log를 로테이션합니다(예: agent.log.1). 30일 넘은 *.log.*는 월 1회 콜드 스토리지로 아카이브하고, 체크포인트 shadow 저장소는 hermes checkpoints prune --max-size-mb 500로 상한을 둡니다.
5.2 건강 점검 임계값(권장)
hermes gateway status = runninghermes chat -q 30초 내 응답일일 점검 스크립트 예: hermes doctor + hermes logs errors --since 24h + df -h. 외부 알림은 ERROR 줄을 로그 파이프라인으로 보내거나 hermes debug share --local로 수동 업로드합니다.
6. 재부팅·네트워크 단절·슬립과 복구 드릴
Mac 슬립/웨이크 후 먼저 hermes gateway status; 미실행이면 hermes gateway start(launchd 설치 시나리오). 네트워크 복구 후 gateway.log에 재연결이 보이는지 확인합니다.
분기 1회 드릴(캘린더에 등록):
- 전체
hermes backup을 오프사이트 디렉터리로 - Mac 재부팅 → 3분 대기 →
hermes status --deep - 메시징 플랫폼에서 테스트 메시지 +
hermes cron tick(cron 있을 때) - RTO 기록: 부팅부터 게이트웨이 가용까지(목표 < 5분, 모델·로그인 항목에 따라 다름)
원격 물리 Mac(ZoneMac 노드 등)에서는 SSH 도달, launchd와 동일 사용자, PATH에 git/node 포함도 확인하세요—
OpenClaw Gateway launchd 트러블슈팅과 같은 PATH 이슈가 흔합니다.
7. 시크릿·권한 검토
- API 키(OpenRouter, Anthropic 등): 90일마다 순환;
hermes auth add/remove사용, skills에 평문 금지. - OAuth(Codex, Anthropic, Copilot):
hermes auth status <provider>; 만료 시 .env 수정이 아닌 재 OAuth. - 도구 권한: 월 1회
hermes tools list; 미사용 터미널/브라우저/MCP 비활성화. - 페어링·webhook:
hermes pairing list; 미사용 구독 정리.
8. 유지보수 캘린더(미리 알림에 붙여넣기)
| 주기 | 할 일 | 검수 |
|---|---|---|
| 매일 | hermes logs errors --since 24h; gateway status |
미처리 ERROR 클러스터 없음 |
| 매주 | hermes doctor; 토큰/비용은 hermes insights |
cron 실패율 < 5% |
| 매월 | 유지보수 창: hermes update --backup; 로그 아카이브; hermes backup |
chat -q + 실제 게이트웨이 테스트 |
| 분기 | 키 순환; 재부팅 드릴; 도구 권한 축소 | RTO 기록 보관 |
| 업데이트마다 | dump → quick backup → update → doctor → 스모크 테스트 | 라벨 zip 7–30일 보관 |
내부 위키용 인용 수치
- 기본 로그:
~/.hermes/logs/, 로테이션agent.log.1+ - quick 백업 크기: 수 MB~수백 MB(세션·skills에 따라); 전체 백업—디스크 ≥ 2× HERMES_HOME 여유
- 프로덕션 게이트웨이 폴링: status 30–60초; 시작 임계 ERROR 1시간 5줄 미만
- 체크포인트 기본 상한:
--max-size-mb 500(디스크에 맞게 조정)
FAQ
Q: brew와 pip 설치의 롤백 차이는?
A: pip는 이전 wheel 재설치; git 설치는 알려진 커밋으로 git checkout 후 deps 재설치. 어느 쪽이든 사용자 데이터 롤백은 hermes import—설정 복구 없이 바이너리만 내리지 마세요.
Q: 여러 프로필은 어떻게 백업하나요?
A: 프로필별 hermes -p <name> backup; 다중 게이트웨이 업데이트 후 hermes gateway restart --all.
9. 요약: Hermes를 지속 가능한 서비스로
장기 안정성 = 백업된 설정 + 추적 가능한 로그 + 복구 가능한 launchd 게이트웨이 + 통제된 업데이트 주기. 유지보수 캘린더를 반복 알림으로 두면 가끔 재설치하는 것보다 낫습니다.
Mac mini에서 Hermes 운영 부담을 줄이기
Hermes Agent는 macOS·launchd 백그라운드 게이트웨이를 네이티브로 지원합니다. Apple Silicon Mac mini의 통합 메모리·낮은 유휴 전력(M4급 약 4W)은 에이전트를 연중 가정·랙 사이드 서비스로 두기에 맞습니다. macOS Unix 도구 체인—Homebrew, SSH, Docker, 터미널—는 WSL·드라이버 없이 바로 쓰고, Gatekeeper·FileVault로 무인 가동 리스크도 줄입니다. 플레이북에 집중하면 됩니다.
백업·업그레이드·재부팅 드릴을 안정적·저소음·원격 접근 가능한 전용 노드에서 돌리려면 Mac mini M4 또는 ZoneMac 원격 물리 Mac이 가성비 좋습니다. 로컬에서 개발하고 게이트웨이·cron은 7×24 원격으로. 지금 Mac mini 노드를 확보해 이 Hermes 유지보수 플레이북을 실전에 적용하세요.
Hermes 전용 원격 Mac이 필요하신가요?
Mac mini 클라우드 물리 노드—게이트웨이·cron·무인 유지보수 창에 맞춤 설계.