Hermes AI 어시스턴트 - 설치, 설정, 워크플로우 및 문제 해결

개발자를 위한 Hermes Agent 설치 및 빠른 시작

Page content

Hermes Agent는 로컬 머신 또는 저비용 VPS에서 실행되는 셀프 호스팅, 모델 비의존형 AI 어시스턴트로, 터미널 및 메시징 인터페이스를 통해 작동하며 반복적인 작업을 재사용 가능한 스킬로 전환함으로써 시간이 지남에 따라 성능이 향상됩니다.

기능 면에서 OpenClaw와 매우 유사합니다. OpenClaw 역시 도구, 메모리, 로컬 제어를 중심으로 구축된 셀프 호스팅 어시스턴트 스택입니다. Anthropic이 2026년 4월 OpenClaw의 Claude 구독 액세스를 차단한 후 많은 개발자들이 Hermes로 향하게 되었습니다. OpenClaw의 부상과 쇠퇴 타임라인는 왜 Hermes가 제공자 의존성 없이 지속적이고 셀프 호스팅된 자동화를 원했던 사용자들에게 자연스러운 대안이 되었는지를 설명합니다.

Hermes를 중심으로 한 셀프 호스팅 어시스턴트, 검색, 로컬 인프라에 대한 더 넓은 panoramique한 그림을 원한다면, AI 시스템 개요가 Hermes가 해결하려는 문제들과 그 주제들을 연결해 줍니다. Hermes와 OpenClaw를 레퍼런스로 삼은 5계층 어시스턴트 모델(LLM, 메모리, 도구, 라우팅, 가시성)에 대해서는 AI 어시스턴트 아키텍처를 참조하세요. 구체적인 도입 데이터(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가 호스팅 매핑을 제공하며, Hermes가 실행 중일 때의 처리량과 지연 시간 측면은 LLM Performance in 2026: Benchmarks, Bottlenecks & Optimization에서 다룹니다. Ollama와 같은 로컬 런타임에서 Qwen 또는 Gemma를 자주 Hermes에 연결한다면, 다단계 도구 사용을 위한 온도 및 페널티 프리셋을 통합하려면 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를 사용하세요.

peronal-ai-assistant on laptop

제 주관적인 의견: Hermes는 가끔 여는 탭이 아니라 인프라로 다룰 때 가장 흥미롭습니다. 서비스가 되고 안정적인 홈 디렉터리가 갖춰지면, 프롬프트는 “채팅"보다는 “운영(Ops)“에 가깝게 보이기 시작합니다.

Hermes Agent란 무엇이며 왜 중요한가

Hermes Agent는 Nous Research가 개발한 오픈 소스 AI 에이전트입니다. 지속적으로 실행되고, 도구(터미널, 파일, 웹 등)를 사용하며, 스킬 및 메모리 시스템을 통해 자신의 동작을 시간이 지남에 따라 개선하도록 설계되었습니다.

이 가이드의 나머지 모든 내용을 형성하는 두 가지 설계 선택 사항이 있으므로 강조할 가치가 있습니다.

첫째, Hermes는 단일 모델 제공자에 종속되지 않습니다. 공식 설정 플로우에는 여러 제공자 및 모든 OpenAI 호환 엔드포인트가 지원되며, 코드 수정이 아닌 hermes model 명령을 통해 전환이 이루어집니다.

둘째, Hermes는 “대화"와 “실행” 사이에 명확한 선을 긋습니다. 에이전트는 종일 대화할 수 있지만, 행동이 필요할 때는 명시적인 도구와 구성 가능한 실행 백엔드를 통해 이를 수행합니다. 안전성, 재현성, 문제 해결이 바로 이곳에서 다뤄집니다.

비용과 라이선싱은 인상적으로 지루합니다. Hermes Agent 자체는 MIT 라이선스에 따른 무료 소프트웨어입니다. 호스티드 모델을 사용하면 ongoing 비용은 제공자가 부과하는 금액 그대로입니다. 로컬 모델을 실행하면 API 비용을 완전히 피할 수 있습니다.

Hermes 설정이 외부 툴링 레이어를 통해 Claude를 사용한다면, 이 Anthropic 구독 변경 사항가 왜 API 기반 과금이 이제 예상되는 경로인지에 대한 유용한 레퍼런스입니다.

Hermes Agent 설치

Hermes는 Linux, macOS, WSL2를 위한 빠른 설치 경로를 제공합니다. 공식 문서에서는 의도적으로 간단하게 유지하고 있습니다.

Linux에서의 Hermes 설치

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install curl git
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

설치 후 셸을 새로고침해 CLI를 시작합니다.

source ~/.bashrc   # 또는 source ~/.zshrc
hermes

설치 프로그램은 단순히 얇은 래퍼가 아닙니다. 설치 가이드에 따르면, 설치 프로그램은 의존성, 리포지토리, 가상 환경, hermes 명령을 설정한 후 첫 번째 채팅 준비 상태로 만들어 줍니다.

기존 OpenClaw 배포에서 시작하는 것이 아니라 새 시작이라면, 먼저 빈 Hermes를 설치하고 검증한 후 OpenClaw를 Hermes Agent로 안전하게 이관하는 방법에서 단계별 전환을 따르세요. hermes claw migrate는 페르소나, 메모리, 스킬, 제공자, MCP 서버를 매핑하지만, cron 작업, 플러그인, 멀티 에이전트 라우팅은 수동으로 다시 구축해야 합니다.

Windows 및 Android 관련 참고 사항

네이티브 Windows는 지원되지 않습니다. 문서에서는 WSL2 사용을 권장하며, 그 안에 Hermes를 실행하라고 안내합니다.

Android의 경우, Hermes는 Termux 설치 경로를 지원합니다. Termux를 감지하고 의존성 및 환경 설정을 그에 맞게 조정하도록 설계되었습니다.

빠른 시작

가장 빠른 첫 실행은 단순히 hermes를 실행하는 것입니다. 그러나 의미 있는 빠른 시작은 두 가지 추가 결정을 포함합니다: 사용할 모델 제공자 선택 및 활성화할 도구 선택.

제공자와 모델 선택

Hermes는 세 가지 상호 보완적인 진입점을 노출합니다.

제공자와 기본 모델을 선택하기 위한 hermes model
도구세트를 활성화하거나 비활성화하기 위한 hermes tools
주요 구성 영역에 걸쳐 인터랙티브 위자드를 실행하기 위한 hermes setup

최소 플로우의 모습은 다음과 같습니다.

hermes model
hermes tools
hermes

실제로 지원되는 범위에 대해, 공식 Quickstart는 다양한 제공자를 나열하고 Hermes가 OpenAI 호환 API와 함께 작동한다고 명시합니다. 이는 호스티드 서비스와 셀프 호스팅된 엔드포인트를 모두 포함하므로 중요합니다.

초기 도구 실행 검증

Hermes를 중심으로 습관을 형성하기 전에, 환경에서 도구 사용이 작동하는지 확인하는 것이 좋습니다. Quickstart는 처음 시도할 기능으로 터미널 사용법을 명시적으로 제안합니다.

실제로, 작은 “스모크 테스트” 프롬프트는 두 가지 역할을 수행합니다: 터미널 도구를 확인하고 권한 프롬프트를 검증합니다.

예시 프롬프트:

디스크 사용량과 가장 큰 5개 디렉터리를 보여줘.

Hermes가 터미널 도구를 실행할 수 없다면, 문제 해결(Troubleshooting)로 건너뛰세요. 터미널 백엔드 구성 오류는 가장 흔한 원인 중 하나이며, 구성을 보면 해결책은 보통 명확합니다.

확장 가능한 구성

Hermes는 상태를 어디에 저장하는지 그리고 구성을 어떻게 해결하는지 이해하는 사용자에게 보상을 줍니다. 또한 “어제는 잘 동작했었는데” 같은 문제들이 발생하는 곳이기도 합니다.

구성 및 상태가 저장되는 위치

Hermes는 설정과 상태를 ~/.hermes 아래에 저장합니다. 공식 구성 가이드는 config.yaml 설정, .env 시크릿, auth.json OAuth 자격 증명, 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는 또한 config.yaml 내에서 ${VAR_NAME} 문법을 통한 환경 변수 대체를 지원합니다. 이는 특정 값을 환경에 유지하면서 구조화된 구성에서 참조하고 싶을 때 유용합니다.

샌드박스 및 실행 백엔드

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에는 가치를 복합적으로 축적하기 위한 두 가지 관련 메커니즘이 있습니다.

스킬은 절차적 메모리입니다. Hermes는 자신의 스킬을 생성, 업데이트, 삭제할 수 있으며 복잡한 작업을 완료한 후 해당 접근법을 스킬로 저장할 수 있도록 제안할 수 있습니다.

내장 메모리는 ~/.hermes 아래에 MEMORY.md와 USER.md와 같은 파일로 저장되며, Hermes는 더 깊은 회상을 위해 외부 메모리 제공자도 사용할 수 있습니다. 메모리 문서에는 여러 제공자 플러그인이 나열되어 있으며, 메모리 제공자 가이드는 인터랙티브 설정 플로우를 문서화합니다. 메모리 아키텍처가 어떻게 작동하는지에 대한 전체적인 기술 분석(동결 스냅샷, 문자 제한, 외부 제공자, 제한된 메모리 뒤의 철학)이 필요하다면 Hermes Agent Memory System: How Persistent AI Memory Actually Works를 참조하세요. 자동적으로 무엇이 기록되는지에 대해 유독 세밀한 제어를 갖춘 로컬 셀프 호스팅 제공자를 원한다면 Mnemosyne for Hermes Agent: Local Memory Quickstart를 참고하세요. 그리고 왜 보존적인 쓰기 기본값이 먼저 중요한지에 대해서는 Self-Reinforcing Memory Loops in AI Agents를 보세요.

같은 머신에서 여러 독립적인 에이전트를 원한다면, Hermes 프로필은 격리를 제공합니다. 각 프로필은 자신의 구성, 시크릿, 메모리, 세션, 스킬, cron 작업, 게이트웨이 상태를 가진 고유한 디렉터리를 갖습니다.

역할(엔지니어, 연구원, 운영자, 경영 워크플로)별로 생산 환경에서 잘 작동하는 스킬이 어느 것인지에 대한 더 깊은 분석이 필요하다면 Hermes AI Assistant Skills for Real Production Setups를 참조하세요. SKILL.md 파일 자체를 작성하거나 디버깅할 준비가 되었다면(YAML 메타데이터, 점진적 공개 수준, 조건부 가시성, 허브 설치 포함) Hermes Agent Skill Authoring — SKILL.md Structure and Best Practices를 사용하세요.

일반적인 워크플로

Hermes를 계속 가지고 있을 에이전트로 취급한다면, 워크플로는 서비스 엔지니어링처럼 보이기 시작합니다.

안정적인 베이스라인

부패하지 않는 경향이 있는 베이스라인은 다음과 같습니다.

CLI에서 첫 번째 채팅을 설치하고 실행합니다.
hermes model로 제공자와 모델을 선택한 후 비용을 확인합니다.
도구세트를 구성하고 터미널 실행이 로컬인지 샌드박스인지 결정합니다.
기본적으로 사용해 본 후에만 SOUL.md에 빠른 변경을 가합니다. 시스템 프롬프트에서 “슬롯 1"이기 때문에 정체성 변경은 사람들이 기대하는 것보다 더 중요합니다.

복합적으로 쌓이는 일상 사용

Hermes는 웹 UI가 아니라 터미널 UI를 가지며, 슬래시 명령, 재개 가능한 세션, 스트리밍 도구 출력을 갖춘 긴 세션을 위해 설계되었습니다. 그 세션을 위한 셸 플래그, 하위 명령, 슬래시 단축키는 Hermes Agent CLI cheat sheet에 있습니다.

실제로, 유용한 리듬은 다음과 같습니다.

프로젝트별로 이름이 붙은 세션에서 작업을 실행합니다
컨텍스트가 너무 커지면 압축합니다
Hermes가 반복적인 루틴을 스킬로 전환하도록 맡깁니다
도구 실행이 감사(감사 추적) 가능하도록 “질문"과 “행동” 사이에 정신적 경계를 유지합니다

24/7 액세스를 위한 메시징 게이트웨이

메시징 게이트웨이는 Hermes가 터미널 앱이 아니라 어시스턴트처럼 느끼게 하는 부분입니다. 문서에서는 이를 여러 플랫폼에 연결하고, 세션을 처리하며, cron 작업을 실행하고, 메시지를 전달하는 단일 프로세스로 설명합니다.

설정은 hermes gateway setup을 통해 실행되며, 게이트웨이는 포그라운드 또는 사용자 서비스로 실행될 수 있습니다. CLI 레퍼런스는 run, install, start, stop, status, restart와 같은 게이트웨이 하위 명령을 문서화합니다. 이 게이트웨이 모델을 전용 서버에서 실행하면서 별도의 데스크톱 클라이언트로 연결하기를 원한다면, Hermes Agent Headless Server and Remote Desktop Setup를 사용하세요.

멀티 에이전트 백로그 및 제어된 스케줄링에 대해서는 Kanban in Hermes Agent for Self Hosted LLM Workflows를 참조하세요. 이는 디스패처 제한, 의존성 체인, cron 기반 배치팅을 다룹니다.

도구를 사용하는 봇의 보안은 중요합니다. 게이트웨이 문서는 특정 플랫폼에 대한 허용 목록(allowlist)과 일회용 페어링 코드를 발급하고 hermes pairing approve를 통한 승인을 요구하는 DM 페어링 플로우를 설명합니다.

드라마 없이 업데이트

Hermes 업데이트는 1급 명령입니다. 업데이트 가이드는 hermes update, 구성 마이그레이션 체크, hermes doctor와 hermes gateway status를 포함한 작은 업데이트 후 검증 루틴을 문서화합니다.

hermes update
hermes doctor
hermes gateway status

문제 해결 및 진단

대부분의 Hermes 실패는 신비롭지 않습니다. 사람들이 모델 레이어만 확인하고 런타임 레이어를 무시하기 때문에 신비롭게 보이는 것입니다.

빠른 트리아지 명령

CLI 레퍼런스는 세 가지 명령을 핵심 루프로 명시적으로 위치시킵니다.

인터랙티브 진단을 위한 hermes doctor
빠른 개요를 위한 hermes status
공유 가능하고 수정된(setup summary) 설정 요약을 위한 hermes dump

로그의 경우, hermes logs는 ~/.hermes/logs 아래에 저장된 파일을 테일링(tail)합니다.

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 변수 누락 등 백엔드별 일반적인 원인을 가리킵니다. 또한 샌드박스 구성에 의문이 있을 때 local로 폴백하는 것이 유효한 디버깅 조치임을 언급합니다.

게이트웨이 문제에 대해, 메시징 가이드는 허용 목록과 페어링을 안전한 기본값으로 강조하며, 이는 많은 “봇이 침묵 중” 인시던트가 실제로는 인가(승인)가 제 기능을 하고 있음을 의미합니다.