헤르메스 에이전트(Hermes Agent)를 처음 설치할 때 가장 중요한 것은 “어디서 막혔는지”를 분리하는 일입니다. 바로 Telegram부터 연결하려고 하면 설치 문제인지, 모델 인증 문제인지, Gateway 설정 문제인지 헷갈리기 쉽습니다.
그래서 이 글은 설치 → 모델 설정 → 로컬 CLI 실행 확인 → Telegram Gateway 연결 순서로 진행합니다. 터미널 명령어가 낯설어도 그대로 따라 할 수 있게, 각 단계에서 무엇을 확인해야 하는지 함께 정리했습니다.
빠른 결론 ― Telegram보다 CLI 첫 대화가 먼저입니다
Hermes Agent 설치는 한 번에 많은 것을 연결할 수 있지만, 초보자일수록 기능을 한 층씩 올리는 편이 안전합니다.
Linux, macOS, WSL2 또는 Termux에서 설치를 먼저 끝내고 hermes 명령어가 잡히는지 확인합니다.
hermes model로 provider와 모델을 설정합니다. Hermes는 최소 64K 컨텍스트 모델을 요구하므로 모델 선택이 중요합니다.
Telegram을 붙이기 전, 터미널에서 Hermes가 정상 답변하는지 먼저 확인합니다.
Telegram 봇, token, 숫자 User ID, allowlist 또는 pairing은 CLI가 정상 작동한 뒤 설정합니다.
Hermes Agent는 무엇인가요?
Hermes Agent는 Nous Research가 만든 개인용 AI 에이전트입니다. 공식 문서에서는 경험에서 skill을 만들고 개선하며, 세션과 기억을 이어 가는 자체 개선형 에이전트로 설명합니다.
핵심은 단순히 터미널에서만 쓰는 도구가 아니라는 점입니다. CLI와 TUI로 대화할 수 있고, Gateway를 통해 Telegram, Discord, Slack, WhatsApp, Signal 같은 여러 메시징 플랫폼에서도 사용할 수 있습니다.
터미널에서 바로 대화하고, 멀티라인 입력·세션 이어가기·도구 실행 상태를 확인할 수 있습니다.
메신저와 Hermes를 이어 주는 백그라운드 프로세스입니다. Telegram 같은 채널은 Gateway를 통해 붙입니다.
대화와 작업 경험을 쌓아 기억과 절차형 skill로 활용하는 구조를 갖고 있습니다.
로컬, Docker, SSH, Modal, Daytona, Vercel Sandbox 등 다양한 터미널 백엔드를 선택할 수 있습니다.
설치 전 준비물
설치 자체는 한 줄 명령어로 시작할 수 있지만, 아래 준비물이 없으면 중간에 멈출 수 있습니다.
Linux, macOS, WSL2를 기준으로 진행합니다. Windows 사용자는 네이티브 Windows가 아니라 WSL2에서 실행하는 흐름을 잡는 것이 좋습니다.
공식 설치 문서 기준 필수 준비물은 Git입니다. Python, Node.js, ripgrep, ffmpeg 등은 설치 스크립트가 처리합니다.
Nous Portal, OpenRouter, OpenAI, Anthropic 등 사용할 provider의 인증이나 API key가 필요합니다.
Telegram 연동까지 진행하려면 개인 Telegram 계정과 BotFather에서 만들 bot token이 필요합니다.
봇은 터미널 접근 권한이 있는 에이전트와 연결될 수 있습니다. 처음부터 공개 봇처럼 열어두지 않는 것이 중요합니다.
1단계 ― Hermes Agent 설치
Linux, macOS, WSL2에서는 공식 설치 스크립트를 실행합니다.
이 명령어는 Hermes Agent 저장소, 가상 환경, 의존성, 전역 hermes 명령어 연결까지 처리합니다. 공식 문서 기준 설치 스크립트가 Python 3.11, Node.js, ripgrep, ffmpeg 같은 주요 의존성도 함께 준비합니다.
설치가 끝나면 현재 터미널에 새 명령어 경로가 반영되도록 shell을 다시 읽습니다.
zsh를 쓰는 macOS 환경이라면 아래 명령어를 사용합니다.
터미널을 완전히 닫았다가 다시 열어도 같은 효과를 얻을 수 있습니다.
2단계 ― hermes 명령어 확인
설치 후에는 바로 복잡한 설정으로 넘어가지 말고, 먼저 명령어가 정상적으로 잡혔는지 확인합니다.
hermes version에서 버전 정보가 나오고, hermes doctor에서 큰 문제가 없다면 설치 자체는 통과한 것입니다. 만약 hermes: command not found가 나오면 shell reload가 안 됐거나 PATH가 반영되지 않은 상태일 수 있습니다.
3단계 ― hermes model로 provider와 모델 설정
Hermes Agent가 답변하려면 사용할 모델 provider를 먼저 연결해야 합니다. 공식 Quickstart에서도 이 단계를 가장 중요한 설정으로 설명합니다.
화면 안내에 따라 Nous Portal, OpenRouter, OpenAI Codex, Anthropic, Hugging Face, DeepSeek, NVIDIA NIM, GitHub Copilot, Custom Endpoint 등 사용할 provider를 선택합니다. 처음 설치라면 하나의 provider만 안정적으로 연결하고, fallback이나 복잡한 라우팅은 나중에 붙이는 편이 좋습니다.
모델 이름, endpoint, context length를 잘 모른다면 wizard가 제안하는 기본값으로 시작하세요.
Hermes는 최소 64,000 tokens 이상의 context window를 요구합니다. 작은 모델은 시작 단계에서 거부될 수 있습니다.
API key와 OAuth token은 공개 채팅, 블로그, 스크린샷, Git 저장소에 남기지 마세요.
Hermes의 설정 파일은 역할이 나뉩니다. API key와 token 같은 secret은 ~/.hermes/.env에, 모델·터미널 backend 같은 일반 설정은 ~/.hermes/config.yaml에 저장됩니다.
4단계 ― 로컬 CLI/TUI에서 첫 대화 확인
Telegram 연결 전에 반드시 로컬 대화를 먼저 확인하세요. 이 단계가 실패하면 Telegram을 붙여도 원인을 찾기 어렵습니다.
새로운 TUI 화면을 먼저 써보고 싶다면 아래 명령어를 사용할 수 있습니다.
실행 후 간단한 질문을 해보세요. 예를 들어 “현재 디렉터리에 어떤 파일이 있는지 요약해 주세요”처럼 결과를 확인하기 쉬운 요청이 좋습니다.
배너에 선택한 모델/provider가 보이고, Hermes가 오류 없이 답변하며, 다음 턴까지 자연스럽게 이어집니다.
답변이 비거나 provider 오류가 난다면 hermes model로 인증과 모델 선택을 다시 확인하세요.
첫 대화가 끝난 뒤 hermes --continue 또는 hermes -c로 이어지는지도 확인하면 좋습니다.
5단계 ― BotFather에서 Telegram 봇 만들기
로컬 CLI 대화가 성공했다면 이제 Telegram 봇을 만듭니다. 모든 Telegram 봇은 공식 BotFather에서 발급한 API token이 필요합니다.
1 BotFather 열기
@BotFather를 검색하거나 https://t.me/BotFather로 들어갑니다.2 새 봇 만들기
/newbot을 입력하고 안내를 따릅니다.3 이름과 username 정하기
bot으로 끝나야 합니다.4 Token 보관
/revoke로 즉시 폐기하세요.6단계 ― hermes gateway setup으로 Telegram 연결
Hermes의 Messaging Gateway는 Telegram, Discord, Slack 같은 플랫폼과 Hermes Agent를 이어 주는 단일 백그라운드 프로세스입니다. Telegram도 이 Gateway를 통해 붙입니다.
wizard에서 Telegram을 선택하고 BotFather token을 입력합니다. Telegram은 username이 아니라 숫자 User ID로 접근 권한을 제어하므로, 내 숫자 ID도 함께 준비해야 합니다.
Telegram에서 @userinfobot 또는 @get_id_bot에게 메시지를 보내 숫자 ID를 확인합니다.
BotFather가 준 token을 입력합니다. 공개 문서에는 실제 token을 절대 남기지 않습니다.
처음에는 본인 숫자 ID만 allowlist에 넣어 개인 봇으로 시작하는 것을 권장합니다.
설정을 마쳤다면 Gateway 상태를 확인하거나 실행합니다.
일반적인 Linux/macOS 서비스 설치 환경이라면 아래처럼 시작할 수 있습니다.
WSL처럼 systemd가 불안정한 환경에서는 foreground 실행을 먼저 확인하는 편이 안전합니다.
7단계 ― allowlist 또는 DM pairing으로 내 계정만 승인하기
Hermes Gateway는 기본적으로 allowlist에 없거나 pairing으로 승인되지 않은 사용자를 거부하는 쪽이 안전한 기본값입니다. 터미널 접근 권한이 있는 에이전트이기 때문에, “누가 말할 수 있는가”를 반드시 제한해야 합니다.
수동으로 설정한다면 ~/.hermes/.env에 아래처럼 둘 수 있습니다.
또는 DM pairing 흐름을 사용할 수 있습니다. 알 수 없는 사용자가 봇에게 DM을 보내면 pairing code가 표시되고, 소유자가 CLI에서 승인합니다.
8단계 ― Telegram 첫 메시지 테스트
이제 Telegram에서 내가 만든 봇에게 짧은 메시지를 보내 봅니다.
정상이라면 Hermes Agent가 Telegram DM으로 답변합니다. 답변이 오지 않으면 아래 순서로 원인을 나누어 확인하세요.
1 CLI는 되는지 확인
hermes에서 로컬 대화가 되는지 다시 확인합니다. 여기서 안 되면 Telegram 문제가 아닙니다.2 Gateway 상태 확인
hermes gateway status로 Gateway가 실행 중인지 봅니다.3 Token과 User ID 확인
4 pairing 상태 확인
hermes pairing list로 pending/approved 상태를 확인합니다.그룹 채팅은 DM 성공 후에 붙이세요
Telegram 그룹은 1:1 DM보다 변수가 많습니다. Telegram Bot Privacy Mode가 기본적으로 켜져 있으면 봇은 일반 그룹 메시지를 모두 읽지 못하고, 명령어·봇에게 단 답장·서비스 메시지처럼 제한된 메시지만 봅니다.
Privacy Mode를 바꾸면 봇을 그룹에서 제거했다가 다시 추가해야 반영되는 점도 헷갈리기 쉽습니다. 처음에는 개인 DM을 먼저 성공시키고, 그 다음 그룹에서 telegram.require_mention: true처럼 멘션 기반으로 작동하는 설정을 검토하세요.
Android/Termux에서 설치할 때의 주의점
Hermes는 Android Termux 설치 흐름도 문서화하고 있습니다. 같은 설치 스크립트가 Termux를 감지해 별도 경로로 진행하지만, 데스크톱/서버와 완전히 같은 경험을 기대하면 안 됩니다.
CLI, cron, PTY/background terminal, Telegram gateway, MCP, Honcho memory, ACP 등 핵심 기능은 테스트된 Termux bundle에 포함됩니다.
.[all], local voice extra, 자동 browser/Playwright bootstrap, Docker isolation은 Termux 테스트 경로에 포함되지 않습니다.
Android가 Termux background job을 중단할 수 있어 Gateway 지속성은 best-effort로 보는 편이 안전합니다.
Termux에서 문제가 생긴다면 공식 문서의 수동 경로처럼 package와 build toolchain을 확인해야 합니다.
OpenClaw에서 넘어오는 경우: dry-run 먼저
OpenClaw를 이미 사용하고 있다면 Hermes의 migration 기능이 도움이 될 수 있습니다. 공식 README 기준으로 SOUL.md, memory, skills, allowlist, messaging settings, 일부 allowlisted secrets 등을 가져올 수 있습니다.
다만 첫 시도에서는 바로 덮어쓰기보다 dry-run으로 무엇이 이동되는지 먼저 확인하세요.
문제가 없고 실제 이전을 진행할 때는 interactive migration을 사용할 수 있습니다.
OpenClaw 설치와 Telegram 연결 흐름을 먼저 보고 싶다면 OpenClaw 설치 절차도 함께 참고할 수 있습니다.
자주 막히는 지점과 recovery toolkit
hermes 명령어를 찾을 수 없음shell reload가 안 됐거나 PATH가 반영되지 않은 상태일 수 있습니다. 터미널을 새로 열거나 source ~/.bashrc / source ~/.zshrc를 실행하세요.
provider 인증, 모델 이름, API key, context window가 맞는지 hermes model로 다시 확인하세요.
Bot token, 숫자 User ID, allowlist 또는 pairing 승인 상태를 확인하세요.
다른 profile을 쓰고 있거나 세션이 저장되지 않았을 수 있습니다. hermes sessions list와 hermes --continue를 확인하세요.
문제가 애매할 때는 아래 순서로 점검하면 원인 분리가 쉽습니다.
보안 체크리스트
Hermes는 강력한 도구를 가진 개인 에이전트입니다. 설치 성공만큼 접근 권한과 실행 권한을 안전하게 잡는 것이 중요합니다.
Telegram bot token, provider API key, OAuth token을 공개 저장소·블로그·캡처에 남기지 않습니다.
Telegram은 숫자 User ID 기준 allowlist 또는 DM pairing으로 본인만 승인합니다.
approval off 또는 yolo mode는 신뢰된 일회성 환경이 아니라면 기본값으로 두지 않습니다.
더 안전한 실행이 필요하면 Docker, SSH, Modal, Daytona 같은 terminal backend 격리를 검토합니다.
회사 문서나 고객정보를 넣기 전에는 문서 등급과 데이터 경로를 먼저 나눕니다.
업무 문서나 민감정보를 다룬다면 회사 문서 AI 입력 판단 기준과 로컬 AI 도구 체크리스트도 함께 확인해 두는 것이 좋습니다.
자주 묻는 질문 (FAQ)
Q1. Windows에서 바로 설치할 수 있나요?
공식 문서 기준 네이티브 Windows는 지원하지 않습니다. Windows 사용자는 WSL2를 설치한 뒤 그 안에서 Linux 흐름으로 진행하는 것을 권장합니다.
Q2. Telegram 봇이 답하지 않으면 무엇부터 확인해야 하나요?
먼저 hermes 로컬 CLI 대화가 되는지 확인하세요. 로컬이 되는데 Telegram만 안 된다면 hermes gateway status, Bot token, 숫자 User ID, allowlist 또는 pairing 상태를 확인하면 됩니다.
Q3. Telegram username을 allowlist에 넣으면 되나요?
아닙니다. Hermes Telegram 설정은 숫자 Telegram User ID를 기준으로 접근을 제어합니다. @userinfobot 또는 @get_id_bot으로 숫자 ID를 확인하세요.
Q4. Android Termux에서도 항상 켜진 Telegram 봇처럼 쓸 수 있나요?
Termux에서도 설치와 Telegram gateway 사용이 가능하지만, Android가 background job을 중단할 수 있습니다. 항상 켜진 봇을 원한다면 VPS나 서버 환경이 더 안정적입니다.
Q5. OpenClaw를 쓰고 있으면 Hermes를 새로 설정해야 하나요?
Hermes에는 OpenClaw migration 기능이 있습니다. 다만 바로 적용하기보다 hermes claw migrate --dry-run으로 가져올 항목을 먼저 확인한 뒤 진행하는 편이 안전합니다.