Hermes Agent 사용법: 설치부터 로컬 vLLM 연결, 스킬·게이트웨이 활용까지
Hermes Agent를 처음 설치하는 사람을 기준으로, 모델 설정, CLI/TUI 실행, 로컬 vLLM 연결, 도구·스킬·메신저 게이트웨이 활용법까지 블로그 글 형태로 정리했습니다.
SEO 최적화 블로그 제목 후보
검색 키워드인 “Hermes Agent”, “사용법”, “설치”, “vLLM”, “AI 에이전트”를 자연스럽게 포함한 제목입니다.
- Hermes Agent 사용법 완벽 가이드: 설치부터 로컬 vLLM 연결까지
- NousResearch Hermes Agent란? AI 에이전트 설치와 활용 방법 총정리
- Hermes Agent 설치 방법: CLI, TUI, 스킬, 메신저 게이트웨이까지 한 번에
- 로컬 LLM과 Hermes Agent 연결하기: vLLM·Ollama·OpenAI 호환 API 설정법
- 개발자를 위한 Hermes Agent 사용법: 도구 실행, 스킬, 자동화 워크플로우
- Hermes Agent로 나만의 AI 에이전트 만들기: 모델 설정부터 실전 사용까지
- AI 코딩 에이전트 Hermes Agent 시작하기: 설치, 설정, 문제 해결 가이드
- Hermes Agent vs 일반 챗봇: 스킬·메모리·도구 실행이 가능한 AI 에이전트
Hermes Agent 사용법 완벽 가이드: 설치부터 로컬 vLLM 연결까지
검색 의도와 클릭률을 동시에 노리기 좋습니다. “사용법”, “설치”, “vLLM” 키워드가 들어가고, 글의 핵심 범위도 명확합니다.
1. Hermes Agent란?
Hermes Agent는 Nous Research가 만든 오픈소스 AI 에이전트입니다. 단순히 터미널에서 LLM과 대화하는 도구가 아니라, 명령 실행, 파일 작업, 웹 검색, 브라우저 자동화, 스킬 관리, 메모리, 메신저 연동, 예약 작업까지 묶어서 사용할 수 있는 에이전트 환경에 가깝습니다.
CLI/TUI 기반 대화, 도구 실행, 스킬, 메모리, 세션 검색, 메신저 게이트웨이를 지원합니다.
OpenRouter, Anthropic, OpenAI Codex, Gemini, Hugging Face, Nous Portal, 로컬 vLLM 등 다양한 provider를 연결할 수 있습니다.
로컬 PC, Docker, SSH 원격 서버, Modal, Daytona, Singularity/Apptainer 같은 백엔드를 선택할 수 있습니다.
코드 분석, PR 작업, 서버 점검, 웹 조사, 반복 작업 자동화, Telegram/Discord/Slack 기반 개인 AI 비서 구성 등에 적합합니다.
2. 설치 전 준비사항
| 항목 | 설명 |
|---|---|
| 운영체제 | Linux, macOS, WSL2, Android Termux를 지원합니다. Windows 네이티브 실행은 권장되지 않고 WSL2를 사용해야 합니다. |
| Python | 설치 스크립트는 기본적으로 Python 3.11 환경을 준비합니다. |
| Node.js | 브라우저 도구 등을 위해 Node.js가 필요할 수 있으며, 설치 스크립트가 확인하거나 설치합니다. |
| LLM Provider | OpenRouter, Anthropic, Gemini, Nous Portal, 로컬 vLLM/Ollama 등 최소 하나의 모델 provider가 필요합니다. |
| 컨텍스트 길이 | Hermes는 agent workflow를 위해 충분히 긴 context window가 필요합니다. 공식 문서에서는 최소 64K 토큰을 요구한다고 안내합니다. |
3. Hermes Agent 설치 방법
가장 빠른 설치 방법은 공식 one-line installer를 실행하는 것입니다.
# Linux / macOS / WSL2 / Android Termux
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash설치가 끝나면 쉘 설정을 다시 로드하고 Hermes를 실행합니다.
source ~/.bashrc
# zsh를 쓰면:
# source ~/.zshrc
hermes개발자용 설치
소스를 직접 수정하거나 기여하려면 저장소를 clone해서 설치할 수 있습니다.
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
./setup-hermes.sh
./hermes공식 README 기준으로 Windows 네이티브 실행은 지원되지 않습니다. Windows에서는 WSL2를 설치한 뒤 WSL2 터미널 안에서 설치 명령을 실행하는 방식이 권장됩니다.
4. 모델 Provider 설정
Hermes는 설치만 했다고 바로 모든 기능이 동작하는 것이 아닙니다.
먼저 hermes model 명령으로 사용할 모델 provider를 설정해야 합니다.
hermes model상황별 추천 설정은 다음과 같습니다.
| 상황 | 추천 Provider |
|---|---|
| 가장 빨리 시작하고 싶음 | Nous Portal 또는 OpenRouter |
| Claude 계정/API를 이미 사용 중 | Anthropic |
| 로컬 GPU 서버 사용 | Custom endpoint + vLLM/SGLang/Ollama |
| 여러 모델을 한 번에 라우팅 | OpenRouter 또는 LiteLLM Proxy |
설정 파일 위치
Hermes 설정은 기본적으로 ~/.hermes/ 아래에 저장됩니다.
~/.hermes/
├── config.yaml # 모델, 터미널, 압축, 도구 등 일반 설정
├── .env # API 키, 토큰, 비밀번호 같은 secret
├── auth.json # OAuth 인증 정보
├── skills/ # 스킬
├── sessions/ # 세션
└── logs/ # 로그공식 문서 기준으로 API 키 같은 secret은 .env, 일반 설정은 config.yaml에 저장하는 구조입니다.
5. 로컬 vLLM 서버 연결 방법
로컬 GPU 서버에서 vLLM을 띄워놓고 Hermes Agent를 붙이고 싶다면,
vLLM이 /v1/chat/completions를 제공하는 OpenAI 호환 API로 실행되어야 합니다.
vLLM 서버 실행 예시
pip install vllm
vllm serve meta-llama/Llama-3.1-70B-Instruct \
--port 8000 \
--max-model-len 65536 \
--tensor-parallel-size 2 \
--enable-auto-tool-choice \
--tool-call-parser hermes그 다음 Hermes에서 custom endpoint를 선택합니다.
hermes model
# 선택:
# Custom endpoint (self-hosted / VLLM / etc.)
# 입력 예시:
# API base URL: http://localhost:8000/v1
# API key: 로컬이면 비워도 됨
# Model name: meta-llama/Llama-3.1-70B-Instruct수동 config.yaml 예시
# ~/.hermes/config.yaml
model:
provider: custom
default: meta-llama/Llama-3.1-70B-Instruct
base_url: http://localhost:8000/v1
api_key: ""
vLLM에서 tool calling을 제대로 쓰려면 --enable-auto-tool-choice와
모델에 맞는 --tool-call-parser가 필요합니다. parser가 맞지 않으면 Hermes가 도구 호출을 실제 tool call로 인식하지 못하고
JSON 텍스트처럼 출력할 수 있습니다.
원격 GPU 서버에 연결하는 경우
Hermes가 로컬 PC에 있고 vLLM이 다른 서버에 있다면 base URL을 서버 IP나 도메인으로 지정합니다.
model:
provider: custom
default: Qwen/Qwen3-Coder-Next-FP8
base_url: http://192.168.0.184:8000/v1
api_key: ""이 경우 방화벽, 포트 개방, reverse proxy, HTTPS, API key 사용 여부를 함께 확인해야 합니다. 외부망에 노출한다면 반드시 인증과 접근 제한을 적용하세요.
6. CLI/TUI 기본 사용법
Hermes는 기본 CLI와 modern TUI를 제공합니다.
# 기본 대화형 실행
hermes
# TUI 실행
hermes --tui
# 단일 질문 모드
hermes chat -q "현재 폴더의 프로젝트 구조를 요약해줘"
# 특정 모델 지정
hermes chat --model "anthropic/claude-sonnet-4"
# 최근 세션 이어서 열기
hermes --continue
hermes -c자주 쓰는 slash command
| 명령어 | 용도 |
|---|---|
/help |
사용 가능한 명령어 확인 |
/model |
현재 세션 안에서 이미 설정된 모델로 전환 |
/tools |
사용 가능한 도구 확인 |
/skills |
스킬 탐색 및 사용 |
/usage |
토큰 사용량 확인 |
/compress |
긴 대화의 context 압축 |
/background <prompt> |
별도 백그라운드 세션에서 작업 실행 |
hermes model은 터미널에서 실행하는 provider 설정 마법사입니다. 반면 /model은 이미 설정된 provider/model 사이를 현재 대화 안에서 바꾸는 명령입니다.
7. 도구와 터미널 백엔드 설정
Hermes의 강점은 LLM 답변만 하는 것이 아니라 실제 작업 도구를 쓸 수 있다는 점입니다. web search, terminal, file editing, browser automation, memory, cron, delegation, MCP 도구 등을 toolset으로 관리합니다.
# 도구 설정 UI 실행
hermes tools
# 특정 toolset으로 실행
hermes chat --toolsets "web,terminal,skills"터미널 백엔드
| Backend | 실행 위치 | 추천 상황 |
|---|---|---|
local |
현재 PC | 개인 개발 환경, 빠른 테스트 |
docker |
Docker 컨테이너 | 격리, 재현성, 안전한 코드 실행 |
ssh |
원격 서버 | GPU 서버, 작업 서버, 에이전트 코드와 실행 환경 분리 |
modal |
Modal 클라우드 | 서버리스 실행, 일시적 컴퓨팅 |
daytona |
Daytona workspace | 클라우드 개발 환경 |
singularity |
Apptainer/Singularity 컨테이너 | HPC, 공유 서버 환경 |
Docker 백엔드 예시
hermes config set terminal.backend docker또는 ~/.hermes/config.yaml에 직접 작성할 수 있습니다.
terminal:
backend: docker
docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
docker_mount_cwd_to_workspace: true
container_cpu: 2
container_memory: 8192
container_disk: 51200
container_persistent: truelocal 백엔드는 에이전트가 사용자 계정 권한으로 파일 시스템에 접근합니다. 신뢰하지 않는 작업이나 자동 명령 실행이 많다면 Docker 또는 SSH 백엔드를 우선 검토하세요.
8. 스킬 시스템 사용법
Hermes의 Skills는 에이전트가 필요할 때 불러오는 작업 지식 문서입니다. 반복되는 작업 절차, 프로젝트 규칙, 배포 방법, 코드 스타일, API 사용법 등을 스킬로 만들어두면 매번 긴 설명을 하지 않아도 됩니다.
# 설치된 스킬 확인
hermes skills list
# 스킬 검색
hermes skills search kubernetes
# 스킬 설치
hermes skills install openai/skills/k8s
# 대화 안에서 스킬 사용
/skills
/github-pr-workflow create a PR for the auth refactor스킬 저장 위치
~/.hermes/skills/
├── devops/
│ └── deploy-k8s/
│ ├── SKILL.md
│ └── references/
└── mlops/
└── vllm/
└── SKILL.md간단한 SKILL.md 예시
---
name: sbtech-api-workflow
description: SBTECH FastAPI + Flutter DTO/API/Provider 생성 규칙
version: 1.0.0
metadata:
hermes:
tags: [fastapi, flutter, riverpod]
category: development
---
# SBTECH API Workflow
## When to Use
FastAPI Swagger를 기준으로 Flutter DTO, API class, Riverpod provider를 생성해야 할 때 사용한다.
## Procedure
1. Swagger schema를 확인한다.
2. request/response DTO를 분리한다.
3. ApiResponseDto<T> envelope 구조를 유지한다.
4. Dio API class를 만든다.
5. Riverpod provider를 만든다.
6. 화면에서는 provider만 주입받아 호출한다.
## Verification
- null safety 오류가 없어야 한다.
- response.data 중첩 구조를 정확히 파싱해야 한다.
- 화면 refresh 후에도 route query parameter가 깨지지 않아야 한다.9. 메신저 게이트웨이 사용법
Hermes Gateway를 사용하면 Telegram, Discord, Slack, WhatsApp, Signal, Email 등에서 Hermes와 대화할 수 있습니다. 항상 켜져 있는 개인 AI 비서처럼 쓰고 싶다면 gateway 구성을 검토할 수 있습니다.
# 메신저 플랫폼 설정
hermes gateway setup
# foreground로 실행
hermes gateway
# 서비스 설치
hermes gateway install
# 서비스 시작/중지/상태 확인
hermes gateway start
hermes gateway stop
hermes gateway statusTelegram 예시 환경 변수
# ~/.hermes/.env
TELEGRAM_BOT_TOKEN=123456:ABC...
TELEGRAM_ALLOWED_USERS=123456789
TELEGRAM_HOME_CHANNEL=123456789터미널 도구가 켜진 봇을 공개 채팅에 열어두면 위험합니다. 반드시 allowed users를 설정하고, 필요하면 pairing 방식만 허용하세요.
10. 자주 발생하는 문제 해결
| 증상 | 가능한 원인 | 해결 방법 |
|---|---|---|
| Hermes가 응답을 못 함 | provider 인증 실패 또는 모델명 오류 | hermes model을 다시 실행하고 provider/model/API key를 확인합니다. |
| 로컬 vLLM은 켜졌는데 Hermes 연결 실패 | base URL, 포트, 모델명, OpenAI 호환 엔드포인트 문제 | curl http://localhost:8000/v1/models로 먼저 서버 응답을 확인합니다. |
| 툴콜이 JSON 텍스트로 출력됨 | vLLM tool parser 미설정 또는 모델과 parser 불일치 | --enable-auto-tool-choice와 모델에 맞는 --tool-call-parser를 설정합니다. |
| 컨텍스트 오류 | 모델 context window가 너무 작음 | 로컬 모델 실행 시 64K 이상 context를 우선 검토하고, Hermes config에 context_length를 명시합니다. |
| 게이트웨이는 켜졌는데 메시지 수신이 안 됨 | bot token, allowed users, platform 설정 누락 | hermes gateway setup을 다시 실행하고 hermes gateway status를 확인합니다. |
| 세션 이어하기 실패 | profile 변경 또는 세션 저장 실패 | hermes sessions list, hermes --continue를 확인합니다. |
공식 recovery 순서
hermes doctor
hermes model
hermes setup
hermes sessions list
hermes --continue
hermes gateway status정리
Hermes Agent는 “터미널에서 쓰는 AI 챗봇”보다 훨씬 넓은 도구입니다. 핵심은 모델 provider 설정 → CLI/TUI로 기본 대화 확인 → 필요한 toolset 활성화 → Docker/SSH 등 안전한 실행 환경 구성 → 스킬과 gateway로 확장 순서입니다.
로컬 LLM을 이미 vLLM으로 서빙하고 있다면 Hermes에서는 custom endpoint만 잡아주면 됩니다. 다만 agent workflow에서는 tool calling과 긴 context가 중요하므로, vLLM 실행 시 tool parser와 max model length를 특히 신경 써야 합니다.
참고 자료
'AI' 카테고리의 다른 글
| AI 오케스트레이션 완벽 가이드: 멀티 에이전트, 워크플로우, 도구 라우팅, LangGraph·CrewAI·OpenAI Agents SDK 비교분석 (8) | 2026.04.25 |
|---|---|
| 클로드 디자인 설치 및 사용법 완벽 가이드: Claude Design으로 UI·프로토타입·프레젠테이션 만드는 방법 (0) | 2026.04.21 |
| PersonaPlex 7B 분석: NVIDIA의 풀듀플렉스 음성 AI, 강점과 한계 정리 (1) | 2026.04.11 |
| vLLM으로 Hugging Face 모델 로컬 서빙하는 방법: 설치부터 API 호출까지 (0) | 2026.04.06 |
| QuiverAI 사용법 총정리: 텍스트·이미지로 SVG 로고와 일러스트 만드는 방법 (0) | 2026.04.06 |