Hermes Agent 윈도우 설치 방법, Claude 구독 연결부터 텔레그램 봇까지

Hermes Agent↗는 Nous Research가 만든 오픈소스 AI 에이전트로, 명령줄과 텔레그램·디스코드 같은 메신저, 데스크톱 앱까지 하나의 설정으로 묶어 씁니다. 이 가이드는 윈도우 11에서 설치 스크립트를 실행해 Claude 구독 로그인으로 모델을 연결하고, 텔레그램 봇을 붙이고, 마지막으로 GUI인 Hermes Desktop까지 켜는 순서를 직접 확인한 기록입니다. 기준 버전은 2026년 9월 13일에 설치한 v0.21.2(메인 브랜치 커밋 e16f6867)인데, 개발 속도가 빨라 설치 당일에도 업스트림 브랜치보다 최대 163개 커밋이 뒤처져 있었으니 화면 문구는 언제든 바뀔 수 있는 상태.

시작하기 전에 필요한 것

• 윈도우 11과 PowerShell. 관리자 권한은 공식 문서에 필수 조건으로 나오지 않습니다.
• Claude 구독(공식 문서 기준 Max 플랜). 프로(Pro) 구독자는 이 로그인 경로를 쓸 수 없고, API 키로 종량제 결제하는 경로만 열려 있습니다.
• 텔레그램 계정과, 새로 만들 봇. 기존에 다른 용도로 쓰는 봇 토큰을 재사용하면 안 됩니다.
• 인터넷 연결. 설치 스크립트가 uv·Python 3.11·Node.js·ripgrep·ffmpeg를 그 자리에서 받습니다.

1. 설치 스크립트 실행하기

PowerShell에서 아래 한 줄을 실행합니다.

스크립트가 자동으로 하는 일은 이렇습니다. uv를 내려받고, 시스템에 있는 Git을 그대로 쓰고(없으면 45MB짜리 이동식 MinGit을 따로 받습니다), Python 3.11을 uv로 설치합니다. 이번 설치에서는 시스템 Node.js가 v24.10.0이라 "unsupported (Hermes requires Node 22.22+, 24.11+, or 26+)" 경고가 뜨면서 Hermes Agent 전용 Node 22 LTS가 별도 폴더에 새로 설치됐는데, 시스템 Node는 건드리지 않았습니다.

진행 중에 빨간 글자로 error: The lockfile at uv.lock needs to be updated, but --locked was provided.가 나올 수 있는데, 설치가 멈추는 신호는 아닙니다. 해시로 고정된 설치 대신 PyPI 쪽 해석으로 넘어가 그대로 진행되고, 잠시 뒤 "Main package installed"와 "All dependencies installed"가 뜬 뒤 스킬 번들이 동기화되면 설정 마법사가 곧바로 이어집니다.

2. 설정 마법사에서 Full setup 고르기

설치가 끝나면 "How would you like to set up Hermes?" 질문이 뜨고 선택지 3개가 나옵니다.

1. Quick Setup (Nous Portal) — API 키 없이 Nous Portal 계정으로 바로 씁니다. 기본값이자 추천 표시.
2. Full setup — 제공자·도구·옵션을 전부 직접 고릅니다.
3. Blank Slate — 최소 기능만 남기고 나머지는 하나씩 켭니다.

Claude로 쓰려면 2번을 골라야 합니다. 1번이 기본값이라 Enter만 누르면 Nous Portal 모델로 연결되니, Claude를 붙일 계획이면 반드시 숫자를 입력합니다.

3. Claude 계정 연결하기

Full setup을 고르면 제공자 목록이 뜨는데, 총 42개 중 기본값은 15번 Hugging Face Inference Providers입니다. Claude는 7번 Anthropic (Claude models via API key or Claude Code)이니, Enter로 넘기지 말고 7을 직접 입력해야 합니다.

7을 입력하면 같은 PC에 로그인해 둔 Claude Code 자격 증명을 자동으로 인식해 "Claude Code credentials: ✓ (auto-detected)"라고 뜨고, 이어서 "Anthropic credentials:" 화면에서 세 가지를 고르게 됩니다 — 1. 기존 자격 증명 사용(기본값), 2. Reauthenticate(새 OAuth 로그인), 3. 취소. 여기서는 2번을 권합니다. 처음에는 2번이 Claude Code 로그인과 완전히 분리된다고 안내했는데, 실제 화면은 "Hermes will use Claude's credential store directly"라고 뜨면서 결과적으로 같은 저장소를 함께 씁니다 — 그래도 2번을 거쳐야 새 OAuth 인가가 따로 발급됩니다.

2를 선택하면 Hermes Agent가 직접 OAuth를 만드는 게 아니라 Claude Code의 공식 명령 claude setup-token을 그대로 호출합니다. 브라우저가 열리고 Claude 공식 로그인 화면에서 "Claude Code님이 귀하의 Claude chat account에 연결을 요청했습니다 / 귀하의 계정은 다음 용도로 사용됩니다: Claude 구독 사용량에 기여 · 개인정보 보호 설정이 코딩 세션에 적용됩니다"라는 동의 화면이 뜨는데, 여기서 승인하면 끝입니다.

로그인이 끝나면 기본 모델 목록이 뜨는데, 여러 Claude 모델 중 하나를 고르면 됩니다. 이번 설치에서는 1번 claude-fable-5.1을 골랐습니다 — claude.ai 사용량 화면에 Fable 전용 주간 칸이 따로 있어서 다른 대화와 섞이지 않을 것으로 기대했는데, 실제로는 이 칸이 끝까지 0%로 남았습니다. 어떤 모델을 고르든 세션·주간 한도는 같은 계정에서 함께 차감된다고 보는 편이 안전합니다.

4. 터미널 백엔드는 로컬로 두기

"Terminal Backend" 화면에서 로컬(1번, 기본값)·Docker·Modal·SSH·Daytona·Vercel 샌드박스 중 고릅니다. 별도 설치가 필요 없는 로컬이 가장 쉬운 경로인데, 공식 문서는 로컬을 고르면 에이전트가 사용자 계정의 파일 시스템 전체에 접근한다고 경고합니다. Docker를 쓰면 컨테이너가 곧 경계가 되어 위험 명령 승인 절차 자체가 필요 없어진다고 안내하지만, Docker Desktop이 따로 필요합니다. 이 가이드는 로컬 백엔드를 기준으로 하고, 대신 8번 단계에서 승인 모드를 수동으로 바꿉니다.

5. 텔레그램 봇 연결하기

"Messaging Platforms" 화면에서 27개 플랫폼 중 24번 텔레그램을 고릅니다. 화면 안내는 스페이스바로 토글하라고 나오지만, 실제로는 번호를 입력해야 켜집니다.

텔레그램 봇을 만드는 방법을 고르는 화면이 이어지는데, 선택지는 두 가지입니다.

1. Automatic (recommended) — QR 코드를 스캔하면 끝. 토큰을 복사할 필요가 없습니다. 기본값.
2. Manual — 직접 봇파더(@BotFather)에서 봇을 만들고 토큰을 붙여넣습니다.

화면은 1번을 추천하지만, 이 가이드는 2번을 권합니다. 자동 방식의 토큰은 Nous Research가 운영하는 관리 봇을 거쳐 발급되는 구조이고, 텔레그램 공식 Bot API 문서(관리 봇 항목)는 관리 봇이 자식 봇의 토큰을 나중에도 다시 받아 올 수 있다고 명시합니다. 실제로 그렇게 토큰을 가져간 사례가 확인된 것은 아니지만, 직접 만든 토큰이라면 이 경로 자체가 없습니다.

2번(Manual)을 고르면 실제 절차는 이렇습니다.

• 텔레그램에서 @BotFather에게 /newbot을 보냅니다.
• 표시 이름을 정하고, bot으로 끝나는 사용자 이름을 정합니다.
• 봇파더가 주는 토큰을 그대로 복사합니다. 형태는 숫자:영문 전체이고, 앞의 숫자(봇 ID)도 토큰의 일부이니 숫자만 빼고 붙여넣으면 안 됩니다.
• Hermes Agent 화면에 붙여넣으면 입력값이 별표로 가려집니다.

토큰을 저장하면 "Allowed user IDs (comma-separated, leave empty for open access)"라는 질문이 나옵니다. 비워 두면 안 됩니다. 화면 문구는 비우면 개방된다고 읽히는데, 실제 소스 코드(gateway/run_startup.py)는 허용 목록이 없으면 알 수 없는 발신자를 기본적으로 거부하고 페어링 코드를 요구하도록 짜여 있습니다. 화면 문구가 실제보다 위험하게 들리는 셈이지만, 그래도 텔레그램의 @userinfobot에게 자기 숫자 ID를 물어본 뒤 그대로 입력하는 편이 안전합니다. 이어지는 홈 채널 질문에는 기본값(자기 ID 사용)을 그대로 따르면 됩니다.

설정을 마치면 게이트웨이를 백그라운드 서비스로 설치할지 물어봅니다. 예(기본값)를 고르면 윈도우 로그인 시 자동 실행할지도 물어보는데, 이것도 예를 고르면 작업 스케줄러에 Hermes_Gateway라는 작업이 등록되고 게이트웨이 프로세스가 곧바로 뜹니다. 창을 닫거나 재부팅해도 로그인만 하면 봇이 계속 살아 있습니다. 이번 설치는 관리자 권한 PowerShell 창에서 진행했는데, 일반 권한 창에서도 서비스 등록이 똑같이 되는지는 확인하지 못했습니다.

6. 도구 목록에서 확인할 세 곳

CLI·텔레그램용 도구 체크리스트가 이어집니다. 대부분 기본값 그대로 둬도 되지만 세 화면은 직접 확인해야 합니다.

• 브라우저 제공자 — 목록 기본값이 5번 Browser Use(클라우드 연동)인데, 별도 설치 없이 쓸 수 있는 것은 1번 Local Browser입니다. 소스 코드 주석은 "신규 설치의 Enter는 무료 로컬 백엔드로 가야 한다"고 적어 두고 있지만, 실제 화면 기본값은 그렇지 않습니다.
• 웹 검색 제공자 — 목록 기본값이 1번 Nous Subscription(구독)입니다. 건너뛰어도(16번 Skip) 문제가 없습니다 — 설정 요약표에는 웹 검색이 ✗로 뜨지만, 9번 단계의 hermes doctor 점검에서는 키 없이 동작하는 무료 순환(Exa·Parallel·Firecrawl·Keenable 등)이 ✓로 확인됩니다.
• xAI(X 검색) — 건너뛰면(3번 Skip) 곧바로 초록색 "✓ no configuration needed!"가 뜨는데, 설정이 끝났다는 뜻이 아니라 인증하지 않았다는 뜻입니다. X 검색을 쓰려면 나중에 hermes auth add xai-oauth로 따로 연결해야 합니다.

컴퓨터 사용(백그라운드 데스크톱 조작) 도구는 기본으로 켜져 있는데, 커서나 키보드 포커스를 가져가지 않고 승인 모드가 off(YOLO)만 아니면 위험한 조작 앞에서 멈춰 서므로 굳이 끌 필요는 없습니다. 이미지 생성은 무료 선택지가 없으니 쓸 계획이 없으면 꺼 두는 편이 낫습니다.

문제가 생기는 경우 — Enter 함정 네 곳

설치 마법사를 진행하다 보면 기본값이 추천 항목이 아닌 화면이 네 번 나옵니다 — 제공자 목록(15번 Hugging Face), 브라우저 제공자(5번 Browser Use), 웹 검색 제공자(1번 Nous Subscription), 그리고 아래 7번 단계의 설치 스크립트 마지막 게이트웨이 질문(기본값 Y)입니다. 네 곳 모두 Enter만 누르면 원치 않는 선택으로 넘어가니, 화면이 뜨면 항상 번호를 확인하고 입력하는 편이 안전합니다.

7. 설치 스크립트 마지막 질문은 n

도구 설정이 끝나면 "Tool Availability Summary"가 뜨고 설치 자체는 끝나는데, 설치 스크립트가 마지막으로 한 번 더 "Would you like to start the gateway now? [Y/n]"을 물어봅니다. 5번 단계에서 이미 게이트웨이를 서비스로 띄웠으니, 여기서 기본값(Y)을 그대로 누르면 같은 토큰으로 게이트웨이가 하나 더 뜹니다. 여기서는 n을 입력합니다.

설치가 끝나면 "Restart your terminal for PATH changes to take effect"라는 안내가 뜹니다. 새 PowerShell 창을 열어야 hermes 명령이 인식됩니다.

8. 승인 모드를 수동으로 바꾸고 첫 대화 확인하기

새 창에서 hermes를 실행하면 배너에 버전과 사용 가능한 도구·스킬 수가 뜹니다. 이번 설치에서는 "Hermes Agent v0.21.2 (2026.9.11) · upstream e16f6867" 배너와 함께 "⚠67 commits behind — run hermes update to update"가 표시됐습니다.

대화창에 /approvals manual을 입력하면 "Approval mode: manual (persistent profile setting)"이 뜨고 즉시 적용됩니다. 4번 단계에서 로컬 백엔드를 골랐다면 이 명령은 꼭 실행합니다. 이제 아무 질문이나 입력해 첫 대화를 확인하면 됩니다 — 이번 설치에서는 웹 검색을 시켜 봤는데, 도구 설정 요약표에는 ✗로 남아 있었는데도 실제로는 검색 결과와 출처 링크를 받아 왔습니다.

9. hermes doctor로 설치 점검하기

PowerShell에서 hermes doctor를 실행하면 보안·파이썬 환경·설정 파일·외부 도구·도구별 사용 가능 여부를 한 번에 점검합니다. 이번 점검에서는 웹 검색이 도구 요약표의 ✗와 다르게 doctor에서는 "✓ web search (firecrawl)"로 뜨는 것을 직접 확인했습니다 — 요약표는 키가 있는지만 보고, doctor는 실제 동작 여부를 봅니다. 둘이 다르게 말하면 doctor 쪽을 믿는 편이 낫습니다.

이번 점검에서는 npm 취약점 경고(브라우저 도구 2건, 웹 워크스페이스 6건)도 함께 나왔습니다. hermes doctor --fix는 이 취약점을 고치지 않고, 워크스페이스 쪽은 잠금 파일이 hermes update로 갱신될 때만 해소됩니다. npm audit fix --force는 실행하지 않습니다 — 메이저 버전을 강제로 올려 설치를 깨뜨릴 수 있습니다.

10. 텔레그램으로 양방향 확인하기

대화창에 "텔레그램봇에게 인사하나 보내줘"라고 입력하면 에이전트가 스스로 hermes gateway --help, hermes --help, hermes send --help, hermes send --list telegram 순서로 사용법을 찾아낸 뒤(총 5회, 약 32초) hermes send --to telegram "..."로 홈 채널에 메시지를 보냅니다. 사용자가 명령을 직접 몰라도 되는 셈.

반대 방향도 확인이 필요합니다. 텔레그램 앱에서 이 봇에게 메시지를 보내자 보낸 시각과 같은 분(오후 10시 22분) 안에 원문을 인용한 답장이 도착. 답장까지 오면 명령줄·게이트웨이·텔레그램 세 경로가 전부 이어진 셈.

11. GUI로 쓰기 — hermes desktop

명령줄로 이미 설치했다면 GUI는 hermes desktop 한 줄로 켭니다(반대로 데스크톱 설치 프로그램으로 먼저 설치했다면 명령줄 도구도 같이 들어옵니다). 첫 실행은 로컬에서 Electron 앱을 새로 빌드하므로 4~5분 걸리고, 그 사이 deprecated 패키지 경고가 여러 줄 뜹니다. 빨간 error가 아니라 노란 warn이면 그냥 진행 중이라는 표시.

빌드가 끝나면 CLI·게이트웨이와 같은 설정·세션·스킬을 그대로 쓰는 데스크톱 창이 열립니다. 터미널에서 만든 대화 세션을 데스크톱에서 그대로 열어 보니, 대화 전문과 도구 실행 요약, 세션별로 골랐던 모델("Opus 5 · Med")까지 이어져 있었습니다. 앞서 웹 검색으로 받은 답변의 출처 링크도 클릭할 수 있는 상태로 남아 있었고, 텔레그램으로 메시지를 보낸 결과는 "Ran 2 commands", "Ran 3 commands" 같은 도구 실행 요약으로 표시됐습니다.

화면 오른쪽 아래 승인 모드 표시가 잠깐 "Smart"로 보일 수 있는데, /approvals manual로 이미 저장해 둔 설정이 있다면 몇 초 뒤 "Manual"로 바뀝니다. 동기화되기 전 기본 표시값일 뿐이니, 그 사이 메뉴 항목은 누르지 않는 편이 안전.

알아둘 점 — 구독 사용량

Claude 구독 로그인으로 Hermes Agent를 쓰면 사용량은 어디서 빠질까요. 이번 설치에서 사용 크레딧을 꺼 둔(US$0) 채로 첫 메시지를 보내기 전 세션 사용률은 5%였는데, 첫 메시지를 보낸 뒤 7%로, 이어서 README 요약 작업을 시킨 뒤 10%로 올랐습니다. 같은 계정의 다른 사용분이 조금 섞였을 수 있으니, Hermes Agent만의 정확한 몫은 따로 구분하지 못한 수치입니다. 같은 구간에 주간 사용률은 19%에서 20%로 늘었고, 크레딧은 끝까지 US$0였습니다. Hermes Agent의 /usage 명령이 보여주는 계정 한도도 Claude 사용량 화면과 정확히 일치했습니다.

이 결과는 Hermes Agent 공식 문서의 설명과 다릅니다. 공식 문서는 이 로그인 경로가 Max 플랜이면서 추가 사용량 크레딧을 구매한 경우에만 동작하고, 기본 할당량은 소비되지 않는다고 적어 두고 있습니다. 반면 앤트로픽 자사 도움말은 Claude Agent SDK와 제3자 앱 사용이 여전히 구독의 사용량 한도에서 차감된다고 안내하는데, 이번 실측은 이 안내와 맞아떨어졌습니다. 앤트로픽의 법률 문서(Legal and compliance)는 제3자 개발자가 구독 계정 자격 증명을 대신 써서 요청을 라우팅하는 것을 일반적으로 금지한다고 명시하는데, Hermes Agent를 이름으로 지목한 문장은 아닙니다.

소스 코드를 열어 보면 이 로그인 경로가 요청을 Claude Code의 것처럼 보이게 만드는 방식으로 동작한다는 사실도 확인되는데, 이 부분은 따로 다뤄야 할 만큼 무게가 있어 다음 리뷰 기사에서 자세히 씁니다. 구독 로그인 대신 ANTHROPIC_API_KEY를 쓰면 이런 충돌 없이 종량제 청구로 끝나는 구조.

여기까지 하면

명령줄에서 Claude 구독 로그인으로 대화하고, 텔레그램 봇으로 어디서든 같은 에이전트에게 말을 걸고, 게이트웨이는 로그인할 때마다 자동으로 떠 있고, 필요하면 hermes desktop으로 같은 세션을 화면으로 볼 수 있습니다. 게이트웨이를 끄려면 hermes gateway stop, 아예 지우려면 hermes gateway uninstall을 씁니다.

출처

• Hermes Agent 공식 저장소(GitHub) — https://github.com/NousResearch/hermes-agent, 2026년 9월 13일 확인
• Hermes Agent 공식 문서 — Quickstart — https://hermes-agent.nousresearch.com/docs/getting-started/quickstart, 2026년 9월 13일 확인
• Hermes Agent 공식 문서 — Security — https://hermes-agent.nousresearch.com/docs/user-guide/security, 2026년 9월 13일 확인
• Hermes Agent 공식 문서 — Providers — https://hermes-agent.nousresearch.com/docs/integrations/providers, 2026년 9월 13일 확인
• Hermes Agent 공식 문서 — Messaging Gateway — https://hermes-agent.nousresearch.com/docs/user-guide/messaging, 2026년 9월 13일 확인
• Hermes Agent GitHub 이슈 #10591 — 텔레그램 자동 페어링 설계 문서 — https://github.com/NousResearch/hermes-agent/issues/10591, 2026년 9월 13일 확인
• Telegram Bot API 공식 문서 — Managed bots — https://core.telegram.org/api/bots/managed-bots, 2026년 9월 13일 확인
• 앤트로픽 도움말 센터 — Use the Claude Agent SDK with your Claude plan — https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan, 2026년 9월 13일 확인
• 앤트로픽(Claude Code) 공식 문서 — Legal and compliance — https://code.claude.com/docs/en/legal-and-compliance, 2026년 9월 13일 확인