AI 에이전트라는 말, 요즘 많이 들리죠. 그런데 막상 "설치해볼까" 마음먹으면 터미널 화면이 뜨고, 영어 에러 메시지가 쏟아지고, 결국 탭을 닫고 맙니다. 저도 처음엔 딱 그랬습니다. 헤르메스 에이전트는 그나마 설치 진입 장벽이 낮은 편인데, 그 과정을 한 번도 빠짐없이 정리한 글이 없더라고요. 그래서 직접 썼습니다.
헤르메스(Hermes)는 Nous Research에서 만든 Claude 기반 AI 에이전트 프레임워크입니다. 쉽게 말하면, Claude라는 두뇌에 팔다리를 붙여준 도구입니다. 텔레그램으로 말을 걸면 일정을 확인해주고, cron으로 매일 아침 뉴스 요약을 보내주고, Obsidian 노트를 알아서 정리합니다.
클로드코드(Claude Code)와 비교하면 차이가 분명합니다. 클로드코드는 코딩에 특화된 CLI 도구입니다. 반면 헤르메스는 코딩 외에도 일정 관리, 블로그 자동화, 스마트홈 제어까지 스킬(Skill) 형태로 붙일 수 있습니다. 개발자가 아닌 1인 창업자나 콘텐츠 크리에이터에게 더 맞는 도구라고 생각합니다.
저는 클로드코드를 6개월 쓰다가 헤르메스로 넘어왔는데, 결정적인 이유는 하나였습니다. 텔레그램으로 폰에서 바로 AI에게 지시를 내릴 수 있다는 것. 노트북을 열지 않아도 됩니다.
설치 전에 딱 세 가지만 확인하면 됩니다.
macOS 사용자
- macOS 12 이상 (터미널에서 sw_vers 입력하면 버전 확인 가능)
- Homebrew 설치 여부 — 없으면 https://brew.sh 에서 먼저 설치
- Node.js 18 이상 — node -v 로 확인
Windows 사용자
- WSL2 필수입니다. Windows 10 21H2 이상이면 설치 가능합니다
- PowerShell을 관리자 권한으로 열고 wsl --install 입력
- WSL2 설치 후에는 macOS와 동일한 명령어를 씁니다
저는 macOS 사용자인데, 처음에 Node.js 버전이 16이어서 설치 도중에 막혔습니다. nvm install 20 한 줄로 해결했지만, 미리 알았더라면 10분은 아꼈을 겁니다.
API 키도 미리 준비해두세요. Anthropic Claude API 키가 기본이고, 무료 조합을 쓰고 싶다면 Google AI Studio의 Gemini API 키(무료 티어 존재)를 권장합니다. API 키 발급은 각 서비스 공식 홈페이지에서 이루어집니다.
터미널을 열고 아래 명령어를 복사해서 붙여넣으면 됩니다. 한 줄입니다.
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | sh
설치 스크립트가 알아서 의존 패키지를 내려받고, 헤르메스 디렉토리를 생성하고, PATH 설정까지 마칩니다. 처음 실행 시 약 2~5분 소요됩니다.
설치가 끝나면 터미널을 재시작한 다음 hermes --version 을 입력해서 버전 번호가 뜨는지 확인합니다. 버전 번호가 보이면 설치 성공입니다.
이어서 초기 설정 마법사를 실행합니다.
hermes setup
프롬프트가 순서대로 API 키, 기본 모델, 언어 설정을 물어봅니다. 처음엔 당황했는데, 그냥 엔터 몇 번이면 됩니다. 설정값은 나중에 ~/.hermes/config.yaml 파일을 직접 수정해서 바꿀 수 있습니다.
헤르메스는 여러 LLM을 바꿔가며 쓸 수 있습니다. ~/.hermes/config.yaml 을 텍스트 에디터로 열면 provider와 model 항목이 보입니다.
Claude (Anthropic) 설정 예시
provider: anthropic
model: claude-sonnet-4-5
api_key: sk-ant-XXXXXXXX
Gemini (Google) 설정 예시
provider: google
model: gemini-2.0-flash
api_key: AIzaXXXXXXXX
DeepSeek 설정 예시
provider: openrouter
model: deepseek/deepseek-chat
api_key: sk-or-XXXXXXXX
저는 평소 Claude Sonnet을 기본으로 쓰고, 비용이 부담스러운 배치 자동화 작업에는 Gemini Flash를 연결해 돌립니다. 모델마다 성격이 달라서, 같은 지시를 내려도 결과물이 꽤 다르게 나옵니다. DeepSeek은 코드 작업에서 속도가 빠른 편입니다.
설정 파일을 저장하면 다음 실행부터 바로 반영됩니다. hermes 명령어를 다시 실행할 필요 없이, 저장만 하면 됩니다.
이 부분이 헤르메스의 핵심입니다. 텔레그램과 연결하면 폰에서 AI에게 지시를 내릴 수 있습니다. 외출 중에도 "오늘 일정 요약해줘"라고 보내면 바로 답이 옵니다.
봇 토큰 발급 순서
1. 텔레그램에서 @BotFather 검색 후 채팅 시작
2. /newbot 입력
3. 봇 이름과 사용자 이름(username) 입력 — username은 bot으로 끝나야 합니다
4. BotFather가 토큰을 발급해줍니다. 이걸 복사해 둡니다
토큰을 받았으면 터미널에서 아래 명령어를 실행합니다.
hermes setup telegram
봇 토큰을 붙여넣으라는 프롬프트가 뜨고, 입력하면 연결이 완료됩니다. 이후 헤르메스를 실행(hermes start)하면 텔레그램 봇이 살아납니다.
처음 연결하던 날, 텔레그램 폰에서 "오늘 날씨 어때?"라고 보냈더니 실제로 답이 왔습니다. 솔직히 그때 좀 소름 돋았습니다. 내 서버에서 돌아가는 AI가 폰으로 대답하는 경험이, 생각보다 훨씬 실감납니다.
설치는 했는데 아무것도 안 되는 상황. 경험해보신 분들 많으실 겁니다. 자주 나오는 에러 세 가지와 해결법입니다.
에러 1: command not found: hermes
설치 후 터미널을 재시작하지 않아서 생기는 경우가 90%입니다. 터미널을 완전히 닫고 새로 열거나, source ~/.zshrc (macOS) 또는 source ~/.bashrc (Linux/WSL2)를 실행해 보세요.
에러 2: API key invalid 또는 401 Unauthorized
config.yaml에 API 키를 넣었는데 공백이나 줄바꿈이 끼어들어간 경우입니다. 키를 복사할 때 앞뒤 공백이 함께 복사되는 경우가 많습니다. 키를 다시 복사해서 텍스트 에디터에 한 번 붙여넣고, 공백 확인 후 config.yaml에 옮겨보세요.
에러 3: 텔레그램 봇이 응답 없음
hermes start 명령어를 실행하지 않은 상태에서 봇에 메시지를 보내면 응답이 없습니다. 헤르메스는 백그라운드에서 계속 실행되어야 합니다. hermes start --daemon 옵션을 쓰면 터미널을 닫아도 계속 동작합니다.
저는 처음에 에러 1번에서 30분을 날렸습니다. 터미널을 껐다 켜는 것만으로 해결될 거라고 생각 못 했거든요.
헤르메스의 진짜 재미는 여기서부터입니다. 스킬(Skill)을 추가하면 에이전트의 능력이 확장됩니다. 공식 문서에는 유튜브 요약, 뉴스 브리핑, 캘린더 연동 등 수십 개의 스킬이 등록되어 있습니다.
스킬 추가는 간단합니다. ~/.hermes/skills/ 디렉토리에 마크다운 파일을 넣으면 됩니다. 스킬 파일은 YAML 헤더와 지시 내용으로 구성됩니다. 공식 문서(https://hermes-agent.nousresearch.com/docs)에서 샘플 스킬을 내려받아서 시작하면 됩니다.
cron 자동화는 더 쉽습니다. 헤르메스 TUI(터미널 UI)에서 /cron 명령어를 입력하면 일정 추가 화면이 뜹니다.
예시: 매일 오전 8시에 오늘 일정 요약을 텔레그램으로 보내는 자동화
일정: 0 8 * * *
작업: 오늘 Google Calendar 일정을 텔레그램으로 요약해줘
이걸 등록해 두고 나서, 다음 날 아침에 텔레그램으로 일정 요약이 딱 오는 걸 보고 나서야 "아, 이게 AI 에이전트구나" 실감했습니다. 알람이 아니라 맥락을 이해하고 요약해주는 게 다릅니다.
많이 물어보시는 부분입니다. 헤르메스 자체는 오픈소스라서 무료입니다. 비용은 LLM API 사용에서 발생합니다.
무료 조합
Google AI Studio의 Gemini 2.0 Flash는 무료 티어가 있습니다. 하루 1,500회 요청, 분당 15회 제한이지만 개인 자동화 수준에서는 충분합니다. 헤르메스를 처음 써보는 분이라면 Gemini Free 티어로 시작해서 감을 잡은 다음, Claude API로 넘어가는 방법을 권합니다.
유료지만 가성비 있는 조합
Claude Sonnet은 입력 100만 토큰에 약 3달러 수준입니다. 하루 10번 정도 사용하는 개인 자동화라면 한 달에 1~2달러 수준으로 유지할 수 있습니다. 무거운 작업(긴 문서 요약, 대용량 데이터 처리)은 Gemini Flash로, 판단이 필요한 작업은 Claude Sonnet으로 나눠 쓰는 구성이 제가 현재 쓰는 방식입니다.
OpenRouter를 경유하면 DeepSeek 같은 저비용 모델도 쓸 수 있습니다. 비용 최적화가 목표라면 공식 문서의 provider 설정 항목을 참고하세요.
헤르메스 에이전트는 설치 자체보다 "설치 후 뭘 할지"를 미리 생각하고 접근하면 훨씬 빠르게 자기 것으로 만들 수 있습니다. 텔레그램 연동 하나만 해도 생활이 달라집니다. 공식 문서 주소는 https://hermes-agent.nousresearch.com/docs 입니다.