Hermes Agent는 단순한 채팅 CLI라기보다, 오래 켜두며 기억과 스킬을 쌓는 개인 에이전트에 가깝습니다.
그래서 처음부터 Telegram, Discord, cron, MCP, 브라우저 자동화까지 한꺼번에 붙이면 오히려 어디서 깨졌는지 찾기 어렵습니다.

2026년 5월 8일 기준 공식 문서를 보면 가장 안전한 순서는 이렇습니다.

  1. 먼저 로컬 CLI에서 한 번 정상 대화가 되는지 확인합니다.
  2. 모델 provider와 인증을 안정화합니다.
  3. 세션 재개와 메모리를 확인합니다.
  4. 그 다음에 스킬, 브라우저, 메시징 게이트웨이, cron을 붙입니다.

바로 보기

먼저 준비할 것

Hermes Agent는 Linux, macOS, WSL2, Android Termux 경로를 지원합니다.
공식 문서는 네이티브 Windows를 지원하지 않는다고 설명하므로, Windows 사용자는 먼저 WSL2 안에서 시작하는 편이 맞습니다.

설치 전 최소로 결정할 것은 세 가지입니다.

1. 어디서 돌릴 것인가

처음에는 본인 노트북이나 개발용 VM에서 CLI만 돌리는 것을 추천합니다.
VPS에 항상 켜두는 봇으로 운영하는 것은 CLI가 정상 동작한 뒤에 하는 편이 안전합니다.

2. 어떤 모델 provider를 쓸 것인가

Hermes는 여러 provider를 지원합니다. 공식 Quickstart 기준으로는 Nous Portal, OpenAI Codex, Anthropic, OpenRouter, GitHub Copilot, Hugging Face, Bedrock, DeepSeek, NVIDIA, custom endpoint 같은 선택지가 있습니다.

초급자는 일단 하나만 고르는 편이 좋습니다.

  • 이미 OpenRouter API 키가 있다면 OpenRouter
  • Anthropic API 키나 Claude Max 기반 설정을 쓸 계획이면 Anthropic
  • GitHub Copilot 구독을 활용하려면 Copilot
  • 자체 vLLM, SGLang, Ollama류를 붙일 계획이면 custom endpoint

처음부터 fallback routing까지 넣으면 문제가 생겼을 때 원인 추적이 어려워집니다.

3. 터미널 권한을 어디까지 줄 것인가

Hermes는 터미널 명령을 실행할 수 있습니다.
공식 보안 문서 기준으로 위험 명령 승인, 컨테이너 격리, MCP 자격증명 필터링, 컨텍스트 파일 검사 같은 방어층이 있지만, 그래도 실제 파일과 서버에 접근하는 도구라는 점은 바뀌지 않습니다.

처음에는 manual 승인 모드와 로컬 테스트로 시작하고, 중요 환경에서는 Docker나 SSH backend 같은 격리 방식을 검토하는 편이 좋습니다.

1. 설치

공식 설치 명령은 아래 한 줄입니다.

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

공식 문서에 따르면 installer는 Python, Node.js, ripgrep, ffmpeg 같은 의존성, 저장소 clone, virtualenv, 전역 hermes 명령, provider 설정까지 자동으로 처리합니다.
다만 최소한 git은 준비되어 있어야 하므로 먼저 확인합니다.

git --version

설치가 끝나면 셸을 다시 로드합니다.

source ~/.bashrc
# zsh를 쓰면:
source ~/.zshrc

그 다음 진단 명령을 한 번 돌립니다.

hermes doctor

hermes: command not found가 나오면 설치 실패보다 PATH 반영 문제일 가능성이 큽니다. 이때는 새 터미널을 열거나 shell rc 파일을 다시 로드합니다.

2. 모델 설정

모델 설정은 hermes model로 시작하는 것이 가장 단순합니다.

hermes model

여기서 provider와 model을 고르고, 필요한 경우 API key나 OAuth 로그인을 진행합니다.

설정이 끝나면 바로 긴 작업을 맡기지 말고 짧은 테스트부터 합니다.

hermes chat -q "한 문장으로 자기소개해줘."

이 단계에서 답변이 비어 있거나 이상하면 아직 Hermes 문제가 아니라 provider 인증, 모델 이름, endpoint 설정 문제일 가능성이 큽니다.
공식 Quickstart도 base chat이 안 되는 상태에서는 gateway, cron, skills, voice, routing을 붙이지 말라고 안내합니다.

3. 첫 대화는 CLI에서 시작

대화형 세션은 그냥 hermes로 실행합니다.

hermes

Hermes CLI는 웹 UI가 아니라 터미널 인터페이스입니다.
멀티라인 입력, slash command 자동완성, 대화 기록, interrupt, streaming tool output을 지원합니다.

자주 쓰는 명령은 이 정도입니다.

/help       사용 가능한 명령 보기
/model      현재 모델 확인 또는 변경
/tools      활성화된 도구 확인
/usage      현재 세션 사용량 확인
/title      세션 이름 지정
/compress   긴 대화 압축

TUI 화면을 쓰고 싶으면 아래처럼 시작할 수 있습니다.

hermes --tui

긴 프롬프트를 넣을 때는 Alt+Enter 또는 Ctrl+J로 줄바꿈을 넣을 수 있습니다.
작업 중인 agent를 멈추고 새 지시를 넣고 싶으면 새 메시지를 입력하거나 Ctrl+C로 interrupt할 수 있습니다.

4. 세션 저장과 이어하기 확인

Hermes는 대화를 session으로 저장합니다.
공식 문서 기준으로 세션은 SQLite 데이터베이스와 JSONL transcript에 저장되며, CLI뿐 아니라 Telegram, Discord, Slack, WhatsApp, Email, cron, API server 같은 여러 source를 구분합니다.

처음 설치 후에는 반드시 resume이 되는지 확인하는 편이 좋습니다.

hermes --continue
hermes -c

특정 세션을 찾고 싶으면:

hermes sessions list
hermes --resume <session_id>

세션 이름을 붙여두면 나중에 찾기 쉽습니다.

/title my research setup

Hermes를 오래 쓰려면 이 단계가 중요합니다.
세션 재개가 안 되는 상태에서 gateway나 cron을 붙이면, 나중에 “기억을 못 한다”는 문제가 설정 문제인지 session 문제인지 구분하기 어려워집니다.

5. 메모리는 직접 확인하면서 키우기

Hermes의 장점 중 하나는 persistent memory입니다.
공식 문서 기준으로 기본 메모리는 두 파일로 나뉩니다.

  • ~/.hermes/memories/MEMORY.md: 환경, 프로젝트, 작업 규칙, 배운 점
  • ~/.hermes/memories/USER.md: 사용자 선호, 말투, 기대치, 업무 습관

단, 메모리는 무제한 저장소가 아닙니다.
공식 문서는 MEMORY.md와 USER.md에 문자 수 제한이 있고, 새 세션 시작 시점의 frozen snapshot으로 system prompt에 들어간다고 설명합니다.

처음에는 이렇게 짧게 시키는 편이 좋습니다.

내 기본 작업 환경을 기억해줘. 
OS는 Ubuntu, 주 프로젝트는 ~/work/blog, 답변은 한국어로 짧게 정리하는 걸 선호해.

중요한 주의점도 있습니다.

  • API key, token, 서버 비밀번호는 메모리에 저장하지 않습니다.
  • “아무거나 다 기억해”보다 정말 필요한 선호와 환경만 저장합니다.
  • 메모리가 바뀌어도 현재 세션의 system prompt에는 바로 반영되지 않을 수 있습니다. 새 세션에서 확인합니다.

6. 프로젝트에서 쓰는 방법

코드베이스나 문서 작업에 Hermes를 붙일 때는 프로젝트 루트에서 실행합니다.

cd ~/work/my-project
hermes

Hermes는 .hermes.md, AGENTS.md, CLAUDE.md, SOUL.md, .cursorrules 같은 context file을 감지해 프로젝트 지침으로 사용할 수 있습니다.

예를 들어 프로젝트 루트에 .hermes.md를 만들 수 있습니다.

# Project Rules

- 변경 전 관련 파일을 먼저 읽는다.
- 테스트가 있으면 수정 후 실행한다.
- 배포 스크립트와 secrets 파일은 건드리지 않는다.
- 한국어로 짧게 작업 요약을 남긴다.

파일이나 diff를 직접 넣고 싶을 때는 @ reference 기능을 쓸 수 있습니다.
공식 기능 설명에 따르면 Hermes는 파일, 폴더, git diff, URL 같은 reference를 메시지에 주입할 수 있습니다.

7. 도구와 스킬은 나중에 켜기

기본 대화가 안정화되면 도구 설정을 봅니다.

hermes tools

도구를 너무 많이 켜면 agent가 할 수 있는 일이 많아지는 대신, 실수 범위도 넓어집니다.
처음에는 terminal, web, file 관련 도구를 필요한 만큼만 열어두는 편이 좋습니다.

스킬은 반복 작업을 줄이는 용도입니다.

hermes skills search kubernetes
hermes skills install openai/skills/k8s

특정 스킬을 세션 시작부터 로드할 수도 있습니다.

hermes -s hermes-agent-dev,github-auth
hermes chat -s github-pr-workflow -q "open a draft PR"

스킬은 편하지만, 처음부터 많이 넣으면 system prompt가 무거워지고 동작을 예측하기 어려워질 수 있습니다. 자주 쓰는 것만 남기는 편이 좋습니다.

8. 메시징 게이트웨이 붙이기

CLI가 잘 동작하면 그 다음에 gateway를 붙입니다.

hermes gateway setup

공식 문서 기준으로 gateway는 Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, Mattermost, Matrix, Teams 등 여러 플랫폼을 연결하는 background process입니다.
설정 후에는 foreground로 실행하거나 service로 설치할 수 있습니다.

hermes gateway
hermes gateway install
hermes gateway start
hermes gateway status

VPS처럼 재부팅 후에도 살아 있어야 하는 환경에서는 system service를 검토할 수 있습니다.

sudo hermes gateway install --system
sudo hermes gateway start --system
sudo hermes gateway status --system

가장 중요한 것은 사용자 제한입니다.
공식 문서 기준으로 gateway는 allowlist나 DM pairing으로 허용된 사용자가 아니면 기본적으로 거부하는 구조입니다.

예시는 이런 식입니다.

TELEGRAM_ALLOWED_USERS=123456789
DISCORD_ALLOWED_USERS=111222333444555666
GATEWAY_ALLOWED_USERS=123456789

GATEWAY_ALLOW_ALL_USERS=true는 공개 봇처럼 열리는 설정이라 일반적인 개인 agent 운영에는 권장하기 어렵습니다.
Hermes는 터미널과 파일에 접근할 수 있으므로, 메시징 bot을 열어두는 순간 서버 운영 문제가 됩니다.

9. 보안 설정에서 꼭 볼 것

Hermes의 위험 명령 승인은 기본적으로 manual 모드입니다.
공식 보안 문서는 세 가지 모드를 설명합니다.

  • manual: 위험 명령 실행 전 사용자에게 묻기
  • smart: 보조 LLM이 위험도를 판단하고 불확실하면 사용자에게 묻기
  • off: 승인 검사 끄기

처음에는 manual을 유지하는 편이 좋습니다.

approvals:
  mode: manual
  timeout: 60

--yolo나 /yolo는 승인 프롬프트를 우회합니다.
테스트용 disposable 환경이 아니라면 습관적으로 켜지 않는 편이 맞습니다.

파일 수정이나 명령 실행이 잦다면 Docker backend도 검토합니다.

hermes config set terminal.backend docker

공식 Quickstart도 sandboxed terminal을 다음 단계로 안내합니다.
중요한 프로젝트나 서버에서는 agent가 직접 host 파일을 만지는지, Docker volume을 통해 제한된 경로만 만지는지 명확히 정해야 합니다.

10. 자주 막히는 지점

hermes 명령이 안 보인다

설치 후 셸 PATH가 아직 반영되지 않았을 수 있습니다.

source ~/.bashrc
which hermes

답변이 비거나 이상하다

대부분 provider 설정 문제입니다.

hermes model
hermes chat -q "ping"

provider routing이나 fallback 설정은 base chat이 안정화된 뒤에 켭니다.

gateway는 켜졌는데 메시지가 안 온다

bot token, allowlist, platform 설정을 다시 봅니다.

hermes gateway setup
hermes gateway status

알 수 없는 사용자는 pairing code를 받을 수 있고, owner가 CLI에서 승인할 수 있습니다.

hermes pairing list
hermes pairing approve telegram ABC12DEF

이어하기가 안 된다

다른 profile에서 실행했거나 세션이 저장되지 않았을 수 있습니다.

hermes sessions list
hermes --continue

설정이 꼬였다

공식 Quickstart의 recovery 순서대로 가면 됩니다.

hermes doctor
hermes model
hermes setup
hermes sessions list
hermes --continue
hermes gateway status

추천 사용 순서

초급자라면 이렇게 나누는 편이 좋습니다.

첫날

  • 설치
  • hermes model
  • hermes chat -q "Hello"
  • hermes
  • /help, /model, /tools 확인
  • hermes --continue 확인

둘째 날

  • ~/.hermes/memories/ 구조 확인
  • 간단한 사용자 선호 저장
  • 프로젝트 루트에서 .hermes.md 작성
  • hermes tools로 필요한 도구만 확인

셋째 날 이후

  • hermes skills로 반복 작업 스킬 추가
  • hermes gateway setup으로 Telegram/Discord/Slack 중 하나만 연결
  • allowlist 또는 pairing 설정
  • 필요하면 Docker backend나 원격 backend 검토

한 줄 결론

Hermes Agent는 설치보다 순서가 중요합니다.
처음부터 모든 기능을 붙이지 말고, CLI에서 한 번 깨끗하게 대화가 되는지 확인한 뒤 모델, 세션, 메모리, 스킬, 게이트웨이 순서로 확장하는 것이 가장 덜 헤맵니다.

같이 보면 좋은 글

출처