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

개발자를 위한 Hermes 에이전트 설치 및 빠른 시작

Page content

Hermes Agent 은 로컬 머신이나 저비용 VPS 에서 실행되는 자체 호스팅, 모델에 구애받지 않는 AI 어시스턴트입니다. 터미널과 메시징 인터페이스를 통해 작동하며, 반복되는 작업을 재사용 가능한 스킬로 변환하여 시간이 지남에 따라 지속적으로 개선됩니다.

이 시스템은 OpenClaw 와 기능적으로 매우 유사합니다. OpenClaw 또한 도구, 메모리, 로컬 제어를 중심으로 구축된 자체 호스팅 어시스턴트 스택입니다.

Hermes 를 둘러싼 자체 호스팅 어시스턴트, 검색, 로컬 인프라의 더 넓은 그림을 원하신다면, AI 시스템 개요 에서 Hermes 가 해결하려는 문제와 동일한 주제를 연결해 드리는 내용을 찾아보실 수 있습니다.

배포 시의 트레이드오프와 런타임 선택 사항에 대해서는 2026 년 LLM 호스팅: 로컬, 자체 호스팅 및 클라우드 인프라 비교 에서 호스팅 지도를 확인하고, Hermes 가 실행된 후 처리량과 지연 시간 측면은 2026 년 LLM 성능: 벤치마크, 병목 현상 및 최적화 에서 다루고 있습니다.

peronal-ai-assistant on laptop

저의 편향된 견해: Hermes 는 가끔 여는 탭으로가 아니라 인프라로 다룰 때 가장 흥미롭습니다. 서비스로 실행되고 안정적인 홈 디렉터리를 갖게 되면, 사용자의 프롬프트는 “채팅"보다는 “운영 (Ops)“에 더 가까워집니다.

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

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

이 가이드의 나머지 내용을 형성하는 두 가지 설계 선택 사항이 있으니 명시적으로 설명하겠습니다.

첫째, Hermes 는 단일 모델 제공업체에 종속되지 않습니다. 공식 설정 흐름은 여러 제공업체와 모든 OpenAI 호환 엔드포인트를 지원하며, 코드 수정이 아닌 hermes model 명령을 통해 전환이 가능합니다.

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

비용과 라이선스는 상쾌하게 지루할 정도로 간단합니다. Hermes Agent 자체는 MIT 라이선스 하의 무료 소프트웨어입니다. 호스팅된 모델을 사용하는 경우, 지속적인 비용은 제공업체의 청구 금액입니다. 로컬 모델을 실행하는 경우 API 요금을 완전히 피할 수 있습니다.

Hermes Agent 설치

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

한 줄 설치

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 를 감지하고 이에 따라 종속성 및 환경 설정을 조정하도록 설계되었습니다.

빠른 시작

가장 빠른 첫 실행은 단순히 hermes 를 실행하는 것이지만, 의미 있는 빠른 시작에는 두 가지 추가 결정이 필요합니다: 사용할 모델 제공업체와 활성화할 도구입니다.

제공업체 및 모델 선택

Hermes 는 세 가지 상호 보완적인 진입점을 제공합니다:

  • hermes model: 제공업체 및 기본 모델 선택
  • hermes tools: 도구 세트 활성화 또는 비활성화
  • hermes setup: 주요 구성 영역에 대한 대화형 마법사 실행

최소한의 흐름은 다음과 같습니다:

hermes model
hermes tools
hermes

실제로 지원되는 것에 관해, 공식 빠른 시작 가이드는 다양한 제공업체를 나열하며 Hermes 가 OpenAI 호환 API 와 함께 작동함을 강조합니다. 이는 호스팅된 서비스와 자체 호스팅 엔드포인트를 모두 포함하기 때문에 중요합니다.

초기 도구 실행 증명

Hermes 를 중심으로 습관을 형성하기 전에, 환경에서 도구 사용이 작동하는지 확인하는 것이 가치가 있습니다. 빠른 시작 가이드는 터미널 사용을 첫 번째로 시도해야 할 기능으로 명시적으로 제안합니다.

실제로는 작은 “연기 테스트 (smoke test)“프롬프트가 두 가지 역할을 합니다: 터미널 도구를 확인하고 권한 프롬프트를 유효화합니다.

예시 프롬프트:

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

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

확장 가능한 구성

Hermes 는 상태가 어디에 저장되고 구성이 어떻게 해결되는지 이해하는 사용자에게 보답합니다. 또한 많은 “어제는 작동했는데"라는 문제들이 여기서 비롯됩니다.

구성 및 상태 저장 위치

Hermes 는 ~/.hermes 에서 설정과 상태를 저장합니다. 공식 구성 가이드는 layout 를 문서화하며, 설정을 위한 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 는 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 프로필은 격리를 제공합니다. 각 프로필은 고유한 구성, 비밀, 메모리, 세션, 스킬, cron 작업, 게이트웨이 상태를 가진 고유한 디렉터리를 갖습니다.

일반적인 워크플로우

Hermes 를 계속 둘 에이전트처럼 다룬다면, 워크플로우는 서비스 엔지니어링처럼 보입니다.

안정적인 베이스라인

부패하지 않는 베이스라인은 다음과 같습니다:

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

누적되는 일상 사용

Hermes 는 웹 UI 가 아닌 터미널 UI 를 가지며, 슬래시 명령, 재개 가능한 세션, 스트리밍 도구 출력을 위한 긴 세션을 위해 설계되었습니다.

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

  • 프로젝트에 대한 이름이 지정된 세션에서 작업을 실행
  • 컨텍스트가 너무 커지면 압축
  • Hermes 가 반복되는 루틴을 스킬로 전환하도록 허용
  • 도구 실행이 감사될 수 있도록 “질문"과 “행동"사이의 정신적 경계를 유지

24/7 접근을 위한 메시징 게이트웨이

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

설치는 hermes gateway setup을 통해 호출되며, 게이트웨이는 전경에서 실행되거나 사용자 서비스로 실행될 수 있습니다. CLI 참조는 run, install, start, stop, status, restart 와 같은 게이트웨이 하위 명령을 문서화합니다.

도구를 사용하는 봇의 보안은 중요합니다. 게이트웨이 문서는 특정 플랫폼에 대한 허용 목록과 일회성 페어링 코드를 발급하고 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 에 저장된 파일을 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 변수가 누락된 등 백엔드별 일반적인 원인을 지적합니다. 또한 샌드박스 구성에 의문이 있을 때 로컬로 되돌아가는 것이 유효한 디버깅 조치임을 언급합니다.

게이트웨이 문제의 경우, 메시징 가이드는 허용 목록과 페어링을 안전한 기본값으로 강조하며, 이는 많은 “봇이 침묵하는"사건이 실제로는 권한 부여가 제 역할을 하고 있음을 의미합니다.

참고 자료