Hermes 데스크톱 앱을 처음 설치하거나 업데이트할 때, 화면 중간에 멈춰 버리는 경우가 있습니다. 로그를 열어보면 Git 충돌과 npm 엔진 오류가 뒤섞여 나오면서 원인을 파악하기 어렵게 만듭니다. 이 글에서는 실제 로그를 바탕으로 한 단계별 해결 방법을 정리합니다.
Hermes 설치 실패의 대부분은 Git 로컬 변경 충돌과 npm 버전 불일치(EBADENGINE) 때문입니다. Git 상태를 초기화하고 npm을 최신 버전으로 업데이트하면 대부분 해결됩니다.
설치 과정에서 발생하는 주요 오류 유형
Hermes는 bootstrap이라는 일련의 단계를 거쳐 설치됩니다. repository, venv, dependencies, node-deps, desktop, configure, gateway 순으로 진행되죠. 실무에서 보면 Git 충돌이 npm 오류보다 먼저 발생하는 경우가 많습니다. 로컬 저장소가 origin/main보다 수천 커밋 뒤처져 있으면 git pull 단계에서 바로 멈춥니다.
두 번째로 흔한 문제는 npm install failed 메시지입니다. 하지만 이 메시지 뒤에 숨은 진짜 원인은 대부분 EBADENGINE 코드입니다. 세 번째로 Gateway가 반복해서 죽는 현상도 있는데, 이건 설치 이후의 안정성 문제로 이어집니다.
Git 충돌 원인과 해결 방법
bootstrap-installer.log를 열어보면 Update pulled new code, but restoring local changes hit conflicts라는 문구가 보입니다. 로컬에 website 디렉토리 관련 변경사항이 남아 있어서 Git이 병합을 실패한 것입니다. 이 상태에서는 이후 단계로 전혀 넘어갈 수 없습니다.
해결은 단순합니다. Hermes 앱을 완전히 종료한 뒤, PowerShell 관리자 권한에서 다음 경로로 이동하세요.
C:\Users\[사용자명]\AppData\Local\hermes\hermes-agent
그리고 아래 명령어를 순서대로 입력합니다.
git reset –hard HEAD
git clean -fd
git pull origin main
git reset은 로컬 변경사항을 모두 버리고, git clean은 추적되지 않는 파일을 삭제합니다. 이건 직접 겪어보면 체감되는데, website 폴더가 문서용이라고 해서 무시하면 안 됩니다. Git working tree가 conflict 상태에 빠지면 bootstrap 전체가 멈추기 때문입니다.
npm EBADENGINE 오류 해결
Git 충돌을 해결하고 나면 이번에는 node-deps 단계에서 멈출 수 있습니다. 로그를 자세히 보면 다음과 같은 메시지가 나옵니다.
Required: node >=22.22.0, npm <11.10.0 || >=11.17.0
Actual: node v24.18.0, npm 11.16.0
Node.js 버전은 충족하지만, npm 11.16.0이 11.10.0 이상 11.17.0 미만이라는 금지 구간에 걸려 있습니다. 이건 직접 겪어보면 체감되는데, npm 버전이 딱 그 구간에 걸리면 에러 메시지가 전혀 다른 문제처럼 보입니다.
많이들 여기서 막히더라고요. 로그를 끝까지 안 읽고 npm 캐시만 지우다가 시간을 낭비합니다.
| 해결 방법 | 소요 시간 | 난이도 | 권장 상황 |
|---|---|---|---|
| npm 최신 버전 업데이트 | 10초 | 쉬움 | npm 11.10.0~11.16.x 구간에 있을 때 |
| Git reset으로 충돌 해제 | 1분 | 쉬움 | Git pull 충돌이 발생했을 때 |
| 전체 폴더 삭제 후 재설치 | 10분 | 보통 | 위 방법으로 해결되지 않을 때 |
가장 빠른 방법은 npm을 최신 버전으로 올리는 것입니다. PowerShell에서 아래 명령어 하나면 충분합니다.
npm install -g npm@latest
이후 Hermes 앱에서 Retry install을 누르면 node-deps와 desktop 단계가 정상 진행됩니다. 만약 이 방법이 안 통한다면, hermes-agent 폴더를 통째로 삭제하고 앱을 재실행해 처음부터 다시 받는 방법도 있습니다.
Hermes Gateway 비정상 종료 대응
설치 이후에도 gateway.lifecycle_ledger 로그를 보면 exited UNCLEANLY라는 기록이 여러 차례 찍혀 있습니다. suspected_oom=False이므로 메모리 부족은 아닙니다. 대부분 외부에서 프로세스를 강제 종료한 경우입니다.
Windows Defender나 기업용 EDR이 Gateway 프로세스를 의심하여 죽이는 경우가 많습니다. Windows 이벤트 뷰어에서 Application 로그를 확인하면 어떤 프로세스가 종료를 유발했는지 알 수 있습니다. eventvwr.msc를 실행하고 Windows 로그 > 응용 프로그램에서 Hermes 관련 오류를 검색해 보세요.
또한 Telegram 연결 실패는 별도 문제입니다. python-telegram-bot과 httpx 버전 불일치가 원인인 경우가 많으므로, Hermes를 최신 버전으로 업데이트하거나 Bot Token을 재확인하는 것이 좋습니다.
설치 성공을 위한 전체 체크리스트
지금 Hermes 설치가 멈춰 있다면, 로그의 마지막 몇 줄을 다시 확인해 보세요. 대부분의 경우 마지막 10줄 안에 정확한 원인이 드러납니다.
- Hermes 앱을 완전히 종료한다. 트레이 아이콘도 포함입니다.
- PowerShell을 관리자 권한으로 연다.
- Git 상태를 확인하고 충돌 여부를 파악한다.
- npm 버전을 확인하고 11.10.0~11.16.x 구간에 있는지 체크한다.
- 필요시 git reset –hard HEAD와 git clean -fd를 실행한다.
- npm install -g npm@latest를 실행한다.
- Hermes를 재실행하고 Retry install을 누른다.
실무 팁: Hermes의 bootstrap-installer.log 파일은 C:\Users\[사용자명]\AppData\Local\Hermes\logs 경로에 저장됩니다. 설치가 멈추면 Retry install을 누르기 전에 이 로그의 마지막 50줄을 먼저 확인하세요. 대부분의 경우 마지막 10줄 안에 정확한 오류 원인이 드러납니다.
흔한 오해와 실제 원인
오해: npm install failed라면 npm 캐시가 문제다
실제로는 npm 캐시 문제가 아닌 경우가 훨씬 많습니다. 로그를 보면 EBADENGINE 코드가 찍히고, Required 버전과 Actual 버전이 명확히 대비되어 나옵니다. 이건 캐시를 비운다고 해결되지 않습니다.
오해: Git 충돌은 website 폴더라서 무시해도 된다
website 폴더는 문서용으로 보이지만, Git working tree가 conflict 상태에 빠지면 이후 모든 단계가 멈춥니다. repository 단계에서 실패하면 venv, dependencies, node-deps, desktop 단계로 전혀 진행되지 않습니다.
오해: Gateway가 죽으면 메모리 부족이다
로그상 suspected_oom=False로 명시되어 있습니다. 대부분 백신이나 EDR이 프로세스를 강제 종료한 경우이므로, Windows 이벤트 뷰어에서 Application 로그를 확인해야 합니다.
마무리
Hermes 설치는 단순히 앱을 켜고 기다리는 것 이상의 과정이 필요합니다. Git 저장소와 npm 의존성이 모두 정상 상태여야 bootstrap이 끝까지 진행되죠.
이 부분이 핵심입니다. 로그를 끝까지 읽지 않으면 npm 캐시만 비우다가 하루를 날릴 수 있습니다.
지금 바로 실행해 보세요. PowerShell 관리자 권한을 열고, Git 저장소 경로로 이동한 뒤 git reset –hard HEAD와 git clean -fd를 입력하세요. 그리고 npm install -g npm@latest를 실행한 후 Hermes에서 Retry install을 누르면 됩니다.
혹시 설치 과정에서 다른 오류 메시지를 마주쳤다면, 댓글에 로그 마지막 줄을 붙여넣어 주세요. 어떤 오류 메시지가 나오셨나요? Hermes 외에 비슷한 구조의 AI 데스크톱 앱을 설치하면서 비교해본 경험이 있으신가요?
다음으로 읽으면 좋은 글:
본 포스팅은 정보 전달 목적이며, 실제 적용 시 발생하는 책임은 사용자에게 있습니다.