Hermes Agent 원클릭 키트 (Windows)

🇰🇷 한국어 문서입니다. 🇺🇸 English: README.en.md

Nous Research의 Hermes Agent(스스로 스킬을 만들고 기억을 유지하는 오픈소스 자율 AI 에이전트)를, 명령어 입력 없이 .bat 더블클릭만으로 설치·실행·로그인·메신저 연결·제거할 수 있게 해 주는 왕초보용 키트입니다.

🔰 컴퓨터·전자기기·AI·메신저가 처음이세요? → 먼저 왕초보_시작_가이드.md (마우스·키보드·인터넷부터)
📱 메신저(텔레그램 등) 연결만 자세히 → 메신저_연결_가이드.md

1. 이게 뭔가요

Hermes Agent = 내 컴퓨터에 사는 AI 비서. 말로 시키면(요약·번역·검색·파일 정리 등) 알아서 해줍니다. 텔레그램 같은 메신저에 연결하면 휴대폰으로도 시킬 수 있어요.
이 키트 = 위 과정을 어려운 명령어 없이 더블클릭 메뉴로 하게 해 줍니다.
준비물: Windows 10/11, 인터넷. 관리자 권한 불필요(설치는 전부 사용자 영역).

2. 빠른 시작 (5단계)

INSTALL.bat 더블클릭 → (5초 뒤 자동 설치 시작) 끝까지 기다리기(수 분~십수 분). 끝에 로그인 화면(Choice [default 1]:)이 뜨면 Enter → 브라우저에서 로그인.
설치 창을 닫고 RUN.bat 더블클릭(새 창이 필요해요 — 이유는 4번).
(설치 끝에서 로그인 안 했으면) RUN → 1) 처음 설정 → 로그인 + AI 모델 선택.
RUN → 3) 메신저 연결 → 1) Set up a messenger(텔레그램) → 그다음 2) Turn the bot ON.
휴대폰 텔레그램에서 내 봇에게 "안녕" → 답이 오면 성공!

⚠️ 설치 직후 절대 누르지 마세요: UNINSTALL.bat · Hermes-Setup.exe(데스크톱 설치파일) · hermes uninstall. → 이게 프로그램을 지웁니다. (9번)

3. 설치 — INSTALL.bat

키트 폴더에서 INSTALL.bat 더블클릭.
5초 카운트다운 후 자동으로 설치가 시작됩니다. (설치하기 싫으면 그 5초 안에 창을 닫으면 취소.)
글자가 막 지나갑니다 — 정상입니다. 창을 닫지 마세요. SSH 실패 → HTTPS 같은 빨간 글씨도 자동 복구되는 정상 과정.
거의 끝나면 "로그인 마법사"가 떠요 — Choice [default 1]: 가 보이면 그냥 Enter(무료 Nous Portal) → 브라우저가 열리면 2분 안에 "Connect". (지금 건너뛰고 나중에 RUN.bat → 1) 처음 설정으로 해도 됩니다.)
[DONE] Hermes is installed! 가 보이면 성공.
(선택) "데스크톱 앱(.exe)도 받을까요?"는 받기만 하고, 봇이 켜진 채로는 실행하지 마세요(설치가 깨집니다).

자동으로 함께 설치되는 것: uv → Python 3.11 → Node.js 22 → Git(MinGit). (ripgrep·ffmpeg는 설치를 시도하지만 환경에 따라 건너뛸 수 있어요 — 없어도 작동하며, 원하면 winget install BurntSushi.ripgrep.MSVC · winget install Gyan.FFmpeg로 따로 설치.)

4. 실행 & 메뉴 — RUN.bat

설치 후엔 반드시 새 창이 필요합니다(설치가 "프로그램 위치(PATH)"를 바꾸는데, 이미 열린 창은 그걸 모름. 새 창은 자동 인식). → 그냥 RUN.bat 더블클릭.

맨 위에 현재 버전·로그인 상태가 보이고, 실제 사용 순서대로 메뉴가 나옵니다:

메뉴	뜻	안에서
1) 처음 설정	로그인 + AI 모델 (제일 먼저!)	`hermes portal`
2) 대화하기	AI와 채팅	`hermes --tui`
3) 메신저 연결	메신저(텔레그램 등)	① Set up a messenger · ② Turn the bot ON
4) 업데이트 / 버전	버전·업데이트	① 버전확인 ② 업데이트확인 ③ 업데이트
5) 고급 기능	진단·로그아웃·설정폴더 등	아래
6) 도움말	잘 안 될 때 (자가 진단)	화면 안내
0) Exit	끄기(또는 `q`)

5) 고급 기능 안: 1) Log in / Connect AI · 2) Log out · 3) Pick AI model · 4) Health check(진단) · 5) Turn bot ON · 6) 설정 폴더 열기 · 7) 도움말 · 8) 데스크톱 앱 페이지 · 9) 지난 대화 · 0) 뒤로.

메뉴는 설치된 hermes에게 직접 물어, 없는 기능은 "이 버전엔 없음"으로 안전 안내합니다.

5. 로그인 & AI 모델 연결

AI가 답하려면 두뇌(모델) 가 필요합니다. 가장 쉬운 길 = Nous Portal(무료, 가입/키 관리 없이 로그인). 설치 끝 마법사에서 이미 로그인했다면 이 단계는 건너뛰세요.

설치 끝 마법사는 1. Quick Setup(무료·키 불필요)과 2. Full setup(내 API 키 직접) 중 고르게 합니다. 1(Enter)이 가장 쉬움. "no API keys"는 "키가 필요 없다"는 뜻이지 못 쓰는 게 아니며, 나중에 설정을 다시 해 2로 본인 키·모델로 바꿀 수 있습니다.

RUN → 1) 처음 설정 을 누르면:

화면에 코드와 링크가 뜨고 브라우저가 열립니다.
2분 안에 브라우저에서 "Connect" 를 누르세요. (코드는 금방 만료돼요.)
"device code not recognized" = 코드 만료. → 이 메뉴를 다시 실행하면 새 코드.
로그인 후 AI 모델(Nous 무료) 도 고릅니다 → 끝나면 봇 재시작(Y).

내부적으로 hermes portal(로그인+모델)을 실행합니다.

6. 메신저 봇 연결 (텔레그램)

텔레그램이 제일 쉬워요. 그림 설명은 메신저_연결_가이드.md. 요약:

RUN → 3) 메신저 연결 → 1) Set up a messenger → 마법사 안내대로 텔레그램 로그인하면 봇이 자동 생성됩니다(가장 쉬움). 또는 @BotFather에서 만든 토큰·내 숫자 ID를 직접 붙여넣기도 가능.
(수동) 텔레그램 @BotFather 에 /newbot → 토큰 / @userinfobot 에서 내 숫자 ID.
RUN → 3) 메신저 연결 → 2) Turn the bot ON → 이 검은 창을 켜둔 채로 두세요.
휴대폰 텔레그램 봇에 메시지 → 답이 옵니다.

⚠️ "user ID"는 숫자만(예 123456789). 토큰(긴 영문+숫자)을 ID 칸에 붙여넣지 마세요. 봇은 "Turn the bot ON" 창이 켜진 동안만 답합니다.

WhatsApp·Signal·Slack·이메일 등 20종+ 도 됩니다 → 메신저 가이드 참고.

7. 자주 쓰는 명령어

보통은 RUN 메뉴면 충분하지만, 새 터미널에서 직접 칠 수도 있어요:

하는 일	명령어
대화 시작	`hermes` 또는 `hermes --tui`
로그인 + 모델	`hermes portal`
로그아웃	`hermes logout`
메신저 설정	`hermes setup gateway`
봇 켜기	`hermes gateway`
봇 재시작	`hermes gateway restart`
버전 확인	`hermes version`
업데이트 확인	`hermes update --check`
업데이트	`hermes update`
AI 모델 선택	`hermes model`
진단	`hermes doctor`
모든 명령 보기	`hermes --help`

8. 오류 대처 (실제 사례별)

증상	원인	해결
봇이 답을 안 함	봇(게이트웨이) 꺼짐	RUN → `3 → 2) Turn the bot ON` 켜고 창 유지
봇이 "model provider failed"	AI 모델 미설정/오류	`5 → 3) Pick AI model` 에서 Nous 모델 → 봇 재시작
"device code not recognized"	로그인 코드 만료	`1) 처음 설정` 다시 실행
`localhost:...` Failed to fetch	서버/게이트웨이 꺼짐	봇을 켜세요
`hermes` 명령 없음	새 창 아님 / 미설치	창 닫고 RUN 다시 / INSTALL 먼저
설치가 자꾸 깨짐	제거류 실행 또는 백신	9번
`y` 안 먹히고 `ㅛ`	한/영 상태	한/영 키 누르고 다시

막히면 RUN → 5 → 4) Health check(hermes doctor) 로 스스로 점검.

9. 안전 & 꼭 지킬 것

설치 후 절대 실행 금지 ❌: UNINSTALL.bat · Hermes-Setup.exe(데스크톱) · hermes uninstall → 프로그램이 지워집니다.
백신이 파일을 지우는 경우 대비 — Windows 보안 → 바이러스·위협 방지 → 설정 관리 → 제외 → 폴더 추가: %LOCALAPPDATA%\hermes.
토큰·비밀번호는 비밀. 캡처/공유 금지. API 키는 로컬 .env에 평문 저장되니 PC를 남과 공유하지 마세요.
Hermes는 실제로 PC에서 작업합니다. 위험한 명령("전부 삭제해" 등)은 시키지 말고, 처음엔 간단한 것부터.

10. 제거 — UNINSTALL.bat

UNINSTALL.bat 더블클릭 → 지워질 항목 미리보기 → yes 입력(대소문자 무관) → 폴더·런처·환경변수·PATH 정리(PATH는 백업 저장). 마지막에 "대화·키 데이터도 지울까요?" 를 따로 물어봅니다(기본 보존).

Windows 전용 공식 제거 절차가 없어 최선의 추정(best-effort). 설치 직후엔 누르지 마세요(9번).

11. 파일 설명 / 저장 위치

파일	하는 일
`INSTALL.bat`	공식 설치 자동 실행 + (선택) 데스크톱 앱 다운로드
`RUN.bat`	2단 메뉴 런처(영어+한글) — 실행·로그인·메신저·버전·업데이트·진단
`UNINSTALL.bat`	미리보기 + `yes` 확인 후 제거(데이터 따로 물음)
`왕초보_시작_가이드.md`	마우스·키보드·AI·메신저까지 가장 기초
`메신저_연결_가이드.md`	텔레그램~21종+ 메신저 연결 전부
`자가테스트.bat`	(개발·검증용) 안전장치 점검만 — 설치 안 함, 왕초보는 안 눌러도 됨

3개 .bat은 "단일 파일 자기완결" — 이름 변경·다른 폴더(USB) 이동에도 작동.
저장 위치: 프로그램·데이터·키가 보통 %LOCALAPPDATA%\hermes 한 폴더에 들어갑니다(설치 버전에 따라 다를 수 있음).

12. 안전·설치 분석 (6항목)

항목	내용
신뢰도	Nous Research 공식, MIT 라이선스, 활발한 개발
유형	Python 자율 AI 에이전트(CLI+데스크톱), 자체 런타임 격리 설치
Win11 호환	네이티브 지원, 관리자 권한 불필요
보안	`iex (irm ...)` 원격 실행(공식 도메인) · API 키 평문 `.env` · 데스크톱 `.exe`는 SmartScreen 경고 가능
충돌	자체 Python/Node/Git 번들로 시스템 충돌 낮음, PATH·환경변수만 추가
최종 판정	공식 방식 자동화라 추가 위험 없음 — 위 "보안"만 인지하면 안전

13. 한계 & 참고

이 키트는 작성자 환경(Windows 11 · Hermes v0.16.0)에서 설치 → 메신저 연결 → 봇 답장 끝단까지 실제 확인했습니다. 단 Hermes 버전·환경에 따라 다를 수 있습니다.
Hermes는 나온 지 얼마 안 된 도구라 설치가 불안정할 수 있습니다. 자꾸 깨지면 9번을 지키고 한 번 깨끗이 설치하세요.

참고 링크 — 공식: https://hermes-agent.nousresearch.com/ · 설치 문서: https://hermes-agent.nousresearch.com/docs/getting-started/installation · GitHub(원본): https://github.com/NousResearch/hermes-agent

14. 라이선스

상위 Hermes Agent(이 키트가 설치하는 대상): Nous Research의 MIT 라이선스(별개). 본 키트는 공식 설치를 자동화하는 래퍼일 뿐, Hermes 자체를 재배포하지 않습니다.

Hermes-Agent_One-Click_Kit