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

요약: Hermes Agent는 Nous Research에서 개발한 오픈 소스 자기 개선형 AI 에이전트예요. CLI 및 다중 플랫폼 메시징 gateway로 실행되며, 지속적인 정체성과 영구 메모리를 디스크에 저장하고, 사용할수록 발전하는 skill을 모으며, OpenAI와 호환되는 모든 LLM 제공업체와 연동돼요. Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Qwen Cloud, Hugging Face, Google, xAI/SuperGrok 또는 직접 호스팅하는 엔드포인트를 사용할 수 있어요.¹²¹⁹ v0.14.0(2026년 5월 16일)부터 Hermes에는 grok-4.3의 1M context를 지원하는 SuperGrok OAuth, OAuth 제공업체를 위한 OpenAI 호환 로컬 프록시(hermes proxy), 정식 x_search, PyPI 설치 지원(v0.19.0부터 지원 중단됨. 현재 지원되는 방식은 한 줄 설치 프로그램이에요), 지연 종속성 설치, LINE과 SimpleX Chat을 포함한 22개 메시징 플랫폼, /handoff, 쓰기 작업 후 LSP 의미 진단, 통합 video_generate, Anthropic 이외 제공업체를 위한 cua-driver 기반 computer_use, 네이티브 Windows 베타, 그리고 12건의 P0 및 50건의 P1 해결 사항이 추가됐어요.¹⁹ 대부분의 신규 사용자가 가장 어려워하는 부분은 제공업체 인증이에요. Hermes는 약 20개의 정식 제공업체와 사용자 지정 엔드포인트를 지원하며, 서로 다른 3가지 인증 경로가 있어요(.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를 가볍게 사용하는 경우와 능숙하게 활용하는 경우의 차이는 5가지 시스템에서 결정돼요. 이 시스템들을 익히면 Hermes를 강력한 생산성 도구로 활용할 수 있어요.

1. 제공업체 선택: 인증 흐름이 API 호출로 연결되는 방식
2. 설정 계층 구조: config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. 도구 및 toolset 시스템: 플랫폼별 제한에 따라 에이전트가 수행할 수 있는 작업
4. Skills 시스템: 에이전트가 만들고 발전시키는 절차적 메모리
5. Gateway + cron + profiles: 현재 있는 곳뿐 아니라 일상적으로 사용하는 환경에서 Hermes 실행하기

핵심 내용

• 제공업체 인증에는 1가지가 아닌 3가지 경로가 있어요. .env의 API 키, hermes model/hermes auth를 통한 OAuth, 또는 config.yaml의 사용자 지정 엔드포인트예요. 익숙해 보이는 경로가 아니라 사용 중인 제공업체에 맞는 경로를 선택하세요.
• 명령 하나로 제공업체를 전환할 수 있어요. hermes model은 OAuth 로그인을 포함해 지원되는 모든 제공업체의 설정 과정을 대화형으로 안내하며, /model provider:model을 사용하면 기록을 잃지 않고 세션 도중에 전환할 수 있어요.²
• 사용자가 편집하는 설정 영역은 2개 파일이에요. ~/.hermes/config.yaml에는 설정이, ~/.hermes/.env에는 비밀 정보가 저장돼요. auth.json, SOUL.md, MEMORY.md, skills/는 Hermes가 직접 관리해요. SOUL.md는 직접 편집할 수 있지만, 나머지는 에이전트가 자체적으로 수정해요.⁴
• Hermes는 OpenClaw의 후속 제품이에요. 이전하는 경우 hermes claw migrate를 사용하면 30개가 넘는 상태 범주를 자동으로 가져올 수 있어요.⁵
• 서비스 품질은 보조 모델에 따라 달라져요. 비전, 웹 요약, 압축, 메모리 플러시는 모두 별도의 보조 LLM을 사용해요. 기본적으로 자동 감지(OpenRouter → Nous → Codex)를 통해 Gemini Flash를 사용해요. 이 가운데 아무것도 설정되지 않았다면 보조 슬롯이 기본 제공업체를 사용하도록 지정할 때까지 이러한 기능의 성능이 별다른 경고 없이 저하돼요.⁴

v0.14에서 달라진 점

v0.14.0은 하나의 대표 기능보다는 설정 부담을 줄이고 Hermes를 실행할 수 있는 환경을 넓히는 데 초점을 맞췄어요.¹⁹ 주요 운영 변경 사항은 다음과 같아요.

• 설치와 시작이 더 가벼워졌어요. PyPI에서 pip install hermes-agent를 사용할 수 있고, 무거운 어댑터는 처음 사용할 때 지연 설치되며, 시작 과정에서 충분한 작업을 뒤로 미뤄 콜드 스타트 시간을 약 19초 단축했어요. (이후 v0.19.0에서 pip 설치 지원이 중단됐어요. 설치를 참고하세요.)
• 구독 서비스를 로컬 API 엔드포인트로 만들 수 있어요. hermes proxy는 Claude Pro, ChatGPT Pro, SuperGrok처럼 OAuth을 기반으로 하는 제공업체를 Codex, Aider, Cline, Continue 등의 도구에서 사용할 수 있는 OpenAI 호환 로컬 엔드포인트로 변환해요.
• Gateway의 지원 범위가 넓어졌어요. LINE과 SimpleX Chat이 추가되면서 지원 플랫폼이 22개로 늘었고, Microsoft Teams가 처음부터 끝까지 연결됐으며, Discord 기록 보충 기능이 기본적으로 활성화됐고, Telegram/Discord의 clarify 프롬프트가 이제 네이티브 버튼을 사용해요.
• 쓰기 작업 시 검증 기능이 개선됐어요. Hermes는 편집 후 다음 턴으로 넘어가기 전에 턴별 파일 변경 요약과 언어 서버의 의미 진단을 표시할 수 있어 증거에 기반한 에이전트 작업에 한층 가까워졌어요.
• 데스크톱 및 미디어 도구의 범위가 넓어졌어요. computer_use는 Anthropic 이외의 제공업체에서 cua-driver를 통해 작동하고, video_generate는 교체 가능한 백엔드 뒤에서 통합됐으며, vision_analyze는 실제로 이미지를 볼 수 있는 모델에 원본 픽셀을 전송해요.

아래의 모든 섹션은 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, context 파일, 도구 지침으로 시스템 프롬프트를 구성해요.³
2. runtime_provider.py를 통해 런타임 제공자를 결정해요. 이 단계에서 인증 방식, 기본 URL, API 모드를 선택해요.³
3. chat_completions, codex_responses, anthropic_messages라는 3가지 API 모드 중 하나로 제공자를 호출해요.³
4. 반환된 도구 호출을 model_tools.py와 중앙 도구 레지스트리(tools/registry.py)를 통해 전달해요.³
5. 모델이 최종 응답을 생성할 때까지 루프를 반복한 다음, 세션을 FTS5가 적용된 SQLite에 저장해요.³

모든 기능은 이 단계 중 하나에 연결되므로 이 루프를 이해해야 해요. personality, memory, skills, compression, fallback이 모두 여기에 해당해요. 설정 키를 살펴보다가 어떤 역할인지 궁금하다면, 대개 “위 루프의 1, 2, 3, 4단계 중 하나를 조정하는 값”이라고 보면 돼요.

플랫폼에 구애받지 않는 핵심 구조. 하나의 AIAgent 클래스가 CLI, gateway, ACP, batch, 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를 어디에 저장하지?”라는 의문이 든다면 위 항목 중 하나에서 찾을 수 있어요.

v0.19.0의 새로운 기능(The Quicksilver Release)

Hermes Agent v0.19.0(태그 v2026.7.20, 2026년 7월 20일)은 전령의 신이 지닌 속도에서 이름을 따왔어요. 이번 릴리스의 중심은 압도적인 응답성으로, 모든 플랫폼에서 첫 요청의 첫 토큰 생성 시간이 약 80% 단축됐어요. 여기에 터미널 결제, 비밀번호 관리자를 이용한 보안 정보 불러오기, 기본으로 활성화되는 스마트 승인, 작업 과정을 확인할 수 있는 subagents, 충돌에도 응답을 안전하게 전달하는 기능이 더해졌어요. v0.18.0 이후의 변화 규모는 프로젝트 사상 가장 커요. 약 2,245개의 커밋과 약 1,065개의 병합된 PR, 약 3,300개의 해결된 이슈, 450명이 넘는 커뮤니티 기여자가 함께했어요.²³

• 어디서나 첫 토큰까지 약 80% 빨라졌어요. 콜드 상태에서 요청 제출부터 전달까지 걸리는 시간이 CLI, gateway, TUI, 데스크톱, cron 모두에서 약 4.3초에서 0.9초로 줄었어요. Discord 기능 감지는 핵심 처리 경로 밖으로 이동했고, Ollama가 아닌 것으로 확인된 제공자에서는 Ollama 탐색을 건너뛰며, 에이전트 초기화 과정의 블로킹 작업도 제거했어요. 체감 지연 시간도 별도로 개선했어요. 이제 추론 모델은 기본적으로 사고 과정을 실시간 스트리밍하며(display.show_reasoning이 켜짐), 응답 상자는 줄 단위가 아닌 토큰 단위로 그려져요.²³
• 데스크톱과 TUI 렌더링 개선. 데스크톱 앱에는 약 20개의 PR에 걸친 속도 개선이 적용됐어요. 점진적 블록 어휘 분석으로 스트리밍 Markdown 분할기의 CPU 사용량을 14배 줄였고, 검토 창의 diff를 가상화했으며, 대규모 대화 기록에서도 세션을 빠르게 전환할 수 있게 했어요. 토큰마다 사이드바와 도구 행을 다시 렌더링하는 문제도 없앴어요. 이제 TUI도 스트리밍되는 Markdown을 블록 단위로 점진적으로 렌더링해요.²³
• pip과 Homebrew 설치 방식은 더 이상 권장되지 않아요. 이제 두 방식 모두 “지원되지 않는 기존 설치 방식”으로 표시돼요. 모든 화면에서 작업을 막지는 않지만 경고가 나타나며, PyPI와 Homebrew를 통한 배포도 중단할 예정이에요. 공식 지원 방식은 한 줄 설치 프로그램이에요. pip이나 brew로 설치했다면 지금부터 이전을 준비하세요.²³
• 비밀번호 관리자에서 보안 정보를 불러올 수 있어요. 새롭게 추가된 확장형 SecretSource 인터페이스는 로드 시점에 Bitwarden과 1Password(op:// 참조)에서 보안 정보를 가져와요. 여러 vault를 동시에 활성화할 수 있고, 일관된 우선순위와 충돌 경고, 변수별 출처 정보도 제공해요. 이제 API 키를 평문 .env에 저장하지 않아도 돼요. 앞으로 추가될 vault 제공자는 plugins 형태로 연결할 수 있어요.²³
• 이제 스마트 승인이 기본이에요. Hermes가 경고 대상으로 지정된 명령을 실행하려 하면, 매번 사용자에게 묻는 대신 독립적인 LLM 검토자가 명령을 평가해요. 각 판정은 평가한 정확한 명령 하나에만 적용돼요. 사용자가 정의한 거부 규칙은 YOLO 모드에서도 일치하는 명령을 차단하며, /deny <reason>는 거부 사유를 전달해 에이전트가 진행 방향을 바로잡도록 해요. 규칙 키와 함께 다시 도입된 plugin pre_tool_call 승인 작업은 도구 호출을 사람의 승인이 필요한 단계로 격상해요.²³
• 터미널 결제: /subscription과 /topup. 터미널을 벗어나지 않고 Nous Portal 요금제를 관리할 수 있어요. 현재 요금제와 남은 사용량을 확인하고, 업그레이드 비용이나 다운그레이드 적용 시점을 정확히 미리 본 다음, 되돌리기 기능과 함께 변경 사항을 적용할 수 있어요. 데스크톱 앱에도 같은 기능을 제공하는 결제 설정 탭이 추가됐어요.²³
• subagents의 작업을 지켜보고, 완료된 답변도 놓치지 마세요. delegate_task가 작업을 전달하면 subagents가 실행되는 즉시 tail -f로 확인할 수 있는 실시간 대화 기록 파일이 제공돼요. 각 하위 에이전트마다 사람이 읽을 수 있는 로그 하나에 모든 도구 호출과 결과, 스트리밍 응답이 기록돼요. 백그라운드 위임의 완료 상태는 재시작 후에도 유지돼요. 최종 gateway 응답은 state.db의 전달 의무 원장에 기록되며, 전송 도중 gateway가 중단되면 다음 시작 시 다시 전달돼요. max_async_children 설정 옵션은 통합된 위임 동시 실행 제한으로 대체되어 더 이상 권장되지 않아요.²³
• 하나의 gateway에서 여러 profiles를 사용할 수 있어요. 하나의 봇 토큰을 공유하는 단일 다중화 gateway가 특정 길드, 채널, 스레드를 서로 다른 profiles로 라우팅할 수 있어요. 각 profile의 설정, skills, memory, 보안 정보는 완전히 분리되며, GATEWAY_MULTIPLEX_PROFILES로 재정의할 수 있어요. 라우팅 인덱스는 state.db로 이동했으며, sessions.json은 이제 선택적으로 사용하는 기존 미러예요.²³
• 제공자와 모델이 대거 추가됐어요. Fireworks AI가 비용 추정 기능과 제공자 선택기의 두 번째 위치를 포함한 공식 지원 제공자로 추가됐고, DeepInfra와 Upstage Solar도 합류했어요. 모델 목록에는 GPT-5.6(Sol, Terra, Luna, Pro까지 전체 흐름에 연결됨), grok-4.5(정식 출시), kimi-k3(kimi-k2.x는 지원 종료), 완전히 연결된 Claude Sonnet 5가 추가됐어요. 제공자별 enabled: false 플래그와 excluded_providers 설정을 사용하면 이용하지 않는 제공자를 /model 선택기와 모델 결정 과정에서 제외할 수 있어요.²³
• 추론 강도를 세밀하게 조절할 수 있어요. 모든 화면에 새로운 max와 ultra 강도 단계가 추가됐어요. 설정에서 모델별로 재정의할 수 있고, MoA 프리셋에서는 슬롯별 강도를 지정할 수 있어요. 조언자는 깊게 사고하고 종합 모델은 빠른 속도를 유지하도록 구성할 수 있어요. 보조 모델에는 작업별 강도를 지정할 수 있으며, CLI에서는 세션 범위의 /reasoning을 사용할 수 있어요.²³
• CLI 및 MCP 기능. hermes sessions export는 Markdown, Quarto, HTML, 프롬프트 전용, Hugging Face 추적 형식으로 내보낼 수 있으며, 선택 사항인 --redact로 민감한 정보를 제거할 수 있어요. /model --once는 한 번의 요청에만 모델을 재정의하고, 슬래시 skill 호출은 중첩해서 사용할 수 있어요(/skill-a /skill-b do XYZ). --safe-mode는 문제 해결을 돕고, hermes config get과 unset은 설정 관리 기능을 보완해요. hermes serve는 진정한 headless backend로 바뀌었으며, MCP 도구는 mcp__server__tool 명명 규칙을 사용해요.²³

v0.18.x에서 업그레이드한다면 무엇보다 먼저 2가지 변경 사항을 확인하세요. pip 또는 Homebrew 설치는 이제 지원되지 않는 기존 방식이라는 경고가 표시되므로 한 줄 설치 프로그램으로 이전해야 해요. 또한 max_async_children은 통합된 위임 동시 실행 제한으로 대체되어 더 이상 권장되지 않아요. 나머지는 모두 기존 기능에 더해지는 변경 사항이에요. 업그레이드해야 할 핵심 이유는 첫 요청 지연 시간이 약 80% 단축됐고, 스마트 승인이 추가됐으며, 전달 원장을 통해 충돌이 발생해도 완료된 답변을 안전하게 전달할 수 있다는 점이에요.

v0.18.0의 새로운 기능 (판단 릴리스)

Hermes Agent v0.18.0(태그 v2026.7.1, 2026년 7월 1일)은 판단이라는 이름에 걸맞게, agent가 성공했다고 주장하는 대신 자신의 작업을 직접 검증하고 실제로 살펴볼 수 있는 앙상블 추론을 제공합니다. 또한 전체 P0/P1 백로그를 마무리해 12일 동안 우선순위가 가장 높은 항목 약 692개를 해결했어요.²²

• 일급 모델로 지원되는 Mixture-of-Agents. 이제 모든 인터페이스에서 MoA를 다른 모델과 동일하게 선택할 수 있으며, 앙상블 추론 과정도 볼 수 있어요. 각 참조 모델의 전체 출력이 레이블이 지정된 개별 블록에 표시되고 답변이 실시간으로 스트리밍되므로, 불투명하게 병합된 답변만 받는 대신 앙상블이 생각하는 과정을 지켜볼 수 있어요.²²
• /goal의 완료 계약. agent는 목표를 완료했다고 보고하기 전에 프로젝트 검사를 실행해 자신의 작업을 직접 검증해요. 성공했다고 주장하는 데 그치지 않고 스스로에게 판단을 적용해요.²²
• /learn — 무엇이든 설명해 skill로 만들기. 워크플로를 설명하면 재사용 가능한 skill로 만들 수 있어요. 생성된 skill은 저장소의 CONTRIBUTING.md 규칙을 자동으로 준수해요.²²
• /journey 타임라인. 시간에 따른 메모리와 skill의 변화를 시각적으로 보여주고 편집도 지원하며, 데스크톱에서는 메모리 그래프도 제공해요.²²
• 백그라운드 하위 agent 병렬 확장. 대화를 중단하지 않고 여러 작업을 동시에 실행하도록 위임할 수 있어요. v0.17.0의 단일 백그라운드 하위 agent가 이제 하나의 집단으로 확장됐어요.²²
• 데스크톱 Projects. 프로젝트, 저장소, 레인 구성 모델을 갖춘 일급 코딩 Projects를 제공해요.²²
• 유휴 시 축소되는 gateway. gateway는 사용하지 않을 때 휴면 상태로 전환되고 원활한 배포를 위해 드레인 작업을 조율할 수 있어요. Hermes를 상시 서비스로 운영하는 사용자에게 특히 유용해요.²²
• Google Vertex AI 지원. 자동 OAuth2 토큰 갱신 기능을 갖춘 GCP 서비스 계정을 통해 Gemini에 접근할 수 있으며, provider 카탈로그에도 추가됐어요.²²
• /prompt 편집기 명령. 입력란과 씨름하지 않고 여러 줄 프롬프트를 작성할 수 있도록 $EDITOR를 열어요.²²

v0.17.x에서 업그레이드해도 CLI에는 영향을 주지 않아요. 업그레이드할 핵심 이유는 스스로 검증하는 목표를 제공하는 완료 계약, 내부 앙상블을 살펴볼 수 있는 일급 MoA, 그리고 skill을 기록하는 /learn이에요.

v0.17.0의 새로운 기능 (확장 릴리스)

Hermes Agent v0.17.0(태그 v2026.6.19, 2026년 6월 19일)은 agent의 활동 범위가 얼마나 넓어졌는지를 나타내는 이름이에요. 새로운 메시징 채널과 모델 provider가 추가됐고, 데스크톱과 대시보드에서 더 세밀하게 제어할 수 있어요. v0.16.x에 기능을 추가한 릴리스이며 CLI 인터페이스는 변경되지 않았어요.²¹

• 새로운 메시징 채널. 이제 Photon Spectrum(기기 코드 OAuth, hermes photon login)을 통해 Mac 릴레이 없이 iMessage를 사용할 수 있어요. WhatsApp Business Cloud API는 브리지 프로세스가 필요했던 기존 방식을 대체하는 공식 Meta 어댑터예요. SimpleX에는 그룹, 기본 첨부 파일, 텍스트 일괄 처리, 자동 수락 기능이 추가됐어요. 또한 계약에 따라 개인정보를 보호하는 웨이크 채널 설계를 갖춘 Raft가 번들 플랫폼 plugin으로 합류했어요.²¹
• 새로운 모델과 provider. 카탈로그에 z-ai/glm-5.2(1M context), anthropic/claude-fable-5, laguna-m.1, nemotron-3-ultra, grok-composer-2.5-fast(xAI OAuth을 통해 제공되는 Cursor 모델, 200k context)가 추가됐어요. xAI 기본값은 grok-build-0.1로 변경됐으며, 이제 Anthropic 적응형 모델은 최신 사고 계약을 따라 reasoning 필드를 전송하지 않아요.²¹
• 데스크톱과 대시보드. 데스크톱에는 위임한 활동을 실시간으로 스트리밍하는 “관찰 창”이 포함된 백그라운드 하위 agent(delegate_task(background=true)), Composer 모델 선택기, 다시 지정할 수 있는 키보드 단축키, 운영체제 기본 알림, 스레드별 Composer 초안, VS Code Marketplace 테마, 일본어와 번체 중국어 인터페이스가 추가됐어요. 대시보드에는 config.yaml을 편집하지 않고 모델, skill, MCP을 설정할 수 있는 전체 profile 빌더, 전역 profile 전환기, 보안 검사를 갖추도록 개편된 Skills Hub, 양식, slash command, 대화, 문서에서 사용할 수 있는 매개변수화된 템플릿인 Automation Blueprints, 그리고 OAuth 게이트 뒤에서 401을 반환하는 안전한 로그인이 추가됐어요.²¹
• skill과 도구. 이제 image_generate는 지원되는 모든 이미지 provider에서 처음부터 이미지를 생성할 뿐만 아니라 원본 이미지를 편집하고 변환할 수도 있어요. memory 도구에는 한 번의 호출로 추가, 교체, 제거를 원자적 일괄 처리할 수 있는 operations 배열이 추가됐어요. 새로운 simplify-code skill은 Chesterton’s-Fence 위험 등급으로 통제되는 3개 agent의 병렬 검토와 정리 과정을 실행해요. 또한 3가지 상태를 지원하던 write_mode는 불리언 write_approval로 대체됐어요.²¹
• 아키텍처. 백그라운드 하위 agent는 즉시 핸들을 반환하고 결과를 새로운 턴으로 다시 전달해요. MCP 요청 처리기를 통해 도구 호출 도중 확인을 요청할 수 있고, 늦게 연결된 MCP 도구는 턴 사이에 노출돼 캐시 안정성을 유지해요. cron은 Chronos 관리형 cron provider를 지원하는 플러그형 CronScheduler가 됐어요. 또한 새로운 Managed 범위(/etc/hermes)를 통해 관리자가 사용자가 변경할 수 없는 설정을 고정할 수 있으며, 여러 gateway 토폴로지를 위한 Gateway-Gateway 릴레이도 추가됐어요.²¹
• 새로운 명령. /version, /billing(대화형 터미널 결제), hermes photon login(iMessage 인증), hermes curator run --consolidate가 추가됐어요. 이제 통합 작업은 선택 사항이므로 일상적인 백그라운드 큐레이션에는 토큰이 들지 않아요.²¹
• 보안. v0.17.0은 셸 이스케이프 거부 목록 우회 문제를 해결하고, 승인 모듈이나 자체 정책 gateway 어댑터가 없으면 안전하게 실패하도록 변경했어요. 또한 cron 작업 스크립트의 하위 프로세스 환경을 정리하고, 요청 디버그 덤프에서 비밀 정보를 가리고, MCP 표준 입출력 설정에서 정보 유출 패턴을 검사하며, CVE를 해결하기 위해 urllib3와 PyJWT 버전을 올렸어요.²¹

v0.16.x에서 업그레이드해도 CLI에는 영향을 주지 않아요. 동일한 agent를 중심으로 새로운 채널, 모델, 인터페이스를 추가한 릴리스예요. 릴레이가 필요 없는 iMessage, 공식 WhatsApp 어댑터, 관리자를 위한 Managed 범위가 업그레이드할 핵심 이유예요.

v0.16.0의 새로운 기능 (인터페이스 릴리스)

Hermes Agent v0.16.0(태그 v2026.6.5, 2026년 6월 5일)은 CLI 중심 agent를 사용할 수 있는 새로운 인터페이스에서 이름을 따왔어요. 가장 큰 변화는 Hermes가 더 이상 터미널에서만 사용할 수 있는 도구가 아니라는 점이에요.²⁰

• 기본 데스크톱 앱. Hermes Desktop은 macOS, Linux, Windows용으로 새롭게 출시된 Electron 앱이며, 한 번의 클릭으로 설치하고 앱 안에서 자동 업데이트할 수 있어요. 스트리밍 채팅 창, 파일 끌어다 놓기, 클립보드 이미지 붙여넣기, Cmd+K 팔레트, 보관과 검색 기능을 갖춘 세션 목록, 상태 표시줄의 모델 선택기를 제공해요. 보안 WebSocket을 통해 원격 Hermes gateway에 연결할 수 있으며, OAuth 또는 사용자 이름과 비밀번호로 인증해요. profile별 원격 호스트와 profile 간 @session 참조로 연결된 여러 profile의 동시 세션도 지원해요. 또한 데스크톱 인터페이스는 형식이 지정된 i18n 계층(display.language, 기본값은 영어)을 통해 전체 중국어 간체(简体中文) 번역을 제공해요.²⁰
• 브라우저 관리 패널. 로컬 웹 대시보드는 상태 보기에서 전체 관리 패널로 발전했어요. 활성화와 비활성화 전환 기능을 갖춘 MCP 카탈로그, 자격 증명 관리, webhook과 hook 생성, 메모리 설정, gateway 제어 기능, 업데이트 전 검사와 원클릭 Debug Share를 제공하는 System 페이지가 포함돼요. 새로운 Channels 페이지에서는 브라우저에서 모든 gateway 메시징 플랫폼(Telegram, Discord, Slack 등)을 설정할 수 있어요. 이제 인증은 플러그형으로 제공돼요. 사용자 이름과 비밀번호 로그인, 일반 자체 호스팅 OIDC provider, 자체 호스팅 OAuth 클라이언트를 위한 hermes dashboard register, 새로 고침 토큰 기반 세션 교체를 지원해요.²⁰
• 새로운 CLI 및 slash command. /undo [N]은 미리 채우기와 소프트 삭제를 사용해 최근 N개의 사용자 턴을 되돌리며, CLI, TUI, 메시징 플랫폼 전반에서 작동해요. 설정 가능한 기본 인터페이스(cli 또는 tui)와 --cli 재정의 옵션이 추가됐고, TUI에는 통합 /model 명령과 Sessions 오버레이가 추가됐어요. hermes portal은 Nous Portal 온보딩 흐름을 쉽게 알아볼 수 있도록 만든 별칭이에요. 처음 실행할 때 Quick Setup과 Full Setup 중에서 선택할 수 있으며, hermes prompt-size와 hermes sessions optimize라는 2가지 진단 명령도 추가됐어요.²⁰
• 새로운 모델과 provider. 선택기에 deepseek-v4-flash, MiniMax-M3(1M context, 기본 MiniMax provider), qwen3.7-plus(Nous 및 OpenRouter), gemini-3.5-flash(Gemini OAuth 및 API 키)가 추가됐어요. 일급 xAI Grok OAuth provider가 데스크톱 실행기에 추가됐고, 모든 인터페이스의 모델 선택기가 퍼지 검색을 지원해요. 여러 엔드포인트를 제공하는 provider는 하나의 행으로 묶이며, 카탈로그 갱신 주기는 매일에서 매시간으로 변경됐어요.²⁰
• 간소화된 skill과 점진적 공개. 기본 skill 세트에서 중복되거나 사용되지 않는 skill을 제거했어요. Spotify는 기본 plugin으로 옮겨졌고, Linear는 hermes mcp install linear로 이전됐으며, 오래된 항목 여러 개가 삭제됐어요. 더 많은 skill이 선택 사항으로 전환됐고, environments: 전면부 관련성 게이트(kanban/docker/s6)가 추가돼 요청하기 전까지 상황별 skill이 색인에 나타나지 않아요. 이제 NVIDIA/skills는 OpenAI, Anthropic, HuggingFace와 함께 Skills Hub에서 기본으로 신뢰하는 소스예요. MCP 및 plugin 도구에는 점진적인 범위별 도구 공개 기능이 추가됐고, 토큰을 얻지 못했는데도 OAuth에 성공했다고 잘못 보고하던 MCP 버그도 수정됐어요.²⁰
• 보안. v0.16.0은 CVE-2026-48710(BadHost)을 해결한 Starlette(≥1.0.1) 버전으로 고정하고, 비동기 경로의 SSRF URL 검사를 이벤트 루프 밖으로 옮겼어요. 하위 프로세스 환경에서 Bedrock 추론 bearer 토큰을 제거하고, 파일 안전 읽기 보호 대상에 bws_cache.json을 추가했으며, 위험 패턴 목록에 docker restart/stop/kill을 추가했어요. 검증된 skill 콘텐츠에 포함된 보이지 않는 유니코드도 정리해요. 이 릴리스에서는 P0 문제 2개와 P1 문제 62개를 해결했으며, 그중 16개에는 보안 태그가 지정돼 있었어요.²⁰

v0.15.x에서 업그레이드해도 CLI 자체에는 호환성을 깨뜨리는 변경이 없어요. 동일한 agent를 중심으로 인터페이스와 provider를 추가한 릴리스예요. 터미널을 사용하지 않는 사용자에게 Hermes를 제공하거나 브라우저에서 원격 gateway를 관리하려면 데스크톱 앱과 관리 패널만으로도 업그레이드할 이유가 충분해요.

설치

공식적으로 지원되는 설치 경로는 한 줄 설치 프로그램이에요. 이 프로그램은 Python, uv, Node.js, ripgrep, ffmpeg, 저장소 복제, 가상 환경, 전역 hermes 명령을 모두 설정해요.⁷

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

pip 및 Homebrew 설치는 v0.19.0부터 더 이상 권장되지 않아요. v0.14.0에서 도입된 PyPI 패키지(pip install hermes-agent)와 Homebrew 공식은 이제 “지원되지 않는 레거시” 설치로 표시돼요. Hermes가 이러한 설치를 감지하면 모든 화면에서 경고하지만 실행을 차단하지는 않아요. 앞으로 PyPI 및 Homebrew 배포도 중단될 예정이에요. pip 또는 brew로 설치했다면 위의 설치 프로그램으로 이전하세요.²³

Linux, macOS, WSL2, Android/Termux에서 작동해요. 설치 프로그램은 Termux를 자동으로 감지하고 검증된 Android 번들로 전환해요.⁷ v0.14.0부터 PowerShell 설치 프로그램을 통한 초기 베타 단계의 네이티브 Windows 지원도 추가됐지만, 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는 누락된 항목과 해결 방법을 정확히 알려줘요.⁷ 도움을 요청할 때 GitHub 이슈나 Discord 스레드에 붙여 넣을 진단 정보는 hermes dump 명령으로 생성할 수 있어요. 비밀 정보가 가려진 전체 설정의 일반 텍스트 요약이에요.⁸

수동 설치

사용할 Python 버전을 직접 지정하거나 특정 추가 기능을 선택하고 Nix/NixOS와 통합하는 등 모든 설정을 직접 제어해야 한다면, 업스트림 설치 가이드에 단계별 수동 설치 절차가 문서화되어 있어요.⁷ uv pip install -e ".[<extras>]"와 함께 조합해서 사용할 수 있는 주요 선택적 추가 기능은 다음과 같아요.

Termux 설치 명령은 달라요. uv pip 대신 제약 조건 파일과 함께 pip를 사용해요.

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

Android에서 .[all]을 사용하면 voice 추가 기능을 통해 faster-whisper가 설치되기 때문이에요. faster-whisper는 Android용으로 배포되지 않는 ctranslate2 wheel에 의존해요.⁷

인증 및 제공업체

Hermes는 약 22개의 공식 제공업체와 사용자 지정 엔드포인트를 지원하며, v0.19.0에서는 Fireworks AI, DeepInfra, Upstage Solar가 추가되었어요. 인증 경로는 3가지로 나뉩니다. 아래에는 보유한 인증 수단에 맞는 경로를 쉽게 찾을 수 있도록 전체 인증 방식을 경로별로 정리했어요.

3가지 인증 경로

Hermes의 모든 제공업체는 다음 3가지 인증 패턴 중 하나를 사용해요.

경로 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과 대부분의 서드 파티 제공업체가 이 방식을 사용해요.² v0.19.0부터는 키를 평문 파일에 저장하지 않아도 됩니다. 플러그형 SecretSource 인터페이스가 로드 시점에 Bitwarden이나 1Password의 비밀 정보와 op:// 참조를 가져올 수 있어요. 여러 보관소를 동시에 사용할 수 있고, 우선순위가 일관되게 적용되며, 충돌 경고와 변수별 출처 정보도 제공해요. .env는 대체 경로로 계속 사용할 수 있습니다. 이 방식은 제공업체 키를 하나의 토큰으로 통합했던 v0.15.0의 Bitwarden Secrets Manager 부트스트랩 토큰과는 달라요. SecretSource는 평문 파일 자체를 대체하며, 향후 보관소 제공업체도 플러그인으로 추가할 수 있습니다.²³

경로 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의 사용자 지정 엔드포인트. Ollama, vLLM, SGLang, llama.cpp, LM Studio, LiteLLM 프록시, Together AI, Groq, Azure OpenAI 또는 직접 호스팅하는 서버처럼 OpenAI 호환 API를 사용하는 모든 서비스에 적용할 수 있어요. hermes model → Custom endpoint에서 한 번 설정하면 config.yaml에 저장됩니다.²

전체 제공업체 표

다음은 모든 공식 제공업체와 각각의 정확한 설정 절차를 정리한 목록이에요.²

v0.19.0부터는 사용하지 않는 제공업체를 목록에서 제외할 수도 있어요. 제공업체별 enabled: false 플래그와 excluded_providers 설정 키를 사용하면 /model 선택기와 내장 제공업체 확인 과정에서 해당 제공업체가 제거됩니다.²³

Anthropic: 3가지 인증 방법

Hermes는 Claude에 연결하는 3가지 경로를 지원하며, 적절한 경로를 선택해야 하므로 Anthropic는 별도로 설명할게요. 업스트림 문서에 따르면 다음과 같습니다.²

# 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: 2가지 모드

Copilot은 2가지 모드를 지원해요. 권장 방식인 Copilot API 직접 연결과 로컬 Copilot CLI를 하위 프로세스로 실행하는 Copilot ACP입니다.²

# 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_*, Copilot Requests 권한이 있는 세분화된 PAT인 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)는 prompt caching을 자동으로 활성화해요. 기본 URL에 x.ai가 포함되어 있으면 Hermes는 모든 요청에 x-grok-conv-id 헤더를 보내요. 이를 통해 하나의 대화 세션이 같은 서버로 전달되고 캐시된 시스템 프롬프트와 기록을 재사용합니다.² 자동으로 작동하므로 별도 설정은 필요하지 않아요.

hermes auth 명령어

hermes auth는 pool과 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

Credential pool을 사용하면 같은 제공업체의 여러 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

두 방법 모두 주 모델, 제공업체, 기본 URL의 단일 정보 원본인 config.yaml에 설정을 저장해요.² 기존 환경 변수 OPENAI_BASE_URL과 LLM_MODEL은 주 모델 설정에서 더 이상 읽지 않아요. hermes model을 사용하거나 config.yaml을 직접 수정하세요.² 다만 보조 작업의 provider: "main" 라우팅 경로에서는 OPENAI_BASE_URL과 OPENAI_API_KEY가 여전히 대체 설정으로 사용돼요. 이 경로에서 사용 중이라면 무작정 삭제하지 마세요.⁴

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

/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의 기본 context 길이는 매우 짧아요. VRAM이 24GB 미만이면 4,096토큰이 기본값입니다. 반드시 OLLAMA_CONTEXT_LENGTH나 Modelfile을 사용해 늘리세요. OpenAI 호환 API는 클라이언트에서 전달하는 context 길이를 받지 않으므로 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>이 필요해요. 지원되는 parser는 hermes(Qwen 2.5, Hermes 2/3), llama3_json, mistral, deepseek_v3, deepseek_v31, xlam, pythonic입니다. 이 플래그가 없으면 도구 호출이 일반 텍스트로 반환돼요.²

SGLang — RadixAttention으로 KV cache를 재사용하는 빠른 제공 방식:

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는 모델 메타데이터에서 context 길이를 읽지만, 많은 GGUF 모델이 기본값을 2048이나 4096으로 보고해요. LM Studio 모델 설정에서 context 길이를 항상 명시적으로 지정하세요. 모델 선택기 옆의 톱니바퀴 아이콘을 클릭하고 “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

그런 다음 세션 도중 3단계 문법으로 전환할 수 있어요.

/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에서 제공업체가 확장될 수 있었던 구조적 변화예요. 제공업체를 추가하기 위해 핵심 코드를 수정하는 대신 플러그인을 배포하면 됩니다.

OpenAI 호환 로컬 프록시(v0.14.0 이상)

hermes proxy는 Hermes에 이미 로그인된 OAuth 제공업체를 기반으로 OpenAI 호환 로컬 엔드포인트를 제공해요. Claude Pro, ChatGPT Pro, SuperGrok 또는 설정된 다른 호환 제공업체를 사용할 수 있습니다.¹⁹ 따라서 Codex CLI, Aider, Cline, Continue, 사용자 지정 스크립트처럼 OpenAI 방식의 API를 기대하는 도구도 별도의 API 키 없이 Hermes의 구독 기반 인증을 재사용할 수 있어요. 이 프록시는 로컬 개발자 기반 시스템으로 취급하세요. 바인딩 대상을 신중하게 지정하고, 외부에 광범위하게 노출하지 말며, 제공업체별 이용 약관도 확인해야 해요.

Context 길이 감지

업스트림 문서에 따르면 다음 2가지 설정을 혼동하는 경우가 많아요.²

• context_length — 입력과 출력의 전체 토큰 예산을 합친 전체 context window예요. 예를 들어 Claude Opus 4.7은 1,000,000이고 Sonnet 4.6은 200,000입니다. Hermes는 이 값을 사용해 기록을 압축할 시점을 결정해요.
• model.max_tokens — 모델이 한 번의 응답에서 생성할 수 있는 최대 토큰 수를 제한해요. 기록 길이와는 관련이 없습니다.

자동 감지에서 window 크기를 잘못 판단하면 context_length를 설정하세요.

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

Hermes는 여러 출처를 다음 순서로 확인해 context window를 감지해요. 설정 재정의 → 사용자 지정 제공업체의 모델별 설정 → 영구 캐시 → 엔드포인트 /models → Anthropic /v1/models → OpenRouter API → Nous Portal → 3800개 이상의 모델 정보가 있는 커뮤니티 관리 레지스트리 models.dev → 기본 대체 값 128K 순서입니다.² 이 시스템은 제공업체를 구분하므로 같은 모델이라도 제공하는 곳에 따라 context 한도가 달라질 수 있어요. 예를 들어 claude-opus-4.6은 Anthropic 직접 연결에서 1M이지만 GitHub Copilot에서는 128K입니다.²

제공업체 순환 및 대체 경로

Credential pool. 같은 제공업체의 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는 이미지 분석, 웹페이지 요약, 브라우저 스크린샷 분석, 위험한 명령어 승인 분류, context 압축, 세션 검색 요약, skill 연결, MCP 도구 전달, 메모리 저장 같은 부가 작업에 가벼운 보조 모델을 사용해요.⁴ 기본적으로 자동 감지를 통해 Gemini Flash를 사용하며, OpenRouter → Nous → Codex 순서로 확인합니다.

각 보조 작업에서 사용할 모델과 제공업체를 설정할 수 있어요. 모든 보조 항목은 provider, model, base_url이라는 같은 3가지 설정을 사용합니다.⁴

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 키를 추가하지 않았다면 vision, 웹 요약, 압축 기능의 품질이 떨어지거나 아예 작동하지 않을 수 있어요. 기본 보조 대체 경로가 OpenRouter를 먼저 확인하기 때문입니다. 보조 작업을 위해 OPENROUTER_API_KEY를 추가하거나, 각 보조 항목에서 주 제공업체를 사용하도록 다시 설정하세요.

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

이는 Hermes를 처음 사용하는 사용자가 가장 흔히 겪는 “기능이 아무런 알림 없이 작동하지 않는” 문제예요.

설정 시스템

Hermes는 계층형 설정 시스템을 사용해요. 상위 계층은 하위 계층보다 우선하며, 이 계층 중 하나는 config.yaml에서 확인할 수 없는 전역 provider registry이므로 우선순위를 이해해야 해요.

설정 파일 구성

공식 문서에 따르면 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 키, bot token, 비밀번호) → .env - 그 외 모든 항목 (model, terminal backend, compression 설정, memory 제한, 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 get KEY        # Print a single value (v0.19.0+)
hermes config unset KEY      # Remove a key so the default applies again (v0.19.0+)
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개 locale이 추가됐어요.¹⁸ v0.14.0에서는 모든 gateway 명령어와 web dashboard가 현지화되고, locale 8개가 추가되어 총 16개로 늘어났어요.¹⁹ 현재 문서는 zh-Hans로만 현지화되어 있어요. Locale은 LC_ALL / LANG 환경 변수나 config.yaml의 명시적인 locale: 키에 따라 결정돼요. 영어는 계속 기본 언어이자 아직 번역되지 않은 문자열의 기준으로 사용돼요.

Profile — 격리된 여러 Hermes instance

Profile을 사용하면 각각 독립된 config, session, skill, memory, gateway PID를 갖는 여러 Hermes instance를 만들 수 있어요. 이를 통해 “업무용 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 명령어 참고 자료를 확인하세요.⁶

전역 옵션

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는 수준, 세션 ID, 시간 범위를 동시에 필터링할 수 있어 로그 파일에 tail -f를 실행하는 것보다 강력해요.⁶

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 활동(플랫폼 연결, 전달, webhooks)

로그 순환은 Python의 RotatingFileHandler를 통해 자동으로 이루어져요. agent.log.1, agent.log.2 등을 확인하세요.⁶

hermes doctor — 진단

문제가 발생하면 가장 먼저 hermes doctor [--fix]를 실행하세요. 이 명령어는 설정의 유효성, 종속성 설치 여부, API 키 사용 가능 여부, 서비스 상태를 확인하며, --fix를 사용하면 자동 복구도 시도해요.⁶

다른 사람과 진단 정보를 공유하려면 hermes dump를 사용하세요. 이 명령어는 API 키를 가린 간결한 일반 텍스트 요약을 생성하므로 GitHub 이슈나 Discord 스레드에 바로 붙여 넣을 수 있어요.⁶

Slash 명령어

Slash 명령어는 활성 채팅 세션(CLI 또는 메시징 플랫폼) 안에서 실행돼요. hermes_cli/commands.py의 공유 COMMAND_REGISTRY에서 명령어를 전달하므로 대부분의 명령어가 인터페이스에 관계없이 동일하게 작동해요.⁹

세션 제어

설정 및 모델

세션 도중 제공업체를 전환할 때는 /model 명령어가 핵심 역할을 해요.⁹

/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

v0.19.0에서는 /model --once가 추가됐어요. 한 차례에만 모델을 재정의하며 응답이 끝나면 이전 모델로 자동 복귀해요.²³

도구, Skills 및 정보

동적 Skill Slash 명령어

설치된 모든 skill은 자동으로 slash 명령어로 제공돼요.⁹

/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

v0.19.0부터 slash-skill 호출을 연이어 적용할 수 있어요. /skill-a /skill-b do XYZ는 하나의 차례에서 두 skill을 순서대로 불러오며, 연결된 이름에 자동 완성과 미리보기 텍스트도 제공해요.²³

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, 이메일, Home Assistant)에서만 작동해요.⁹

• /status — 세션 정보 표시
• /sethome (별칭 /set-home) — 현재 채팅을 플랫폼 홈으로 지정
• /approve [session|always] — 대기 중인 위험한 명령 승인
• /deny [reason] — 대기 중인 위험한 명령 거부. v0.19.0부터는 /deny <reason>이 거부 이유를 에이전트에 전달하므로, 에이전트가 이유를 모른 채 다시 시도하는 대신 접근 방식을 수정할 수 있어요²³
• /update — Hermes Agent를 최신 버전으로 업데이트
• /commands [page] — 모든 명령어와 skill을 페이지별로 탐색

또한 일부 명령어는 CLI에서만 사용할 수 있어요. /skin, /tools, /toolsets, /browser, /config, /cron, /skills, /platforms, /paste, /statusbar, /plugins.⁹

Tools 및 Toolsets

Hermes에는 웹 검색, 브라우저 자동화, 터미널 실행, 파일 편집, 메모리, 위임, RL 학습, 메시지 전송, Home Assistant 통합 등을 지원하는 폭넓은 내장 도구 레지스트리가 포함되어 있어요.¹⁰ 도구는 논리적인 toolset으로 구성되며, 플랫폼별로 활성화하거나 비활성화할 수 있어요.

상위 수준 카테고리

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

도구 관리

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>으로 도구를 전환할 수 있어요. 변경된 도구 모음을 적용하기 위해 세션이 초기화돼요.⁹

터미널 백엔드

터미널 도구는 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 기능 제거, 권한 상승 차단, PID 제한(프로세스 256개), 완전한 네임스페이스 격리, 볼륨을 통한 영구 작업 공간이 포함돼요.¹⁰

백그라운드 프로세스

터미널 도구는 명시적인 프로세스 관리 기능과 함께 백그라운드 실행을 지원해요.¹⁰

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 도구를 사용할 수 있어요.¹⁰

Sudo

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

Multi-Agent Kanban (v0.13.0+)

v0.13.0에서는 Multi-Agent 협업이 핵심 기본 요소로 자리 잡았어요. Agent와 재시작 전반에 걸쳐 작업, 상태, 작업자 식별 정보를 추적하는 영구 Kanban 보드가 도입되었어요.¹⁸ 이 보드 덕분에 Hermes 작업자 무리는 중단된 인계 과정에서 멈추지 않고 실제로 작업을 완료할 수 있어요.

Kanban 보드는 목표 측의 /goal(목표가 고정된 Ralph 루프), 그리고 생성 방식에 사용하는 기존 delegate_task 도구와 자연스럽게 연동돼요. 그 결과 모든 Agent가 다음에 수행할 작업, 현재 작업 담당자, 막힌 작업에 관한 하나의 정보 원천을 공유하는 작업자 무리 패턴이 만들어져요.

Skills 시스템

Skills는 에이전트가 필요할 때 불러올 수 있는 온디맨드 지식 문서예요. 토큰 사용량을 최소화하기 위해 점진적 공개 방식을 따르며 agentskills.io 공개 표준과 호환돼요.¹¹

모든 skills는 기본 디렉터리이자 단일 기준 정보원인 ~/.hermes/skills/에 저장돼요. 새로 설치하면 번들 skills가 저장소에서 복사돼요. Hub에서 설치하거나 에이전트가 만든 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)

에이전트는 실제로 필요할 때만 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는 사용 가능한 도구에 따라 표시되거나 숨겨질 수 있어요. 이 기능은 특히 대체 skills에 유용해요. 프리미엄 도구를 사용할 수 없을 때만 표시되어야 하는 무료 또는 로컬 대안이에요.¹¹

예시: 기본 제공 duckduckgo-search skill은 fallback_for_toolsets: [web]을 사용해요. FIRECRAWL_API_KEY가 설정되어 있으면 web toolset을 사용할 수 있으므로 에이전트는 web_search를 사용하고 DuckDuckGo skill은 숨겨져요. API 키가 없으면 DuckDuckGo skill이 자동으로 대체 수단으로 표시돼요.¹¹

에이전트가 관리하는 Skills

에이전트는 skill_manage 도구를 통해 자체 skills를 만들고 업데이트하거나 삭제할 수 있어요. 이는 에이전트의 절차 기억 역할을 해요. 에이전트가 복잡한 작업 흐름을 파악하면 나중에 재사용할 수 있도록 그 방법을 skill로 저장해요.¹¹

에이전트가 skills를 만드는 경우:¹¹ - 복잡한 작업을 성공적으로 완료한 후(도구 호출 5회 이상) - 오류나 막다른 경로를 겪은 뒤 제대로 작동하는 방법을 찾았을 때 - 사용자가 에이전트의 접근 방식을 바로잡았을 때 - 복잡한 작업 흐름을 발견했을 때

작업:¹¹

Skill Hub

온라인 레지스트리에서 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는 데이터 유출, 프롬프트 인젝션, 파괴적인 명령어, 공급망 위험 신호와 기타 위협을 확인하는 보안 검사를 거쳐요.¹¹

신뢰 수준:¹¹

--force를 사용하면 community skills에 적용된 위험하지 않은 정책 차단을 무시할 수 있어요. 하지만 dangerous 검사 판정은 무시할 수 없어요.¹¹

외부 Skill 디렉터리

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

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

경로에서는 ~ 확장과 ${VAR} 환경 변수 치환을 지원해요. 외부 디렉터리는 읽기 전용이에요. 에이전트가 skill을 만들거나 수정할 때는 항상 ~/.hermes/skills/에 저장해요. 동일한 이름의 skill이 두 위치에 모두 있으면 로컬 skill이 우선해요.¹¹

영구 메모리

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

두 파일은 모두 세션 시작 시 고정된 스냅샷으로 시스템 프롬프트에 삽입됩니다. 에이전트는 memory tool의 add, replace, remove를 사용해 자체 메모리를 관리합니다.¹²

고정 스냅샷 패턴: 시스템 프롬프트에 삽입되는 내용은 세션 시작 시 한 번만 캡처되며 세션 도중에는 변경되지 않습니다. 이는 의도된 동작으로, 성능을 위해 LLM의 프리픽스 캐시를 유지합니다. 세션 중 변경한 내용은 디스크에 즉시 저장되지만, 다음 세션이 시작될 때까지 시스템 프롬프트에는 반영되지 않습니다.¹²

저장할 내용

다음 내용은 저장하세요(에이전트가 능동적으로 수행합니다):¹² - 사용자 선호 사항: “JavaScript보다 TypeScript을 선호해요” → user - 환경 정보: “이 서버는 Debian 12와 PostgreSQL 16을 사용해요” → memory - 수정 사항: “Docker 명령에는 sudo를 사용하지 마세요. 사용자가 docker 그룹에 속해 있어요” → memory - 규칙: “프로젝트에서는 탭, 120자 줄 너비, Google 스타일 독스트링을 사용해요” → memory - 완료한 작업: “2026년 1월 15일에 데이터베이스를 MySQL에서 PostgreSQL로 마이그레이션했어요” → memory

다음 내용은 저장하지 마세요:¹² - 사소하거나 명백한 정보 - 쉽게 다시 찾을 수 있는 정보 - 원시 데이터 덤프(메모리에 저장하기에는 너무 큼) - 특정 세션에서만 유효한 일시적 정보 - 컨텍스트 파일에 이미 있는 정보

세션 검색

에이전트는 MEMORY.md와 USER.md 외에도 session_search tool을 사용해 과거 대화를 검색할 수 있습니다. 모든 CLI 및 메시징 세션은 FTS5 전문 검색 기능과 함께 SQLite(~/.hermes/state.db)에 저장됩니다. 쿼리를 실행하면 Gemini Flash가 요약한 관련 과거 대화가 반환됩니다.¹²

외부 메모리 제공자

Hermes에는 MEMORY.md와 USER.md보다 심층적인 영구 메모리를 제공하는 외부 메모리 제공자 플러그인 8개, Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, Supermemory가 포함되어 있습니다.¹²

외부 제공자는 내장 메모리를 대체하지 않고 함께 실행되며, 지식 그래프, 시맨틱 검색, 자동 정보 추출, 세션 간 사용자 모델링과 같은 기능을 추가합니다.⁶¹²

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 기반 작업은 프로세스가 재시작되더라도 더 이상 컨텍스트 창을 초기화하지 않습니다.

Checkpoints v2(v0.13.0 이상)

v0.13.0에서는 상태 저장 기능이 실질적인 정리, 디스크 보호 장치, 고립된 섀도 저장소가 없는 단일 저장소 설계로 새롭게 작성되었습니다.¹⁸ 이전 checkpoint 시스템은 장시간 실행되는 profile에서 디스크에 상태를 계속 누적했습니다. v2 저장소는 로컬 checkpoint 저장 공간에 엄격한 상한을 적용하고, 이러한 증가를 유발한 중복 관리 기록을 제거합니다. 사용자가 config를 변경할 필요는 없으며, 다음 checkpoint 쓰기부터 v2 경로를 사용합니다.

성격과 SOUL.md

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

Hermes는 기본 SOUL.md를 ~/.hermes/SOUL.md에 자동으로 생성합니다. 사용자 지정 profile에서는 $HERMES_HOME/SOUL.md에 생성됩니다. 기존 사용자 파일은 절대 덮어쓰지 않습니다. Hermes는 HERMES_HOME에서만 SOUL.md를 불러오며 현재 작업 디렉터리에서는 찾지 않습니다. 따라서 프로젝트가 달라져도 성격이 일관되게 유지됩니다.¹³

SOUL.md에 포함할 내용

지속적으로 적용할 말투와 성격 지침에 사용하세요.¹³ - 어조 - 소통 방식 - 직설적인 표현의 정도 - 기본 상호 작용 방식 - 문체에서 피해야 할 요소 - Hermes가 불확실성, 의견 충돌, 모호함을 처리하는 방식

다음 용도로는 가급적 사용하지 마세요:¹³ - 일회성 프로젝트 지침 - 파일 경로 - 저장소 규칙 - 임시 워크플로 세부 정보

이러한 내용은 SOUL.md가 아니라 AGENTS.md에 포함해야 합니다.

SOUL.md와 AGENTS.md 비교

이는 Hermes 정체성 관리에서 가장 중요한 차이입니다.¹³

SOUL.md — 정체성, 어조, 문체, 기본 소통 방식, 성격 수준의 행동 방식입니다.

AGENTS.md — 프로젝트 아키텍처, 코딩 규칙, 선호하는 tool, 저장소별 워크플로, 명령, 포트, 경로, 배포 참고 사항입니다.

유용한 원칙은 다음과 같습니다. 어디에서나 따라야 하는 내용은 SOUL.md에 포함하세요. 특정 프로젝트에 해당하는 내용은 AGENTS.md에 포함하세요.¹³

내장 성격

Hermes에는 /personality로 전환할 수 있는 내장 성격이 포함되어 있습니다.¹³

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

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와 /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 자격 증명으로 엄선된 도구 모음을 관리형으로 이용할 수 있어요. 별도의 API 키를 관리할 필요가 없습니다.²⁸ Hermes CLI 자체는 계속 MIT 라이선스가 적용되는 완전한 오픈 소스예요. 달라진 점은 이제 Portal 인증으로 모델 추론뿐만 아니라 더 많은 기능을 이용할 수 있다는 점이에요.

gateway에서 제공하는 기능

작동 방식

새로운 use_gateway 설정 필드를 통해 도구별로 gateway 사용을 선택할 수 있어요. hermes auth에 Portal 자격 증명이 있고 특정 도구에서 gateway를 활성화하면 해당 도구의 호출이 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를 사용할 수 있고 도구에 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 auth에 이미 등록된 Portal OAuth 자격 증명으로 구독 상태가 자동 감지되므로 별도로 로그인할 필요가 없어요. v0.19.0부터는 세션 안에서 구독 자체도 관리할 수 있어요. /subscription은 요금제와 남은 사용량을 보여 주고, 업그레이드 비용이나 다운그레이드 적용 시점을 정확히 미리 안내하며, 예약 변경 배너와 실행 취소 기능을 통해 변경 사항을 적용해요. /topup으로는 크레딧을 추가할 수 있어요. 데스크톱 앱에도 이에 대응하는 결제 설정 탭이 있습니다.²³

요금 및 이용 권한

요금과 등급 이름은 Nous Portal 요금 페이지(https://portal.nousresearch.com/pricing)에 게시돼요. 등급은 Hermes CLI가 아니라 Portal 제품에서 관리하고 Hermes 릴리스와 별개로 변경되므로 이 가이드에서는 등급을 열거하지 않아요. https://portal.nousresearch.com/에서 가입한 뒤 요금 페이지에서 현재 등급을 확인하세요.

지원 중단 안내

• HERMES_ENABLE_NOUS_MANAGED_TOOLS 환경 변수는 v0.10.0에서 제거되었습니다. 이제 관리형 도구는 도구별 use_gateway 설정 필드로 활성화하며, Portal 구독 상태에 따라 이용할 수 있어요.²⁸

이 릴리스에 대한 오해 바로잡기

Hermes Agent CLI는 구독해야만 이용할 수 있는 제품이 아닙니다. 프로젝트에는 여전히 MIT 라이선스가 적용되며, 모든 핵심 기능(CLI, skills, 메모리, messaging gateway, cron, MCP, 로컬 대시보드, 모든 제공업체의 BYOK)은 비용을 지불하지 않아도 처음부터 끝까지 사용할 수 있어요. v0.10.0은 이미 Nous Portal을 유료로 이용하는 사용자에게 편리한 경로를 추가했을 뿐이며, 무료 이용 경로에서 어떤 기능도 제거하지 않았어요.

Messaging Gateway

Hermes는 하나의 gateway 프로세스에서 22개 messaging 플랫폼에 연결되는 장기 실행 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 어댑터입니다.^327171819 v0.9.0에서는 BlueBubbles를 통한 iMessage 지원(자동 웹훅 등록, 설정 마법사, 충돌 복원력)과 iLink Bot API를 통한 네이티브 WeChat 지원이 추가되었으며, 기업용 앱을 위한 WeCom 콜백 모드도 도입되었어요.¹⁶ v0.11.0에서는 QQBot이 추가되었어요.²⁷ v0.12.0에서는 Microsoft Teams와 Tencent Yuanbao가 추가되었어요.¹⁷ v0.13.0에서는 20번째 플랫폼으로 Google Chat이 추가되었으며, 기존과 동일한 플러그형 어댑터 아키텍처를 사용해요. IRC와 Microsoft Teams도 범용 env_enablement_fn / cron_deliver_env_var 플러그인 훅을 사용하는 새로운 어댑터 패턴으로 이전되었어요.¹⁸ v0.14.0에서는 LINE과 SimpleX Chat이 추가되었으며, Graph 인증, 웹훅 리스너, 파이프라인 런타임, 아웃바운드 전송을 포함한 Microsoft Teams 스택이 처음부터 끝까지 완성되었어요.¹⁹ v0.17.0(2026년 6월 19일)에서는 Photon Spectrum을 통한 릴레이 없는 iMessage(hermes photon login으로 기기 코드 OAuth 사용, Mac/BlueBubbles 릴레이 불필요), 브리지 프로세스 요구 사항을 대체하는 공식 WhatsApp Business Cloud API 어댑터, SimpleX 그룹과 네이티브 첨부 파일, 번들 플랫폼 플러그인인 Raft가 추가되었어요.²¹

설정

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 토큰, 봇 아이디, 채널 매핑, 허용 목록을 단계별로 안내해요.⁶

메시지 처리 흐름

업스트림 아키텍처 문서에 따르면 다음과 같이 처리돼요.³

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 플랫폼은 CLI와 동일한 AIAgent 대화 루프를 통해 실행됩니다. 이 때문에 슬래시 명령어가 두 환경에서 동일하게 작동하며, Telegram에서 예약한 cron 작업의 결과를 Discord로 전달할 수도 있어요. 플랫폼 간 차이는 가장자리의 연결 방식뿐이에요.³

v0.19.0에서는 profile 기반 메시지 라우팅과 내구성 있는 전송 기능이 추가되었어요. 하나의 봇 토큰을 공유하는 단일 멀티플렉스 gateway에서 특정 길드, 채널 또는 스레드를 서로 다른 profiles로 라우팅할 수 있어요. 각 profile의 설정, skills, 메모리, 비밀 정보는 완전히 격리되며 GATEWAY_MULTIPLEX_PROFILES 재정의도 지원해요. 또한 안정성이 강화되어 하나의 profile이 잘못 설정되더라도 전체 gateway가 중단되지 않아요. 내부적으로 라우팅 인덱스는 state.db로 이전되었고, sessions.json은 이제 선택적인 레거시 미러로만 사용돼요. 최종 응답은 플랫폼 전송 전후에 내구성 있는 전송 의무 원장에 기록되므로, 답변이 완성된 직후 gateway가 중단되더라도 조용히 유실되지 않고 다음 부팅 시 다시 전송돼요.²³

사용자 인증 및 페어링

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

페어링 코드는 모르는 사람이 gateway와 대화하지 못하도록 막아 줘요. 사용자가 자신의 messaging 플랫폼에서 페어링 코드를 보내면 관리자가 hermes pairing approve로 승인해요. 승인된 사용자는 이후부터 계속 인증된 상태로 이용할 수 있어요.⁶

예약 작업 (Cron)

Hermes에는 셸 명령어가 아닌 agent 작업으로 실행되는 기본 cron 시스템이 있어요. 예약된 각 작업은 설정된 프롬프트와 선택적으로 첨부된 skills를 사용해 새로운 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

또는 messaging 채팅 안에서 대화로 작업을 생성할 수도 있어요.

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"

v0.19.0부터 MCP 도구는 mcp__server__tool 명명 규칙에 따라 모델에 노출돼요. 모든 도구 이름에 서버 이름이 포함되므로 2개의 서버가 같은 도구를 제공해도 더 이상 충돌하지 않아요. 또한 MCP 서버 로그 알림은 agent.log에 표시돼요.²³

서버로 사용 — Hermes 대화를 다른 agents에 공개하세요.

hermes mcp serve
hermes mcp serve -v    # Verbose

Context Compression

Hermes는 긴 대화가 모델의 컨텍스트 창을 벗어나지 않도록 자동으로 압축해요. 압축 요약기는 별도의 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은 압축할 대화의 중간 부분 전체를 전달받으므로, 기본 모델 이상의 컨텍스트 길이를 지원해야 해요.⁴

예산 압박 경고

에이전트가 도구를 많이 호출하는 복잡한 작업을 수행하면 자신도 모르는 사이에 반복 예산을 소진할 수 있어요. 기본값은 90턴이에요. 예산 압박 기능은 모델에 자동으로 경고해요.⁴

스트림 타임아웃

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

로컬 LLM는 큰 컨텍스트를 미리 채운 뒤 첫 번째 토큰을 생성하기까지 몇 분이 걸릴 수 있으므로, 로컬 endpoint의 소켓 읽기 타임아웃은 30분으로 연장돼요.⁴

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

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

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

watch_patterns를 사용하면 백그라운드 프로세스 출력에서 모니터링할 패턴을 설정하고, 패턴이 일치할 때 실시간 알림을 받을 수 있어요.¹⁶ 폴링하지 않고도 오류를 모니터링하고, 특정 이벤트인 “포트에서 수신 대기 중”을 기다리거나, 빌드 로그를 지켜볼 수 있어요. 백그라운드 작업이 완료되면 알려 주는 v0.8.0의 notify_on_complete와 결합되어, 이제 Hermes는 완전한 백그라운드 프로세스 관측 계층을 제공해요.¹⁵

교체 가능한 Context Engine (v0.9.0+)

이제 hermes plugins를 통해 컨텍스트 관리를 교체 가능한 슬롯으로 사용할 수 있어요. 필터링, 요약, 도메인별 컨텍스트 주입 등을 통해 에이전트가 매 턴마다 확인할 내용을 제어하는 커스텀 context engine으로 교체할 수 있어요.¹⁶ 컨텍스트 전략이 핵심 에이전트 루프에서 분리되므로, 프로젝트나 도메인별로 컨텍스트를 맞춤 설정할 수 있어요.

백업 및 복원 (v0.9.0+)

hermes backup은 설정, 세션, skill, memory를 모두 포함한 아카이브를 생성해요. hermes import는 백업 아카이브에서 이를 복원해요.¹⁶ 컴퓨터 간에 환경을 이전하거나, 큰 변경 전에 스냅샷을 만들거나, 정상 작동이 확인된 구성을 팀원과 공유할 때 사용하세요.

Termux 및 Android 지원 (v0.9.0+)

Hermes는 Termux를 통해 Android에서 네이티브로 실행돼요. 조정된 설치 경로, 모바일 화면에 맞춘 TUI 최적화, 음성 backend 지원, /image 명령을 기기에서 사용할 수 있어요.¹⁶

보안 강화 (v0.13.0+)

v0.13.0에서는 P0 보안 문제 8개를 해결하고, 기본 설정 1개를 사용자에게 더 안전한 방향으로 변경했어요.¹⁸ 이어서 v0.14.0에서는 P0 문제 12개와 P1 문제 50개를 추가로 해결했어요. 여기에는 sudo 무차별 대입 및 sudo 표준 입력 강화, 위험한 명령 우회 수정, 모델에 다시 주입하기 전 도구 오류 정제, 대시보드 plugin API 인증, skills-hub SSRF 방어, 설치 중 공급망 보안 권고 검사 등이 포함돼요.¹⁹

Hermes 배포 환경을 관리한다면 v0.13.0과 v0.14.0을 단순한 기능 업데이트가 아닌 보안 관련 업그레이드로 간주하세요. v0.13.0은 Discord 서버 간 우회 문제와 2개의 TOCTOU 구간을 해결했으며, v0.14.0은 sudo 처리, 도구 오류 재주입, plugin APIs, skills-hub SSRF, 의존성 보안 권고 전반을 추가로 강화했어요.

실무자를 위한 아키텍처

이 섹션은 내부에서 어떤 일이 일어나는지 이해해 디버깅하거나, 기능을 확장하거나, 성능을 분석하려는 분을 위한 내용이에요. 업스트림 아키텍처 문서를 종합했어요.³

진입점 → 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    │  │              │             │
│  └──────────────┘ └──────────────┘  └──────────────┘             │
└──────────────────────────────────────────────────────────────────┘

업스트림 아키텍처 문서를 바탕으로 수정한 다이어그램이에요.³

배너의 “28 tools”와 “47 tools / 20 toolsets”가 다른 이유. “47 tools”는 업스트림 저장소의 전체 도구 레지스트리 수예요. 즉, 모든 toolset에 걸쳐 Hermes가 소스 코드와 함께 제공하는 모든 도구를 뜻해요. 실제로 실행 중인 CLI의 시작 배너에는 이보다 작은 숫자가 표시돼요. 이 가이드를 검증할 때 사용한 설치 환경에서는 28 tools / 89 skills로 표시됐어요. 이는 버그가 아니에요. 많은 toolset은 선택 사항이며 config.yaml의 toolsets: 아래에서 명시적으로 활성화해야 해요. 메시징 플랫폼 어댑터, 브라우저 자동화, 고급 스크래핑 도구 등이 여기에 해당해요. 레지스트리의 전체 수는 “사용 가능한 항목”을, 배너의 숫자는 “현재 profile에서 활성화된 항목”을 뜻해요. hermes tools --list로 활성화된 toolset을 확인하고, ~/.hermes/config.yaml의 toolsets: 블록에서 개별 toolset을 활성화하거나 비활성화하세요. 실행 중인 세션 안에서는 /tools list, /tools enable <name>, /tools disable <name>을 사용할 수도 있어요. 도구를 제거하면 에이전트가 도구 매니페스트를 다시 구성할 수 있도록 세션이 초기화돼요.

3가지 API 모드

Hermes는 제공자별 차이를 3가지 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가 기반이며, 나머지 모든 요소가 그 위에 쌓여요.¹³

세션 저장소

SQLite 기반 세션 저장소이며 FTS5 전체 텍스트 검색을 지원해요. 세션에는 계보 추적 기능이 있어 압축 전후의 부모와 자식 관계를 기록하며, 플랫폼별 격리와 경합 처리를 포함한 원자적 쓰기도 지원해요.³

플러그인 시스템

탐색 소스는 ~/.hermes/plugins/(사용자), .hermes/plugins/(프로젝트), pip 진입점의 3가지예요. 플러그인은 컨텍스트 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), 에이전트 기본값(추론 수준, 압축, 사람처럼 보이기 위한 지연 시간, 시간대, 샌드박스), 세션 초기화 정책, 승인 규칙, TTS 설정, 브라우저 설정, 도구 설정, 실행 제한 시간, 명령 허용 목록, gateway 설정, 3개 소스의 API 키예요.⁶

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

API 키는 설정값 → ~/.openclaw/.env → auth-profiles.json 순으로 3개 소스를 확인해 결정해요.⁶

문제 해결

“추론 제공자가 설정되지 않았습니다. 제공자와 모델을 선택하려면 ‘hermes model’을 실행하세요”

새로 설치할 때 가장 먼저 마주치는 오류입니다. Hermes에 아직 확정된 제공자가 없다는 뜻이에요. 즉, 3가지 인증 경로 중 어느 것도 사용할 수 있는 제공자를 준비하지 못한 상태입니다. 다음을 실행하세요.

hermes model

대화형 선택 화면에서는 OAuth 기기 코드 흐름(Nous Portal, GitHub Copilot, Anthropic, OpenAI Codex)과 자체 호스팅 서버용 사용자 지정 엔드포인트를 포함하여 지원되는 모든 제공자를 안내해요. 제공자가 이미 설정되어 있어야 한다고 생각했다면 hermes doctor를 실행해 Hermes에서 실제로 확인할 수 있는 자격 증명을 살펴보세요. 흔한 원인으로는 API 키를 잘못된 위치에 설정한 경우(셸 프로필이 아니라 .env에 넣거나 hermes config set으로 설정해야 해요), ~/.hermes/auth.json의 OAuth 자격 증명이 만료된 경우, config.yaml의 사용자 지정 엔드포인트에서 base_url이 누락된 경우가 있습니다. 인증 경로는 인증 및 제공자에서 자세히 설명해요.²⁷

“API 키가 설정되지 않음”

hermes model을 실행하여 제공자를 대화형으로 설정하거나 hermes config set OPENROUTER_API_KEY your_key를 실행하세요. hermes doctor 명령을 사용하면 누락된 키를 정확히 확인할 수 있어요.⁷

시작 시 “컨텍스트 제한: 2048 토큰”이 표시됨(로컬 모델)

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

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

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

서버에서 도구 호출이 활성화되지 않았거나, 서버 구현을 통해 해당 모델의 도구 호출을 사용할 수 없는 상태입니다.²

응답이 문장 중간에서 끊김

가능한 원인은 2가지입니다.²

1. 서버의 출력 한도(max_tokens)가 낮게 설정되어 있을 수 있어요. SGLang은 기본적으로 응답당 128토큰을 사용합니다. 서버에서 --default-max-tokens를 설정하거나 config.yaml에서 model.max_tokens를 구성하세요.
2. 컨텍스트가 소진되었을 수 있어요. 모델이 컨텍스트 창을 모두 채운 상태입니다. model.context_length를 늘리거나 Hermes에서 컨텍스트 압축을 활성화하세요.

WSL2에서 Windows에 호스팅된 모델 서버에 연결할 때 “연결이 거부됨”

WSL2는 자체 서브넷이 있는 가상 네트워크 어댑터를 사용해요. 따라서 WSL2 내부의 localhost는 Windows 호스트가 아니라 Linux 가상 머신을 가리킵니다. 해결 방법은 2가지입니다.²

미러링 네트워킹(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 위치를 출력해요.⁶

자주 묻는 질문

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

Claude Code은 Anthropic에서 공식 제공하는 CLI이며, Anthropic 모델만 사용할 수 있어요. Hermes Agent는 Nous Research의 오픈 소스 에이전트 프레임워크로, Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Hugging Face, Google 또는 자체 호스팅 엔드포인트 등 OpenAI 호환 제공자라면 어디서든 사용할 수 있습니다.¹² 또한 Hermes에는 Claude Code에서 제공하지 않는 Telegram/Discord/Slack/WhatsApp/Signal용 메시징 gateway가 포함되어 있어요.

Hermes에서 Anthropic API 키를 사용할 수 있나요?

네. 다음 3가지 방법이 있어요.²

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(설정 토큰 또는 OAuth 토큰)을 대체 수단으로 설정하세요

같은 컴퓨터에서 이미 Claude Code을 사용하고 있다면 2번 방법을 권장해요. 갱신할 수 있는 Claude 자격 증명의 갱신 기능을 그대로 유지할 수 있습니다.

대화를 잃지 않고 제공자를 전환하려면 어떻게 하나요?

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

/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, 설정, 메모리, 세션, gateway 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는 Ollama, vLLM, SGLang, llama.cpp/llama-server, LM Studio, LocalAI, Jan 또는 자체 서버 등 OpenAI 호환 서버라면 어디서든 사용할 수 있습니다.² 서버별 설정은 사용자 지정 및 자체 호스팅 엔드포인트를 참고하세요.

시작 배너에 가이드보다 적은 수의 도구가 표시되는 이유는 무엇인가요?

가이드에 나온 47개 도구와 20개 toolset은 업스트림 아키텍처 레지스트리를 기준으로 한 수치로, Hermes가 모든 toolset에 걸쳐 소스 코드를 제공하는 도구의 전체 개수예요. 실행 중인 설치 환경의 배너에는 더 적은 수가 표시됩니다. 이 가이드에서 사용한 참조 설치 환경에는 28개 도구가 표시돼요. Hermes가 시작할 때 기본 toolset 모음만 활성화하기 때문입니다. 여러 toolset은 사용자가 직접 활성화해야 해요. 메시징 gateway 어댑터, 브라우저 자동화, 고급 스크래핑 스택과 일부 특수 통합 기능은 로드되기 전에 ~/.hermes/config.yaml의 toolsets: 아래에 명시적으로 등록해야 합니다. 레지스트리 합계는 “활성화하면 사용할 수 있는 항목”이고, 배너 합계는 “현재 profile에 실제로 로드된 항목”이에요. hermes tools --list를 사용하면 활성 상태인 toolset과 사용 가능하지만 비활성화된 toolset을 확인할 수 있습니다. /tools enable <name>과 /tools disable <name>으로 런타임에 개별 toolset을 전환하세요. 비활성화하면 세션이 재설정되어 에이전트가 변경된 구성에 맞게 도구 매니페스트를 다시 만들어요.

기본 제공자에 문제가 생기면 Hermes는 모델 대체를 어떻게 처리하나요?

config.yaml에서 fallback_model 블록을 설정하세요.²

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

기본 모델이 실패하면(요청 한도 초과, 서버 오류, 인증 실패) Hermes는 대화 기록을 잃지 않고 세션 도중에 대체 모델로 전환해요. 세션당 최대 1번만 실행됩니다.

에이전트가 시간이 지남에 따라 자체 skill을 개선할 수 있나요?

네. 이것이 바로 Hermes Agent의 “자기 개선” 기능입니다. 에이전트는 skill_manage tool을 통해 skill을 생성, 업데이트, 삭제할 수 있어요. 복잡한 워크플로를 파악하면 나중에 다시 활용할 수 있도록 그 접근 방식을 skill로 저장합니다.¹¹ 에이전트는 복잡한 작업(도구 호출 5회 이상)을 마쳤을 때, 오류를 겪고 작동하는 방법을 찾았을 때, 사용자가 접근 방식을 수정해 주었을 때, 또는 복잡한 워크플로를 발견했을 때 skill을 생성해요.

IDE 통합 기능이 있나요?

네. Hermes는 VS Code, Zed, JetBrains용 ACP(Agent Client Protocol) 서버로 실행할 수 있어요.⁶

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

변경 기록

참고 자료