Hermes Agent: 실무자를 위한 레퍼런스 (2026)

요약: Hermes Agent는 Nous Research가 만든 오픈소스 자기 개선형 AI agent입니다. CLI로 실행되고 멀티 플랫폼 messaging gateway로도 작동하며, 디스크에 오래 유지되는 identity와 persistent memory를 저장하고, 사용할수록 개선되는 skill을 모으며, OpenAI와 호환되는 어떤 LLM provider와도 함께 사용할 수 있습니다. Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Qwen Cloud, Hugging Face, Google, xAI/SuperGrok, 또는 직접 self-hosted endpoint를 사용할 수 있습니다.¹²¹⁹ v0.14.0(2026년 5월 16일) 기준으로 Hermes에는 grok-4.3 1M context를 지원하는 SuperGrok OAuth, OAuth provider용 OpenAI 호환 로컬 proxy(hermes proxy), 일급 x_search, PyPI 설치 지원, lazy dependency 설치, LINE과 SimpleX Chat을 포함한 22개 messaging platform, /handoff, 쓰기 후 LSP semantic diagnostics, 통합 video_generate, Anthropic가 아닌 provider용 cua-driver 기반 computer_use, native Windows beta, 그리고 12개 P0 / 50개 P1 종료 항목이 추가되었습니다.¹⁹ 대부분의 신규 사용자에게 가장 어려운 부분은 provider 인증입니다. Hermes는 약 20개의 일급 provider와 custom endpoint를 지원하며, 인증 경로도 3가지(API key in .env, hermes model을 통한 OAuth, 또는 config.yaml의 custom endpoint)로 나뉩니다. 먼저 익혀야 할 부분은 auth model입니다. 그 밖의 모든 동작은 어떤 provider가 resolve되는지에 따라 이어집니다.

Hermes Agent는 chat wrapper가 아니라 완전한 agent runtime으로 작동합니다. 파일 시스템을 읽고, sandboxed backend에서 명령을 실행하고, 웹을 스크랩하고, subagent를 생성하고, scheduled cron job을 실행하고, 단일 gateway process에서 Telegram/Discord/Slack/WhatsApp/Signal/Email과 대화하며, 경험을 바탕으로 자체 skill을 만듭니다.¹ CLI는 run_agent.py의 conversation loop 위에 구축된 terminal UI이고, gateway는 messaging platform의 메시지를 같은 conversation loop로 라우팅하는 장기 실행 프로세스입니다.³

가볍게 쓰는 Hermes와 전문가 수준으로 쓰는 Hermes의 차이는 5가지 시스템을 얼마나 이해하느냐에 달려 있습니다. 이 시스템을 익히면 Hermes는 강력한 생산성 배율 장치가 됩니다.

1. Provider resolution: auth flow가 API 호출에 매핑되는 방식
2. Configuration hierarchy: config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. Tool + toolset system: agent가 무엇을 할 수 있는지, platform별로 어떻게 제한되는지
4. Skills system: agent가 만들고 발전시키는 절차적 memory
5. Gateway + cron + profiles: 지금 있는 곳뿐 아니라 실제로 생활하는 곳에서 Hermes를 실행하는 방식

핵심 요점

• Provider auth는 하나가 아니라 3가지 경로입니다. .env의 API key, hermes model/hermes auth를 통한 OAuth, 또는 config.yaml의 custom endpoint입니다. 익숙해 보이는 경로가 아니라 provider에 맞는 경로를 선택하세요.
• Provider 전환은 명령 하나로 끝납니다. hermes model은 OAuth 로그인을 포함해 지원되는 모든 provider를 대화형으로 안내하고, /model provider:model은 history를 잃지 않고 session 중간에 전환합니다.²
• 사용자가 편집하는 config 표면은 2개 파일입니다. ~/.hermes/config.yaml에는 설정이 있고 ~/.hermes/.env에는 secret이 있습니다. auth.json, SOUL.md, MEMORY.md, skills/는 Hermes가 직접 관리합니다. SOUL.md는 직접 편집할 수 있지만, 나머지는 agent 자체가 다룹니다.⁴
• Hermes는 OpenClaw의 후속입니다. 마이그레이션 중이라면 hermes claw migrate가 30개 이상의 state 카테고리를 자동으로 가져옵니다.⁵
• 서비스 품질은 auxiliary model에 달려 있습니다. Vision, web summarization, compression, memory flush는 모두 별도의 auxiliary LLM을 사용합니다. 기본값은 자동 감지(OpenRouter → Nous → Codex)를 통한 Gemini Flash입니다. 이 중 아무것도 설정되어 있지 않으면, auxiliary slot을 main provider로 지정할 때까지 이 기능들은 조용히 성능이 저하됩니다.⁴

v0.14에서 바뀐 점

v0.14.0은 하나의 대표 기능보다, Hermes가 실행될 수 있는 범위를 넓히면서 설정 부담을 줄이는 데 초점이 있습니다.¹⁹ 주요 운영 변경 사항은 다음과 같습니다.

• 설치와 시작이 더 가벼워졌습니다. pip install hermes-agent로 PyPI에서 설치할 수 있고, 무거운 adapter는 처음 사용할 때 lazy-install되며, 실행 경로가 충분한 작업을 뒤로 미뤄 cold start를 약 19초 줄입니다.
• 구독 서비스를 로컬 API endpoint로 만들 수 있습니다. hermes proxy는 Claude Pro, ChatGPT Pro, SuperGrok 같은 OAuth 기반 provider를 Codex, Aider, Cline, Continue 같은 도구에서 쓸 수 있는 OpenAI 호환 로컬 endpoint로 바꿉니다.
• Gateway 지원 범위가 넓어졌습니다. LINE과 SimpleX Chat이 추가되어 platform 수가 22개가 되었고, Microsoft Teams는 end-to-end로 연결되었으며, Discord history backfill은 기본값으로 켜져 있고, Telegram/Discord clarify prompt는 이제 native button을 사용합니다.
• 쓰기 시점 검증이 개선되었습니다. 편집 후 Hermes는 다음 turn 전에 turn별 file-mutation summary와 language-server semantic diagnostics를 표시할 수 있어, evidence-driven agent work에 더 가까워졌습니다.
• Desktop 및 media tooling이 확장되었습니다. computer_use는 Anthropic가 아닌 provider에서 cua-driver를 통해 작동하고, video_generate는 pluggable backend 뒤에서 통합되었으며, vision_analyze는 실제로 볼 수 있는 model에 raw pixel을 보냅니다.

아래의 모든 섹션은 hermes-agent.nousresearch.com/docs의 upstream documentation과 github.com/NousResearch/hermes-agent의 source tree를 기반으로 합니다. 모든 사실 주장은 해당 내용이 나온 구체적인 upstream page를 가리키는 footnote를 포함합니다.

경로 선택하기

Hermes 작동 방식: Mental Model

Hermes는 모든 진입점이 호출할 수 있는 하나의 대화 루프를 중심으로 구성되어 있어요. 진입점은 CLI(cli.py), messaging gateway(gateway/run.py), editor 통합을 위한 ACP adapter, batch runner, 그리고 API 서버입니다.³ 이들은 모두 결국 run_agent.py의 AIAgent.run_conversation()을 호출하며, 이 함수는 다음을 수행해요.

1. prompt_builder.py를 통해 SOUL.md, MEMORY.md, USER.md, skills, context files, tool guidance에서 system prompt를 구성해요³
2. runtime_provider.py를 통해 runtime provider를 결정해요. 이 단계에서 auth, base URL, API mode가 선택됩니다³
3. chat_completions, codex_responses, anthropic_messages 중 하나의 API mode로 provider를 호출해요³
4. 반환된 tool call을 model_tools.py와 중앙 tool registry(tools/registry.py)를 통해 dispatch해요³
5. 모델이 final response를 생성할 때까지 루프를 돌고, 이후 세션을 FTS5가 포함된 SQLite에 저장해요³

이 루프를 이해해야 하는 이유는 personalities, memory, skills, compression, fallback 같은 모든 기능이 이 단계 중 하나에 연결되기 때문이에요. 설정 키를 읽다가 이 키가 무엇을 하는지 궁금하다면, 대개 답은 “위 루프의 1, 2, 3, 4단계 중 하나를 조정하는 knob”입니다.

플랫폼에 독립적인 core. 하나의 AIAgent 클래스가 CLI, gateway, ACP, batch, API 서버를 모두 담당해요. 플랫폼별 차이는 진입점에 있고, agent 자체에는 없습니다.³ 그래서 같은 slash command가 terminal과 Telegram에서 모두 작동해요. 이 command들은 hermes_cli/commands.py의 공유 COMMAND_REGISTRY에서 dispatch됩니다.⁶

디렉터리 구조가 곧 시스템입니다. 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를 어디에 저장하지?”를 찾고 있다면, 위 항목 중 하나입니다.

설치

대부분의 사용자에게는 한 줄 installer가 권장되는 안내 경로입니다. 이 installer는 Python, uv, Node.js, ripgrep, ffmpeg, repo clone, virtual environment, global hermes command를 처리해요.⁷ v0.14.0에는 실제 PyPI package도 포함되어 있어서, 이미 Python environment를 직접 관리하고 있다면 이제 pip install hermes-agent도 바로 설치할 수 있는 방법입니다.¹⁹

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

pip install hermes-agent
hermes

Linux, macOS, WSL2, Android/Termux에서 작동합니다. installer는 Termux를 자동 감지하고 검증된 Android bundle로 전환해요.⁷ v0.14.0은 PowerShell installer를 통해 native Windows 지원을 early beta로 추가했지만, Windows 경로가 더 성숙해지기 전까지 production 용도에는 WSL2를 더 안전한 선택으로 권장합니다.¹⁹

완료 후에는 다음을 실행하세요.

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

필수 사전 조건은 git뿐입니다. installer는 uv를 통해 Python 3.11을 자동으로 준비하고(sudo 필요 없음), Node.js v22(browser automation 및 WhatsApp bridge용), 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 issue나 Discord thread에 붙여 넣기 위한 diagnostic command입니다. 전체 설정을 plain-text로 요약하되 secrets는 redacted 처리해요.⁸

수동 설치

사용자 지정 Python version, 특정 extras, Nix/NixOS integration처럼 완전한 제어가 필요하다면, upstream installation guide에 수동 흐름이 단계별로 문서화되어 있어요.⁷ uv pip install -e ".[<extras>]"와 함께 조합할 수 있는 주요 optional extras는 다음과 같습니다.

Termux install command는 다릅니다. uv pip가 아니라 constraints file과 함께 pip를 사용해요.

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

이는 Android에서 .[all]이 voice extra를 통해 faster-whisper를 가져오고, 이 패키지가 Android용으로 publish되지 않은 ctranslate2 wheels에 의존하기 때문입니다.⁷

인증 및 Providers

Hermes는 약 19개의 일급 providers와 custom endpoints, 그리고 3가지 인증 경로를 지원해요. 아래는 보유한 인증 방식에 맞는 경로를 찾을 수 있도록 전체 인증 범위를 경로별로 정리한 내용입니다.

3가지 인증 경로

Hermes의 모든 provider는 다음 3가지 인증 패턴 중 하나에 속해요.

경로 1 — .env의 API key. 키를 ~/.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, 그리고 대부분의 third-party providers에서 사용해요.²

경로 2 — hermes model 또는 hermes auth를 통한 OAuth. device code flow를 시작하고, 브라우저를 열고, 자격 증명을 ~/.hermes/auth.json에 저장해요. 또한 Claude Code 또는 Codex CLI 같은 도구의 기존 자격 증명도 가져올 수 있어요. Nous Portal, OpenAI Codex (ChatGPT account), GitHub Copilot, Anthropic (Claude Pro/Max)에서 사용해요.²

경로 3 — config.yaml의 Custom endpoint. OpenAI-compatible API라면 무엇이든 사용할 수 있어요. 예를 들면 Ollama, vLLM, SGLang, llama.cpp, LM Studio, LiteLLM proxy, Together AI, Groq, Azure OpenAI, 직접 self-hosted server가 여기에 해당해요. hermes model → Custom endpoint로 한 번 설정하면 config.yaml에 저장돼요.²

전체 Provider Matrix

아래는 각 provider의 정확한 설정 흐름을 포함한 일급 providers 전체 목록이에요.²

Anthropic: 3가지 인증 방법

Anthropic는 별도 섹션이 필요해요. Hermes가 Claude로 들어가는 3가지 경로를 지원하고, 올바른 방식을 고르는 일이 중요하기 때문입니다. upstream docs 내용은 다음과 같아요.²

# 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 자체 credential store를 우선 사용해요. 이렇게 하면 refreshable Claude 자격 증명이 계속 refreshable 상태로 유지돼요.² 같은 머신에서 이미 Claude Code을 사용 중이라면 이 방식이 가장 깔끔해요.

config.yaml에 Anthropic를 영구 고정하려면 다음을 사용하세요.

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

--provider claude와 --provider claude-code도 --provider anthropic의 shorthand로 작동해요.²

GitHub Copilot: 2가지 모드

Copilot은 두 가지 모드로 지원돼요. 직접 Copilot API(권장)과 Copilot ACP(로컬 Copilot CLI를 subprocess로 실행)가 있습니다.²

# 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

upstream docs에 따르면 인증은 다음 순서로 확인돼요.² 1. COPILOT_GITHUB_TOKEN environment variable 2. GH_TOKEN environment variable 3. GITHUB_TOKEN environment variable 4. gh auth token CLI fallback 5. hermes model을 통한 OAuth device code login

Token type이 중요해요. Copilot API는 classic Personal Access Tokens(ghp_*)를 지원하지 않아요. 지원되는 타입은 OAuth tokens(gho_*), fine-grained PATs(Copilot Requests permission이 있는 github_pat_*), GitHub App tokens(ghu_*)입니다. gh auth token이 ghp_* token을 반환한다면, 대신 hermes model을 사용해 OAuth로 인증하세요.²

Chinese AI Providers (일급 지원)

Hermes는 dedicated provider IDs로 z.ai/GLM, Kimi/Moonshot, MiniMax(global + China endpoints), Alibaba Cloud를 내장 지원해요.²

# 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

Base URLs는 GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL, MINIMAX_CN_BASE_URL, DASHSCOPE_BASE_URL environment variables로 override할 수 있어요.²

Z.AI는 endpoint를 자동 감지해요. z.ai/GLM provider를 사용할 때 Hermes는 여러 endpoints(global, China, coding variants)를 probe해서 사용자의 API key를 받아들이는 endpoint를 찾아요. 작동하는 endpoint는 자동으로 cache되므로 대부분의 사용자는 GLM_BASE_URL이 필요하지 않아요.²

xAI (Grok)는 prompt caching을 자동으로 활성화해요. base URL에 x.ai가 포함되어 있으면 Hermes는 모든 요청에 x-grok-conv-id header를 보내 conversation session 안에서 같은 서버로 route하고, cached system prompts와 history를 재사용해요.² 자동으로 처리되며 config는 필요하지 않아요.

hermes auth Command

hermes auth는 pools와 OAuth credentials를 관리하는 credential management command입니다.⁶

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

Credential pools는 같은 provider에 대해 여러 API keys 또는 OAuth tokens를 rotation하는 방식이에요. 코드를 바꾸지 않고 여러 keys에 rate limits를 분산할 때 유용합니다.⁶ 기존 hermes login / hermes logout commands는 제거되었으므로, 대신 hermes auth를 사용하세요.⁶

Custom 및 Self-Hosted Endpoints

Hermes는 OpenAI-compatible API endpoint라면 무엇이든 사용할 수 있어요. 서버가 /v1/chat/completions를 구현한다면 Hermes가 해당 서버를 가리키게 할 수 있습니다.²

Interactive setup(권장):

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에 저장되며, 이 파일은 main-model, provider, base URL의 단일 진실 공급원입니다.² 기존 env vars인 OPENAI_BASE_URL과 LLM_MODEL은 더 이상 main-model configuration에서 읽지 않아요. hermes model을 사용하거나 config.yaml을 직접 편집하세요.² (OPENAI_BASE_URL + OPENAI_API_KEY는 auxiliary provider: "main" routing path의 fallback으로는 여전히 존중되므로, 그 용도로 사용 중이라면 무턱대고 삭제하지 마세요.)⁴

세션 중 custom endpoints 전환:

/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(bare, model name 없음)은 endpoint의 /v1/models API를 query하고, 로드된 model이 정확히 1개이면 해당 model을 자동 선택해요. 단일 model을 실행하는 local servers에 유용합니다.²

Local LLM Servers (Setup Templates)

upstream docs에는 Ollama, vLLM, SGLang, llama.cpp, LM Studio에 대한 전체 setup guides가 있어요. 여기서는 실제로 실행하게 될 핵심 commands만 정리합니다. 각 command는 Hermes가 가리킬 수 있는 작동 endpoint를 만들도록 설계되어 있어요.²

Ollama — 가장 쉬운 local path, zero config:

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는 기본 context length가 매우 낮아요(24GB VRAM 기준 4,096 tokens). OLLAMA_CONTEXT_LENGTH 또는 Modelfile을 통해 반드시 높여야 해요. OpenAI-compatible API는 client에서 context length를 받지 않으므로 Hermes가 대신 설정할 수 없습니다.² agent 용도로는 최소 16k-32k를 설정하세요.

vLLM — high-performance GPU serving:

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

Tool calling에는 --enable-auto-tool-choice와 --tool-call-parser <name>이 필요해요. 지원되는 parsers는 hermes(Qwen 2.5, Hermes 2/3), llama3_json, mistral, deepseek_v3, deepseek_v31, xlam, pythonic입니다. 이 flags가 없으면 tool calls가 plain text로 반환돼요.²

SGLang — KV cache reuse를 위한 RadixAttention 기반 fast serving:

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

tool calling에는 --jinja가 필요해요. 이 옵션이 없으면 llama-server가 tools parameter를 완전히 무시하고, model은 응답 텍스트에 JSON를 써서 tool을 호출하려고 해요. Hermes는 이를 실제 tool calls로 parse할 수 없습니다.²

LM Studio — GUI가 있는 desktop app:

LM Studio app에서 서버를 시작하세요(Developer tab → Start Server). 또는 CLI로 lms server start(port 1234에서 시작)와 lms load qwen2.5-coder --context-length 32768을 실행할 수 있어요.² 그런 다음 hermes model이 http://localhost:1234/v1을 가리키게 하세요.

중요한 LM Studio 주의점: LM Studio는 model metadata에서 context length를 읽지만, 많은 GGUF models는 기본값을 2048 또는 4096으로 보고해요. LM Studio model settings에서 항상 context length를 명시적으로 설정하세요. model picker 옆의 gear icon을 클릭하고 “Context Length”를 최소 16384, 가능하면 32768로 설정한 다음 model을 다시 로드하세요.²

Named Custom Providers

여러 custom endpoints를 다룬다면, 예를 들어 local dev server와 remote GPU server를 함께 사용한다면, config.yaml에서 named custom providers로 정의하세요.²

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

그런 다음 triple syntax로 세션 중 전환할 수 있어요.

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

interactive hermes model menu에서도 named custom providers를 선택할 수 있어요.²

Pluggable Provider Architecture (v0.13.0+)

v0.13.0에는 ProviderProfile ABC와 plugins/model-providers/ directory가 포함되어 있어, third-party inference providers가 core 수정 없이 drop in할 수 있어요.¹⁸ provider가 OpenAI-, Anthropic-, 또는 Codex-compatible API mode를 지원한다면, auth path, base URL, model catalog, caching headers를 선언하는 ProviderProfile subclass를 구현할 수 있어요. Hermes는 built-in providers와 같은 runtime_provider.py path를 통해 이를 resolve합니다. 이것이 v0.13.0 provider expansion의 기반이 된 architecture change입니다. provider를 추가하기 위해 core code를 편집하는 대신 plugin을 배포하면 됩니다.

OpenAI-Compatible Local Proxy (v0.14.0+)

hermes proxy는 Hermes가 이미 signed in한 OAuth provider를 기반으로 OpenAI-compatible local endpoint를 노출해요. 여기에는 Claude Pro, ChatGPT Pro, SuperGrok, 또는 설정된 다른 compatible provider가 포함됩니다.¹⁹ 즉 Codex CLI, Aider, Cline, Continue, custom scripts처럼 OpenAI-style API를 기대하는 도구가 별도의 API key 없이 subscription-backed Hermes auth를 재사용할 수 있어요. 이 proxy는 local developer infrastructure로 취급하세요. 의도적으로 bind하고, 넓게 노출하지 말고, provider-specific terms를 염두에 두세요.

Context Length Detection

upstream docs에 따르면 두 설정이 자주 혼동돼요.²

• context_length — 전체 context window입니다(combined input + output token budget, 예: Claude Opus 4.7의 1,000,000 또는 Sonnet 4.6의 200,000). Hermes는 history를 언제 compress할지 결정할 때 이 값을 사용해요.
• model.max_tokens — output cap입니다(model이 단일 응답에서 생성할 수 있는 max tokens). history length와는 관련이 없어요.

auto-detection이 window size를 잘못 잡을 때는 context_length를 설정하세요.

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

Hermes는 context windows를 감지하기 위해 multi-source resolution chain을 사용해요. 순서는 config override → custom provider per-model → persistent cache → endpoint /models → Anthropic /v1/models → OpenRouter API → Nous Portal → models.dev(3800개 이상 models를 다루는 community-maintained registry) → fallback defaults(128K)입니다.² 이 시스템은 provider-aware이므로, 같은 model도 누가 제공하느냐에 따라 context limits가 달라질 수 있어요. 예를 들어 claude-opus-4.6은 Anthropic direct에서는 1M이지만 GitHub Copilot에서는 128K입니다.²

Provider Rotation 및 Fallback

Credential pools. 같은 provider에 대해 여러 API keys가 있다면 hermes auth를 통해 rotation strategy를 설정하세요. 여러 keys에 rate limits를 분산하는 방식입니다.⁶

Fallback model. primary model이 실패할 때(rate limits, server errors, auth failures) Hermes가 자동으로 전환할 backup 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

fallback은 conversation을 잃지 않고 세션 중 model과 provider를 바꿔요. 세션당 최대 한 번만 실행됩니다.² fallback을 지원하는 providers는 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입니다.²

Auxiliary Models

Hermes는 side tasks에 lightweight “auxiliary” models를 사용해요. image analysis, web page summarization, browser screenshot analysis, dangerous command approval classification, context compression, session search summarization, skill matching, MCP tool dispatch, memory flush가 여기에 포함됩니다.⁴ 기본값은 auto-detection(OpenRouter → Nous → Codex)을 통한 Gemini Flash입니다.

각 auxiliary task가 사용할 model과 provider를 설정할 수 있어요. 모든 auxiliary slot은 같은 3가지 knobs인 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" provider option은 “내 main agent가 사용하는 provider를 사용한다”는 뜻이에요. 이는 오직 auxiliary:, compression:, fallback_model: configs 안에서만 유효합니다. top-level model.provider 설정에는 유효하지 않아요. custom OpenAI-compatible endpoint를 main model로 사용한다면 model: section에서 provider: custom을 설정하세요.⁴

이것이 중요한 이유: Anthropic OAuth만 설정했다면(OpenRouter key 없음), vision, web summarization, compression이 저하되거나 실패할 수 있어요. 기본 auxiliary fallback chain이 OpenRouter를 먼저 시도하기 때문입니다. auxiliary tasks용으로 OPENROUTER_API_KEY를 추가하거나, 각 auxiliary slot이 main provider를 사용하도록 다시 설정하세요.

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

이것은 신규 Hermes 사용자가 가장 자주 겪는 “기능이 조용히 작동하지 않는다” 문제입니다.

설정 시스템

Hermes에는 계층형 설정 시스템이 있어요. 우선순위를 이해하는 것이 꼭 필요해요. 상위 계층이 하위 계층을 덮어쓰며, 그중 한 계층은 config.yaml에서 볼 수 없는 전역 provider registry이기 때문이에요.

Config 파일 구성

업스트림 문서에 따르면 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 vs .env — 둘 다 설정되어 있으면, 비밀이 아닌 설정에서는 config.yaml이 우선해요.⁴ 규칙은 다음과 같아요: - 비밀 정보 (API keys, bot tokens, passwords) → .env - 그 외 모든 항목 (model, terminal backend, compression settings, memory limits, toolsets) → config.yaml

비밀 정보는 shell 스타일 보간을 사용해 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 arguments — hermes chat --model anthropic/claude-sonnet-4 (호출별 override)
2. 환경 변수 — 프로세스 시작 시 적용돼요
3. config.yaml — 기본 설정 파일이에요
4. .env — 비밀 정보 전용이에요
5. 내장 기본값 — 다른 곳에서 값을 설정하지 않았을 때 적용돼요

CLI flags는 해당 단일 호출에서 항상 우선해요. 장기적인 진실 공급원은 config.yaml이에요.

현지화 (v0.13.0+)

v0.13.0에서는 CLI 및 gateway 메시지에 7개 locale이 추가됐어요. 중국어(간체), 일본어, 독일어, 스페인어, 프랑스어, 우크라이나어, 터키어예요.¹⁸ v0.14.0은 모든 gateway 명령과 web dashboard를 현지화하고, locale 8개를 더 추가해 총 16개가 됐어요.¹⁹ 문서는 현재 zh-Hans로만 현지화되어 있어요. Locale은 LC_ALL / LANG 환경 변수 또는 config.yaml의 명시적인 locale: 키에서 결정돼요. 영어는 여전히 기본값이며, 번역이 아직 다루지 않은 문자열의 진실 공급원이에요.

Profiles — 격리된 여러 Hermes 인스턴스

Profiles를 사용하면 각각 자체 config, sessions, skills, memory, gateway PID를 가진 격리된 Hermes 인스턴스를 여러 개 둘 수 있어요. 이를 통해 “work Hermes”와 “personal 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 스레드에 바로 붙여넣을 수 있습니다.⁶

Slash Commands

Slash commands는 활성 채팅 세션(CLI 또는 메시징 플랫폼) 안에서 실행됩니다. hermes_cli/commands.py의 공유 COMMAND_REGISTRY에서 디스패치되기 때문에, 대부분의 명령은 표면이 달라도 동일하게 작동합니다.⁹

세션 제어

설정 및 Model

/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

Tools, Skills 및 정보

동적 Skill Slash Commands

설치된 모든 skill은 자동으로 slash command로 노출됩니다.⁹

/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

config.yaml에서 짧은 이름을 더 긴 prompt의 별칭으로 연결하는 quick commands도 정의할 수 있습니다.⁹

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을 입력하세요.

Prefix 매칭

명령은 prefix 매칭을 지원합니다. /h를 입력하면 /help로, /mod를 입력하면 /model로 해석됩니다. prefix가 모호한 경우 registry 순서상 첫 번째 등록이 우선합니다. 전체 명령 이름과 등록된 alias는 항상 prefix 매칭보다 우선합니다.⁹

메시징 전용 명령

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

• /status — 세션 정보를 표시합니다
• /sethome (alias /set-home) — 현재 채팅을 플랫폼 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 레지스트리를 제공합니다.¹⁰ Tools는 논리적인 toolsets로 구성되며, 플랫폼별로 활성화하거나 비활성화할 수 있습니다.

상위 수준 범주

일반적인 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 disable <name> 및 /tools enable <name>로 tools를 전환할 수 있으며, 새 tool 세트가 적용되도록 세션이 재설정됩니다.⁹

터미널 백엔드

터미널 tool은 6가지 서로 다른 환경에서 명령을 실행할 수 있습니다.¹⁰

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

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

SSH 백엔드(보안을 위해 권장 — 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 백엔드:

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를 사용하면 설치된 패키지, 파일, 설정이 세션 간에 유지됩니다.¹⁰

모든 컨테이너 백엔드는 보안 강화를 적용해 실행됩니다. 읽기 전용 루트 파일 시스템(Docker), DAC_OVERRIDE, CHOWN, FOWNER를 제외한 모든 Linux capabilities 제거, 권한 상승 차단, PID 제한(256개 프로세스), 전체 namespace 격리, volumes를 통한 영구 워크스페이스를 제공합니다.¹⁰

백그라운드 프로세스

터미널 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 협업을 일급 프리미티브로 만듭니다. 바로 agents 간, 재시작 간에도 작업, 상태, worker 식별자를 추적하는 영속적인 Kanban 보드입니다.¹⁸ 이 보드는 Hermes worker 무리가 중단된 handoff에 막히지 않고 실제로 작업을 끝내게 해 줍니다.

Kanban 보드는 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에 비용을 지불하는 사용자를 위한 편의 경로를 추가한 것이며, 무료 경로에서 어떤 것도 제거하지 않습니다.

Messaging 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, LINE, SimpleX Chat, 범용 Webhook 어댑터까지 22개 메시징 플랫폼에 연결되는 장기 실행 gateway 프로세스로 실행할 수 있어요.^320171819 v0.9.0에서는 BlueBubbles를 통한 iMessage(자동 webhook 등록, 설정 마법사, 충돌 복원력)와 엔터프라이즈 앱을 위한 WeCom 콜백 모드를 갖춘 iLink Bot API 기반 네이티브 WeChat 지원이 추가되었어요.¹⁶ v0.11.0에서는 QQBot이 추가되었어요.²⁰ v0.12.0에서는 Microsoft Teams와 Tencent Yuanbao가 추가되었어요.¹⁷ v0.13.0에서는 Google Chat이 20번째 플랫폼으로 추가되었고, 같은 플러그형 어댑터 아키텍처를 기반으로 동작해요. IRC와 Microsoft Teams도 범용 env_enablement_fn / cron_deliver_env_var plugin 훅을 갖춘 새 어댑터 패턴으로 마이그레이션되었어요.¹⁸ v0.14.0에서는 LINE과 SimpleX Chat이 추가되었고 Graph 인증, webhook 리스너, 파이프라인 런타임, 아웃바운드 전송까지 Microsoft Teams 스택이 end-to-end로 완성되었어요.¹⁹

설정

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)

대화형 설정은 각 플랫폼 연결 과정을 안내해요. API 토큰, 봇 ID, 채널 매핑, 허용 목록을 설정합니다.⁶

메시지 흐름

상위 아키텍처 문서에 따르면 다음과 같아요.³

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

모든 메시징 플랫폼은 CLI와 같은 AIAgent 대화 루프를 통해 실행돼요. 그래서 slash command가 양쪽에서 똑같이 동작하고, Telegram에서 예약한 cron 작업의 출력을 Discord로 전달할 수 있어요. 플랫폼 차이는 가장자리에서만 발생합니다.³

사용자 승인 및 페어링

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

페어링 코드는 무작위 낯선 사람이 gateway와 대화하는 일을 막아줘요. 사용자가 자신의 메시징 플랫폼에서 페어링 코드를 보내면, hermes pairing approve로 승인하세요. 그때부터 해당 사용자는 승인된 상태가 됩니다.⁶

예약 작업 (Cron)

Hermes에는 작업이 셸 명령이 아니라 agent 작업인 일급 cron 시스템이 있어요. 각 예약 작업은 설정된 프롬프트, 선택적으로 연결된 skill과 함께 새로운 AIAgent를 통해 실행되고, 결과를 어떤 플랫폼으로든 전달합니다.³⁶

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

또는 메시징 채팅 안에서 대화로 만들 수도 있어요.

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

agent는 도구를 통해 cron 작업을 설정해요. 작업은 JSON에 유지되며 재시작 후에도 남아 있어요.³

MCP 통합

Hermes는 Model Context Protocol을 클라이언트와 서버 양쪽으로 지원해요.⁶

클라이언트로 사용 — Hermes를 외부 MCP 서버에 연결해 도구 범위를 확장하세요.

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"

서버로 사용 — Hermes 대화를 다른 agent에 노출하세요.

hermes mcp serve
hermes mcp serve -v    # Verbose

Context Compression

Hermes는 긴 대화를 자동으로 압축해 모델의 context 창 안에 머물도록 해요. 압축 요약기는 별도의 LLM 호출이에요. 원하는 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은 대화의 전체 중간 구간을 받아 압축하므로, 최소한 기본 모델만큼 큰 context 길이를 지원해야 해요.⁴

예산 압박 경고

agent가 많은 도구 호출이 필요한 복잡한 작업을 처리할 때, 이를 알아차리지 못한 채 반복 예산(기본값: 90턴)을 소진할 수 있어요. 예산 압박은 모델에 자동으로 경고를 보여줍니다.⁴

스트림 타임아웃

LLM 스트리밍 연결에는 로컬 provider(localhost, LAN IP)에 맞춰 자동 조정되는 2개의 타임아웃 계층이 있어요.⁴

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

로컬 Web Dashboard (v0.9.0+)

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

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

watch_patterns를 사용하면 백그라운드 프로세스 출력에서 모니터링할 패턴을 설정하고, 일치하는 항목이 있을 때 실시간 알림을 받을 수 있어요.¹⁶ 오류를 감시하거나, 특정 이벤트(“listening on port”)를 기다리거나, 빌드 로그를 확인할 수 있으며, 폴링은 필요 없어요. v0.8.0의 notify_on_complete(백그라운드 작업 완료 시 알림)와 함께 Hermes는 이제 완전한 백그라운드 프로세스 관측 계층을 갖추게 되었어요.¹⁵

플러그형 Context Engine (v0.9.0+)

context 관리는 이제 hermes plugins를 통한 플러그형 슬롯이에요. agent가 매 턴마다 보는 내용을 제어하는 custom context engine으로 교체할 수 있어요. 필터링, 요약, 도메인별 context 주입이 가능합니다.¹⁶ 이를 통해 context 전략이 핵심 agent 루프에서 분리되어, 프로젝트별 또는 도메인별 context 커스터마이징이 가능해져요.

백업 및 복원 (v0.9.0+)

hermes backup은 config, 세션, skill, memory의 전체 아카이브를 만듭니다. hermes import는 백업 아카이브에서 복원해요.¹⁶ 머신 간 마이그레이션, 큰 변경 전 스냅샷 생성, 팀원과 검증된 설정 공유에 사용하세요.

Termux / Android 지원 (v0.9.0+)

Hermes는 Termux를 통해 Android에서 네이티브로 실행돼요. 조정된 설치 경로, 모바일 화면용 TUI 최적화, 음성 백엔드 지원, /image 명령이 기기에서 동작합니다.¹⁶

보안 강화 (v0.13.0+)

v0.13.0에서는 8개의 P0 보안 문제를 해결하고 사용자에게 유리하도록 기본값 하나를 변경했습니다.¹⁸ v0.14.0에서는 sudo 무차별 대입 / sudo-stdin 강화, 위험한 명령 우회 수정, 모델에 다시 주입되기 전 tool 오류 정리, dashboard plugin API 인증, skills-hub SSRF 범위 확대, 설치 중 공급망 보안 권고 스캔을 포함해 P0 12개와 P1 50개를 추가로 해결했습니다.¹⁹

Hermes 배포를 유지 관리한다면 v0.13.0과 v0.14.0을 단순한 기능 추가가 아니라 보안 관련 업그레이드로 다루세요. v0.13.0은 Discord cross-guild 우회와 2개의 TOCTOU 창을 해결합니다. v0.14.0은 sudo 처리, tool-error 재주입, plugin API, skills-hub SSRF, dependency advisory 전반에 걸쳐 추가 강화 작업을 더합니다.

실무자를 위한 아키텍처

이 섹션은 내부에서 어떤 일이 일어나는지 이해해 디버깅하거나 확장하거나 성능을 판단하려는 사람을 위한 내용입니다. upstream 아키텍처 문서를 종합한 것입니다.³

Entry Point → AIAgent

Hermes의 모든 entry point는 결국 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    │  │              │             │
│  └──────────────┘ └──────────────┘  └──────────────┘             │
└──────────────────────────────────────────────────────────────────┘

다이어그램은 upstream 아키텍처 문서를 바탕으로 조정했습니다.³

배너의 “28 tools”와 “47 tools / 20 toolsets”의 차이. “47 tools” 수치는 upstream repository의 전체 tool registry입니다. 즉 Hermes가 소스 코드로 함께 제공하는 모든 toolset의 모든 tool을 뜻합니다. 실제로 실행 중인 CLI의 시작 배너에는 더 작은 숫자가 표시됩니다(이 가이드를 검증한 설치 환경에서는 28 tools / 89 skills로 표시되었습니다). 버그가 아닙니다. 많은 toolset은 opt-in 방식이며, messaging platform adapter, browser automation, 더 무거운 scraping tool 등은 config.yaml의 toolsets: 아래에서 명시적으로 활성화해야 합니다. registry 총계는 “사용 가능한 것”이고, 배너 숫자는 “현재 profile에서 활성화된 것”입니다. 활성화된 toolset은 hermes tools --list로 확인하고, 개별 toolset은 ~/.hermes/config.yaml의 toolsets: 블록에서 활성화하거나 비활성화하세요. 실행 중인 session 안에서는 /tools list / /tools enable <name> / /tools disable <name>를 사용할 수도 있습니다. tool을 제거하면 agent가 tool manifest를 다시 빌드하도록 session reset이 트리거됩니다.

3가지 API 모드

Hermes는 provider별 차이를 3가지 API 모드로 추상화하며, 런타임에 자동으로 선택합니다.³

runtime_provider.py resolver는 18개 이상의 provider에 대해 (provider, model) tuple을 (api_mode, api_key, base_url)로 매핑하며, OAuth 흐름, 자격 증명 pool, alias resolution을 처리합니다.³

CLI Session의 Data Flow

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

upstream 아키텍처 페이지에서 가져왔습니다.³

Prompt 조립 순서

prompt stack에는 다음이 포함됩니다.¹³

1. SOUL.md(agent identity. 사용할 수 없으면 built-in fallback)
2. Tool-aware 동작 지침
3. Memory/user context(MEMORY.md, USER.md)
4. Skills 지침
5. Context 파일(AGENTS.md, .cursorrules)
6. Timestamp
7. Platform별 formatting hint
8. /personality 같은 선택적 system-prompt overlay

SOUL.md가 기반이며, 다른 모든 것은 그 위에 쌓입니다.¹³

Session 저장소

SQLite 기반 session 저장소이며 FTS5 full-text search를 사용합니다. session은 lineage tracking(compression 전후의 parent/child), platform별 isolation, contention handling이 포함된 atomic write를 지원합니다.³

Plugin System

Discovery source는 3가지입니다. ~/.hermes/plugins/(사용자), .hermes/plugins/(프로젝트), pip entry point입니다. plugin은 context API를 통해 tool, hook, CLI command를 등록합니다. Memory provider는 plugins/memory/ 아래의 특수한 plugin 유형입니다.³

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

설계 원칙

upstream 아키텍처 페이지의 내용입니다.³

OpenClaw에서 Migration

Hermes Agent는 OpenClaw의 후속입니다. 기존 OpenClaw 설치에서 migration하는 경우:⁶⁵

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에서 읽고(legacy ~/.clawdbot, ~/.moldbot directory도 자동 감지), ~/.hermes에 씁니다.⁶

직접 import되는 항목(30개 이상 category): SOUL.md, MEMORY.md, USER.md, AGENTS.md, 4개 source directory의 skill, 기본 model, custom provider, MCP server, messaging platform token과 allowlist(Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), agent 기본값(reasoning effort, compression, human delay, timezone, sandbox), session reset policy, approval rule, TTS config, browser 설정, tool 설정, exec timeout, command allowlist, gateway config, 3개 source의 API key입니다.⁶

수동 검토를 위해 archive되는 항목: cron job, plugin, hook/webhook, memory backend(QMD), skills registry config, UI/identity, logging, multi-agent setup, channel binding, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md입니다.⁶

API key resolution은 config 값 → ~/.openclaw/.env → auth-profiles.json 순서로 3개 source를 확인합니다.⁶

문제 해결

“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

변경 기록

참고 자료