Hermes Agent: 실무자용 참고서 (2026)

TL;DR: Hermes Agent는 Nous Research에서 만든 오픈소스 자기 개선형 AI 에이전트입니다. CLI와 멀티 플랫폼 메시징 gateway로 동작하며, 영속적인 정체성과 지속적인 메모리를 디스크에 저장하고, 사용할수록 발전하는 skill을 통합 관리하며, OpenAI 호환 LLM 제공자라면 무엇이든 — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Alibaba, Hugging Face, Google 또는 직접 자체 호스팅한 엔드포인트까지 — 함께 사용할 수 있습니다.¹² 대부분의 신규 사용자가 가장 어려워하는 부분은 제공자 인증입니다. Hermes는 약 19개의 1급 제공자와 커스텀 엔드포인트를 지원하며, 세 가지 서로 다른 인증 경로(.env의 API 키, hermes model을 통한 OAuth, config.yaml의 커스텀 엔드포인트)를 제공합니다. 가장 먼저 익혀야 할 것은 인증 모델입니다 — 그 외 모든 것은 어떤 제공자가 선택되었는지에 따라 달라지는 후속 단계일 뿐입니다.

Hermes Agent는 채팅 래퍼가 아니라 완전한 에이전트 런타임으로 동작합니다. 파일 시스템을 읽고, 샌드박스화된 백엔드에서 명령을 실행하며, 웹을 스크레이핑하고, 서브에이전트를 생성하고, 예약된 cron 작업을 수행하며, 단일 gateway 프로세스에서 Telegram/Discord/Slack/WhatsApp/Signal/Email과 통신하고, 경험을 통해 자체 skill을 만들어냅니다.¹ CLI는 run_agent.py의 대화 루프 위에 구축된 터미널 UI이며, gateway는 동일한 대화 루프를 통해 메시징 플랫폼의 메시지를 라우팅하는 장기 실행 프로세스입니다.³

Hermes를 가볍게 사용하는 것과 전문가 수준으로 사용하는 것의 차이는 다섯 가지 시스템에서 결정됩니다. 이를 익히면 Hermes는 강력한 증폭기가 됩니다.

1. 제공자 해석(Provider resolution): 인증 흐름이 API 호출에 매핑되는 방식
2. 설정 계층 구조: config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. Tool + toolset 시스템: 에이전트가 할 수 있는 작업과 플랫폼별 권한 제어
4. Skill 시스템: 에이전트가 생성하고 발전시키는 절차적 메모리
5. Gateway + cron + profile: Hermes를 단순히 머무는 곳이 아니라 실제 생활하는 곳에서 실행하기

핵심 요약

• 제공자 인증은 하나가 아니라 세 가지 경로입니다. .env의 API 키, hermes model/hermes auth를 통한 OAuth, 또는 config.yaml의 커스텀 엔드포인트입니다. 익숙한 경로가 아니라 제공자에 맞는 경로를 선택하세요.
• 제공자 전환은 단 하나의 명령으로 가능합니다. hermes model은 OAuth 로그인을 포함한 모든 지원 제공자를 대화형으로 안내하며, /model provider:model은 대화 기록을 잃지 않고 세션 중간에 전환할 수 있게 해줍니다.²
• 사용자가 편집하는 설정 파일은 두 개입니다. ~/.hermes/config.yaml에는 설정이, ~/.hermes/.env에는 비밀 정보가 들어 있습니다. auth.json, SOUL.md, MEMORY.md, skills/는 Hermes가 직접 관리합니다 — SOUL.md는 직접 편집할 수 있지만, 나머지는 에이전트 자체가 관리합니다.⁴
• Hermes는 OpenClaw의 후속작입니다. 마이그레이션을 진행 중이라면 hermes claw migrate가 30개 이상의 상태 카테고리를 자동으로 가져옵니다.⁵
• 서비스 품질은 보조(auxiliary) 모델에 따라 달라집니다. 비전, 웹 요약, 압축, 메모리 플러시는 모두 별도의 보조 LLM를 사용합니다. 기본값은 자동 감지(OpenRouter → Nous → Codex)를 통한 Gemini Flash이며 — 이 중 어느 것도 설정되지 않은 경우 보조 슬롯을 메인 제공자로 지정할 때까지 해당 기능들이 조용히 저하됩니다.⁴

아래의 모든 섹션은 hermes-agent.nousresearch.com/docs의 업스트림 문서와 github.com/NousResearch/hermes-agent의 소스 트리를 근거로 합니다. 모든 사실 관계 주장에는 출처가 된 특정 업스트림 페이지를 가리키는 각주가 달려 있습니다.

경로 선택

Hermes 작동 방식: 멘탈 모델

Hermes는 모든 진입점에서 호출할 수 있는 단일 대화 루프를 중심으로 설계되어 있어요. 진입점으로는 CLI(cli.py), 메시징 gateway(gateway/run.py), 편집기 통합을 위한 ACP 어댑터, 배치 실행기, 그리고 API 서버가 있습니다.³ 이들 모두 궁극적으로 run_agent.py의 AIAgent.run_conversation()을 호출하며, 이 함수는 다음과 같이 동작해요:

1. prompt_builder.py를 통해 SOUL.md, MEMORY.md, USER.md, skills, 컨텍스트 파일, 도구 안내를 조합하여 시스템 프롬프트를 구성합니다³
2. runtime_provider.py를 통해 런타임 프로바이더를 결정합니다 — 이 단계에서 인증, 기본 URL, API 모드가 선택돼요³
3. 세 가지 API 모드 중 하나를 사용하여 프로바이더를 호출합니다: chat_completions, codex_responses, 또는 anthropic_messages³
4. 반환된 도구 호출을 model_tools.py와 중앙 도구 레지스트리(tools/registry.py)를 통해 디스패치합니다³
5. 모델이 최종 응답을 생성할 때까지 루프를 반복한 후, FTS5가 적용된 SQLite에 세션을 저장합니다³

이 루프를 이해하는 것이 중요한 이유는 모든 기능 — 성격, 메모리, skills, 압축, 폴백 — 이 이 단계들 중 하나에 연결되기 때문이에요. 설정 키가 무엇을 하는지 궁금할 때, 답은 대개 “위 루프의 1, 2, 3, 4단계 중 하나를 조절하는 설정”입니다.

플랫폼에 독립적인 코어. 하나의 AIAgent 클래스가 CLI, gateway, ACP, 배치, API 서버를 모두 처리해요. 플랫폼별 차이는 진입점에만 존재하며, 에이전트 자체에는 없습니다.³ 같은 슬래시 명령어가 터미널과 Telegram에서 모두 작동하는 이유가 바로 이것입니다 — hermes_cli/commands.py의 공유 COMMAND_REGISTRY에서 디스패치되기 때문이에요.⁶

디렉토리 구조가 곧 시스템입니다. Hermes는 모든 것을 ~/.hermes/(기본이 아닌 profile의 경우 $HERMES_HOME) 아래에 저장합니다:⁴

~/.hermes/
├── config.yaml        # Settings (model, terminal, TTS, compression, etc.)
├── .env               # API keys and secrets
├── auth.json          # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md            # Primary agent identity (slot #1 in system prompt)
├── memories/          # Persistent memory (MEMORY.md, USER.md)
├── skills/            # Bundled + agent-created + hub-installed skills
├── cron/              # Scheduled jobs
├── sessions/          # Gateway session state
└── logs/              # agent.log, gateway.log, errors.log (secrets auto-redacted)

위의 모든 파일은 각각 고유한 역할을 가지며 서로 겹치지 않아요. “Hermes가 X를 어디에 저장하는가”가 궁금하다면, 이 목록 중 하나에 해당합니다.

설치

원라인 설치 스크립트는 95%의 사용자에게 적합한 방법이에요. Python, uv, Node.js, ripgrep, ffmpeg, 저장소 클론, 가상 환경, 그리고 글로벌 hermes 명령어를 모두 처리합니다.⁷

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

Linux, macOS, WSL2, Android/Termux에서 동작합니다(설치 스크립트가 Termux를 자동 감지하여 테스트된 Android 번들로 전환해요).⁷ 네이티브 Windows는 지원되지 않습니다 — WSL2를 설치한 후 위 명령어를 실행하세요.⁷

설치가 완료된 후:

source ~/.bashrc    # or ~/.zshrc
hermes              # Start chatting

유일한 사전 요구 사항은 git이에요. 설치 스크립트가 uv를 통해 Python 3.11을(sudo 불필요), Node.js v22(브라우저 자동화 및 WhatsApp 브릿지용), ripgrep, ffmpeg를 자동으로 설치합니다.⁷

설치 확인

hermes version      # Check version
hermes doctor       # Diagnose config/dependency issues
hermes status       # Show current configuration + auth state
hermes dump         # Copy-pasteable setup summary for debugging

hermes doctor는 누락된 항목과 해결 방법을 정확히 알려줘요.⁷ hermes dump는 GitHub 이슈나 Discord 스레드에서 도움을 요청할 때 붙여넣기용 진단 명령어입니다 — 시크릿이 자동으로 가려진 전체 설정 요약을 일반 텍스트로 출력해요.⁸

수동 설치

완전한 제어가 필요한 경우 — 커스텀 Python 버전, 특정 extras, Nix/NixOS 통합 — 수동 설치 과정은 업스트림 설치 가이드에 단계별로 문서화되어 있어요.⁷ uv pip install -e ".[<extras>]"와 함께 조합할 수 있는 주요 선택적 extras는 다음과 같습니다:

Termux 설치 명령어는 다릅니다 — uv pip가 아닌 제약 조건 파일과 함께 pip을 사용해요:

python -m pip install -e ".[termux]" -c constraints-termux.txt

이는 Android에서 .[all]을 사용하면 voice extra를 통해 faster-whisper를 가져오는데, 이것이 Android용으로 배포되지 않은 ctranslate2 휠에 의존하기 때문이에요.⁷

인증 및 제공자

Hermes는 약 19개의 일급 제공자와 사용자 정의 엔드포인트를 지원하며, 세 가지 별개의 인증 경로를 제공합니다. 다음은 전체 인증 영역을 경로별로 정리한 것이므로, 보유하신 자격 증명에 맞는 경로를 찾으실 수 있습니다.

세 가지 인증 경로

Hermes의 모든 제공자는 다음 세 가지 인증 패턴 중 하나에 해당합니다.

경로 1 — .env 파일의 API 키. ~/.hermes/.env에 키를 넣어두면 Hermes가 시작 시 이를 읽어들입니다. OpenRouter, AI Gateway, z.ai/GLM, Kimi/Moonshot, MiniMax(및 MiniMax China), Alibaba Cloud/DashScope, Kilo Code, OpenCode Zen, OpenCode Go, DeepSeek, Hugging Face, Google/Gemini, 그리고 대부분의 서드파티 제공자가 이 방식을 사용합니다.²

경로 2 — hermes model 또는 hermes auth를 통한 OAuth. 디바이스 코드 플로우를 시작하고 브라우저를 열어 자격 증명을 ~/.hermes/auth.json에 저장합니다(Claude Code 또는 Codex CLI와 같은 도구의 기존 자격 증명을 가져올 수도 있습니다). Nous Portal, OpenAI Codex(ChatGPT 계정), GitHub Copilot, 그리고 Anthropic(Claude Pro/Max)가 이 방식을 사용합니다.²

경로 3 — config.yaml의 사용자 정의 엔드포인트. OpenAI 호환 API라면 무엇이든 가능합니다 — Ollama, vLLM, SGLang, llama.cpp, LM Studio, LiteLLM 프록시, Together AI, Groq, Azure OpenAI, 또는 직접 셀프 호스팅한 서버. hermes model → Custom endpoint를 통해 한 번 구성하면 config.yaml에 영구 저장됩니다.²

전체 제공자 매트릭스

다음은 일급 제공자의 전체 목록과 각각의 정확한 설정 흐름입니다.²

Anthropic: 세 가지 인증 방법

Anthropic가 별도의 섹션을 갖는 이유는 Hermes가 Claude로 진입하는 세 가지 별개의 경로를 지원하며, 올바른 경로를 선택하는 것이 중요하기 때문입니다. 업스트림 문서에서 인용:²

# Method 1: API key (pay-per-token)
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6

# Method 2: OAuth through hermes model (preferred)
# Uses Claude Code's credential store when available
hermes model

# Method 3: Manual setup-token (fallback/legacy)
export ANTHROPIC_TOKEN=***
hermes chat --provider anthropic

# Auto-detect Claude Code credentials
hermes chat --provider anthropic   # reads Claude Code files automatically

hermes model을 통해 Anthropic OAuth를 선택하면, Hermes는 토큰을 ~/.hermes/.env로 복사하기보다 Claude Code의 자체 자격 증명 저장소를 우선시합니다. 이렇게 하면 갱신 가능한 Claude 자격 증명이 갱신 가능한 상태로 유지됩니다.² 동일한 머신에서 이미 Claude Code를 사용하고 계시다면, 이 방법이 가장 깔끔한 경로입니다.

config.yaml에 Anthropic를 영구적으로 고정하려면 다음과 같이 설정합니다:

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"

--provider claude 및 --provider claude-code도 --provider anthropic의 단축형으로 동작합니다.²

GitHub Copilot: 두 가지 모드

Copilot은 두 가지 모드로 지원됩니다: 직접 Copilot API(권장) 그리고 Copilot ACP(로컬 Copilot CLI를 서브프로세스로 생성).²

# Direct Copilot API
hermes chat --provider copilot --model gpt-5.4

# Copilot ACP (requires the Copilot CLI in PATH + an existing copilot login)
hermes chat --provider copilot-acp --model copilot-acp

업스트림 문서에 따르면, 인증은 다음 순서로 확인됩니다:² 1. COPILOT_GITHUB_TOKEN 환경 변수 2. GH_TOKEN 환경 변수 3. GITHUB_TOKEN 환경 변수 4. gh auth token CLI 폴백 5. hermes model을 통한 OAuth 디바이스 코드 로그인

토큰 유형이 중요합니다. Copilot API는 클래식 Personal Access Token(ghp_*)을 지원하지 않습니다. 지원되는 유형은 OAuth 토큰(gho_*), 세분화된 PAT(Copilot Requests 권한이 있는 github_pat_*), 그리고 GitHub App 토큰(ghu_*)입니다. gh auth token이 ghp_* 토큰을 반환한다면, hermes model을 사용하여 OAuth로 인증하시기 바랍니다.²

중국 AI 제공자(일급 지원)

Hermes는 z.ai/GLM, Kimi/Moonshot, MiniMax(글로벌 + 중국 엔드포인트), 그리고 Alibaba Cloud에 대해 전용 제공자 ID로 내장 지원을 제공합니다.²

# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5                 # Requires: GLM_API_KEY

# Kimi / Moonshot AI
hermes chat --provider kimi-coding --model kimi-for-coding   # Requires: KIMI_API_KEY

# MiniMax (global)
hermes chat --provider minimax --model MiniMax-M2.7          # Requires: MINIMAX_API_KEY

# MiniMax (China)
hermes chat --provider minimax-cn --model MiniMax-M2.7       # Requires: MINIMAX_CN_API_KEY

# Alibaba Cloud / DashScope (Qwen)
hermes chat --provider alibaba --model qwen3.5-plus          # Requires: DASHSCOPE_API_KEY

베이스 URL은 GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL, MINIMAX_CN_BASE_URL, 또는 DASHSCOPE_BASE_URL 환경 변수로 재정의할 수 있습니다.²

Z.AI는 엔드포인트를 자동 감지합니다. z.ai/GLM 제공자를 사용할 때, Hermes는 여러 엔드포인트(글로벌, 중국, 코딩 변형)를 탐색하여 API 키를 수락하는 엔드포인트를 찾습니다. 작동하는 엔드포인트는 자동으로 캐싱되므로, 대부분의 사용자는 GLM_BASE_URL이 필요하지 않습니다.²

xAI(Grok)는 프롬프트 캐싱을 자동으로 활성화합니다. 베이스 URL에 x.ai가 포함되어 있으면, Hermes는 모든 요청과 함께 x-grok-conv-id 헤더를 전송하여 대화 세션 내에서 동일한 서버로 라우팅하고 캐시된 시스템 프롬프트와 히스토리를 재사용합니다.² 자동으로 처리되며, 별도 설정이 필요 없습니다.

hermes auth 명령

hermes auth는 풀 및 OAuth 자격 증명을 위한 자격 증명 관리 명령입니다.⁶

hermes auth                              # Interactive wizard
hermes auth list                         # Show all credential pools
hermes auth list openrouter              # Show one provider's pool
hermes auth add openrouter --api-key sk-or-v1-xxx
hermes auth add anthropic --type oauth
hermes auth remove openrouter 2          # Remove by index
hermes auth reset openrouter             # Clear cooldowns

자격 증명 풀은 동일한 제공자에 대해 여러 API 키나 OAuth 토큰을 로테이션하는 방법입니다 — 코드를 변경하지 않고도 여러 키에 걸쳐 속도 제한을 분산시키는 데 유용합니다.⁶ 레거시 hermes login / hermes logout 명령은 제거되었으니, 대신 hermes auth를 사용하시기 바랍니다.⁶

사용자 정의 및 셀프 호스팅 엔드포인트

Hermes는 모든 OpenAI 호환 API 엔드포인트와 함께 작동합니다. 서버가 /v1/chat/completions를 구현한다면, Hermes를 그쪽으로 향하게 할 수 있습니다.²

대화형 설정(권장):

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter: API base URL, API key, Model name

수동 config.yaml:

model:
  default: your-model-name
  provider: custom
  base_url: http://localhost:8000/v1
  api_key: your-key-or-leave-empty-for-local

두 접근 방식 모두 config.yaml에 영구 저장되며, 이는 메인 모델, 제공자, 베이스 URL의 단일 소스입니다.² 레거시 환경 변수 OPENAI_BASE_URL과 LLM_MODEL은 더 이상 메인 모델 구성에 사용되지 않습니다 — hermes model을 사용하거나 config.yaml을 직접 편집하시기 바랍니다.² (OPENAI_BASE_URL + OPENAI_API_KEY는 보조 provider: "main" 라우팅 경로의 폴백으로 여전히 유효하므로, 그곳에서 사용 중이라면 무작정 삭제하지 마세요.)⁴

세션 중 사용자 정의 엔드포인트 전환:

/model custom:qwen-2.5             # Custom endpoint with explicit model
/model custom                      # Auto-detect the model from the endpoint
/model custom:local:qwen-2.5       # Named custom provider "local"
/model custom:work:llama3          # Named custom provider "work"
/model openrouter:claude-sonnet-4  # Back to a cloud provider

/model custom(모델명 없이)은 엔드포인트의 /v1/models API를 쿼리하여 정확히 하나의 모델만 로드되어 있는 경우 자동으로 선택합니다 — 단일 모델을 실행 중인 로컬 서버에 유용합니다.²

로컬 LLM 서버(설정 템플릿)

업스트림 문서에는 Ollama, vLLM, SGLang, llama.cpp, 그리고 LM Studio에 대한 전체 설정 가이드가 있습니다. 다음은 실제로 실행하실 핵심 명령들입니다. 각각은 Hermes가 가리킬 수 있는 작동하는 엔드포인트를 만들도록 설계되었습니다.²

Ollama — 가장 쉬운 로컬 경로, 별도 설정 불필요:

ollama pull qwen2.5-coder:32b
OLLAMA_CONTEXT_LENGTH=32768 ollama serve   # Raise from 4k default
hermes model   # Custom endpoint → http://localhost:11434/v1 → qwen2.5-coder:32b

중요한 Ollama 함정: Ollama는 매우 낮은 컨텍스트 길이(24GB VRAM 미만에서 4,096 토큰)를 기본값으로 사용합니다. OLLAMA_CONTEXT_LENGTH 또는 Modelfile을 통해 반드시 이를 높여야 합니다 — OpenAI 호환 API는 클라이언트로부터 컨텍스트 길이를 받아들이지 않으므로, Hermes가 이를 설정해 줄 수 없습니다.² 에이전트 사용 시 최소 16k–32k로 설정하시기 바랍니다.

vLLM — 고성능 GPU 서빙:

pip install vllm
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --port 8000 \
  --max-model-len 65536 \
  --tensor-parallel-size 2 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

도구 호출에는 --enable-auto-tool-choice와 --tool-call-parser <name>이 필요합니다. 지원되는 파서: hermes(Qwen 2.5, Hermes 2/3), llama3_json, mistral, deepseek_v3, deepseek_v31, xlam, pythonic. 이 플래그들 없이는 도구 호출이 일반 텍스트로 반환됩니다.²

SGLang — KV 캐시 재사용을 위한 RadixAttention을 갖춘 빠른 서빙:

pip install "sglang[all]"
python -m sglang.launch_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --port 30000 \
  --context-length 65536 \
  --tp 2 \
  --tool-call-parser qwen

SGLang 함정: 기본 max_tokens는 128입니다. 응답이 잘리는 경우, 서버에서 --default-max-tokens를 설정하거나 config.yaml에서 model.max_tokens를 구성하시기 바랍니다.²

llama.cpp / llama-server — CPU 및 Apple Silicon Metal:

./build/bin/llama-server \
  --jinja -fa \
  -c 32768 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

도구 호출에는 --jinja가 필수입니다. 이것 없이는 llama-server가 tools 매개변수를 완전히 무시하며, 모델은 응답 텍스트에 JSON를 작성하여 도구를 호출하려 시도합니다 — Hermes는 이를 실제 도구 호출로 파싱할 수 없습니다.²

LM Studio — GUI를 갖춘 데스크톱 앱:

LM Studio 앱(Developer 탭 → Start Server)에서 서버를 시작하거나, CLI를 통해 시작합니다: lms server start(포트 1234에서 시작) 그리고 lms load qwen2.5-coder --context-length 32768.² 그런 다음 hermes model을 http://localhost:1234/v1로 향하게 합니다.

중요한 LM Studio 함정: LM Studio는 모델 메타데이터에서 컨텍스트 길이를 읽지만, 많은 GGUF 모델이 2048 또는 4096을 기본값으로 보고합니다. 항상 LM Studio 모델 설정에서 컨텍스트 길이를 명시적으로 설정하시기 바랍니다 — 모델 선택기 옆의 톱니바퀴 아이콘을 클릭하고, “Context Length”를 최소 16384(가급적이면 32768)로 설정한 다음, 모델을 다시 로드하세요.²

명명된 사용자 정의 제공자

여러 사용자 정의 엔드포인트(예: 로컬 개발 서버와 원격 GPU 서버)를 사용하는 경우, config.yaml에 명명된 사용자 정의 제공자로 정의할 수 있습니다:²

custom_providers:
  - name: local
    base_url: http://localhost:8080/v1
    # api_key omitted — Hermes uses "no-key-required" for keyless local servers
  - name: work
    base_url: https://gpu-server.internal.corp/v1
    api_key: corp-api-key
    api_mode: chat_completions      # optional, auto-detected from URL
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    api_key: proxy-key
    api_mode: anthropic_messages    # for Anthropic-compatible proxies

그런 다음 트리플 구문으로 세션 중에 이들 사이를 전환할 수 있습니다:

/model custom:local:qwen-2.5
/model custom:work:llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4

대화형 hermes model 메뉴에서도 명명된 사용자 정의 제공자를 선택할 수 있습니다.²

플러그인 가능한 제공자 아키텍처(v0.13.0+)

v0.13.0은 ProviderProfile ABC와 plugins/model-providers/ 디렉터리를 함께 제공하여, 서드파티 추론 제공자가 코어 수정 없이 추가될 수 있도록 합니다.¹⁸ 제공자가 OpenAI, Anthropic, 또는 Codex 호환 API 모드로 통신한다면, 인증 경로, 베이스 URL, 모델 카탈로그, 캐싱 헤더를 선언하는 ProviderProfile 서브클래스를 구현하실 수 있습니다. Hermes는 내장 제공자가 사용하는 것과 동일한 runtime_provider.py 경로를 통해 이를 해석합니다. 이것이 v0.13.0 제공자 확장 뒤에 있는 아키텍처적 변화입니다: 제공자를 추가하기 위해 코어 코드를 편집하는 대신, 플러그인을 출시합니다.

컨텍스트 길이 감지

업스트림 문서에 따르면, 두 가지 설정이 끊임없이 혼동됩니다:²

• context_length — 전체 컨텍스트 윈도우(입력 + 출력 토큰 예산의 합계, 예: Claude Opus 4.7의 경우 1,000,000 또는 Sonnet 4.6의 경우 200,000). Hermes는 이를 사용하여 히스토리를 언제 압축할지 결정합니다.
• model.max_tokens — 출력 한도(모델이 단일 응답에서 생성할 수 있는 최대 토큰 수). 히스토리 길이와는 관련이 없습니다.

자동 감지가 윈도우 크기를 잘못 가져올 때 context_length를 설정합니다:

model:
  default: "qwen3.5:9b"
  base_url: "http://localhost:8080/v1"
  context_length: 131072      # tokens

Hermes는 컨텍스트 윈도우를 감지하기 위해 다중 소스 해석 체인을 사용합니다: 구성 재정의 → 사용자 정의 제공자 모델별 설정 → 영구 캐시 → 엔드포인트 /models → Anthropic /v1/models → OpenRouter API → Nous Portal → models.dev(3800개 이상의 모델을 위한 커뮤니티 유지 레지스트리) → 폴백 기본값(128K).² 시스템은 제공자를 인식하므로, 동일한 모델이 누가 서빙하느냐에 따라 다른 컨텍스트 한도를 가질 수 있습니다(예: claude-opus-4.6은 Anthropic 직접에서 1M이지만 GitHub Copilot에서는 128K).²

제공자 로테이션 및 폴백

자격 증명 풀. 동일한 제공자에 대해 여러 API 키가 있는 경우, hermes auth를 통해 로테이션 전략을 구성합니다. 이것이 여러 키에 걸쳐 속도 제한을 분산시키는 방법입니다.⁶

폴백 모델. 기본 모델이 실패할 때(속도 제한, 서버 오류, 인증 실패) Hermes가 자동으로 전환할 백업 provider:model을 구성합니다:²

fallback_model:
  provider: openrouter            # required
  model: anthropic/claude-sonnet-4  # required
  # base_url: http://localhost:8000/v1    # optional, for custom endpoints
  # api_key_env: MY_CUSTOM_KEY           # optional, env var name

폴백은 대화를 잃지 않으면서 세션 중에 모델과 제공자를 교체합니다. 세션당 최대 한 번 발동됩니다.² 폴백에 지원되는 제공자: openrouter, nous, openai-codex, copilot, copilot-acp, anthropic, huggingface, zai, kimi-coding, minimax, minimax-cn, deepseek, ai-gateway, opencode-zen, opencode-go, kilocode, alibaba, custom.²

보조 모델

Hermes는 부가 작업에 경량 “보조” 모델을 사용합니다: 이미지 분석, 웹 페이지 요약, 브라우저 스크린샷 분석, 위험한 명령 승인 분류, 컨텍스트 압축, 세션 검색 요약, 스킬 매칭, MCP 도구 디스패치, 그리고 메모리 플러시.⁴ 기본적으로 자동 감지(OpenRouter → Nous → Codex)를 통해 Gemini Flash를 사용합니다.

각 보조 작업에 어떤 모델과 제공자를 사용할지 구성할 수 있습니다. 모든 보조 슬롯은 동일한 세 가지 제어 항목을 사용합니다: provider, model, base_url.⁴

auxiliary:
  vision:
    provider: "auto"                # "auto", "openrouter", "nous", "codex", "main", etc.
    model: ""                       # e.g. "openai/gpt-4o", "google/gemini-2.5-flash"
    base_url: ""                    # Custom OpenAI-compatible endpoint
    api_key: ""                     # Falls back to OPENAI_API_KEY
    timeout: 30
    download_timeout: 30
  web_extract:
    provider: "auto"
    model: ""
    timeout: 360
  approval:
    provider: "auto"
    model: ""
    timeout: 30
  compression:
    timeout: 120
  session_search: { provider: "auto", model: "", timeout: 30 }
  skills_hub:    { provider: "auto", model: "", timeout: 30 }
  mcp:           { provider: "auto", model: "", timeout: 30 }
  flush_memories:{ provider: "auto", model: "", timeout: 30 }

"main" 제공자 옵션은 “내 메인 에이전트가 사용하는 어떤 제공자든 사용한다”는 의미입니다 — auxiliary:, compression:, 그리고 fallback_model: 구성 내부에서만 유효합니다. 최상위 model.provider 설정에는 유효하지 않습니다. 메인 모델로 사용자 정의 OpenAI 호환 엔드포인트를 사용하시는 경우, model: 섹션에 provider: custom을 설정하시기 바랍니다.⁴

이것이 중요한 이유: Anthropic OAuth만 구성하셨다면(OpenRouter 키 없이), 비전, 웹 요약, 그리고 압축 기능이 저하되거나 실패합니다. 기본 보조 폴백 체인이 OpenRouter를 먼저 시도하기 때문입니다. 보조 작업을 위해 OPENROUTER_API_KEY를 추가하시거나, 각 보조 슬롯을 메인 제공자를 사용하도록 재구성하시기 바랍니다:

auxiliary:
  vision:
    provider: "main"
  web_extract:
    provider: "main"

이는 신규 Hermes 사용자에게 가장 흔한 “내 기능이 조용히 작동하지 않음” 함정입니다.

구성 시스템

Hermes에는 계층화된 구성 시스템이 있습니다. 상위 계층이 하위 계층을 재정의하고, 계층 중 하나가 config.yaml에서 볼 수 없는 전역 프로바이더 레지스트리이기 때문에 우선순위를 이해하는 것이 필수적입니다.

구성 파일 레이아웃

업스트림 문서에 따르면 다음 파일들이 Hermes 구성을 구성합니다:⁴

~/.hermes/
├── config.yaml       # All settings (model, terminal, TTS, compression, memory, toolsets, ...)
├── .env              # Secrets (API keys, bot tokens, passwords)
├── auth.json         # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md           # Primary agent identity (slot #1 in system prompt)
├── memories/         # Persistent memory (MEMORY.md, USER.md)
├── skills/           # Bundled + agent-created + hub-installed skills
├── cron/             # Scheduled jobs
├── sessions/         # Gateway session state
└── logs/             # agent.log, gateway.log, errors.log (secrets auto-redacted)

config.yaml 대 .env — 둘 다 설정된 경우, 비밀이 아닌 설정에서는 config.yaml이 우선합니다.⁴ 규칙은 다음과 같습니다: - 시크릿 (API 키, 봇 토큰, 비밀번호) → .env - 그 외 모든 것 (모델, 터미널 백엔드, 압축 설정, 메모리 제한, toolset) → config.yaml

시크릿은 셸 스타일 보간을 사용하여 config.yaml에서 참조할 수 있습니다:⁴

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}
  delegation:
    api_key: ${DELEGATION_KEY}

구성 관리

hermes config                # View current configuration
hermes config show           # Same as above
hermes config edit           # Open config.yaml in your editor
hermes config set KEY VAL    # Set a specific value
hermes config path           # Print the config file path
hermes config env-path       # Print the .env file path
hermes config check          # Check for missing options (after updates)
hermes config migrate        # Interactively add missing options

예시:⁴

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # Saves to .env

hermes config check와 hermes config migrate는 모든 hermes update 이후에 실행해야 할 명령어입니다 — 파일에 아직 없는 새로 추가된 구성 옵션을 잡아냅니다.⁶

구성 우선순위

Hermes는 여러 소스에서 구성을 로드합니다. 여러 소스가 같은 값을 설정한 경우, 우선순위가 더 높은 소스가 우선합니다:⁴

1. CLI 인수 — hermes chat --model anthropic/claude-sonnet-4 (호출별 재정의)
2. 환경 변수 — 프로세스 시작 시 적용
3. config.yaml — 기본 설정 파일
4. .env — 시크릿 전용
5. 내장 기본값 — 다른 어떤 것도 값을 설정하지 않을 때 적용

CLI 플래그는 해당 단일 호출에서 항상 우선합니다. config.yaml은 장기적인 진실 소스입니다.

현지화 (v0.13.0+)

v0.13.0은 CLI 및 gateway 메시지에 대해 7개 로케일을 추가합니다: 중국어(간체), 일본어, 독일어, 스페인어, 프랑스어, 우크라이나어, 터키어.¹⁸ 문서는 현재 zh-Hans로만 현지화되어 있습니다. 로케일은 LC_ALL / LANG 환경 변수 또는 config.yaml의 명시적인 locale: 키에서 확인됩니다. 영어는 기본값이며, 번역이 아직 다루지 않은 문자열에 대한 진실 소스로 남아 있습니다.

profile — 여러 개의 격리된 Hermes 인스턴스

profile은 각자 고유한 구성, 세션, skill, 메모리, gateway PID를 가진 여러 격리된 Hermes 인스턴스를 제공합니다. 이를 통해 “업무용 Hermes”와 “개인용 Hermes”를 나란히 실행하면서 서로의 상태를 보지 않게 할 수 있습니다.⁶

hermes profile list
hermes profile create work --clone                  # Clone from current profile
hermes profile use work                             # Set sticky default
hermes profile alias work --name h-work             # Create wrapper script
hermes profile export work -o work-backup.tar.gz
hermes profile import work-backup.tar.gz --name restored
hermes -p work chat -q "Hello from work profile"    # One-off without switching

각 profile은 자체 HERMES_HOME(기본값 ~/.hermes-<name>/)을 가지므로, 여러 profile이 서로 충돌하지 않고 동시에 gateway를 실행할 수 있습니다.⁶³

CLI 명령어

이 섹션은 최상위 CLI 명령어에 대한 실무 참고 자료입니다. 코드 기반의 공식 참고 자료는 업스트림 CLI Commands Reference를 확인하세요.⁶

전역 옵션

hermes [global-options] <command> [subcommand/options]

최상위 명령어

hermes chat — 주요 진입점

hermes를 인수 없이 실행하면 대화형 채팅으로 진입합니다. hermes chat은 옵션을 지정할 수 있는 명시적 형태입니다:⁶

hermes chat -q "Summarize the latest PRs"           # One-shot, non-interactive
hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6
hermes chat --toolsets web,terminal,skills          # Enable specific toolsets
hermes chat --quiet -q "Return only JSON"           # Programmatic mode
hermes chat --worktree -q "Review repo and open a PR"

주요 옵션:

hermes setup — 전체 마법사

전체 설정 마법사를 실행하거나 특정 섹션으로 바로 진입합니다:⁶

hermes setup                 # Full wizard
hermes setup model           # Provider and model only
hermes setup terminal        # Terminal backend only
hermes setup gateway         # Messaging platforms only
hermes setup tools           # Tool enable/disable per platform
hermes setup agent           # Agent behavior only
hermes setup --non-interactive
hermes setup --reset         # Reset config to defaults before setup

hermes logs — 구조화된 로그 쿼리

hermes logs는 로그 파일에 tail -f를 사용하는 것보다 강력합니다. 레벨, 세션 ID, 시간 범위를 동시에 필터링할 수 있기 때문입니다.⁶

hermes logs                          # Last 50 lines of agent.log
hermes logs -f                       # Follow in real time
hermes logs gateway -n 100           # Last 100 lines of gateway.log
hermes logs --level WARNING --since 1h   # Warnings from the last hour
hermes logs --session abc123         # Filter by session ID substring
hermes logs errors --since 30m -f    # Follow errors.log from 30m ago
hermes logs list                     # List all log files with sizes

로그 파일은 ~/.hermes/logs/에 위치합니다:⁶ - agent.log — 모든 에이전트 활동 (API 호출, 도구 디스패치, 세션 생명주기, INFO+) - errors.log — 경고와 오류만 포함 (agent.log의 필터링된 하위 집합) - gateway.log — 메시징 gateway 활동 (플랫폼 연결, 디스패치, webhook)

로테이션은 Python의 RotatingFileHandler를 통해 자동으로 이루어집니다 — agent.log.1, agent.log.2 등의 파일을 확인하세요.⁶

hermes doctor — 진단

hermes doctor [--fix]는 문제가 발생했을 때 가장 먼저 실행해야 할 명령어입니다. 설정 유효성, 의존성 존재 여부, API 키 가용성, 서비스 상태를 확인하며, --fix 옵션으로 자동 복구를 시도할 수 있습니다.⁶

진단 정보를 다른 사람과 공유하려면 hermes dump을 사용하세요 — API 키가 마스킹된 간결한 일반 텍스트 요약을 생성하며, GitHub 이슈나 Discord 스레드에 바로 붙여넣을 수 있습니다.⁶

슬래시 명령

슬래시 명령은 활성 채팅 세션(CLI 또는 메시징 플랫폼) 내에서 실행됩니다. hermes_cli/commands.py의 공유 COMMAND_REGISTRY에서 디스패치되므로 대부분의 명령이 여러 표면에서 동일하게 작동합니다.⁹

세션 제어

설정 및 모델

/model 명령은 세션 중간에 provider를 전환하는 핵심 도구입니다.⁹

/model                              # Show current model and options
/model claude-sonnet-4              # Switch model (auto-detect provider)
/model zai:glm-5                    # Switch provider:model
/model custom:qwen-2.5              # Use model on custom endpoint
/model custom                       # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5        # Named custom provider
/model openrouter:anthropic/claude-sonnet-4   # Back to cloud

도구, skill 및 정보

동적 skill 슬래시 명령

설치된 모든 skill은 자동으로 슬래시 명령으로 노출됩니다.⁹

/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor
/excalidraw       # Just the skill name loads it and lets the agent ask what you need

또한 짧은 이름을 더 긴 프롬프트의 별칭으로 지정하는 quick command를 config.yaml에 정의할 수 있습니다.⁹

quick_commands:
  review: "Review my latest git diff and suggest improvements"
  deploy: "Run the deployment script at scripts/deploy.sh and verify the output"
  morning: "Check my calendar, unread emails, and summarize today's priorities"

그런 다음 CLI에서 /review, /deploy 또는 /morning을 입력하세요.

접두사 매칭

명령은 접두사 매칭을 지원합니다. /h를 입력하면 /help로, /mod는 /model로 해석됩니다. 접두사가 모호할 경우 레지스트리 순서상 첫 번째 등록이 우선합니다. 전체 명령 이름과 등록된 별칭은 항상 접두사 매칭보다 우선합니다.⁹

메시징 전용 명령

일부 명령은 메시징 플랫폼(Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant)에서만 작동합니다.⁹

• /status — 세션 정보 표시
• /sethome (별칭 /set-home) — 현재 채팅을 플랫폼 홈으로 표시
• /approve [session|always] — 보류 중인 위험 명령 승인
• /deny — 보류 중인 위험 명령 거부
• /update — Hermes Agent를 최신 버전으로 업데이트
• /commands [page] — 모든 명령과 skill 탐색 (페이지 매김)

그리고 일부는 CLI 전용입니다: /skin, /tools, /toolsets, /browser, /config, /cron, /skills, /platforms, /paste, /statusbar, /plugins.⁹

Tools 및 Toolsets

Hermes는 웹 검색, 브라우저 자동화, 터미널 실행, 파일 편집, 메모리, 위임, RL 학습, 메시지 전송, Home Assistant 통합 등을 포괄하는 폭넓은 내장 tool registry를 제공해요.¹⁰ Tools는 플랫폼별로 활성화하거나 비활성화할 수 있는 논리적 toolset으로 구성되어 있어요.

상위 수준 카테고리

일반적인 toolset 이름에는 web, terminal, file, browser, vision, image_gen, moa, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, clarify, homeassistant, rl이 포함돼요.¹⁰

Tools 관리하기

hermes chat --toolsets "web,terminal"       # Use specific toolsets
hermes tools                                # Interactive per-platform tool config
hermes tools --summary                      # Print enabled-tools summary

Tools는 /tools disable <name> 및 /tools enable <name>로 세션 중간에도 전환할 수 있으며, 이때 새 tool set이 적용되도록 세션이 재설정돼요.⁹

터미널 Backend

터미널 tool은 6가지 환경에서 명령을 실행할 수 있어요.¹⁰

hermes config set terminal.backend <name> 또는 config.yaml에서 backend를 전환하세요.

terminal:
  backend: docker      # or: local, ssh, singularity, modal, daytona
  cwd: "."             # Working directory
  timeout: 180         # Command timeout in seconds

SSH backend(보안을 위해 권장 — agent가 자기 코드를 수정할 수 없어요):¹⁰

terminal:
  backend: ssh

# In ~/.hermes/.env
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=myuser
TERMINAL_SSH_KEY=~/.ssh/id_rsa

Docker backend:

terminal:
  backend: docker
  docker_image: python:3.11-slim

컨테이너 리소스(docker, singularity, modal, daytona에 적용):¹⁰

terminal:
  container_cpu: 1
  container_memory: 5120          # MB (default 5GB)
  container_disk: 51200           # MB (default 50GB)
  container_persistent: true      # Persist filesystem across sessions

container_persistent: true를 사용하면 설치된 패키지, 파일, 설정이 세션 간에도 유지돼요.¹⁰

모든 컨테이너 backend는 보안 강화를 적용해 실행돼요. 읽기 전용 루트 파일 시스템(Docker), DAC_OVERRIDE, CHOWN, FOWNER를 제외한 모든 Linux capability 제거, 권한 상승 차단, PID 제한(256개 프로세스), 전체 namespace 격리, 볼륨을 통한 영구 작업공간을 포함해요.¹⁰

백그라운드 프로세스

터미널 tool은 명시적인 프로세스 관리와 함께 백그라운드 실행을 지원해요.¹⁰

terminal(command="pytest -v tests/", background=true)
# Returns: {"session_id": "proc_abc123", "pid": 12345}

process(action="list")                            # Show all running processes
process(action="poll", session_id="proc_abc123")  # Check status
process(action="wait", session_id="proc_abc123")  # Block until done
process(action="log", session_id="proc_abc123")   # Full output
process(action="kill", session_id="proc_abc123")  # Terminate
process(action="write", session_id="proc_abc123", data="y")  # Send input

PTY 모드(pty=true)는 Codex 및 Claude Code 같은 대화형 CLI tools를 사용할 수 있게 해줘요.¹⁰

Sudo

명령에 sudo가 필요하면 Hermes가 비밀번호를 요청해요(세션 동안 캐시됨). 또는 ~/.hermes/.env에 SUDO_PASSWORD를 설정하세요.¹⁰

Multi-Agent Kanban (v0.13.0+)

v0.13.0은 multi-agent 협업을 1급 프리미티브로 끌어올려요. 바로 agents와 재시작을 가로질러 작업, 상태, worker identity를 추적하는 영구 Kanban board예요.¹⁸ 이 board 덕분에 Hermes workers의 swarm은 끊긴 handoff에서 멈추는 대신 실제로 작업을 끝낼 수 있어요.

Kanban board는 target 쪽에서는 /goal(locked-target Ralph loop)과, spawn semantics 쪽에서는 기존 delegate_task tool과 자연스럽게 맞물려요. 그 결과 모든 agent가 다음에 무엇을 해야 하는지, 누가 하고 있는지, 무엇이 막혔는지에 대한 단일 진실 공급원을 공유하는 swarm 패턴이 만들어져요.

Skills 시스템

Skills는 agent가 필요할 때 로드할 수 있는 온디맨드 지식 문서예요. 토큰 사용량을 줄이기 위해 점진적 공개 패턴을 따르며, agentskills.io 공개 표준과 호환돼요.¹¹

모든 skills는 ~/.hermes/skills/에 있습니다 — 이곳이 기본 디렉터리이자 진실 공급원이에요. 새로 설치하면 번들 skills가 repo에서 복사됩니다. Hub에서 설치한 skills와 agent가 만든 skills도 여기에 저장돼요.¹¹

점진적 공개

Level 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Level 1: skill_view(name)        → Full content + metadata                 (varies)
Level 2: skill_view(name, path)  → Specific reference file                 (varies)

agent는 실제로 필요할 때만 skill 전체 콘텐츠를 로드해요.¹¹

SKILL.md 형식

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]      # Optional — restrict to OS platforms
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]     # Conditional activation
    requires_toolsets: [terminal]    # Conditional activation
    config:                          # Config.yaml settings
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Prompt for setup"
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

조건부 활성화

Skills는 사용 가능한 tools에 따라 자신을 표시하거나 숨길 수 있어요. 이는 fallback skills에 특히 유용합니다. 즉, premium tool을 사용할 수 없을 때만 나타나야 하는 무료 또는 로컬 대안이에요.¹¹

예: 내장 duckduckgo-search skill은 fallback_for_toolsets: [web]를 사용해요. FIRECRAWL_API_KEY가 설정되어 있으면 web toolset을 사용할 수 있고 agent는 web_search를 사용합니다. 이때 DuckDuckGo skill은 숨겨진 상태로 유지돼요. API key가 없으면 DuckDuckGo skill이 fallback으로 자동 표시됩니다.¹¹

Agent 관리 Skills

agent는 skill_manage tool을 통해 자체 skills를 만들고, 업데이트하고, 삭제할 수 있어요. 이것은 agent의 절차적 memory입니다. 즉, 사소하지 않은 workflow를 알아내면 나중에 다시 사용할 수 있도록 그 접근 방식을 skill로 저장해요.¹¹

agent가 skills를 만드는 경우:¹¹ - 복잡한 작업(5회 이상의 tool 호출)을 성공적으로 완료한 뒤 - 오류나 막다른 길을 만났고 작동하는 경로를 찾았을 때 - 사용자가 접근 방식을 수정해 주었을 때 - 사소하지 않은 workflow를 발견했을 때

작업:¹¹

Skill Hub

온라인 registries에서 skills를 탐색, 검색, 설치, 관리할 수 있어요.⁶¹¹

hermes skills browse                          # Browse all hub skills
hermes skills browse --source official        # Browse official optional skills
hermes skills search kubernetes               # Search all sources
hermes skills search react --source skills-sh # Search skills.sh directory
hermes skills inspect openai/skills/k8s       # Preview before installing
hermes skills install openai/skills/k8s       # Install with security scan
hermes skills install skills-sh/anthropics/skills/pdf --force
hermes skills check                           # Check for upstream updates
hermes skills update                          # Reinstall changed hub skills
hermes skills audit                           # Re-scan installed hub skills
hermes skills uninstall k8s
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills tap add myorg/skills-repo       # Add custom GitHub source

통합 hub 소스:¹¹

기본 GitHub taps(설정 없이 탐색 가능): openai/skills, anthropics/skills, VoltAgent/awesome-agent-skills, garrytan/gstack.¹¹

보안 스캔

hub에서 설치한 모든 skills는 데이터 유출, prompt injection, 파괴적 명령, 공급망 신호, 기타 위협을 확인하는 보안 scanner를 거쳐요.¹¹

신뢰 수준:¹¹

--force는 community skills의 위험하지 않은 정책 차단을 재정의할 수 있어요. 하지만 dangerous scan verdict는 재정의하지 않습니다.¹¹

외부 Skill 디렉터리

Hermes가 로컬 디렉터리와 함께 스캔할 추가 skill 디렉터리를 지정할 수 있어요.¹¹

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

Paths는 ~ 확장과 ${VAR} environment variable 치환을 지원해요. 외부 디렉터리는 읽기 전용입니다. agent가 skill을 만들거나 편집할 때는 항상 ~/.hermes/skills/에 씁니다. skill 이름이 두 위치 모두에 있으면 로컬 우선순위가 적용돼요.¹¹

지속 메모리

Hermes에는 세션 간에 유지되는 제한적이고 선별된 메모리가 있습니다. 에이전트의 메모리는 두 파일로 구성되며, 둘 다 ~/.hermes/memories/에 저장됩니다:¹²

둘 다 세션 시작 시 고정된 스냅샷으로 system prompt에 주입됩니다. 에이전트는 memory tool을 통해 자신의 메모리를 관리하며, add, replace, remove를 사용할 수 있습니다.¹²

고정 스냅샷 패턴: system prompt 주입은 세션 시작 시 한 번 캡처되고 세션 중에는 바뀌지 않습니다. 이는 의도된 동작입니다. 성능을 위해 LLM의 prefix cache를 보존하기 위해서입니다. 세션 중에 변경한 내용은 즉시 디스크에 저장되지만, 다음 세션 전까지는 system prompt에 나타나지 않습니다.¹²

저장할 내용

다음은 저장하세요(에이전트가 능동적으로 수행합니다):¹² - 사용자 선호 사항: “I prefer TypeScript over JavaScript” → user - 환경 정보: “This server runs Debian 12 with PostgreSQL 16” → memory - 수정 사항: “Don’t use sudo for Docker commands, user is in docker group” → memory - 규칙: “Project uses tabs, 120-char line width, Google-style docstrings” → memory - 완료된 작업: “Migrated database from MySQL to PostgreSQL on 2026-01-15” → memory

다음은 건너뛰세요:¹² - 사소하거나 명백한 정보 - 쉽게 다시 찾을 수 있는 사실 - 원시 데이터 덤프(메모리에 넣기에는 너무 큼) - 세션에만 해당하는 일시적 정보 - 이미 context 파일에 있는 정보

세션 검색

MEMORY.md와 USER.md 외에도 에이전트는 session_search tool을 사용해 과거 대화를 검색할 수 있습니다. 모든 CLI 및 메시징 세션은 SQLite(~/.hermes/state.db)에 저장되며, FTS5 전체 텍스트 검색을 지원합니다. 쿼리는 Gemini Flash 요약과 함께 관련 과거 대화를 반환합니다.¹²

외부 메모리 제공자

MEMORY.md와 USER.md를 넘어 더 깊은 지속 메모리를 위해 Hermes는 8개의 외부 메모리 제공자 플러그인인 Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, and Supermemory를 제공합니다.¹²

외부 제공자는 내장 메모리를 대체하지 않고 함께 실행되며, knowledge graph, semantic search, 자동 사실 추출, 세션 간 사용자 모델링 같은 기능을 추가합니다:⁶¹²

hermes memory setup         # Pick a provider and configure it
hermes memory status        # Check what's active
hermes memory off           # Disable external provider (built-in only)

한 번에 하나의 외부 제공자만 활성화할 수 있습니다. 내장 메모리는 항상 활성화되어 있습니다.⁶

세션 자동 재개 (v0.13.0+)

v0.13.0에서는 에이전트 작업 중단을 복구할 수 있습니다. gateway는 재시작 후 중단된 세션을 자동으로 재개합니다. /update 재시작은 업그레이드 중에도 세션 상태를 보존합니다. 개발 중 소스 파일이 다시 로드되어도 새 세션을 강제로 시작하지 않고 활성 세션을 유지합니다.¹⁸ 실제 효과는 다음과 같습니다. 오래 걸리는 gateway 작업과 cron 기반 작업은 프로세스가 재시작되어도 더 이상 context window를 초기화하지 않습니다.

Checkpoints v2 (v0.13.0+)

v0.13.0에서는 상태 지속성이 실제 가지치기, 디스크 보호 장치, 고아 shadow repo 없음을 갖춘 단일 저장소 설계로 다시 작성되었습니다.¹⁸ 이전 checkpoint 시스템은 오래 실행되는 profile 전반에서 디스크에 상태를 계속 쌓았습니다. v2 저장소는 로컬 checkpoint 저장소에 엄격한 상한을 두고, 그 증가를 유발하던 중복 bookkeeping을 제거합니다. 사용자 대상 설정 변경은 필요하지 않습니다. 다음 checkpoint 쓰기부터 v2 경로를 사용합니다.

Personality 및 SOUL.md

SOUL.md는 Hermes 인스턴스의 기본 정체성입니다. system prompt의 1번 슬롯을 차지하며, 하드코딩된 기본 정체성을 대체합니다.¹³

Hermes는 기본 SOUL.md를 ~/.hermes/SOUL.md(또는 사용자 지정 profile의 경우 $HERMES_HOME/SOUL.md)에 자동으로 생성합니다. 기존 사용자 파일은 절대 덮어쓰지 않습니다. Hermes는 HERMES_HOME에서만 SOUL.md를 로드하며, 현재 작업 디렉터리는 확인하지 않습니다. 이렇게 해서 personality가 프로젝트 간에 예측 가능하게 유지됩니다.¹³

SOUL.md에 들어갈 내용

지속적인 말투와 personality 지침에 사용하세요:¹³ - 어조 - 커뮤니케이션 스타일 - 직접성의 수준 - 기본 상호작용 스타일 - 스타일상 피해야 할 것 - Hermes가 불확실성, 의견 차이, 모호함을 다루는 방식

다음에는 덜 적합합니다:¹³ - 일회성 프로젝트 지침 - 파일 경로 - repo 규칙 - 임시 워크플로 세부 사항

이런 내용은 SOUL.md가 아니라 AGENTS.md에 들어갑니다.

SOUL.md vs AGENTS.md

Hermes 정체성 관리에서 가장 중요한 차이는 다음과 같습니다:¹³

SOUL.md - 정체성, 어조, 스타일, 커뮤니케이션 기본값, personality 수준의 동작.

AGENTS.md - 프로젝트 아키텍처, 코딩 규칙, tool 선호도, repo별 워크플로, 명령어, 포트, 경로, 배포 메모.

유용한 규칙은 이렇습니다. 어디서나 따라야 하는 내용이면 SOUL.md에 들어갑니다. 특정 프로젝트에 속한 내용이면 AGENTS.md에 들어갑니다.¹³

내장 Personality

Hermes는 /personality로 전환할 수 있는 내장 personality를 제공합니다:¹³

config.yaml의 사용자 지정 personality:¹³

agent:
  personalities:
    codereviewer: >
      You are a meticulous code reviewer. Identify bugs, security issues,
      performance concerns, and unclear design choices. Be precise and constructive.

그런 다음 /personality codereviewer로 전환하세요.

SOUL.md vs /personality

SOUL.md는 기준 말투입니다. /personality는 세션 수준의 오버레이입니다.¹³ 실용적인 기본 SOUL.md를 유지한 다음, 튜터링 대화에는 /personality teacher를, 브레인스토밍에는 /personality creative를 사용하세요.

Nous Tool Gateway (v0.10.0+)

Hermes Agent v0.10.0(2026년 4월 16일)부터 유료 Nous Portal 구독자는 기존 Portal 자격 증명으로 선별된 tool 세트에 대한 관리형 접근 권한을 얻습니다. 추가 API 키를 관리할 필요가 없습니다.²⁰ Hermes CLI 자체는 계속 MIT 라이선스이며 완전히 오픈 소스입니다. 달라진 점은 이제 Portal auth가 모델 추론 이상의 기능을 열어준다는 점입니다.

gateway에 포함된 것

작동 방식

gateway는 새로운 use_gateway 설정 필드를 통해 tool별로 opt-in합니다. hermes auth에 Portal 자격 증명이 있고 해당 tool에 대해 gateway를 활성화하면, 그 tool의 호출은 Portal을 통해 라우팅됩니다. 그렇지 않으면 직접 설정한 API 키가 있는 경우 그것을 사용합니다.

# config.yaml — per-tool gateway opt-in
tools:
  web_search:
    provider: firecrawl
    use_gateway: true          # route via Nous Portal subscription
  image_generation:
    provider: fal
    use_gateway: true

런타임 우선순위: gateway를 사용할 수 있고 tool에 use_gateway: true가 설정되어 있으면, 직접 API 키를 함께 설정했더라도 Hermes는 gateway를 우선합니다. 이는 청구에 중요합니다. gateway 호출은 직접 API 키의 잔액이 아니라 Portal 구독에서 차감됩니다.

gateway 활성화

hermes model                      # select Nous Portal (OAuth flow)
hermes tools                      # per-platform tool picker integrates gateway tools
hermes status                     # confirms gateway/subscription detection

별도의 hermes subscribe 또는 hermes login --portal 명령은 없습니다. 구독은 hermes auth에 이미 있는 Portal OAuth 자격 증명에서 자동으로 감지됩니다.

가격 및 접근

가격과 tier 이름은 Nous Portal 가격 페이지(https://portal.nousresearch.com/pricing)에 게시됩니다. 이 가이드에서는 tier를 나열하지 않습니다. tier는 Hermes CLI가 아니라 Portal 제품의 책임이며, Hermes 릴리스와 독립적으로 변경되기 때문입니다. https://portal.nousresearch.com/에서 가입하고 가격 페이지에서 현재 tier를 확인하세요.

지원 중단 안내

• HERMES_ENABLE_NOUS_MANAGED_TOOLS env var는 v0.10.0에서 제거되었습니다. 이제 관리형 tool은 tool별 use_gateway 설정 필드를 통해 활성화되며, Portal 구독 상태에 따라 사용 가능 여부가 결정됩니다.²⁰

프레이밍: 이 릴리스가 아닌 것

Hermes Agent CLI는 구독 뒤에 잠겨 있지 않습니다. 프로젝트는 여전히 MIT 라이선스이고, 모든 핵심 기능(CLI, skills, memory, messaging gateway, cron, MCP, local dashboard, 모든 provider에 대한 BYOK)은 누구에게도 비용을 지불하지 않고 end-to-end로 작동합니다. v0.10.0은 이미 Nous Portal에 비용을 지불하는 사용자를 위한 편의 경로를 추가한 것이며, 무료 경로에서 어떤 것도 제거하지 않습니다.

메시징 gateway

Hermes는 단일 gateway 프로세스에서 Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin (WeChat), BlueBubbles (iMessage), QQBot, Microsoft Teams, Tencent Yuanbao, Google Chat, 그리고 범용 Webhook adapter까지 20개 messaging platform에 연결되는 장기 실행 gateway 프로세스로 실행할 수 있습니다.^3191718 v0.9.0에서는 BlueBubbles를 통한 iMessage 지원(자동 webhook 등록, 설정 wizard, crash resilience)과 enterprise app용 WeCom callback mode가 포함된 iLink Bot API 기반 네이티브 WeChat 지원이 추가되었습니다.¹⁶ v0.11.0에서는 QQBot이 추가되었습니다.¹⁹ v0.12.0에서는 Microsoft Teams와 Tencent Yuanbao가 추가되었습니다.¹⁷ v0.13.0에서는 20번째 platform으로 Google Chat이 추가되었고, 동일한 pluggable adapter architecture를 사용합니다. IRC와 Microsoft Teams도 범용 env_enablement_fn / cron_deliver_env_var plugin hooks가 있는 새로운 adapter pattern으로 이전되었습니다.¹⁸

설정

hermes gateway setup                # Interactive platform configuration
hermes gateway install              # Install as user service (systemd/launchd)
hermes gateway start                # Start the installed service
hermes gateway stop
hermes gateway restart
hermes gateway status
hermes gateway run                  # Run in foreground (debugging)

대화형 설정은 각 platform 연결 과정을 안내합니다. API tokens, bot IDs, channel mappings, allowlists를 설정하게 됩니다.⁶

메시지 흐름

upstream architecture docs에 따르면 다음과 같습니다.³

Platform event → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → authorize user
    → resolve session key
    → create AIAgent with session history
    → AIAgent.run_conversation()
    → deliver response back through adapter

모든 messaging platform은 CLI와 동일한 AIAgent conversation loop를 거칩니다. 그래서 slash command가 양쪽에서 똑같이 작동하고, Telegram에서 예약한 cron job이 결과를 Discord로 전달할 수도 있습니다. platform 차이는 가장자리의 차이일 뿐입니다.³

사용자 인증 및 pairing

hermes pairing list                    # Show pending and approved users
hermes pairing approve <platform> <code>
hermes pairing revoke <platform> <user-id>
hermes pairing clear-pending

pairing code는 임의의 낯선 사람이 gateway에 말을 거는 일을 막아 줍니다. 사용자가 자신의 messaging platform에서 pairing code를 보내면, hermes pairing approve로 승인합니다. 그 이후부터는 해당 사용자가 인증됩니다.⁶

예약 작업 (cron)

Hermes에는 job이 shell command가 아니라 agent task인 일급 cron system이 있습니다. 각 예약 job은 설정된 prompt, 선택적으로 연결된 skill과 함께 새 AIAgent를 통해 실행되며, 결과를 어떤 platform으로든 전달할 수 있습니다.³⁶

hermes cron list
hermes cron create --prompt "Check HN for AI news and summarize" --schedule "0 9 * * *" --deliver telegram
hermes cron edit <id>
hermes cron pause <id>
hermes cron resume <id>
hermes cron run <id>         # Trigger now on the next tick
hermes cron remove <id>
hermes cron status           # Check if scheduler is running
hermes cron tick             # Run due jobs once and exit

또는 messaging chat 안에서 대화로 만들 수도 있습니다.

Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.

agent는 도구를 통해 cron job을 설정합니다. job은 JSON에 저장되며 재시작 후에도 유지됩니다.³

MCP 통합

Hermes는 Model Context Protocol을 client와 server 양쪽으로 지원합니다.⁶

client로 사용 — Hermes를 외부 MCP server에 연결해 tool surface를 확장합니다.

hermes mcp add <name> --url https://example.com/mcp
hermes mcp add <name> --command npx --args "-y,@modelcontextprotocol/server-github"
hermes mcp list
hermes mcp test <name>
hermes mcp remove <name>
hermes mcp configure <name>   # Toggle individual tool selection

또는 config.yaml에서 직접 설정합니다.¹⁴

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

server로 사용 — Hermes conversation을 다른 agent에 노출합니다.

hermes mcp serve
hermes mcp serve -v    # Verbose

컨텍스트 압축

Hermes는 긴 conversation을 자동으로 압축해 model의 context window 안에 유지합니다. 압축 summarizer는 별도의 LLM call입니다. 원하는 provider나 endpoint로 지정할 수 있습니다.⁴

compression:
  enabled: true
  threshold: 0.50                           # Compress at this % of context limit
  target_ratio: 0.20                        # Fraction to preserve as recent tail
  protect_last_n: 20                        # Min recent messages to keep uncompressed
  summary_model: "google/gemini-3-flash-preview"
  summary_provider: "auto"                  # "auto", "openrouter", "nous", "codex", "main", etc.
  summary_base_url: null                    # Custom OpenAI-compatible endpoint

Provider 옵션:⁴

summary_model은 conversation의 전체 중간 구간을 받아 압축하므로, 최소한 main model만큼 큰 context length를 지원해야 합니다.⁴

Budget Pressure 경고

agent가 많은 tool call이 필요한 복잡한 task를 처리할 때, 이를 인지하지 못한 채 iteration budget(기본값: 90 turns)을 빠르게 소진할 수 있습니다. Budget pressure는 model에 자동으로 경고합니다.⁴

Stream Timeout

LLM streaming connection에는 local provider(localhost, LAN IPs)에 맞춰 자동 조정되는 timeout layer가 2개 있습니다.⁴

local LLM는 큰 context에서 첫 token을 생성하기 전 prefill에 몇 분이 걸릴 수 있으므로, local endpoint에서는 socket read timeout이 30분으로 늘어납니다.⁴

로컬 웹 대시보드 (v0.9.0+)

Hermes Agent를 로컬에서 관리하기 위한 브라우저 기반 대시보드입니다. config 파일이나 터미널을 건드리지 않고 설정을 구성하고, session을 모니터링하고, skill을 탐색하고, gateway를 관리할 수 있습니다.¹⁶ hermes dashboard로 실행하세요. GUI를 선호하는 신규 사용자에게 가장 쉬운 onboarding 경로입니다.

백그라운드 프로세스 모니터링 (v0.9.0+)

watch_patterns를 사용하면 백그라운드 프로세스 output에서 모니터링할 pattern을 설정하고, 일치할 때 실시간 알림을 받을 수 있습니다.¹⁶ error를 모니터링하거나, 특정 event(“listening on port”)를 기다리거나, build log를 감시할 수 있으며, polling은 필요 없습니다. v0.8.0의 notify_on_complete(백그라운드 task 완료 알림)와 결합되어, 이제 Hermes에는 완전한 백그라운드 프로세스 observability layer가 있습니다.¹⁵

플러그형 context engine (v0.9.0+)

context management는 이제 hermes plugins를 통해 pluggable slot으로 제공됩니다. agent가 각 turn에서 보는 내용을 제어하는 custom context engine을 교체해 사용할 수 있습니다. filtering, summarization, domain-specific context injection이 가능합니다.¹⁶ 이를 통해 context strategy가 core agent loop에서 분리되어, project별 또는 domain별 context customization을 할 수 있습니다.

백업 및 복원 (v0.9.0+)

hermes backup은 config, session, skill, memory의 전체 archive를 생성합니다. hermes import는 backup archive에서 복원합니다.¹⁶ machine 간 migration, 큰 변경 전 snapshot 생성, teammate와 검증된 configuration 공유에 사용하세요.

Termux / Android 지원 (v0.9.0+)

Hermes는 Termux를 통해 Android에서 native로 실행됩니다. 조정된 install path, mobile screen용 TUI 최적화, voice backend support, /image command가 device에서 작동합니다.¹⁶

보안 강화 (v0.13.0+)

v0.13.0에서는 8개 P0 security issue가 해결되었고, 사용자에게 유리한 방향으로 default 하나가 변경되었습니다.¹⁸

Hermes deployment를 유지 관리한다면 v0.13.0을 단순한 feature drop이 아니라 security-relevant upgrade로 다루세요. Discord cross-guild bypass와 2개의 TOCTOU window는 이전 version에서 exploit 가능합니다.

실무자를 위한 아키텍처

이 섹션은 내부 동작 원리를 이해해 디버깅하거나 확장하거나 성능에 대해 추론하고 싶은 분들을 위한 내용입니다. 업스트림 아키텍처 문서를 종합한 것입니다.³

진입점 → AIAgent

Hermes의 모든 진입점은 궁극적으로 AIAgent.run_conversation()을 호출합니다:

┌──────────────────────────────────────────────────────────────────┐
│                        Entry Points                              │
│                                                                  │
│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)  │
│  Batch Runner    API Server                  Python Library     │
└──────────┬──────────────┬───────────────────────┬────────────────┘
           │              │                       │
           ▼              ▼                       ▼
┌──────────────────────────────────────────────────────────────────┐
│                     AIAgent (run_agent.py)                       │
│                                                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐             │
│  │ Prompt      │  │ Provider     │  │ Tool         │             │
│  │ Builder     │  │ Resolution   │  │ Dispatch     │             │
│  └──────┬──────┘  └──────┬───────┘  └──────┬───────┘             │
│         │                │                 │                    │
│  ┌──────┴───────┐ ┌──────┴───────┐  ┌──────┴───────┐             │
│  │ Compression  │ │ 3 API Modes  │  │ Tool Registry│             │
│  │ & Caching    │ │ chat_compl   │  │ 47 tools     │             │
│  │              │ │ codex_resp   │  │ 20 toolsets  │             │
│  │              │ │ anthropic    │  │              │             │
│  └──────────────┘ └──────────────┘  └──────────────┘             │
└──────────────────────────────────────────────────────────────────┘

다이어그램은 업스트림 아키텍처 문서에서 가져온 것입니다.³

배너의 “47 tools / 20 toolsets” vs “28 tools”. “47 tools” 수치는 업스트림 저장소의 전체 도구 레지스트리입니다 — 모든 toolset에 걸쳐 Hermes가 소스 코드와 함께 제공하는 모든 도구입니다. 실제로 실행 중인 CLI의 시작 배너에는 더 작은 숫자가 표시됩니다(이 가이드를 검증한 설치본에서는 28 tools / 89 skills가 보고됩니다). 이는 버그가 아닙니다. 많은 toolset이 옵트인이며 config.yaml의 toolsets: 아래에서 명시적으로 활성화해야 합니다 — 메시징 플랫폼 어댑터, 브라우저 자동화, 더 무거운 스크래핑 도구 등이 그렇습니다. 레지스트리 총합은 “사용 가능한 것”이고, 배너 숫자는 “현재 프로필에서 활성화된 것”입니다. 어떤 toolset이 활성화되어 있는지 hermes tools --list로 확인하고, ~/.hermes/config.yaml의 toolsets: 블록(또는 실행 중인 세션 안에서 /tools list / /tools enable <name> / /tools disable <name> — 도구를 제거하면 세션 리셋이 트리거되어 에이전트가 도구 매니페스트를 다시 빌드합니다)으로 개별 toolset을 활성화하거나 비활성화할 수 있습니다.

세 가지 API 모드

Hermes는 프로바이더 차이를 세 가지 API 모드로 추상화하며, 런타임에 자동으로 선택됩니다:³

runtime_provider.py 리졸버는 18개 이상의 프로바이더에 대해 (provider, model) 튜플을 (api_mode, api_key, base_url)로 매핑하며, OAuth 플로우, 자격 증명 풀, 별칭 해석을 처리합니다.³

CLI 세션의 데이터 흐름

User input → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API call (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → loop
    → final response → display → save to SessionDB

업스트림 아키텍처 페이지에서 가져왔습니다.³

프롬프트 조립 순서

프롬프트 스택은 다음을 포함합니다:¹³

1. SOUL.md (에이전트 정체성 — 사용 불가능한 경우 내장 폴백)
2. 도구 인식 동작 가이드
3. 메모리/사용자 컨텍스트 (MEMORY.md, USER.md)
4. skills 가이드
5. 컨텍스트 파일 (AGENTS.md, .cursorrules)
6. 타임스탬프
7. 플랫폼별 포매팅 힌트
8. /personality와 같은 선택적 시스템 프롬프트 오버레이

SOUL.md는 토대입니다 — 다른 모든 것이 그 위에 쌓입니다.¹³

세션 저장소

FTS5 전체 텍스트 검색 기능을 갖춘 SQLite 기반 세션 저장소입니다. 세션은 계보 추적(압축 전반에 걸친 부모/자식), 플랫폼별 격리, 경합 처리를 갖춘 원자적 쓰기를 지원합니다.³

플러그인 시스템

세 가지 디스커버리 소스가 있습니다: ~/.hermes/plugins/ (사용자), .hermes/plugins/ (프로젝트), 그리고 pip 엔트리 포인트입니다. 플러그인은 컨텍스트 API를 통해 도구, 후크, CLI 명령을 등록합니다. 메모리 프로바이더는 plugins/memory/ 아래의 특화된 플러그인 유형입니다.³

hermes plugins                       # Interactive enable/disable UI
hermes plugins install <repo>        # Install from Git URL or owner/repo
hermes plugins enable <name>
hermes plugins disable <name>
hermes plugins list

설계 원칙

업스트림 아키텍처 페이지에서:³

OpenClaw에서의 마이그레이션

Hermes Agent는 OpenClaw의 후속작입니다. 기존 OpenClaw 설치에서 마이그레이션하는 경우:⁶⁵

hermes claw migrate --dry-run                    # Preview what would be migrated
hermes claw migrate --preset full                # Full migration including API keys
hermes claw migrate --preset user-data --overwrite   # User data only, no secrets
hermes claw migrate --source /custom/path        # Non-default OpenClaw location

hermes claw migrate는 기본적으로 ~/.openclaw에서 읽으며(레거시 ~/.clawdbot 및 ~/.moldbot 디렉터리도 자동 감지) ~/.hermes에 씁니다.⁶

직접 가져오기 (30개 이상 카테고리): SOUL.md, MEMORY.md, USER.md, AGENTS.md, 4개 소스 디렉터리의 skills, 기본 모델, 커스텀 프로바이더, MCP 서버, 메시징 플랫폼 토큰 및 허용 목록(Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), 에이전트 기본값(reasoning effort, compression, human delay, timezone, sandbox), 세션 리셋 정책, 승인 규칙, TTS 설정, 브라우저 설정, 도구 설정, exec 타임아웃, 명령 허용 목록, gateway 설정, 그리고 3개 소스의 API 키.⁶

수동 검토를 위해 보관됨: cron 작업, 플러그인, 후크/웹훅, 메모리 백엔드(QMD), skills 레지스트리 설정, UI/정체성, 로깅, 멀티 에이전트 설정, 채널 바인딩, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md.⁶

API 키 해석은 우선순위 순서로 세 가지 소스를 확인합니다: config 값 → ~/.openclaw/.env → auth-profiles.json.⁶

문제 해결

“API key not set”

hermes model을 실행하여 프로바이더를 대화형으로 구성하거나, hermes config set OPENROUTER_API_KEY your_key를 사용하세요. hermes doctor 명령은 어떤 키가 누락되었는지 정확하게 알려줍니다.⁷

시작 시 “Context limit: 2048 tokens” (로컬 모델)

Hermes는 서버의 /v1/models 엔드포인트에서 컨텍스트 길이를 자동 감지하지만, 많은 로컬 서버는 낮은 기본값을 보고합니다. config.yaml에서 명시적으로 설정하세요:²

model:
  default: your-model
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768

도구 호출이 실행되지 않고 텍스트로 표시됨

서버에 도구 호출 기능이 활성화되어 있지 않거나, 모델이 서버 구현을 통해 이를 지원하지 않습니다.²

응답이 문장 중간에 잘림

두 가지 가능한 원인이 있습니다:²

1. 서버의 낮은 출력 한도 (max_tokens) — SGLang은 응답당 기본값이 128 토큰입니다. 서버에 --default-max-tokens를 설정하거나 config.yaml에서 model.max_tokens를 구성하세요.
2. 컨텍스트 고갈 — 모델이 컨텍스트 창을 다 채웠습니다. model.context_length를 늘리거나 Hermes에서 컨텍스트 압축을 활성화하세요.

WSL2에서 Windows에 호스팅된 모델 서버로 “Connection refused”

WSL2는 자체 서브넷이 있는 가상 네트워크 어댑터를 사용합니다 — WSL2 내부의 localhost는 Windows 호스트가 아닌 Linux VM을 가리킵니다. 두 가지 옵션이 있습니다:²

미러링된 네트워킹 (Windows 11 22H2 이상): %USERPROFILE%\.wslconfig을 편집하세요:

[wsl2]
networkingMode=mirrored

그런 다음 wsl --shutdown 후 재시작하세요. 이제 localhost가 양방향으로 작동합니다.

호스트 IP 폴백 (구버전 Windows): WSL2 내부에서 Windows 호스트 IP를 가져와 localhost 대신 사용하세요:

ip route show | grep -i default | awk '{ print $3 }'
# Use that IP as the base_url host

또한 모델 서버를 127.0.0.1이 아닌 0.0.0.0에 바인딩해야 합니다 — Ollama의 경우 OLLAMA_HOST=0.0.0.0을 설정하고, llama-server/SGLang의 경우 --host 0.0.0.0을 추가하거나, LM Studio에서 “Serve on Network”를 활성화하세요.²

모든 것이 어디에 있나요?

hermes status와 hermes dump가 여기서 유용합니다. hermes logs list는 모든 로그 파일과 크기를 보여줍니다. hermes config path는 설정 파일 위치를 출력합니다. hermes config env-path는 .env 위치를 출력합니다.⁶

FAQ

Hermes Agent와 Claude Code의 차이점은 무엇인가요?

Claude Code은 Anthropic의 공식 CLI으로, Anthropic 모델에 고정되어 있습니다. Hermes Agent는 Nous Research의 오픈소스 에이전트 프레임워크로, 모든 OpenAI 호환 프로바이더와 함께 작동합니다 — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Hugging Face, Google, 또는 자체 호스팅 엔드포인트.¹² Hermes는 또한 Claude Code에 없는 Telegram/Discord/Slack/WhatsApp/Signal용 메시징 게이트웨이를 제공합니다.

Anthropic API key로 Hermes를 사용할 수 있나요?

네. 세 가지 방법이 있습니다:²

1. ~/.hermes/.env에 ANTHROPIC_API_KEY를 설정하고 hermes chat --provider anthropic --model claude-sonnet-4-6을 실행
2. hermes model을 실행하고 Anthropic를 선택 — Hermes는 사용 가능한 경우 Claude Code의 자격 증명 저장소를 사용합니다
3. 폴백으로 수동 ANTHROPIC_TOKEN (setup-token 또는 OAuth 토큰)을 설정

같은 머신에서 이미 Claude Code을 사용하고 있다면 옵션 2가 선호됩니다 — 갱신 가능한 Claude 자격 증명을 갱신 가능한 상태로 유지합니다.

대화를 잃지 않고 프로바이더를 전환하려면 어떻게 하나요?

세션 내에서 /model provider:model을 사용하세요. 대화 기록, 메모리, 스킬이 모두 이어집니다:⁹

/model zai:glm-5
/model openrouter:anthropic/claude-sonnet-4
/model custom:local:qwen-2.5

Anthropic를 구성했지만 비전/웹/압축이 작동하지 않습니다

보조 모델 폴백에 걸린 것입니다. 비전, 웹 요약, 압축 및 기타 부수 작업은 별도의 보조 LLM를 사용합니다 — 기본적으로 자동 감지를 통한 Gemini Flash (OpenRouter → Nous → Codex). 이들 중 어느 것도 구성되지 않았고 Anthropic만 설정되어 있다면, 이러한 기능은 조용히 저하됩니다.⁴

해결 방법: 보조 작업을 위해 OPENROUTER_API_KEY를 추가하거나, 보조 슬롯을 메인 프로바이더를 사용하도록 재구성하세요. 컨텍스트 압축은 자체적인 최상위 compression: 블록에 있으며 auxiliary.compression.provider가 아닌 summary_provider를 받는다는 점에 유의하세요 — auxiliary.compression 슬롯은 timeout만 노출합니다. 전체 해결 방법:

auxiliary:
  vision:      { provider: "main" }
  web_extract: { provider: "main" }

compression:
  summary_provider: "main"

SOUL.md와 AGENTS.md의 차이점은 무엇인가요?

SOUL.md는 에이전트의 정체성입니다 — 어조, 스타일, 커뮤니케이션 기본값. ~/.hermes/SOUL.md에 있으며 어디든 따라갑니다. AGENTS.md는 프로젝트별 — 아키텍처, 규칙, 명령, 경로 — 이며 프로젝트 디렉터리에 있습니다.¹³ 어디든 따라가야 한다면 SOUL.md. 프로젝트에 속한다면 AGENTS.md입니다.

여러 Hermes 인스턴스를 나란히 실행하려면 어떻게 하나요?

profile입니다. 각 profile은 자체 HERMES_HOME, config, 메모리, 세션, 게이트웨이 PID를 가집니다:⁶

hermes profile create work --clone
hermes profile use work                 # Sticky default
hermes -p work chat -q "..."            # One-off without switching
hermes profile alias work --name h-work # Wrapper script

Hermes는 로컬 LLM를 지원하나요?

네, 커스텀 엔드포인트 경로를 통해서요. Hermes는 모든 OpenAI 호환 서버와 작동합니다: Ollama, vLLM, SGLang, llama.cpp/llama-server, LM Studio, LocalAI, Jan, 또는 자체 서버.² 서버별 설정은 Custom & Self-Hosted Endpoints를 참조하세요.

시작 배너에 가이드에서 언급한 것보다 적은 도구가 표시되는 이유는 무엇인가요?

가이드는 업스트림 아키텍처 레지스트리에서 47개 도구 / 20개 toolset을 인용합니다 — 그것은 Hermes가 모든 toolset에 걸쳐 소스 코드를 제공하는 도구의 전체 수입니다. 실행 중인 설치는 배너에 더 작은 숫자를 표시합니다 (이 가이드에 사용된 참조 설치는 28개 도구를 보고합니다). 이는 Hermes가 시작 시 기본 toolset 세트만 활성화하기 때문입니다. 많은 toolset은 옵트인 방식입니다: 메시징 게이트웨이 어댑터, 브라우저 자동화, 더 무거운 스크래핑 스택, 그리고 여러 특수 통합은 로드되기 전에 ~/.hermes/config.yaml의 toolsets: 아래에 명시적으로 나열되어야 합니다. 레지스트리 총합 = “활성화하면 사용 가능한 것.” 배너 총합 = “현재 profile이 실제로 로드한 것.” hermes tools --list를 사용하여 어떤 toolset이 활성화되어 있고 어떤 것이 사용 가능하지만 비활성화되어 있는지 확인하세요. 런타임에 개별 toolset을 /tools enable <name> 및 /tools disable <name>으로 토글할 수 있습니다 (비활성화는 세션 리셋을 트리거하여 에이전트가 새로운 형태로 도구 매니페스트를 재구축하도록 합니다).

기본 프로바이더가 실패할 때 Hermes는 모델 폴백을 어떻게 처리하나요?

config.yaml에서 fallback_model 블록을 구성하세요:²

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

기본 프로바이더가 실패하면 (속도 제한, 서버 오류, 인증 실패), Hermes는 대화 기록을 잃지 않고 세션 중간에 폴백으로 전환합니다. 세션당 최대 한 번 발생합니다.

에이전트는 시간이 지남에 따라 자체 skill을 향상시킬 수 있나요?

네 — 그것이 Hermes Agent의 “자가 개선” 부분입니다. 에이전트는 skill_manage 도구를 통해 skill을 생성, 업데이트, 삭제할 수 있습니다. 사소하지 않은 워크플로를 파악하면, 향후 재사용을 위해 그 접근 방식을 skill로 저장합니다.¹¹ 에이전트는 복잡한 작업 후 (5개 이상의 도구 호출), 오류에 부딪혀 작동하는 경로를 찾았을 때, 사용자가 접근 방식을 수정했을 때, 또는 사소하지 않은 워크플로를 발견했을 때 skill을 생성합니다.

IDE 통합이 있나요?

네 — Hermes는 VS Code, Zed, JetBrains용 ACP (Agent Client Protocol) 서버로 실행될 수 있습니다:⁶

pip install -e '.[acp]'
hermes acp

변경 로그

참고 자료