🇰🇷 한국어 문서입니다. 🇺🇸 English: README.en.md
Nous Research의 Hermes Agent (스스로 스킬을 만들고 기억을 유지하는 오픈소스 자율 AI 에이전트)를, 명령어 입력 없이 .bat 더블클릭만으로 설치·실행·로그인·메신저 연결·제거할 수 있게 해 주는 왕초보용 키트입니다.
🔰 컴퓨터·전자기기·AI·메신저가 처음이세요? → 먼저 왕초보_시작_가이드.md (마우스·키보드·인터넷부터) 📱 메신저(텔레그램 등) 연결만 자세히 → 메신저_연결_가이드.md
- 이게 뭔가요 · 2. 빠른 시작 · 3. 설치 · 4. 실행 & 메뉴 · 5. 로그인 & AI 모델 · 6. 메신저 연결 · 7. 명령어 · 8. 오류 대처 · 9. 안전 · 10. 제거 · 11. 파일/위치 · 12. 설치 분석 · 13. 한계
- Hermes Agent = 내 컴퓨터에 사는 AI 비서. 말로 시키면(요약·번역·검색·파일 정리 등) 알아서 해줍니다. 텔레그램 같은 메신저에 연결하면 휴대폰으로도 시킬 수 있어요.
- 이 키트 = 위 과정을 어려운 명령어 없이 더블클릭 메뉴로 하게 해 줍니다.
- 준비물: Windows 10/11, 인터넷. 관리자 권한 불필요(설치는 전부 사용자 영역).
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번)
- 키트 폴더에서
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로 따로 설치.)
설치 후엔 반드시 새 창이 필요합니다(설치가 "프로그램 위치(PATH)"를 바꾸는데, 이미 열린 창은 그걸 모름. 새 창은 자동 인식). → 그냥 RUN.bat 더블클릭.
맨 위에 현재 버전·로그인 상태가 보이고, 실제 사용 순서대로 메뉴가 나옵니다:
| 메뉴 | 뜻 | 안에서 |
|---|---|---|
| 1) 처음 설정 | 로그인 + AI 모델 (제일 먼저!) | hermes portal |
| 2) 대화하기 | AI와 채팅 | hermes --tui |
| 3) 메신저 연결 | 메신저(텔레그램 등) | 1 Set up a messenger · 2 Turn the bot ON |
| 4) 업데이트 / 버전 | 버전·업데이트 | 1 버전확인 2 업데이트확인 3 업데이트 |
| 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에게 직접 물어, 없는 기능은 "이 버전엔 없음"으로 안전 안내합니다.
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(로그인+모델)을 실행합니다.
텔레그램이 제일 쉬워요. 그림 설명은 메신저_연결_가이드.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종+ 도 됩니다 → 메신저 가이드 참고.
보통은 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 |
| 증상 | 원인 | 해결 |
|---|---|---|
| 봇이 답을 안 함 | 봇(게이트웨이) 꺼짐 | 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) 로 스스로 점검.
- 설치 후 절대 실행 금지 ❌:
UNINSTALL.bat·Hermes-Setup.exe(데스크톱) ·hermes uninstall→ 프로그램이 지워집니다. - 백신이 파일을 지우는 경우 대비 — Windows 보안 → 바이러스·위협 방지 → 설정 관리 → 제외 → 폴더 추가:
%LOCALAPPDATA%\hermes. - 토큰·비밀번호는 비밀. 캡처/공유 금지. API 키는 로컬
.env에 평문 저장되니 PC를 남과 공유하지 마세요. - Hermes는 실제로 PC에서 작업합니다. 위험한 명령("전부 삭제해" 등)은 시키지 말고, 처음엔 간단한 것부터.
UNINSTALL.bat 더블클릭 → 지워질 항목 미리보기 → yes 입력(대소문자 무관) → 폴더·런처·환경변수·PATH 정리(PATH는 백업 저장). 마지막에 "대화·키 데이터도 지울까요?" 를 따로 물어봅니다(기본 보존).
Windows 전용 공식 제거 절차가 없어 최선의 추정(best-effort). 설치 직후엔 누르지 마세요(9번).
| 파일 | 하는 일 |
|---|---|
INSTALL.bat |
공식 설치 자동 실행 + (선택) 데스크톱 앱 다운로드 |
RUN.bat |
2단 메뉴 런처(영어+한글) — 실행·로그인·메신저·버전·업데이트·진단 |
UNINSTALL.bat |
미리보기 + yes 확인 후 제거(데이터 따로 물음) |
왕초보_시작_가이드.md |
마우스·키보드·AI·메신저까지 가장 기초 |
메신저_연결_가이드.md |
텔레그램~21종+ 메신저 연결 전부 |
자가테스트.bat |
(개발·검증용) 안전장치 점검만 — 설치 안 함, 왕초보는 안 눌러도 됨 |
- 3개
.bat은 "단일 파일 자기완결" — 이름 변경·다른 폴더(USB) 이동에도 작동. - 저장 위치: 프로그램·데이터·키가 보통
%LOCALAPPDATA%\hermes한 폴더에 들어갑니다(설치 버전에 따라 다를 수 있음).
| 항목 | 내용 |
|---|---|
| 신뢰도 | Nous Research 공식, MIT 라이선스, 활발한 개발 |
| 유형 | Python 자율 AI 에이전트(CLI+데스크톱), 자체 런타임 격리 설치 |
| Win11 호환 | 네이티브 지원, 관리자 권한 불필요 |
| 보안 | iex (irm ...) 원격 실행(공식 도메인) · API 키 평문 .env · 데스크톱 .exe는 SmartScreen 경고 가능 |
| 충돌 | 자체 Python/Node/Git 번들로 시스템 충돌 낮음, PATH·환경변수만 추가 |
| 최종 판정 | 공식 방식 자동화라 추가 위험 없음 — 위 "보안"만 인지하면 안전 |
- 이 키트는 작성자 환경(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
- 이 키트(
.bat3종 +자가테스트.bat+ 문서): Apache License 2.0 — © 2026 SoDam AI Studio. 전체 본문은LICENSE참고. - 상위 Hermes Agent(이 키트가 설치하는 대상): Nous Research의 MIT 라이선스(별개). 본 키트는 공식 설치를 자동화하는 래퍼일 뿐, Hermes 자체를 재배포하지 않습니다.