허메스 AI 어시스턴트 - 설치, 설정, 워크플로우 및 문제 해결
개발자를 위한 Hermes Agent 설치 및 빠른 시작
Hermes Agent은(는) 자체 호스팅(self-hosted) 방식이며 모델에 구애받지 않는 AI 어시스턴트로, 로컬 머신이나 저비용 VPS에서 실행됩니다. 터미널 및 메시징 인터페이스를 통해 작동하며, 반복적인 작업을 재사용 가능한 스킬(skill)로 변환함으로써 시간이 지남에 따라 성능이 향상됩니다.
이 시스템은 도구, 메모리, 로컬 제어를 중심으로 구축된 또 다른 자체 호스팅 어시스턴트 스택인 OpenClaw와 기능적으로 매우 유사합니다. 많은 개발자들은 2026년 4월 Anthropic이 OpenClaw의 Claude 구독 접근을 차단한 이후 Hermes로 이동했습니다. OpenClaw의 부상과 몰락 타임라인에서 프로바이더 의존성 없이 지속적이고 자체 호스팅되는 자동화를 원하는 사용자들이 Hermes를 자연스러운 대안으로 선택한 이유를 설명하고 있습니다.
Hermes를 둘러싼 자체 호스팅 어시스턴트, 검색(Retrieval), 로컬 인프라의 더 넓은 그림을 보고 싶다면, AI 시스템 개요에서 Hermes가 해결하려고 시도하는 문제들과 연결된 주제들을 살펴볼 수 있습니다. GitHub 스타 수, OpenRouter 일일 토큰 사용량, PyPI 다운로드 수, CVE 기록, Reddit 커뮤니티 감정 분석 등 구체적인 채택 데이터를 원한다면, OpenClaw vs Hermes Agent: Stars, Downloads & Usage 2026을 참조하세요. 이 자료는 Hermes가 측정 가능한 모든 지표에서 19가지 대안과 어떻게 비교되는지를 추적합니다.
배포 상의 트레이드오프와 런타임 선택에 관해서는, LLM Hosting in 2026: Local, Self-Hosted & Cloud Infrastructure Compared에서 호스팅 지도를 제공하고, LLM Performance in 2026: Benchmarks, Bottlenecks & Optimization에서는 Hermes가 실행된 후의 처리량(throughput) 및 대기시간(latency) 측면을 다룹니다. Ollama와 같은 로컬 런타임에서 Qwen 또는 Gemma를 Hermes에 정기적으로 연결하여 사용한다면, 다단계 도구 사용을 위한 temperature 및 penalty 프리셋을 통합하려면 Agentic LLM inference parameters for Qwen and Gemma를 참조하세요. 셸 명령어(hermes gateway, hermes memory, hermes doctor, 슬래시 숏컷 등)에 대한 간략한 지도가 필요하다면 Hermes Agent CLI cheat sheet를 사용하세요. 모바일에서의 메시지가 주요 진입점이라면, 음성 스택 및 플랫폼별 설정을 위해 Hermes Voice Control from Your Phone을 사용하세요.
저의 편향된 견해: Hermes는 가끔 여는 탭이 아니라 인프라로 취급할 때 가장 흥미롭습니다. 서비스로 실행되고 안정적인 홈 디렉토리가 갖춰지면, 프롬프트는 “채팅"처럼 보이기보다는 “운영(ops)“처럼 보이기 시작합니다.
Hermes Agent란 무엇이며 왜 중요한가
Hermes Agent는 Nous Research가 구축한 오픈 소스 AI 에이전트입니다. 지속적으로 실행되고 도구(터미널, 파일, 웹 등)를 사용하며, 스킬 및 메모리 시스템을 통해 시간이 지남에 따라 자신의 행동을 개선하도록 설계되었습니다.
이 가이드의 나머지 부분을 형성하는 두 가지 설계 결정이 주목할 가치가 있습니다.
첫째, Hermes는 단일 모델 프로바이더에 잠겨 있지 않습니다. 공식 설정 흐름은 여러 프로바이더 및 모든 OpenAI 호환 엔드포인트를 지원하며, 전환은 코드 수정이 아닌 hermes model 명령어를 통해 이루어집니다.
둘째, Hermes는 “대화"와 “실행” 사이에 명확한 경계를 긋습니다. 에이전트는整天 대화할 수 있지만, 행동이 필요할 때는 명시적인 도구와 구성 가능한 실행 백엔드를 통해 행합니다. 바로 그곳이 안전성, 재현성, 그리고 문제 해결이 존재하는 곳입니다.
비용과 라이선싱은 상쾌할 정도로 지루합니다. Hermes Agent 자체는 MIT 라이선스 하의 무료 소프트웨어입니다. 호스팅된 모델을 사용한다면, 지속되는 비용은 프로바이더가 청구하는 금액 그대로입니다. 로컬 모델을 실행한다면 API 요금을 완전히 피할 수 있습니다.
Hermes 설정이 외부 도구 레이어를 통해 Claude를 사용하는 경우, Anthropic 구독 변경은 API 기반 청구가 이제 예상되는 경로가 된 이유에 대한 유용한 참조 자료입니다.
Hermes Agent 설치
Hermes는 Linux, macOS, WSL2용 빠른 설치 경로를 제공합니다. 공식 문서에서는 이를 의도적으로 단순하게 유지합니다.
Linux에서 Hermes 설치
sudo apt-get update
sudo apt-get upgrade
sudo apt-get curl git
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
설치 후 셸을 새로고침하고 CLI를 시작하세요.
source ~/.bashrc # 또는 source ~/.zshrc
hermes
인스톨러는 단순히 얇은 래퍼가 아닙니다. 설치 가이드에 따르면, 이 인스톨러는 종속성, 리포지토리, 가상 환경, 그리고 hermes 명령어를 설정한 후 사용자가 첫 번째 채팅 준비 상태로 이동할 수 있도록 합니다.
Windows 및 Android 참고 사항
네이티브 Windows는 지원되지 않습니다. 문서에서는 WSL2를 사용하고 그 안에서 Hermes를 실행하는 것을 권장합니다.
Android의 경우, Hermes는 Termux 설치 경로를 지원합니다. Termux를 감지하고 그에 따라 종속성 및 환경 설정을 적응하도록 설계되었습니다.
빠른 시작(Quickstart)
가장 빠른 첫 번째 실행은 단순히 hermes를 실행하는 것뿐이지만, 의미 있는 빠른 시작을 위해서는 두 가지 추가 결정이 필요합니다: 사용할 모델 프로바이더와 활성화할 도구입니다.
프로바이더 및 모델 선택
Hermes는 세 가지 보완적인 진입점을 제공합니다:
hermes model: 프로바이더 및 기본 모델 선택hermes tools: 도구 세트 활성화 또는 비활성화hermes setup: 주요 구성 영역에 대한 대화형 위즈드 실행
최소한의 흐름은 다음과 같습니다:
hermes model
hermes tools
hermes
실제로 지원되는 항목에 관해서는, 공식 Quickstart는 다양한 프로바이더를 나열하고 Hermes가 OpenAI 호환 API와 함께 작동함을 명시합니다. 이는 호스팅된 서비스와 자체 호스팅된 엔드포인트를 모두 포함한다는 점에서 중요합니다.
도구 실행을 조기에 증명하세요
Hermes 사용 습관을 만들기 전에, 환경에서 도구 사용이 작동하는지 확인하는 것이 중요합니다. Quickstart는 첫 번째 기능으로 터미널 사용을 명시적으로 제안합니다.
실무에서, 작은 “스모크 테스트(smoke test)” 프롬프트는 두 가지 역할을 합니다: 터미널 도구를 확인하고 권한 프롬프트를 검증합니다.
예시 프롬프트:
내 디스크 사용량과 가장 큰 디렉토리 5개를 보여줘.
Hermes가 터미널 도구를 실행할 수 없다면, 문제 해결(Troubleshooting) 섹션으로 건너뛰세요. 터미널 백엔드 오 구성은 가장 흔한 원인 중 하나이며, 구성 파일을 보면 해결책은 보통 명확합니다.
확장 가능한 구성
Hermes는 상태를 저장하는 위치와 구성을 해결하는 방식을 이해하는 사람들에게 보상을 줍니다. 또한 많은 “어제에는 작동했는데"라는 문제들이 여기서 발생합니다.
구성 및 상태가 저장되는 위치
Hermes는 설정과 상태를 ~/.hermes 아래에 저장합니다. 공식 구성 가이드는 구성을 문서화하며, 여기에는 설정을 위한 config.yaml, 시크릿을 위한 .env, OAuth 자격 증명을 위한 auth.json, 아이덴티티를 위한 SOUL.md, 그리고 메모리, 스킬, cron, 세션, 로그를 위한 폴더들이 포함됩니다.
이것이 중요한 이유는 두 가지입니다.
- 디버깅은 정확히 어디를 봐야 하는지 알기 때문에 기계적으로 이루어집니다.
- 백업은 에이전트 상태의 대부분을 포착하는 하나의 디렉토리 때문에 직관적입니다.
구성 우선순위 및 config.yaml에서 시크릿 제외
Hermes는 우선순위 순서로 구성을 해결합니다. 맨 위에는 CLI 오버라이드가 있고, 그 다음이 config.yaml, 그 다음이 .env이며, 가장 아래에는 기본값이 있습니다.
좋은 세부 사항으로, hermes config set은 값을 올바른 파일로 라우팅합니다: API 키는 .env로, 비시크릿 설정은 config.yaml으로 보내집니다.
hermes config set model openrouter/meta-llama/llama-3.1-70b-instruct
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxx
Hermes는 또한 ${VAR_NAME} 구문을 통해 config.yaml 내부에서 환경 변수 대체를 지원합니다. 이는 특정 값을 환경에 유지하면서 여전히 구조화된 구성에서 참조하고 싶을 때 유용합니다.
샌드박스 및 실행 백엔드
Hermes는 셸 명령어가 실제로 실행되는 위치를 정의하는 여러 터미널 백엔드를 지원합니다. 구성 가이드는 local, docker, ssh, modal, daytona, singularity를 나열합니다.
의견이 개연적이되 전도적인 방식이 아닌 관점에서 이를 생각해보면:
local은 가장 빠르고 간단하지만 격리되어 있지 않습니다.docker는 실용적인 안전성과 재현성 레이어입니다.ssh는 채팅 장치를 컴퓨팅 박스에서 분리하는 깔끔한 방법입니다.modal과daytona는 “서버리스이지만 충분히 지속 가능한” 워크플로우에 적합합니다.singularity는 HPC 친화적인 옵션입니다.
최소한의 Docker 백엔드 예시:
# ~/.hermes/config.yaml
terminal:
backend: docker
docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
docker_volumes:
- "/home/user/projects:/workspace/projects"
docker_forward_env:
- "GITHUB_TOKEN"
문서에는 Docker 백엔드에 대한 보안 강화(예: 기능 제거 및 권한 에스컬레이션 비활성화)에 대한 설명도 포함되어 있습니다.
스킬, 메모리, 프로필
Hermes는 가치를 복리처럼 늘리기 위한 두 가지 관련 메커니즘을 가지고 있습니다.
스킬(Skills)은 절차적 메모리입니다. Hermes는 자체 스킬을 생성, 업데이트, 삭제할 수 있으며, 복잡한 작업을 완료한 후 접근 방식을 스킬로 저장할 것을 제안할 수 있습니다.
내장 메모리는 ~/.hermes 아래의 MEMORY.md 및 USER.md와 같은 파일로 저장되며, Hermes는 더 깊은 회상을 위해 외부 메모리 프로바이더도 사용할 수 있습니다. 메모리 문서에는 여러 프로바이더 플러그인이 나열되어 있으며, 메모리 프로바이더 가이드는 대화형 설정 흐름을 문서화합니다. 메모리 아키텍처가 어떻게 작동하는지(동결된 스냅샷, 문자 수 제한, 8개의 외부 프로바이더, 그리고 유계 메모리(bounded memory) 뒤의 철학)에 대한 완전한 기술적 분해는 Hermes Agent Memory System: How Persistent AI Memory Actually Works를 참조하세요.
동일한 머신에서 여러 독립적인 에이전트를 원한다면, Hermes 프로필이 격리를 제공합니다. 각 프로필은 자체 구성, 시크릿, 메모리, 세션, 스킬, cron 작업, 게이트웨이 상태를 가진 자체 디렉토리를 갖습니다.
역할(엔지니어, 연구원, 운영자, 그리고 경영진 워크플로우)에 따라 프로덕션에서 잘 작동하는 스킬에 대한 더 깊은 분석은 Hermes AI Assistant Skills for Real Production Setups을 참조하세요. SKILL.md 파일 자체(메타데이터, 점진적 공개 레벨, 조건부 가시성, 허브 설치)를 작성하거나 디버깅할 준비가 되었을 때는 Hermes Agent Skill Authoring — SKILL.md Structure and Best Practices을 사용하세요.
일반적인 워크플로우
Hermes를 유지할 에이전트처럼 취급한다면, 워크플로우는 서비스 엔지니어링처럼 보이기 시작합니다.
안정적인 베이스라인
부식되지 않는 경향이 있는 베이스라인은 다음과 같습니다:
- CLI에서 설치하고 첫 번째 채팅을 실행합니다.
hermes model로 프로바이더와 모델을 선택한 후 비용을 확인합니다.- 도구 세트를 구성하고 터미널 실행이 로컬인지 샌드박스인지 결정합니다.
- 기본값을 잠시 사용한 후에만
SOUL.md를 빠르게 변경합니다. 아이덴티티 변경은 사람들이 예상하는 것보다 더 중요합니다. 그것은 시스템 프롬프트의 “슬롯 1"이기 때문입니다.
축적되는 일상적 사용
Hermes에는 웹 UI가 아닌 터미널 UI가 있으며, 슬래시 명령어, 재개 가능한 세션, 스트리밍 도구 출력을 갖춘 긴 세션을 위해 설계되었습니다.
실무에서 유용한 리듬은 다음과 같습니다:
- 프로젝트의 이름이 지정된 세션에서 작업을 실행합니다.
- 컨텍스트가 너무 커지면 컨텍스트를 압축합니다.
- Hermes가 반복적인 루틴을 스킬로 변환하도록 둡니다.
- 도구 실행이 감사(auditable)되도록 유지하기 위해 “질문하기"와 “행동하기” 사이에 정신적 경계를 유지합니다.
24/7 접근을 위한 메시징 게이트웨이
메시징 게이트웨이는 Hermes를 터미널 앱이 아닌 어시스턴트처럼 느끼게 하는 부분입니다. 문서에서는 이를 여러 플랫폼에 연결하고, 세션을 처리하며, cron 작업을 실행하고, 메시지를 전달하는 단일 프로세스로 설명합니다.
설치는 hermes gateway setup을 통해 호출되며, 게이트웨이는 포어그라운드(foreground)에서 실행되거나 사용자 서비스(user service)로 실행될 수 있습니다. CLI 참조에는 run, install, start, stop, status, restart와 같은 게이트웨이 서브커맨드가 문서화되어 있습니다.
다중 에이전트 백로그와 제어된 스케줄링에 대해서는 Kanban in Hermes Agent for Self Hosted LLM Workflows를 참조하세요. 여기에서는 디스패처 제한, 의존성 체인, cron 기반 배치 처리에 대해 다룹니다.
도구를 사용하는 봇의 보안은 중요합니다. 게이트웨이 문서는 특정 플랫폼을 위한 허용 목록(allowlists)과 일회성 페어링 코드를 발급하고 hermes pairing approve를 통해 승인을 요구하는 DM 페어링 흐름을 설명합니다.
드라마 없는 업데이트
Hermes 업데이트는 일급 명령어입니다. 업데이트 가이드는 hermes update, 구성 마이그레이션 체크, 그리고 hermes doctor와 hermes gateway status를 포함한 작은 업데이트 후 검증 루틴을 문서화합니다.
hermes update
hermes doctor
hermes gateway status
문제 해결 및 진단
대부분의 Hermes 실패는 신비롭지 않습니다. 사람들이 모델 레이어만 확인하고 런타임 레이어를 무시하기 때문에 신비로워 보입니다.
빠른 분류 명령어
CLI 참조는 세 명령어를 핵심 루프로 명시적으로 위치시킵니다:
hermes doctor: 대화형 진단용hermes status: 빠른 개요용hermes dump: 공유 가능하고 익명화된 설정 요약용
로그의 경우, hermes logs는 ~/.hermes/logs 아래에 저장된 파일을 tails합니다.
hermes doctor --fix
hermes status
hermes dump --show-keys
hermes logs errors -f
일반적인 설치 실패
FAQ 및 문제 해결 가이드에는 Python 버전 문제, uv 미찾음, sudo 설치와 사용자 설치를 혼합하여 발생하는 권한 문제 등 반복되는 문제들과 그 해결책이 나열되어 있습니다.
이러한 오류를 만나면, 문서는 Python 업그레이드, uv 설치, sudo 없이 Hermes 재설치와 같은 구체적인 복구 단계를 제공합니다.
프로바이더 및 모델 문제
API 키가 작동하지 않을 때, FAQ는 구성을 확인하거나 hermes model을 다시 실행하거나 hermes config set을 통해 키를 직접 설정할 것을 권장합니다. 또한 일반적인 함정을 지적합니다: 키는 프로바이더별로 다릅니다.
“모델을 찾을 수 없음” 문제의 경우, FAQ는 유효한 식별자를 선택하기 위해 hermes model을 사용하라고 가리키며 구성 및 세션별 오버라이드를 모두 보여줍니다.
속도 제한 및 컨텍스트 길이 문제도 다룹니다. FAQ는 429 오류를 기다리거나, 프로바이더나 모델로 전환하거나, 압축 또는 새 세션을 통해 컨텍스트 압력을 줄일 것을 제안합니다.
터미널 백엔드 및 게이트웨이 문제
터미널 명령어가 즉시 실패할 경우, 구성 가이드에는 “일반적인 터미널 백엔드 문제” 섹션이 포함되어 있으며 Docker 미실행 및 누락된 SSH 변수를 포함한 백엔드별 전형적인 원인을 가리킵니다. 또한 샌드박스 구성이 의심스러울 때 로컬로 폴백하는 것이 유효한 디버깅 행동임을 명시합니다.
게이트웨이 문제의 경우, 메시징 가이드는 허용 목록과 페어링을 안전한 기본값으로 강조하며, 이는 많은 “봇이 침묵하는” 사건들이 실제로 권한 부여가 역할을 하고 있음을 의미합니다.
