Hermes AI 어시스턴트 – 설치, 설정, 워크플로우 및 트러블슈팅
개발자를 위한 Hermes Agent 설치 및 빠른 시작
Hermes Agent은 로컬 머신 또는 저비용 VPS에서 구동되는 자체 호스팅, 모델 비의존적 AI 어시스턴트로, 터미널 및 메시징 인터페이스를 통해 작동하며 반복적인 작업을 재사용 가능한 스킬로 전환함으로써 시간이 지남에 따라 지속적으로 개선됩니다.
이것은 도구, 메모리 및 로컬 제어를 중심으로 구축된 또 다른 자체 호스팅 어시스턴트 스택인 OpenClaw와 기능적으로 매우 유사합니다. 많은 개발자들이 2026년 4월 Anthropic이 OpenClaw의 Claude 구독 접근을 차단한 후 Hermes로 유입되었습니다 — OpenClaw의 부흥과 쇠퇴 타임라인는 프로바이더 의존성 없이 지속적이고 자체 호스팅된 자동화를 원했던 사용자들에게 Hermes가 자연스러운 대안으로 떠올랐던 이유를 설명합니다.
Hermes를 둘러싼 자체 호스팅 어시스턴트, 검색 및 로컬 인프라의 더 큰 그림이 궁금하다면, AI 시스템 개요는 이러한 주제들을 Hermes가 해결하려는 동일한 문제들과 연결합니다. LLM, 메모리, 도구, 라우팅, 관찰력이라는 5층 어시스턴트 모델에 대해 Hermes와 OpenClaw를 참고 구현으로 확인하려면 AI 어시스턴트 아키텍처를 참고하세요. 구체적인 도입 데이터(GitHub 스타, OpenRouter 일일 토큰 볼륨, PyPI 다운로드 횟수, CVE 기록, Reddit 커뮤니티 여론)에 대해서는 OpenClaw vs Hermes Agent: Stars, Downloads & Usage 2026를 통해 Hermes가 측정 가능한 모든 신호에서 19개의 대안 대비 어떻게 비교되는지 추적할 수 있습니다.
배포 트레이드오프와 런타임 선택에 대해, 2026년 LLM 호스팅: 로컬, 자체 호스팅 및 클라우드 인프라 비교가 호스팅 지도를 제공하며, Hermes가 구동된 후 처리량과 지연 시간 측면에 대해서는 2026년 LLM 성능: 벤치마크, 병목 현상 및 최적화를 참조하세요. Ollama와 같은 로컬 런타임에서 Qwen 또는 Gemma를 루틴하게 사용하신다면, 멀티스텝 도구 사용을 위한 온도 및 페널티 프리셋을 통합하여 Qwen 및 Gemma를 위한 에이전틱 LLM 추론 파라미터를 사용하세요. 셸 명령(hermes gateway, hermes memory, hermes doctor, 슬래시 단축키 등)에 대한 컴팩트한 지도가 필요하다면, Hermes Agent CLI 치트시트를 사용하세요. 모바일에서의 메시징이 주요 진입점이라면, 로컬 Whisper와 무료 Edge TTS를 사용하여 Telegram과 Discord에서 Hermes 음성 제어를 설정하고, 설정, 튜닝 팁, 예시, 문제 해결을 포함한 휴대폰으로 Hermes 음성 제어를 음성 스택 및 플랫폼별 설정에 사용하세요.
제 주관적인 평가: 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 명령어를 설정한 후 첫 채팅이 가능한 상태로 만들어 줍니다.
새로 시작하는 것이 아니라 기존 OpenClaw 배포에서 넘어오는 경우, 먼저 빈 Hermes를 설치하고 검증한 다음, OpenClaw에서 Hermes Agent로 안전하게 마이그레이션하는 방법에 따른 단계적 전환을 따르세요 — hermes claw migrate는 페르소나, 메모리, 스킬, 프로바이더, MCP 서버를 매핑하지만, cron 작업, 플러그인, 멀티 에이전트 라우팅은 수동으로 다시 구축해야 합니다.
Windows 및 Android 관련 주의사항
네이티브 Windows는 지원되지 않습니다. 문서에서는 WSL2를 권장하며 그 내부에서 Hermes를 실행할 것을 제안합니다.
Android의 경우, Hermes는 Termux 설치 경로를 지원합니다. Termux를 감지하고 이에 따라 종속성 및 환경 설정을 적응하도록 설계되어 있습니다.
빠른 시작(Quickstart)
가장 빠른 첫 실행은 단순히 hermes만 입력하는 것뿐이지만, 의미 있는 빠른 시작을 위해서는 두 가지 추가 결정이 필요합니다: 사용할 모델 프로바이더를 고르는 것과 어떤 도구를 활성화할 것인가를 정하는 것입니다.
프로바이더 및 모델 선택
Hermes는 세 가지 상호 보완적인 진입점을 노출합니다:
hermes model: 프로바이더 및 기본 모델 선택hermes tools: 도구 세트 활성화 또는 비활성화hermes setup: 주요 설정 영역에 걸쳐 대화형 마법사 실행
최소 흐름은 다음과 같습니다:
hermes model
hermes tools
hermes
실제로 지원되는 것에 대해, 공식 빠른 시작 가이드는 다양한 프로바이더의 범위를 나열하며 Hermes가 OpenAI 호환 API와도 작동한다고 명시하고 있습니다. 이는 호스팅된 서비스와 자체 호스팅 엔드포인트를 모두 포함한다는 점에서 중요합니다.
초기 도구 실행 증명
Hermes 주위에 습관을 만들기 전에, 환경에서 도구 사용이 작동하는지 확인하는 것이 가치가 있습니다. 빠른 시작 가이드는 명시적으로 터미널 사용을 시도할 첫 번째 기능으로 제안합니다.
실제로, 작은 “스모크 테스트” 프롬프트는 두 가지 작업을 수행합니다: 터미널 도구를 확인하고 권한 프롬프트를 검증하는 것입니다.
예제 프롬프트:
내 디스크 사용량과 가장 큰 디렉토리 5개를 보여줘.
Hermes가 터미널 도구를 실행할 수 없다면, 문제 해결(Troubleshooting) 섹션으로 건너뛰세요. 터미널 백엔드 잘못된 구성은 가장 흔한 원인 중 하나이며, 설정을 살펴보면 수정 방법이 보통 명백합니다.
확장 가능한 설정(Configuration that scales)
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(High Performance Computing)에 친화적인 옵션
최소한의 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 백엔드 위한 보안 강화(예: 기능(capabilities) 제거, 권한 상승(disable privilege escalation) 방지)을 설명합니다.
스킬, 메모리, 프로파일
Hermes에는 가치를 축적하기 위한 두 가지 관련 메커니즘이 있습니다.
스킬은 절차적 기억(procedural memory)입니다. Hermes는 자신의 스킬을 생성, 업데이트, 삭제할 수 있으며 복잡한 작업을 완료한 후 해당 접근법을 스킬로 저장할 것을 제안할 수 있습니다.
내장 메모리는 ~/.hermes 아래에 MEMORY.md, USER.md와 같은 파일로 저장되며, Hermes는 더 깊은 회상을 위해 외부 메모리 프로바이더도 사용할 수 있습니다. 메모리 문서에는 여러 프로바이더 플러그인이 나열되어 있으며, 메모리 프로바이더 가이드는 대화형 설정 플로우를 문서화합니다. 메모리 아키텍처가 어떻게 작동하는지에 대한 전체적인 기술적 분석(동결 스냅샷, 문자 한계, 외부 프로바이더, 그리고 제한된 메모리背后的 철학)을 보려면 Hermes Agent 메모리 시스템: 지속적 AI 메모리가 실제로 작동하는 방식를 참고하세요. 자동으로 기록되는 것에 대해 비정상적으로 세밀한 제어를 원한다면, Hermes Agent를 위한 Mnemosyne: 로컬 메모리 빠른 시작를 참조하세요 — 그리고 AI 에이전트에서의 자기 강화형 메모리 루프를 통해 보수적인 쓰기 기본값이 왜 중요한지 이유를 알아보세요.
같은 머신에서 여러 독립적 에이전트를 원한다면, Hermes 프로파일은 격리를 제공합니다. 각 프로파일은 자신의 설정, 시크릿, 메모리, 세션, 스킬, cron 작업, 게이트웨이 상태를 가진 고유한 디렉토리를 갖습니다.
역할(엔지니어, 연구자, 운영자, 경영진 워크플로우)에 따라 프로덕션에서 잘 작동하는 스킬이 무엇인지 더 깊이 살펴보고 싶다면, 실제 프로덕션 세팅을 위한 Hermes AI 어시스턴트 스킬를 참조하세요. SKILL.md 파일 자체를 작성하거나 디버깅할 준비가 되었을 때(YAML 메타데이터, 점진적 공개 레벨, 조건부 가시성, 허브 설치 등)— Hermes Agent 스킬 작성 — SKILL.md 구조 및 모범 사례를 사용하세요.
전형적인 워크플로우
Hermes를 계속 둘 에이전트로 취급한다면, 워크플로우가 서비스 엔지니어링처럼 보이기 시작합니다.
안정적인 베이스라인
부패하지 않는 경향이 있는 베이스라인은 다음과 같습니다:
- CLI에서 설치 후 첫 채팅 실행.
hermes model로 프로바이더 및 모델 선택 후 비용 확인.- 도구 세트 구성 및 터미널 실행이 로컬인지 샌드박스인지 결정.
- 기본값을しばらく 사용한 후에만
SOUL.md에 빠른 변경 사항을 적용. 아이덴티티 변경은 시스템 프롬프트에서 “슬롯 1"이기 때문에 사람들이 예상하는 것보다 더 중요합니다.
축적되는 일상적 사용
Hermes는 웹 UI가 아닌 터미널 UI를 가지며, 슬래시 명령, 재개 가능한 세션, 스트리밍 도구 출력을 위한 긴 세션에 설계되어 있습니다.
실제로, 유용한 리듬은 다음과 같습니다:
- 프로젝트마다 이름이 지정된 세션에서 작업 수행
- 컨텍스트가 너무 커지면 압축
- Hermes가 반복적인 루틴을 스킬로 전환하도록 방치
- 도구 실행이 감사 가능한도록 “질문(ask)“과 “행동(act)” 사이의 정신적 경계 유지
24/7 접근을 위한 메시징 게이트웨이
메시징 게이트웨이는 Hermes가 터미널 앱이 아닌 어시스턴트처럼 느끼게 하는 부분입니다. 문서에서는 이를 여러 플랫폼에 연결하고, 세션을 처리하고, cron 작업을 실행하고, 메시지를 전달하는 단일 프로세스로 설명합니다.
설정은 hermes gateway setup을 통해 호출되며, 게이트웨이는 포그라운드로 실행되거나 사용자 서비스로 실행될 수 있습니다. CLI 레퍼런스는 run, install, start, stop, status, restart와 같은 게이트웨이 서브커맨드를 문서화합니다. 이 게이트웨이 모델을 전용 서버에서 실행하면서 별도의 데스크톱 클라이언트로 연결하고 싶다면, Hermes Agent 헤드리스 서버 및 원격 데스크톱 설정를 사용하세요.
멀티 에이전트 백로그와 제어된 스케줄링에 대해서는, 자체 호스팅 LLM 워크플로우를 위한 Hermes Agent의 칸반를 참조하세요. 여기서는 디스패처 한계, 의존성 체인, cron 기반 배치링을 다룹니다.
도구 사용 봇의 보안은 중요합니다. 게이트웨이 문서는 특정 플랫폼에 대한 허용 목록(allowlists)과 hermes pairing approve을 통한 승인이 필요한 일회용 페어링 코드를 발급하는 DM 페어링 플로우를 설명합니다.
무사고 업데이트
Hermes 업데이트는 1급(first-class) 명령어입니다. 업데이트 가이드는 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 아래에 저장된 파일의 테일(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 변수 누락 등)을 가리킵니다. 또한 샌드박스 구성에 의문이 있을 때 로컬로 폴백하는 것이 유효한 디버깅 수단이 된다고 언급합니다.
게이트웨이 문제에 대해, 메시징 가이드는 허용 목록과 페어링을 안전한 기본값으로 강조하며, 이는 많은 “봇이 침묵하고 있다"는 사고가 실제로는 인가(authorisation)가 그 역할을 수행하고 있는 것이라는 것을 의미합니다.
