헤르메스(Hermes) 설치가이드

대상: Windows 10/11 노트북 · 터미널을 처음 열어 보는 분
작성일 기준: 2026-08-06 (공식 사이트 hermes-agent.org/ko/, 공식 문서 hermes-agent.nousresearch.com, GitHub NousResearch/hermes-agent README 확인)

📌 이전 가이드에서 바뀐 점
예전 안내에는 헤르메스가 "길드 내부 배포 도구라서 공개 다운로드가 없다"고 적혀 있었습니다. 지금은 아닙니다. 헤르메스는 공식 사이트에서 누구나 내려받는 공개 도구입니다. 예전 문서를 보고 배포 가이드를 기다리고 계셨다면 이 문서대로 바로 설치하시면 됩니다.
헤르메스 자체의 별도 길드 로그인 계정은 없습니다. 설치를 마친 뒤 공식 안내에 따라 모델 제공자 키(주관사가 배포하는 실습용 키)와 필요한 시스템만 연결하면 됩니다. 로그인 계정을 기다리실 필요가 없습니다.

⚡ 빠른 설치 — 아는 분용 (약 15분)

① 공식 사이트 확인 — 크롬 주소창에 붙여넣기

https://hermes-agent.org/ko/

② PowerShell 열기 — 시작 버튼에 붙여넣고 Enter (관리자 권한 아님)

powershell

③ 설치 — 아래 한 줄을 붙여넣고 Enter. 5~15분 걸립니다 (Python·Node.js 등을 자동으로 함께 설치).

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

④ PowerShell을 닫고 새로 연 뒤 설치 확인

Get-Command hermes

⑤ 모델 제공자 연결 — 주관사가 배포한 실습용 키(접속 정보) 를 당일 안내대로 등록 (별도 길드 로그인 계정은 없습니다)

hermes setup

⑥ 알림 범위 설정 — 알림을 "완료 여부만 / 결과 요약 미포함", 대상은 본인 1:1 방 으로 (5-3). 이걸 하기 전에는 실제 업무에 쓰지 마세요.

⑦ 실행 후 테스트 — hermes 로 실행하고 입력창에 붙여넣기

가상의 임대차 분쟁 사례를 하나 만들고, 임차인 입장의 쟁점 3가지를 정리해서 보고해 줘. 실제 사건 정보는 사용하지 마.

1. 이 도구는 무엇인가

헤르메스는 여러 AI 에이전트에게 일을 나눠 주고 결과를 모아 한 번에 보고하는 "조율 담당" 에이전트입니다. 도구를 하나씩 오가며 지시하는 대신 한 번 요청하면 알맞은 담당 에이전트에게 일을 분배하고, 끝나면 메신저로 알림을 보냅니다.

법률 업무 예시: "이 가상 사건의 쟁점을 정리하고, 관련 법령을 찾고, 상대방 주장 반박 초안을 잡아 줘" 한 번 요청 → 조사·법령검색·초안작성을 각각 담당 에이전트에 맡기고 세 결과를 하나의 보고로 묶어 줍니다. 그 사이 다른 일을 하다가 알림을 받고 확인하면 됩니다.

Nous Research가 2026년 2월 공개한 오픈소스 도구(MIT 라이선스) 이며, 내 컴퓨터에서 돌아갑니다.

왜 이 도구를 배우는가 — 주요 특징 네 가지

특징	무슨 뜻인가
지속적 메모리	대화 세션이 바뀌어도 내 선호와 진행 중인 일을 기억합니다. 쓸수록 손발이 맞습니다.
자동 스킬 생성	한 번 풀어낸 복잡한 작업을 재사용 가능한 "스킬" 문서로 스스로 정리해 둡니다.
멀티플랫폼 연동	텔레그램·디스코드·슬랙 등 메신저와 터미널을 하나의 창구로 묶습니다.
예약 자동화	크론(Cron) 스케줄러로 "매일 아침 보고" 같은 무인 작업을 돌릴 수 있습니다.

낯선 용어(스킬·크론)는 워크북 부록 "AI 에이전트 상식 사전"에 있습니다.

⚠️ 주소를 반드시 확인하세요 — 비슷한 이름의 사이트가 많습니다.
공식 배포처는 아래 세 곳뿐입니다.

• hermes-agent.org (한국어 안내 포함)
• hermes-agent.nousresearch.com (공식 문서·설치 스크립트)
• github.com/NousResearch/hermes-agent (소스 코드)

검색하면 이름이 비슷한 제3자 사이트·블로그가 함께 나옵니다. 그런 곳의 설치 명령은 실행하지 마세요. 터미널 설치 명령은 실행하는 순간 내 계정 권한으로 무엇이든 할 수 있습니다.

🔐 보안 원칙 (전 과정 적용)

• API 키·비밀번호를 문서·메모·카카오톡·메일에 적지 마세요. 화면에서 바로 입력하고 "어디에 보관했는지"만 기록합니다.
• 발급받은 실습용 키를 채팅방에 붙여넣어 질문하지 마세요. 질문할 땐 키 부분을 가리고 캡처합니다.
• 회사 보안 프로그램이 막으면 임의로 끄거나 예외 등록하지 말고 담당자에게 문의하세요.
• 실습은 AX실습 폴더에서만. 실제 사건 자료 폴더와 반드시 분리합니다.

2. 설치 전 확인

• Windows 10/11 (64비트) — 관리자 권한은 필요 없습니다. 설치 파일이 내 사용자 폴더 안에만 들어갑니다.
• 여유 저장 공간 3GB 이상 — 설치 프로그램이 Python·Node.js·Git까지 함께 받아 옵니다.
• 인터넷 연결 — 다운로드 용량이 커서 회선이 느리면 15분 이상 걸립니다.
• 주관사가 배포하는 실습용 키(모델 제공자 접속 정보) — 설치가 아니라 5절 모델 연결에 필요합니다. 헤르메스용 별도 로그인 계정은 없습니다. 아직 못 받았어도 3절 설치까지는 진행할 수 있습니다.
• 메신저 계정 — 알림 연동용. 업무용 단체방이 있는 계정과 분리 권장 (알림이 업무방에 가는 사고 방지).
• 사내 정책 확인 — 회사 노트북에 외부 도구 설치가 가능한지 미리 확인. 막혀 있다면 개인 노트북이 빠릅니다.
• 실습 폴더 — 파일 탐색기 주소창에 아래를 붙여넣어 폴더가 열리는지 확인 (없으면 만드세요)

%USERPROFILE%\Desktop\AX실습

💡 "폴더를 찾을 수 없다"고 나오면 OneDrive가 바탕 화면을 대신 관리하는 경우입니다. 아래를 대신 붙여넣으세요.

탐색기 주소창에 붙여넣기복사

%OneDrive%\Desktop\AX실습

Node.js를 미리 설치하지 않아도 됩니다. 헤르메스 설치 프로그램이 Python 3.11, Node.js, Git(휴대용 버전), 검색·음성 도구를 알아서 함께 설치합니다. 이미 설치되어 있으면 그것을 그대로 쓰고, 시스템에 이미 있는 Git은 건드리지 않습니다.

받은 것 기록표 (키·비밀번호는 적지 마세요)

3. 설치 절차

1단계 — 공식 사이트에서 안내 확인

크롬 주소창에 아래를 붙여넣고 Enter.

https://hermes-agent.org/ko/

여기서 하는 일은 "주소가 맞는지 눈으로 확인하는 것" 입니다. 실제 설치는 다음 단계의 명령 한 줄로 끝납니다.

💡 내려받을 .exe 파일을 찾지 마세요. 헤르메스는 클릭해서 설치하는 프로그램이 아니라 명령 한 줄로 설치하는 도구입니다. 다운로드 버튼이 안 보이는 게 정상입니다.

📎 당일 배포 USB는 보조 수단입니다. 교육장 인터넷이 느려 3단계가 오래 걸릴 때만 사용합니다. USB 사용 절차는 당일 배포 안내를 따르세요 — 표준 경로는 어디까지나 아래 공식 설치 명령입니다.

2단계 — PowerShell 열기

시작 버튼을 클릭하고 아래를 붙여넣은 뒤 Enter.

powershell

⚠️ 관리자 권한으로 열지 마세요. 헤르메스 설치 프로그램은 관리자 권한 없이 내 사용자 폴더에만 설치하도록 만들어져 있습니다. 관리자 창에서 설치하면 나중에 실행할 때 권한이 꼬일 수 있습니다.

3단계 — 설치 명령 붙여넣기

아래 한 줄을 드래그해 Ctrl + C → PowerShell 창을 클릭하고 Ctrl + V → Enter.

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

설치되는 위치 (관리자 권한이 필요 없는 이유)

%LOCALAPPDATA%\hermes

💡 화면이 멈춘 것처럼 보여도 기다리세요. 큰 파일을 받는 동안 몇 분씩 아무 글자도 안 나올 수 있습니다. 창을 닫지 말고 두세요.

4단계 — PowerShell 새로 열기 (건너뛰면 다음 절이 실패합니다)

PowerShell 창을 닫고(오른쪽 위 X) 시작 버튼 → powershell → Enter 로 새 창을 엽니다.

hermes 명령의 위치가 방금 등록되었기 때문에, 열려 있던 창은 아직 그것을 모릅니다.

4. 설치 확인 (30초)

새 PowerShell 창에 아래를 붙여넣고 Enter.

Get-Command hermes

5. 초기 설정·연동

5-1. 모델 제공자 연결 (실습용 키 등록)

헤르메스에는 별도의 길드 로그인 계정이 없습니다. 여기서 하는 일은 헤르메스가 사용할 AI 모델 제공자를, 주관사가 배포한 실습용 키(접속 정보) 로 연결하는 것입니다.

PowerShell에 아래를 붙여넣고 Enter.

hermes setup

🔑 어느 항목을 고를지는 받은 실습용 키의 종류(Nous Portal / OpenRouter / LiteLLM)에 따라 다릅니다. 당일 안내를 따르세요. 안내를 못 받았으면 고르지 말고 Facilitator에게 먼저 확인하세요.

🔗 주관사가 운영하는 LiteLLM 서버 주소와 sk- 로 시작하는 실습용 키를 받았다면 — 목록에서 사용자 지정 엔드포인트를 고르고 LiteLLM 연결가이드의 5-2절 절차를 따르세요.

• 키는 그 자리에서 바로 입력하고 화면 캡처를 남기지 마세요.
• 붙여넣을 때 키 앞뒤에 공백이나 줄바꿈이 딸려 오지 않았는지 확인하세요 — 인증 실패 원인 1위입니다.
• 실습용 키를 메모장 파일에 저장하는 것은 금지입니다. 브라우저 비밀번호 관리자나 사내 허용 저장소만 사용하세요.
• 이 키는 실습 전용입니다. 실제 사건 자료를 다루는 작업에 쓰지 마세요.

5-2. 권한 승인 — 무엇을 위임하는지 읽고 승인

헤르메스는 다른 에이전트와 도구에 일을 대신 시키는 도구입니다. 승인하는 권한의 범위가 곧 "헤르메스가 내 대신 할 수 있는 일"의 범위입니다.

허용을 누르기 전에 아래를 확인하세요.

5-3. 메신저 알림 연동과 범위 설정 — 사건 정보 미포함

메신저 알림은 회사 밖 서버를 거쳐 개인 휴대폰으로 갑니다. 알림 본문에 사건 정보가 담기면 그 자체가 비밀유지의무 위반 소지가 됩니다.

• ✅ 좋은 알림: 작업 1 완료 (3건 처리) / 요청하신 검토가 끝났습니다. 결과는 프로그램에서 확인하세요.
• ❌ 있어서는 안 되는 알림: 의뢰인 이름, 사건번호, 상대방 이름, 계약 금액, 문서 원문 일부.

메신저 연동은 아래 명령으로 시작합니다.

hermes gateway setup

연결한 뒤 두 가지를 반드시 지정합니다.

1. 알림 내용 → "완료 여부만 / 결과 요약 미포함"
2. 알림 대상 → 본인 1:1 방 (업무 단체방은 절대 지정하지 마세요)

6. 첫 동작 테스트 (1분)

가상 정보로만 진행합니다. 실제 의뢰인·사건번호·상대방 이름을 입력하지 마세요.

PowerShell에서 헤르메스를 실행합니다.

hermes

입력창에 아래를 붙여넣고 Enter.

가상의 임대차 분쟁 사례를 하나 만들고, 임차인 입장의 쟁점 3가지를 정리해서 보고해 줘. 실제 사건 정보는 사용하지 마.

알림 문구를 반드시 확인하세요. 사례 내용이 알림에 그대로 실려 왔다면 5-3 설정이 안 된 것입니다. 실제 업무 사용 전에 고치세요.

💡 최신 상태로 업데이트하려면 PowerShell에서 아래를 실행합니다.

검색창에 입력복사

hermes update

7. 문제 해결

증상 1 — 'hermes' 용어를 인식할 수 없습니다 / ... 인식되지 않습니다

• 원인: ① 설치 후 PowerShell을 다시 열지 않아 윈도우가 아직 명령의 위치를 모르는 상태, ② 설치가 중간에 실패.
• 해결: PowerShell을 완전히 닫고 새로 여세요. 대부분 이것으로 해결됩니다. 그래도 같으면 파일 탐색기 주소창에 아래를 붙여넣어 설치 폴더가 실제로 있는지 확인하고, 없으면 3절 3단계를 다시 실행합니다.

%LOCALAPPDATA%\hermes

증상 2 — 설치 명령을 붙여넣었더니 스크립트를 로드할 수 없습니다 / 실행 정책 오류

• 원인: 회사 노트북에 PowerShell 스크립트 실행 제한 정책이 걸려 있는 경우입니다.
• 해결: 실행 정책을 임의로 바꾸지 마세요. Set-ExecutionPolicy 로 시작하는 해결책이 인터넷에 많이 나오지만, 회사 보안 설정을 개인이 푸는 것은 그 자체가 사고입니다. 오류 문구를 캡처해 ① 사내 전산·보안 담당자와 ② Facilitator에게 전달하고 지침을 기다리세요. 개인 노트북으로 전환하는 편이 빠를 수 있습니다.

증상 3 — 백신이 설치를 차단한다 / uv.exe 가 위험하다고 뜬다

• 원인: 헤르메스가 함께 설치하는 uv.exe(파이썬 설치 도구)는 백신이 자주 오탐하는 파일입니다. 공식 문서도 알려진 오탐이라고 안내합니다.
• 해결: 백신을 끄거나 예외 등록을 스스로 하지 마세요. 차단 팝업을 캡처해 ① 사내 전산·보안 담당자와 ② Facilitator에게 함께 전달하고 지침을 기다립니다. (담당자가 예외를 등록해 준다면 파일 하나가 아니라 %LOCALAPPDATA%\hermes 폴더 단위로 등록해야 합니다 — 업데이트할 때마다 파일이 바뀌기 때문입니다.)

증상 4 — 다운로드가 계속 끊기거나 몇 십 분째 끝나지 않는다

• 원인: 받아야 할 용량이 크고, 교육장 와이파이나 사내 프록시가 느리거나 막고 있는 경우입니다.
• 해결: ① 같은 명령을 그대로 다시 실행합니다 — 이 설치 명령은 여러 번 실행해도 안전하며, 이미 받은 것은 건너뜁니다. ② 휴대폰 테더링으로 네트워크를 바꿔 재시도 (교육장에서 가장 확실합니다). ③ 그래도 안 되면 당일 배포 USB를 요청하세요. 프록시 설정을 직접 바꾸지는 마세요.

증상 5 — 요청을 보냈는데 응답이 없고 계속 대기

• 원인: 네트워크 지연, 사내 방화벽 차단, 또는 모델 제공자 연결 만료(키 만료·한도 소진).
• 해결: ① 2분 기다립니다(여러 에이전트를 거치므로 일반 챗봇보다 느립니다). ② 그래도 멈춰 있으면 종료·재실행하고 hermes setup 으로 모델 제공자 연결 상태부터 확인. ③ 개인 핫스팟에서는 되고 회사 와이파이에서만 안 되면 사내 방화벽 문제입니다 — 임의로 우회하지 말고 담당자에게 문의하세요.

증상 6 — 알림이 오지 않는다 / 반대로 내용이 너무 자세히 온다

• 원인: 메신저 연동 누락, 또는 알림 범위가 기본값.
• 해결: 5-3으로 돌아가 hermes gateway setup 을 다시 실행하고 대상(본인 1:1 방)과 범위를 설정한 뒤, 6절 테스트로 실제 문구를 확인합니다. 내용이 자세히 오는 쪽이 더 위험합니다. 고치기 전까지 실제 업무 관련 요청을 넣지 마세요.

증상 7 — 모델 제공자 연결이 되지 않는다 / authentication failed

• 원인: ① 키 앞뒤에 공백·줄바꿈이 딸려 들어갔거나, ② 5-1에서 발급받은 키 종류와 다른 항목을 골랐거나(예: OpenRouter 키를 받았는데 Nous Portal을 선택), ③ 발급받은 실습용 키가 아직 활성화되지 않았거나 사용 한도가 소진됐습니다.
• 해결: hermes setup 을 다시 실행해 처음부터 진행합니다. 키를 붙여넣기 전에 메모장에 한 번 붙여넣어 앞뒤 빈칸을 눈으로 확인한 뒤 키 부분만 다시 복사하세요 (확인 후 메모장은 저장하지 말고 닫습니다). 그래도 안 되면 Facilitator에게 알리세요 — 키 값 자체는 메신저로 보내지 말고 오류 문구만 전달합니다.

8. 제거·연동 해제

순서는 연동 해제 → 키·권한 정리 → 프로그램 제거 입니다. 프로그램만 지우면 위임한 권한과 키가 남습니다.

⚠️ 공식 문서에 별도의 제거 명령이 안내되어 있지 않습니다. 아래는 설치 위치를 되돌리는 절차이며, 확실하지 않으면 Facilitator에게 확인하세요.

8-1. 메신저 알림 연동 해제 (가장 먼저)

헤르메스의 게이트웨이 설정에서 연동을 해제하고, 메신저 앱 쪽에서도 연결된 앱/봇 목록에서 헤르메스 항목을 삭제합니다. 한쪽만 지우면 알림이 계속 옵니다.

hermes gateway setup

8-2. 예약 작업 정리

크론(예약 자동화)을 하나라도 만들었다면 먼저 지웁니다. 지우지 않으면 프로그램을 제거한 뒤에도 예약이 남아 오류를 낼 수 있습니다. 만든 적이 없으면 건너뛰세요.

8-3. 실습용 키·권한 회수

1. 5-1에서 연결한 모델 제공자(Nous Portal 등)의 "연결된 앱" 화면에서 헤르메스의 액세스 권한을 삭제합니다.
2. 발급받은 실습용 키의 폐기·재발급은 Facilitator에게 요청하세요. 주관사가 배포한 키이므로 개인이 임의로 처리하지 않습니다.
3. 본인이 직접 발급한 API 키가 있다면 발급처에서 폐기(revoke) 하세요. 내 PC에서 지우는 것만으로는 키가 살아 있습니다.

8-4. 프로그램 제거

파일 탐색기 주소창에 아래를 붙여넣어 폴더를 연 뒤, hermes 폴더를 삭제하지 말고 먼저 다른 곳으로 옮겨 며칠 두었다가 문제가 없으면 지우세요.

%LOCALAPPDATA%

헤르메스가 실행 중이면 삭제가 안 됩니다. PowerShell 창을 모두 닫고 다시 시도하세요.

8-5. 실습 자료 정리

바탕 화면\AX실습 에서 남길 결과물만 옮기고 나머지는 삭제합니다. 실제 사건 정보를 입력한 적이 있다면 해당 파일과 대화 기록을 반드시 삭제하고 Facilitator에게 알리세요.

다른 설치 방법

본문의 표준 경로(PowerShell 한 줄 설치)로 진행하는 것을 권장합니다. 아래는 해당되는 경우에만 보세요.

① WSL2에서 설치 — 공식 사이트의 한국어 설치 문서는 "네이티브 Windows 지원은 실험적이므로 WSL2를 쓰라"고 안내하는 반면, 공식 GitHub README와 실제 설치 스크립트는 Windows 네이티브 설치를 정식으로 지원합니다(휴대용 Git을 함께 넣어 주고 관리자 권한도 필요 없습니다). 초보자에게는 WSL2 설치 자체가 더 큰 산이므로 이 가이드는 네이티브 설치를 표준으로 삼았습니다. 이미 WSL2를 쓰고 계신 분만 아래 명령을 WSL 터미널에서 사용하세요.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

② 당일 배포 USB — 교육장 인터넷이 느릴 때만 쓰는 보조 수단입니다. USB 안의 파일 구성과 실행 절차는 교육 당일 배포 안내를 따르세요.

막히면: 오류 화면을 그대로 캡처(Windows 키 + Shift + S)해 Facilitator 에게 보내세요. 단, 비밀번호·API 키가 보이면 그 부분을 가리고 보내야 합니다. 오류 메시지는 요약하지 말고 글자 그대로 전달하는 것이 가장 빠릅니다.

확인한 공식 출처 (2026-08-03 최초 확인 · 2026-08-06 재확인)

• https://hermes-agent.nousresearch.com/docs/integrations/providers — 모델 제공자 목록과 자격 정보 방식: Nous Portal은 OAuth 승인 방식으로 입력할 API 키가 없음, OpenRouter는 OPENROUTER_API_KEY, OpenAI 등은 각 제공자 키, 사용자 지정 엔드포인트는 config.yaml. (2026-08-06 확인)
• https://hermes-agent.org/ko/ — 한국어 소개·설치 안내, 주요 특징 4종, 메신저 연동·크론
• https://hermes-agent.org/ko/docs/installation — 설치 4단계(hermes setup / hermes / hermes gateway setup / hermes update), Windows는 WSL2 권장이라고 안내
• https://github.com/NousResearch/hermes-agent README — Windows 네이티브 설치 명령 iex (irm .../install.ps1), 지원 OS, 휴대용 Git 동봉, uv.exe 백신 오탐 안내
• https://hermes-agent.nousresearch.com/install.ps1 — 설치 위치 %LOCALAPPDATA%\hermes, 관리자 권한 불필요, Python 3.11·Node.js 22·PortableGit·ripgrep·ffmpeg 자동 설치