Hermes Agent란? Gemini AI 연동 설치 방법 완전 정복 (2026년 최신)

이 글에서 다루는 것
요즘 AI 에이전트 커뮤니티에서 자주 보이는 Hermes Agent가 뭔지, 그리고 영상에서 주로 다루는 Claude 대신 Gemini AI와 연동하는 방법까지 설치부터 첫 실행까지 정리했습니다.

솔직히 처음엔 "OpenClaw랑 뭐가 달라?" 싶었어요. 그냥 비슷한 AI 에이전트 도구 하나 더 생긴 거 아닌가 하고 대충 넘겼는데, 직접 써보니 좀 달랐습니다. 특히 스스로 스킬을 만들고 기억하는 구조가 생각보다 실용적이더라고요.

게다가 저는 Claude API보다 Gemini를 쓰고 싶었는데, 의외로 연동 방법이 명확하게 정리된 한국어 자료가 없어서 직접 삽질하면서 정리했습니다. 이 글이 저처럼 Gemini 연동을 원하는 분들한테 도움이 됐으면 해요.

Hermes Agent, 한마디로 뭔가요?

Nous Research라는 미국 AI 연구소가 만든 오픈소스 자기학습 AI 에이전트입니다. MIT 라이선스라 무료로 쓸 수 있고, GitHub 스타가 2026년 4월 기준 10만 개를 넘겼어요. 오픈소스 AI 에이전트 중에선 굉장히 빠르게 성장한 프로젝트입니다.

핵심은 딱 하나예요. "쓸수록 똑똑해진다"는 거. 그냥 답변 생성하는 챗봇이 아니라, 본인이 한 작업을 스스로 분석해서 '스킬'로 저장하고, 다음번에 비슷한 작업이 오면 그 스킬을 꺼내 씁니다. 마치 처음 들어온 신입사원이 시간이 지나면서 회사 업무를 통달하는 것처럼요.

💡 Claude Code와 비교하면?
Claude Code가 "Claude 모델에 묶인 코딩 전용 CLI"라면, Hermes Agent는 "어떤 모델이든 붙일 수 있는 범용 자율 에이전트"입니다. Gemini, Claude, GPT, 로컬 모델까지 원하는 걸 선택해서 쓸 수 있어요.

먼저 '하네스(Harness)' 개념을 알아야 해요

Hermes를 이해하는 열쇠가 바로 하네스(Harness)라는 개념입니다. 영단어 원래 뜻은 말에 씌우는 '마구(馬具)'인데, AI 세계에서는 "LLM 모델을 실제로 일하는 에이전트로 만들어주는 전체 구조"를 뜻합니다.

비유하자면 이렇습니다. 아무리 똑똑한 사람(LLM 모델)도 업무 시스템, 규칙, 툴, 메모리가 없으면 제대로 일 못 합니다. 하네스는 그 모든 걸 모델에게 입혀주는 껍데기이자 인프라예요.

레이어	역할	Hermes에서의 예시
인스트럭션	에이전트 행동 방식 정의	SOUL.md, AGENTS.md
제약	위험 행동 방지, 권한 경계	보안 5계층 모델
피드백	결과 평가 → 다음 작업 개선	스킬 자동 생성·업데이트
메모리	장기 기억, 사용자 컨텍스트	MEMORY.md + SQLite DB
오케스트레이션	여러 에이전트·도구 간 협업	멀티 에이전트 팀 구성

이 구조 덕분에 모델을 교체해도 에이전트는 그대로 성장합니다. Gemini 쓰다가 Claude로 바꿔도 스킬과 메모리는 전혀 영향 없어요. 이게 하네스 설계의 진짜 강점이에요.

Hermes의 핵심 기능 4가지

① 자동 스킬 생성 (Self-Improving)

개인적으로 가장 마음에 든 기능입니다. 에이전트가 복잡한 작업(대략 도구 5번 이상 사용)을 마치면 스스로 묻습니다. "이 작업 방식을 스킬로 저장할까?" 저장하면 ~/.hermes/skills/에 마크다운 파일로 남아요. 다음번 유사 작업 때 처음부터 방법 찾지 않고 바로 꺼내씁니다.

# 설치된 스킬 목록 보기
hermes skills

# 커뮤니티 스킬 설치 예시
hermes skills install github-notifications
hermes skills install daily-briefing

② 세션을 넘나드는 영구 메모리

대화를 끊고 다시 켜도 이전 맥락을 기억합니다. MEMORY.md 파일과 SQLite DB를 함께 쓰는데, FTS5 전체 텍스트 검색이 지원돼서 오래된 대화도 키워드로 빠르게 찾을 수 있어요. OpenClaw가 단순 md 파일 기록이었다면, Hermes는 진짜 DB 기반이라 훨씬 유연합니다.

hermes memory
hermes memory search "docker"

③ 멀티플랫폼 메시징 게이트웨이

터미널만 되는 게 아닙니다. 서버에 설치해두고 스마트폰 Telegram으로 제어하는 게 가능해요. 지원 플랫폼은 Telegram, Slack, Discord, Microsoft Teams, iMessage(v0.9.0부터)까지입니다. 긴 작업 돌려놓고 Telegram으로 진행 상황 확인하면서 추가 지시 내릴 수 있어서 VPS 활용에 특히 좋습니다.

④ 크론 스케줄러

반복 작업을 자동화합니다. 한 줄만 등록해두면 됩니다.

# 매일 오전 9시 뉴스 요약 → Telegram 전송
hermes cron add "0 9 * * *" "오늘의 주요 뉴스를 요약해서 Telegram으로 보내줘"

hermes cron list

OpenClaw 쓰던 분들을 위한 비교표

저도 OpenClaw 먼저 써봤는데, 툴 호출이 잦아지면 끊기는 게 좀 있었어요. Hermes는 비동기 처리 덕분에 그런 현상이 없고 안정적이더라고요. 아래 표로 정리했습니다.

항목	OpenClaw	Hermes Agent
메모리 방식	md 파일 기록	전용 DB + SQLite
스킬 시스템	수동 관리	자동 생성·개선
툴 호출 안정성	잦으면 불안정	비동기 처리로 안정적
멀티플랫폼	제한적	Telegram·Slack·Discord 등
OpenClaw 마이그레이션	—	자동 감지·마이그레이션

⚠️ OpenClaw 사용 중이라면 — Hermes 설치 마법사가 ~/.openclaw 폴더를 자동 감지해서 설정·메모리·API 키를 마이그레이션할지 물어봐요. 먼저 --dry-run 옵션으로 미리보기 하고 진행하길 추천합니다.

STEP 1. 설치하기 (macOS / Linux / WSL2)

OS	지원 상태	비고
macOS	✅ 완전 지원
Linux (Ubuntu 등)	✅ 완전 지원
Windows (WSL2)	✅ 권장	Windows는 이 방법이 가장 안정적
Windows (네이티브)	⚠️ 얼리 베타	안정성 미보장, 비권장
Android (Termux)	✅ 지원	Linux와 동일 설치 명령어

설치 스크립트 한 줄이 전부입니다. Python 3.11, Node.js, uv, ripgrep, ffmpeg 등 의존성을 전부 자동으로 처리해줘서 따로 뭔가 설치할 필요가 없어요. 보통 5분 안에 끝납니다.

# macOS / Linux / WSL2 — 이 한 줄이면 됩니다
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

설치가 끝나면 셸을 재로드해줍니다.

# bash 사용자
source ~/.bashrc

# zsh 사용자 (macOS 기본값)
source ~/.zshrc

설치 후에는 무조건 아래 명령어 한 번 돌려보세요. 뭔가 빠진 게 있으면 해결 방법까지 알려줍니다.

hermes doctor

STEP 2. Gemini API 키 발급받기

영상에서는 기본 설정으로 진행하지만, 저는 Google Gemini AI와 연동하는 방식으로 합니다. 먼저 API 키가 필요해요.

1. Google AI Studio에 접속합니다
2. 구글 계정으로 로그인
3. 좌측 메뉴에서 "Get API key" 클릭
4. "Create API key" 버튼 클릭
5. 생성된 키를 복사해서 안전한 곳에 저장

🚨 주의 — API 키는 생성 시 딱 한 번만 표시됩니다. 꼭 복사해두세요. 잃어버리면 새로 발급해야 합니다.

STEP 3. Gemini 연동 설정 (2가지 방법)

설치 완료 후 설정 마법사가 자동 실행됩니다. 나중에 다시 실행하고 싶으면 hermes setup을 입력하면 돼요.

방법 A. Google AI Studio 직접 연동

가장 단순한 방법입니다. Gemini가 OpenAI 호환 엔드포인트를 제공하기 때문에 Custom endpoint로 바로 연결됩니다.

Base URL	https://generativelanguage.googleapis.com/v1beta/openai
API Key	Google AI Studio에서 발급받은 키
Model	gemini-2.5-pro (또는 아래 모델 참고)

방법 B. OpenRouter를 통한 연동 (더 안정적, 추천)

개인적으로 이쪽을 더 추천합니다. Hermes의 tool-calling 포맷과 Gemini의 function-calling API 사이에서 OpenRouter가 중간 변환을 처리해줘서 오류가 훨씬 적어요. 특히 복잡한 작업할 때 차이가 납니다.

1. OpenRouter 가입 후 API 키 발급
2. 설정 마법사에서 openrouter 선택
3. API 키 입력
4. 모델 입력: google/gemini-2.5-pro

💡 OpenRouter의 또 다른 장점 — 하나의 API 키로 Gemini 외에도 Claude, GPT, DeepSeek 등 200개 이상의 모델을 전환해서 쓸 수 있습니다. 나중에 다른 모델 테스트해보고 싶을 때 편해요.

어떤 Gemini 모델을 고를까?

모델	컨텍스트	입력 단가	출력 단가	추천 상황
Gemini 2.5 Pro	1M 토큰	$1.25/1M	$10/1M	복잡한 추론, 긴 에이전트 세션
Gemini 2.5 Flash	1M 토큰	$0.30/1M	$2.50/1M	일상 자동화, 가성비 중시
Gemini 3 Flash Preview	1M 토큰	$0.50/1M	$3/1M	에이전트 추론 최신 모델 체험

⚠️ Thinking 토큰 주의 — Gemini 2.5 Pro는 Thinking 모드 활성화 시 thinking 토큰이 별도로 과금됩니다 ($3.50/1M). 추론이 많은 작업에서는 실제 비용이 기본 단가의 2~3배가 될 수 있으니 처음엔 Flash로 테스트하고 필요할 때 Pro로 올리는 걸 추천해요.

나중에 모델 변경하기

모델을 바꾸고 싶으면 언제든 아래 명령어 하나면 됩니다. 대화 세션이 끊기지 않아요.

hermes model

STEP 4. 실행 및 첫 대화

설정이 끝났으면 이제 실행해봅니다.

hermes

실행하면 연결된 AI 모델, 사용 가능한 도구, 스킬 목록이 표시되고 입력창이 열립니다. 첫 몇 번의 작업을 하고 나면 Hermes가 스스로 스킬을 생성하기 시작하는데, 그 알림이 뜨면 정상입니다.

> 오늘 AI 관련 뉴스 요약해줘
> 이 Python 스크립트 버그 찾아서 수정해줘
> 매일 아침 8시에 GitHub 알림을 Telegram으로 보내는 작업 만들어줘

자주 쓰는 명령어 모음

명령어	설명
hermes	에이전트 시작 (대화 모드)
hermes setup	설정 마법사 재실행
hermes model	AI 모델·프로바이더 변경
hermes doctor	환경 점검 및 문제 진단
hermes dump	설정 요약 출력 (API 키 자동 마스킹)
hermes skills	스킬 목록 조회
hermes memory	현재 메모리 보기
hermes memory search "키워드"	메모리 내 검색
hermes cron add "크론식" "작업"	반복 작업 등록
hermes setup gateway	Telegram 등 메시징 연동

알아두면 좋은 것들 (주의·팁)

💡 처음엔 Flash로 시작하세요 — Gemini 2.5 Flash는 무료 티어도 있고 Flash 속도에 1M 컨텍스트라 일상적인 작업엔 충분합니다. 가격 감각을 익히고 나서 Pro로 올려도 늦지 않아요.

⚠️ 직접 연동 시 tool-calling 오류가 잦다면 — Google AI Studio 직접 연동보다 OpenRouter 경유가 더 안정적입니다. 특히 복잡한 멀티스텝 작업에서 직접 연동은 간혹 함수 호출 포맷 오류나 스트리밍 토큰이 끊기는 현상이 있어요.

⚠️ 파일 시스템 권한 — Hermes는 파일을 만들고 폴더를 정리하고 터미널 명령까지 실행할 수 있습니다. 처음 쓸 때는 테스트용 디렉토리에서 연습하는 게 낫습니다. 권한을 너무 넓게 주면 원치 않는 파일이 수정될 수 있어요.

💡 VPS에 설치하면 더 좋습니다 — 월 $5짜리 저렴한 VPS에서도 잘 돌아가요. PC를 꺼두어도 에이전트가 계속 작동하고, Telegram으로 어디서나 원격 제어가 가능합니다.

마무리

Hermes Agent, 생각보다 꽤 쓸 만합니다. 처음엔 OpenClaw랑 비슷하겠지 했는데 메모리 구조나 스킬 자동화 쪽에서 차이가 느껴졌어요. Gemini 연동도 OpenRouter 경유로 가니까 큰 문제 없이 잘 작동하고 있고요.

아직 네이티브 Google 프로바이더는 개발 중이라, 나중에 정식 지원되면 더 안정적해질 것 같아요. 지금 당장 써보고 싶다면 일단 Gemini 2.5 Flash로 시작해보는 걸 추천합니다.