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.21 계열의 변경 사항을 통합한 패치인 v0.21.5(태그 v2026.9.24, 2026년 9월 24일)입니다. v0.21.5의 새로운 기능에서 변경 사항을 확인할 수 있으며, 이후 릴리스 섹션은 최신 버전부터 오래된 버전순으로 이어집니다.⁵² 대부분의 신규 사용자가 가장 어려워하는 부분은 제공업체 인증입니다. Hermes는 태그 v2026.9.24를 기준으로 정적 선택 목록에 39개 제공업체를 포함하며, 번들로 제공되는 38개 제공업체 플러그인을 통해 이 목록을 자동으로 확장합니다. 여기에 사용자 지정 엔드포인트와 서로 다른 3가지 인증 경로가 있습니다. 인증 경로는 .env의 API 키, hermes model을 통한 OAuth, 또는 config.yaml의 사용자 지정 엔드포인트입니다.⁵³ 가장 먼저 익혀야 할 부분은 인증 모델입니다. 나머지 모든 동작은 어떤 제공업체가 선택되는지에 따라 결정됩니다.

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

Hermes를 가볍게 사용하는 것과 전문적으로 사용하는 것의 차이는 5가지 시스템을 얼마나 잘 다루는지에 달려 있습니다. 다음을 숙달하면 Hermes를 강력한 생산성 증폭 도구로 활용할 수 있습니다.

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

핵심 요점

• 제공업체 인증에는 하나가 아닌 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 호출로 실행됩니다. 해당 태그에서 auto는 이 모든 작업을 주 채팅 모델로 전달합니다. 따로 설정할 필요는 없지만, 비용이 높은 추론 모델을 사용하면 이러한 부가 작업으로 상당한 비용이 발생할 수 있습니다. 비용이 중요하다면 개별 auxiliary.<task> 슬롯에 저렴하고 빠른 모델을 지정하세요.⁴³⁴

아래의 모든 섹션은 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. agent/prompt_builder.py를 통해 SOUL.md, MEMORY.md, USER.md, skill, context 파일, 도구 지침으로 시스템 프롬프트를 구성합니다. 2026년 9월의 코드 분리 작업을 통해 이 기능은 새로운 agent/ 패키지로 이동했습니다.³
2. runtime_provider.py를 통해 런타임 공급자를 결정합니다. 이 단계에서 인증 방식, 기본 URL, API 모드를 선택합니다.³
3. chat_completions, codex_responses, anthropic_messages 중 하나의 API 모드로 공급자를 호출합니다.³
4. 반환된 도구 호출을 model_tools.py와 중앙 도구 레지스트리(tools/registry.py)를 통해 전달합니다.³
5. 모델이 최종 응답을 생성할 때까지 루프를 반복한 다음, 세션을 FTS5를 사용하는 SQLite에 저장합니다.³

이 루프를 이해해야 하는 이유는 성격, 메모리, skill, 압축, 대체 처리 등 모든 기능이 이 단계 중 하나에 연결되기 때문입니다. 설정 키를 살펴보다가 그 역할이 궁금하다면, 대개 “위 루프의 1, 2, 3, 4단계 중 하나를 조정하는 항목”이라고 이해하면 됩니다.

플랫폼에 구애받지 않는 핵심 구조. 하나의 AIAgent 클래스가 CLI, gateway, ACP, 배치, API 서버를 모두 처리합니다. 플랫폼별 차이는 agent 자체가 아니라 진입점에 있습니다.³ 따라서 터미널과 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.21.5의 새로운 기능(9월 24일 통합 릴리스)

Hermes Agent v0.21.5(태그 v2026.9.24, 2026년 9월 24일)는 현재 릴리스이며, v0.21.x 계열의 세 번째 소규모 통합 릴리스입니다. “이 태그는 v0.21.4 이후 병합된 약 460개의 PR을 하위 소비자가 사용할 수 있는 안정적인 태그 릴리스로 통합합니다.” 엄선된 릴리스 노트는 다시 v0.22.0으로 미뤄졌습니다. 다음은 해당 태그의 소스에서 확인한 운영자 관련 변경 사항입니다.⁵²⁵³

• Hindsight 메모리가 핵심 코드 트리에서 분리되었습니다. 번들로 제공되던 Hindsight 공급자와 hermes-agent[hindsight] pip 추가 패키지는 제거되었습니다. 이제 Hindsight는 Vectorize가 관리하는 플러그인 카탈로그에서 설치하며, 이 변경 사항은 릴리스 노트에 기재되지 않았습니다. 설정에 memory.provider: hindsight가 지정되어 있으면 hermes update가 이를 사용하는 모든 profile 홈에 카탈로그 플러그인을 설치합니다. 그래도 설치되어 있지 않다면 agent를 처음 시작할 때 설치됩니다. 단, security.allow_lazy_installs가 false이면 자동으로 설치되지 않으므로 hermes plugins install hindsight를 실행해야 합니다. 설정, .env 키, 메모리 데이터는 변경되지 않습니다. 외부 메모리 공급자를 참조하세요.
• gateway.multiplex_profiles: false가 폐지되었습니다. gateway는 이 값을 해당 파일에서 true로 다시 작성하고, 일회성 테두리 알림을 표시합니다. 자체 gateway를 유지해야 하는 명명된 profile은 자체 config.yaml에서 gateway.standalone: true를 설정해야 합니다. 서비스 중인 profile 하나를 오프라인으로 전환할 때는 이제 hermes -p <name> gateway stop을 실행하면 호스트를 중지하지 않고 해당 profile만 대기 상태로 전환합니다. 메시징 Gateway를 참조하세요.
• Nous 및 OpenRouter 선택기에 새로운 모델이 추가되었습니다. GPT-6 Sol과 GPT-6 Luna에는 각각 -pro 변형이 제공되며, Claude Opus 5.5도 추가되었습니다.
• 플러그인 호환성은 변경되지 않았습니다. plugins.allow_deprecated_imports: true는 계속 작동합니다.

업데이트 방법: hermes update 또는 설치 프로그램 한 줄 명령을 사용하세요. Docker 및 Hermes Cloud 이미지는 nousresearch/hermes-agent:v2026.9.24에서 빌드됩니다.⁵²

v0.21.4의 새로운 기능 (두 번째 통합 패치)

Hermes Agent v0.21.4(태그 v2026.9.21, 2026년 9월 21일)는 v0.21.x 계열에서 의도적으로 변경 사항을 최소화한 두 번째 통합 릴리스입니다. 릴리스 자체에서는 다음과 같이 설명합니다. “패치 릴리스입니다. 이 태그는 v0.21.3 이후 병합된 약 1,800개의 PR을 하위 소비자(Docker 이미지, Hermes Cloud, 호스팅 배포)가 사용할 수 있도록 안정적인 태그 릴리스로 통합합니다.” v0.21.3 이후 구간에는 “병합을 제외한 커밋 5,071개”, “변경된 파일 5,169개”, “병합된 PR 1,812개”, “종료된 이슈 2,116개”가 포함됩니다. 커밋 수를 기준으로 하면 프로젝트 역사상 태그 사이 구간 중 v0.21.1의 5,139개에 이어 두 번째로 크며, 병합된 PR 수를 기준으로는 가장 큽니다. 엄선된 변경 내역은 이번에도 다음과 같은 문구와 함께 미뤄졌습니다. “이 구간의 전체 선별 릴리스 노트는 v0.22.0과 함께 제공되며, v0.21.0 이후의 모든 변경 사항을 문서화합니다.” 또한 “이 구간에서는 어떤 항목도 누락하지 않습니다.” 릴리스 노트에는 이번에 문서화하지 않은 항목이 나열되어 있으며, 아래의 각 항목은 해당 태그의 소스에서 확인했습니다. 이 가이드의 기존 섹션을 변경하는 항목에는 관련 링크를 바로 덧붙였습니다.⁵⁰⁵¹

• 호스트마다 gateway 하나만 실행하며, Desktop은 다시 생성하지 않고 연결합니다. OS 사용자별로 호스트마다 hermes serve 하나와 hermes gateway run 하나만 실행하고, 각각 모든 profile을 다중화한다는 원칙입니다. 새로 추가된 호스트 전역 단일 인스턴스 계층이 이를 강제합니다. 이 계층은 실행권을 확보한 프로세스가 살아 있는 동안 유지하는 호스트 잠금과 (pid, createTime)을 담은 접선 레코드로 구성됩니다. 따라서 두 번째 호출은 소유자가 동일한 활성 프로세스인지 확인한 뒤 두 번째 포트를 바인딩하는 대신 기존 프로세스에 연결할 수 있습니다. 오래된 상태라고 추정하지 않고 반드시 입증하며, Desktop 앱도 같은 방식을 적용해 두 번째 백엔드를 생성하지 않고 호스트에서 실행 중인 백엔드에 연결합니다. 자세한 작동 방식은 메시징 Gateway를 참조하세요.⁵¹
• 커넥터가 백엔드 소유의 단일 작업과 하나의 설정 카드로 통합됩니다. manage_connections tool 호출이 백엔드에서 순수 데이터 기반 연결 상태 머신을 구동하며, Desktop, TUI, CLI는 이를 모두 동일한 설정 카드로 표시합니다. 누락된 자격 증명마다 필드 하나가 제공되며, 모든 필수 필드에 텍스트가 입력될 때까지 카드의 동작 버튼은 활성화되지 않습니다. Nous 무료 등급 하위 섹션을 참조하세요.⁵¹
• --format stream-json: 머신에서 읽을 수 있는 일회성 실행 형식입니다. hermes chat -q ... --format stream-json은 CI 실행기와 오케스트레이터를 위해 stdout의 각 줄에 JSON 객체 하나를 출력합니다. 먼저 system/init 이벤트가 나오고, 이어서 text 델타, tool_use, tool_result 이벤트가 나온 뒤, 마지막으로 종료 코드, 최종 텍스트, 토큰 통계를 담은 result 봉투 하나가 출력됩니다. 진단 정보와 세션 ID는 stderr에 유지되며, tool 출력은 이벤트당 5,000자로 제한됩니다. 이 플래그는 --quiet를 암묵적으로 적용하고 -q 또는 --query-file이 필요하며, 둘 다 없으면 종료 코드 2를 반환합니다. --tui와 함께 사용할 수 없습니다. 해당 플래그는 hermes chat 옵션 표에 추가되었습니다.⁵¹
• skills.auto_load가 모든 세션에 skill을 고정합니다. config.yaml의 skills.auto_load 아래에 나열된 이름은 CLI, TUI, gateway, cron, API을 비롯한 모든 새 세션에 완전히 로드되며, 프롬프트를 처음 구성할 때 한 번만 확인됩니다. Skills System에 고정된 Skill 하위 섹션이 추가되었습니다.⁵¹
• 승인되지 않은 DM을 위한 decline 옵션이 추가되었습니다. unauthorized_dm_behavior에는 pair와 ignore 외에 세 번째 값인 decline이 추가되었습니다. 이 값은 정중한 거절 메시지를 한 번 보낸 뒤 해당 발신자에게 24시간 동안 응답하지 않습니다. 사용자 승인 및 페어링을 참조하세요.⁵¹
• mcp.discovery_concurrency가 MCP 탐색 연결 수를 제한합니다. 기본값은 4이며 0은 무제한을 뜻합니다. 설정된 모든 서버에 여전히 연결하지만, 더 이상 모든 연결이 한꺼번에 시작되지 않습니다. MCP 통합을 참조하세요.⁵¹
• session_search에 시간 범위와 검색 재시도 기능이 추가되었습니다. 탐색 형식은 after/before 범위(ISO 또는 7d 같은 상대 기간)를 지원하며, 여러 단어로 검색한 결과가 0개이면 FTS5가 암묵적으로 적용하는 모든 단어 AND 조건 대신 어느 단어든 일치하는 조건으로 다시 검색합니다. 세션 검색을 참조하세요.⁵¹
• hermes sessions set-journal-mode delete|wal: 오프라인 저널 변환 도구입니다. 잘못된 SQLite 저널 모드에 고정된 state.db를 사용자가 직접 복구하는 경로입니다. 이전에는 PRAGMA journal_mode=DELETE를 직접 실행해야 했습니다. 먼저 gateway, dashboard, 모든 CLI를 중지해야 합니다. 다른 프로세스가 데이터베이스를 점유하고 있으면 작업을 거부하며, 열려 있는 프로세스가 종료되기를 기다리지 않고 모드를 전환한 뒤 SQLite 헤더 바이트를 검증합니다. Windows에서는 점유 프로세스를 검색할 수 없으므로, 모든 Hermes 프로세스를 직접 중지하고 --force를 전달해야 실행됩니다. 이제 hermes doctor도 이 명령을 안내합니다. 최상위 명령의 hermes sessions 행에서 확인할 수 있습니다.⁵¹
• Desktop: 글꼴 설정, 원클릭 엔진 업데이트, plugin 제거 기능이 추가되었습니다. 설정에 profile별로 desktop.font_family에 저장되는 글꼴 모음 필드가 추가되었습니다. 이 설정은 채팅과 UI 전반에서 테마의 산세리프 글꼴을 재정의합니다. 제안 목록에는 접근성이 좋은 글꼴(OpenDyslexic, Atkinson Hyperlegible, Lexend)이 먼저 표시되며, 비워 두면 테마가 글꼴을 결정합니다. 관리형 로컬 모델 런타임에는 업데이트가 있을 때 “엔진 업데이트” 버튼이 표시되며, 업데이트에 실패해도 버튼이 계속 표시되어 바로 다시 시도할 수 있습니다. 또한 Plugins 허브에서는 확인 대화 상자를 거쳐 plugin을 제거할 수 있습니다.⁵¹
• 비디오 카탈로그: LTX 2.5와 Kling O3가 추가되었습니다. FAL 비디오 plugin에 ltx-2.5(Lightricks의 오픈 소스 오디오 및 비디오 모델: 기본 오디오 지원, 최대 20초 및 4K 이미지 투 비디오, 카메라 움직임 프리셋, 저가 등급. fal은 1440p/2160p에서 10초를 초과하는 클립을 거부합니다)와 kling-o3(Kuaishou의 최첨단 모델 제품군, 프리미엄 등급: 여러 장면을 활용한 기본 스토리텔링, 선택적 오디오, 3~15초)가 추가되었습니다.⁵¹
• plugin 카탈로그가 함께 배포되는 디렉터리이자 웹사이트로 바뀝니다. 저장소의 plugin-catalog/ 디렉터리는 v2026.9.14의 항목 9개에서 이 태그의 228개로 늘어났습니다. 각 plugin에는 검토된 YAML 하나가 있으며 정확한 커밋 SHA에 고정됩니다. 이제 문서 사이트는 plugin별 페이지와 작성자별 페이지를 생성하고, 각 페이지에는 고정된 커밋의 plugin README가 표시됩니다. 릴리스에서 소개한 커뮤니티 plugin 10개도 모두 해당 태그의 카탈로그에 포함되어 있습니다. 자세한 내용은 Plugin System을 참조하세요.⁵¹
• 그리고 대규모 수정 작업이 진행되었습니다. profile 및 다중화 격리, cron, 칸반, Desktop, state.db 전반에 걸친 수정 사항이며, 릴리스에서는 범주만 소개합니다. 엄선된 수정 기록은 v0.22.0에서 작성될 예정입니다.⁵⁰

이 구간에도 plugin 호환성 되돌리기는 아직 반영되지 않았습니다. COMPAT_MANIFEST.md, compat_manifest.json, 호환성 보정 코드는 모두 v2026.9.21에 남아 있습니다. 이 구간에서 hermes_cli/plugin_compat.py에 적용된 변경은 프로세스 전역 검색 캐시(다중화 gateway는 제공되는 profile마다 plugin을 한 번 검색하며, 모든 plugin의 소스를 반복해서 구문 분석하면 부팅 경로에서 profile당 약 0.4초가 걸렸습니다)와 Windows의 POSIX 형식 적중 경로(#112576)뿐입니다. 날짜 제한과 리터럴 불리언 우회 설정은 변경되지 않았으므로, plugins.allow_deprecated_imports: true를 사용하면 영향을 받는 plugin을 계속 로드할 수 있습니다. Plugin System의 호환성 상자에서 현재 상태를 확인할 수 있습니다.⁴²

업데이트 방법은 바뀌지 않았습니다. git으로 설치한 경우 hermes update를 사용하고, 새로 설치할 때는 셸 설치 프로그램을 사용합니다. Docker 및 Hermes Cloud 이미지는 이 태그에서 빌드됩니다(nousresearch/hermes-agent:v2026.9.21).⁵⁰

v0.21.3의 새로운 기능 (9월 14일 패치)

Hermes Agent v0.21.3(태그 v2026.9.14, 2026년 9월 14일)은 main의 3일 치 변경 사항을 항목 2개짜리 릴리스 노트로 묶은 버전입니다. Cloud 에이전트가 최신 릴리스 태그로 자동 업데이트되며, 원격 gateway 로그인 수정 사항이 해당 에이전트에 적용되어야 했기 때문에 릴리스되었습니다. (1) 이제 새로 고침 요청이 몰려도 원격 dashboard 세션이 취소되지 않습니다. gateway의 두 새로 고침 경로(쿠키 게이트와 Desktop의 기본 bearer 경로)는 동일한 순환형 새로 고침 토큰을 사용하는 동시 요청을 하나의 작업으로 합칩니다. 따라서 Desktop이 절전 상태에서 깨어날 때 요청이 몰려도 이미 교체된 토큰이 Portal의 재사용 감지 기능에 다시 전달되어 전체 세션이 취소되는 일이 없습니다. 또한 새로 고침은 이벤트 루프 외부에서 실행되므로 느린 ID 공급자가 더 이상 /api/status를 멈추게 하지 않습니다. (2) 장기 실행 프로세스가 중복된 state.db 쓰기 핸들을 생성하지 않습니다. gateway, dashboard/Desktop 백엔드, ACP, CLI 판독기는 읽기 전용으로 연결되며, 프로세스 내부의 쓰기 작업은 레지스트리 핸들을 공유합니다. 이 구간에는 “병합을 제외한 커밋 1,036개”, “변경된 파일 2,642개”, “병합된 PR 338개”가 포함됩니다. 그 밖의 모든 내용은 의도적으로 미뤄졌습니다. 릴리스는 문서화하지 않은 항목(모든 모델 선택기의 추론 강도 선택 기능, OpenRouter OAuth PKCE, HEIF/HEIC/AVIF 디코딩, 대규모 FAL 카탈로그 추가, Slack에 붙여 넣은 표와 Agent Sessions API, 가상 머신 간 파일 시스템에서의 state.db WAL 거부 등)을 밝히고, 엄선된 기록을 제공하겠다고 다음과 같이 약속합니다. “이 구간의 전체 선별 릴리스 노트는 v0.22.0과 함께 제공되며, v0.21.0 이후의 모든 변경 사항을 문서화합니다.” 또한 “이 구간에서는 어떤 항목도 누락하지 않습니다.”⁴⁹

그리고 plugin 호환성 기한은 예정대로 도래했습니다. v0.21.1에서 예고한 2026년 9월 14일 제거 조치는 코드 되돌리기가 아니라 배포된 코드의 날짜 제한으로 적용되었습니다. 태그 v2026.9.14에서 hermes_cli/plugin_compat.py는 COMPAT_REMOVAL_DATE = 2026-09-14를 포함하며, removal_in_effect()는 해당 날짜부터 참을 반환합니다. 매니페스트 파일이 사라지면 날짜와 관계없이 즉시 참을 반환합니다. 따라서 영향을 받는 외부 plugin은 이제 로드할 때 빨간색 안내문과 함께 비활성화됩니다. 아직 일어나지 않은 일은 이전 가져오기 경로를 실제로 삭제하는 되돌리기입니다. COMPAT_MANIFEST.md, compat_manifest.json, 호환성 보정 코드는 해당 태그에 여전히 남아 있으며, v2026.9.21과 9월 22일 기준 main에도 남아 있습니다. 이 때문에 plugins.allow_deprecated_imports: true가 여전히 우회 설정으로 작동합니다. 로더가 진행하도록 허용하면 이전 경로가 계속 해석됩니다. 주의할 점은 2가지입니다. 키에는 반드시 리터럴 YAML 불리언을 사용해야 합니다. 코드는 불리언 True만 허용하며, "true"나 "false"처럼 따옴표로 감싼 문자열은 소스 주석 “리터럴 불리언만 허용”에 따라 설정되지 않은 것으로 처리됩니다. 또한 되돌리기가 반영되는 즉시 경로 자체가 사라지므로 이 우회 설정도 작동하지 않게 됩니다. Plugin System의 호환성 상자에서 현재 상태를 확인할 수 있습니다.⁴²⁴⁹

v0.21.2의 새로운 기능 (state.db 패치 릴리스)

Hermes Agent v0.21.2(태그 v2026.9.11, 2026년 9월 11일)는 무엇보다도 v0.21.0에서 발생한 문제를 해결하기 위한 릴리스입니다. 릴리스 노트는 이를 명확히 설명합니다. “v0.21.0에는 세션 저장소의 연결 처리 방식을 대폭 재작성한 변경 사항이 포함되었으며, 일부 설치 환경에서는 이로 인해 state.db가 불안정해졌습니다. 두 번째 쓰기 프로세스가 서로의 잠금을 취소하고, 정상적인 데이터베이스를 손상된 것으로 보고하며, 잘못된 행 하나 때문에 sessions list 전체가 실패했습니다. 이번 릴리스는 이 문제 유형을 해결하고, v0.21.1 이후 4일 동안 main에 반영된 나머지 변경 사항도 모두 포함합니다.” 의도적으로 간략하게 작성된 v0.21.1의 릴리스 노트와 달리, 이번 릴리스는 주요 변경 사항을 직접 설명합니다. 이 기간에는 “병합을 제외한 커밋 947개”, “변경된 파일 1,869개”, “병합된 PR 312개”, “기여자 140명”이 기록되었으며, v0.21.x 전체에 대한 선별된 기록은 여전히 v0.22.0에서 작성할 예정입니다.⁴⁸

• state.db 안정성 개선 작업: PR 6개로 이슈 44개 해결. 릴리스에서 가장 먼저 제시하는 운영자 권장 사항은 여러분도 따라야 합니다. 0.21.0이나 0.21.1에서 state.db가 손상되었다면 hermes doctor를 실행하세요. 이제 모든 문제를 “FTS 쓰기 손상”이라고 부르는 대신 구조 손상과 전문 검색 인덱스 손상을 구분하여 알려 주며, 재구축만으로 충분하지 않을 때는 hermes sessions recover --inspect-only를 안내합니다. 이 명령은 오프라인에서 실행되고 데이터를 변경하지 않으며 profile이 고정됩니다. 또한 출력 데이터베이스를 생성하지 않고 정식 테이블을 읽을 수 있는지 보고합니다. 근본 원인을 해결하기 위한 작업에서는 저장소에 접근하던 모든 두 번째 쓰기 프로세스를 제거했습니다. profile gateway가 5초마다 호스팅된 방의 상태를 루트 state.db에 기록하고 있었지만, 이제 이러한 조정 정보는 전용 shared-state.db에 저장되므로 profile gateway가 마스터 세션 저장소를 쓰기 가능 모드로 열지 않습니다. dashboard는 먼저 읽기 전용으로 열립니다. cron의 수명 주기 보호 장치는 사용 중인 데이터베이스에 원시 open()을 호출하는 대신 추적되는 연결 레지스트리를 거칩니다. 원시 open()은 gateway의 POSIX 잠금을 취소하며, 이는 SQLite를 손상시키는 전형적인 방식입니다. 또한 doctor --fix는 안전성을 입증할 수 없는 checkpoint를 거부합니다. 쓰기 프로세스 외에도 여러 문제가 해결되었습니다. 이제 FTS 인덱스가 손상되면 전체 요청을 차단하는 대신 검색 기능만 저하되고 나중에 인덱스를 재구축합니다. 손상된 행 하나 때문에 sessions list, 내보내기 또는 인사이트가 모두 실패하지 않으며, 잘못된 행은 해당 세션을 명시하는 경고와 함께 ?로 표시됩니다. 세션은 다른 profile의 데이터베이스에 연결하거나 이를 읽지 않습니다. 읽기 전용으로 열 때 더 이상 쓰기 잠금을 획득하지 않으므로, 사용량이 많은 gateway 뒤에서 일회성으로 실행한 hermes의 지연 및 실패 시간이 4~20초에서 0.01초로 줄었습니다.⁴⁸
• 다중 profile 격리 강화. 이 가이드는 v0.19.0부터 profile 라우팅을 사용하면 각 profile에 “완전히 격리된 설정, skills, memory, secrets”가 제공된다는 프로젝트의 주장을 반복해서 소개했습니다. v0.21.2에서는 이 약속에 남아 있던 허점이 모두 해결되었습니다. 보조 profile의 봇이 기본 profile의 허용 목록을 물려받고, 어댑터가 기본 profile의 호스트로 자격 증명을 전송할 수 있었으며, stdio MCP 서버가 기본 profile의 vault secrets를 전달받았습니다. MEDIA: 전송은 다른 profile의 .env/auth.json/state.db를 첨부할 수 있었고, webhook과 Feishu 콜백은 라우팅된 profile에서 벗어날 수 있었으며, 보조 profile은 프로세스별 메모를 통해 다른 profile의 Nous bearer를 가져올 수 있었습니다(#107609-#107630). 하나의 다중화된 gateway에서 여러 profile을 실행한다면, 이번 릴리스부터 비로소 격리된다는 주장이 실제로 성립합니다.⁴⁸
• 비밀번호를 볼 수 없는 자격 증명 vault. 이제 에이전트는 비밀 정보를 직접 보지 않고도 1Password, Bitwarden 또는 로컬 Hermes vault를 사용하여 브라우저에서 로그인하고 결제하며 주소를 입력할 수 있습니다. 이중 인증 코드는 저장된 인증 키에서 가져오거나 사용자의 UI에서 입력을 요청합니다. TOTP에는 base32 seed 또는 otpauth://totp URI를 사용할 수 있으며, 카운터 기반 HOTP는 거부됩니다. 모든 백엔드는 에이전트에 로그인 메타데이터와 불투명한 네임스페이스 handle이라는 동일한 형식을 전달합니다. 로컬 handle은 vault_, 외부 handle은 op: 또는 bw:를 사용하며, 비밀번호는 입력 시점에만 확인됩니다. 외부 관리자는 해당 세션에서 사용자가 잠금을 해제할 때까지 잠긴 상태로 유지되며, 마스터 비밀번호는 “tool 인수로도, argv로도 전달되지 않고, 어디에도 저장되지 않습니다.” 이는 provider API 키를 일반 텍스트 .env에서 제거한 v0.19.0의 SecretSource 작업을 바탕으로 하며, 이제 vault가 에이전트의 브라우징 자격 증명에도 같은 보호를 적용합니다.⁴⁸
• 선별되고 SHA로 고정된 plugin 카탈로그. hermes plugins browse는 “선별된 plugin 카탈로그의 모든 항목”을 표시하고, hermes plugins search는 카탈로그를 검색하며, hermes plugins install은 Git URL 및 owner/repo와 함께 카탈로그 이름도 해석합니다. hermes plugins pack은 “선언적이고 공유 가능한 plugin 모음”을 제공하여 기능을 완성합니다. 하나의 hermes-pack.yaml에서 plugin 모음을 정확한 커밋 SHA로 고정하고, pack install은 이를 일반적인 고정 설치로 각각 확장하면서 기능 동의 절차를 plugin별로 유지합니다. pack export는 현재 설치 상태에 대한 pack을 생성하며, pack show는 실제 변경 없이 결과를 미리 보여 줍니다. Plugin 시스템의 명령 블록에 새로운 하위 명령이 포함되어 있습니다.⁴⁸
• Nous 무료 등급과 안내형 첫 실행. 새로 설치하면 단일 로그인 명령만으로 무료 추론 기능과 커넥터를 즉시 사용할 수 있고, 채팅 안에서도 /login을 사용할 수 있으며, Gmail, Linear, Notion을 비롯한 커넥터 tool은 tool_search로 검색할 수 있습니다. 데스크톱의 안내형 첫 실행은 HERMES_GUEST_ONBOARDING=1로 활성화되며, 문자 그대로 1을 지정한 경우에만 켜집니다. 데스크톱 자체 테스트에서는 'true', '0', 빈 값이 모두 이 기능을 활성화하지 않는지 확인합니다. 또한 실행 여부는 새로 생성되는 백엔드의 환경에 기록되므로 상속된 값이 의도치 않게 전달되지 않습니다. Nous Tool Gateway를 참조하세요.⁴⁸
• 데스크톱 백엔드의 무분별한 생성 문제가 해결되었습니다. 이전에는 Bot Mode가 실행 시점과 roster를 갱신할 때마다 각 profile에 대해 백엔드를 하나씩 생성하거나 연결을 시도했고, Bots roster의 항목 위에 마우스를 올리면 행마다 백엔드가 생성되었으며, profile을 전환하면 기본 백엔드가 중복으로 생성될 수 있었습니다. 이 기간에 이러한 문제가 모두 해결되었습니다.⁴⁸

업데이트 방법은 이전과 같습니다. 기존 설치에서는 hermes update를 실행하고, 새로 설치할 때는 shell 설치 프로그램을 사용하세요.⁴⁸

v0.21.1의 새로운 기능(The Rollup Patch)

Hermes Agent v0.21.1(태그 v2026.9.7, 2026년 9월 7일)은 의도적으로 간소합니다. “태그 기반 배포와 다운스트림 사용자를 위해 v0.21.0 이후 현재 main까지의 변경 사항을 모은 패치 릴리스”입니다. 본문에는 해당 기간의 통계로 “변경된 파일 4,364개에 걸친 비병합 커밋 5,139개(+601,014 / -768,419)”와 “병합된 PR 632개”가 제시되지만, 상세 설명은 “이 기간의 엄선된 전체 릴리스 노트는 v0.22.0과 함께 제공됩니다”라며 뒤로 미룹니다. 따라서 이는 프로젝트 역사상 태그 사이의 변경 규모가 가장 큰 단일 기간이면서도 가장 짧은 릴리스 노트로 배포된 버전입니다(이전의 인접 태그 기간 중 v2026.7.20..v2026.7.30의 비병합 커밋 2,790개를 넘은 사례는 없습니다). v0.22.0에서 정리된 기록을 제공하기 전까지는 아래 6가지 변화가 이 태그에서 Hermes를 운영하는 방식에 실질적인 영향을 줍니다. 각 내용은 소스에서 검증했습니다.⁴¹

• 코드베이스가 분리되었으며, 플러그인 호환성 유예 기간은 9월 14일에 종료되었습니다. 2026년 9월의 코드 분리 작업(PR #102117)은 저장소의 대형 모듈을 역할별 파일로 나눴습니다. 새로운 agent/ 패키지에는 대화 루프의 내부 구현이 포함됩니다(최상위 모듈 214개와 하위 패키지 7개이며, prompt_builder.py는 이제 agent/prompt_builder.py에 있고 run_agent.py는 계속 AIAgent가 정의된 파일입니다). CLI의 하위 명령 파서는 hermes_cli/subcommands/ 패키지(모듈 61개)로 이동했습니다. 정적 CANONICAL_PROVIDERS 목록은 hermes_cli/models.py에서 hermes_cli/models_catalog_static.py로 이동했습니다(목록 자체는 변경되지 않아 정적 항목 39개이며, 번들로 제공되는 provider-plugin 디렉터리 39개에서 계속 자동 확장됩니다). delegate_task는 약 12개의 tools/delegate_tool_* 모듈로 분리되었습니다. 내부 import 경로는 안정적인 API가 아니므로 저장소 루트에 새로운 COMPAT_MANIFEST.md가 추가되었습니다. 이 파일은 이동된 공개 이름 1,148개를 기존 모듈 경로에서 지연 방식으로 다시 내보내며, 이름이 확인될 때마다 프로세스별, 이름별로 한 번씩 HermesPluginCompatWarning을 표시합니다. 이 호환성 계층은 임시로 제공되었으며, 태그 출시 6일 뒤인 2026년 9월 14일에 예정대로 제거 정책이 발효되었습니다. 이는 코드를 되돌린 것이 아니라 이미 배포된 코드에 포함된 날짜 조건이 활성화된 것입니다. 해당 날짜부터 영향을 받는 타사 플러그인은 로드되지 않습니다. CLI 배너, hermes doctor, hermes update에는 비활성화된 플러그인의 이름과 함께 빨간색 알림이 표시되고, 데스크톱에는 일회성 모달이 나타나며, hermes plugins list에는 비활성화 사유가 표시됩니다. 외부 플러그인을 사용한다면 반드시 확인하세요. hermes plugins compat <path>는 기존 경로 -> 새 경로 형식으로 모든 file:line을 출력하며, 남은 항목이 하나라도 있으면 종료 코드 1을 반환합니다(--json을 사용하면 머신 판독 형식으로 출력되며, 인수 없이 실행하면 설치된 전체 플러그인을 검사합니다). 작성자가 아직 대응하지 않은 플러그인을 위한 임시 해결책은 config.yaml에서 plugins.allow_deprecated_imports: true를 설정하는 것이며, 이 방법은 여전히 작동합니다. 기존 import 경로를 실제로 삭제하는 변경 사항은 9월 22일 현재도 반영되지 않았습니다(태그 v2026.9.21과 main에서 확인). 따라서 로더의 진행을 허용하면 기존 경로도 계속 확인됩니다. 이후 상황에 대한 자세한 내용은 위의 v0.21.2의 새로운 기능을 참조하세요. Plugin 시스템 섹션에는 현재 상태를 설명하는 상자가 있습니다.⁴²
• Gateway 대화는 이제 어떤 경우에도 타이머에 따라 교체되지 않습니다. 세션 수명 주기 문서에는 이제 계약이 명확하게 명시되어 있습니다. “비활성 시간이나 실제 경과 시간으로 대화가 교체되는 일은 없습니다. /new와 /reset은 명시적인 경계를 생성하며, 긴 기록은 계속 context compression으로 관리합니다. 기존 타이머 설정은 무시됩니다. 기존 SessionResetPolicy 데이터 타입은 호환성을 위한 비활성 데이터일 뿐, 런타임 정책이 아닙니다.” 경계는 사용자가 명시적으로 생성합니다. hermes claw migrate를 통해 OpenClaw 시절의 세션 재설정 타이머를 가져왔다면 이제 해당 설정은 비활성 데이터로만 남습니다. Messaging Gateway를 참조하세요.⁴³
• MCP 인증에 기기 코드 방식이 추가되었습니다. hermes mcp login <name>에 --flow {browser,device}가 추가되었습니다. browser는 기존 PKCE 방식이며, device는 브라우저 콜백을 사용하기 어려운 머신을 위한 RFC 8628 기기 코드 로그인입니다. 이 플래그는 서버의 oauth.flow 설정을 재정의합니다. 이 기간에는 나머지 MCP 인증 영역도 강화되었습니다. OAuth 세션 전반에서 profile 소유권을 확인하고, 잘못된 OAuth 메타데이터 캐시는 서버를 멈추게 하는 대신 무시하며, 데스크톱은 클라이언트 로컬 콜백을 통해 MCP OAuth을 중계합니다. 이와 관련해 -t/--toolsets는 이제 실제로 시작할 설정된 MCP 서버도 필터링하므로, 일회성 hermes -z -t <toolsets> 실행에서는 필요 없는 서버의 콜드 스타트를 건너뜁니다. MCP 통합의 명령 블록에는 이제 login과 reauth [--all]도 포함됩니다. 두 명령 모두 이 기간 이전부터 존재했지만 이 가이드에는 문서화되지 않았습니다.⁴⁴
• Delegation이 백그라운드 작업의 실제 상태를 정확하게 전달합니다. 다음은 태그 시점의 delegate tool 소스에서 확인한 delegate_task의 안정성 개선 사항 6가지입니다. (1) 백그라운드 batch는 기본적으로 하나의 완료 결과로 반환됩니다. delegation.independent_completions를 활성화하면 호출이 여러 완료 단위로 나뉩니다. group 값이 같은 작업은 함께 묶여 결과를 보고하고, 그룹이 없는 작업은 각각 완료되는 즉시 개별적으로 보고합니다. 이 기본 동작은 의도된 것입니다. 소스에는 작업별로 완료 알림이 쏟아질 경우 “이에 대한 계획이 없는 오케스트레이터가 단편화되었다”고 설명되어 있습니다. (2) 자식이 process_manage(action="handoff")를 사용해 백그라운드 프로세스를 부모에게 넘기지 않으면 자식 종료 시 해당 프로세스도 종료됩니다. 넘기지 않고 남은 프로세스는 결과에 orphaned_processes로 표시되며, 한 번도 읽히지 않은 채 종료된 자식 프로세스는 출력의 마지막 부분과 함께 unread_completions로 표시됩니다. 소스의 docstring에 명시된 설계 원칙에 따르면 부모는 자식이 “watcher running”이라고 주장하는 것을 신뢰하는 대신 런타임에서 “반드시 그 사실을 전달받아야 합니다.” (3) delegation.fallback_providers가 실제 설정 항목으로 동작합니다. null은 provider가 고정되지 않은 자식에 부모 체인을 상속하고, []는 fallback을 비활성화합니다. provider, endpoint 또는 model로 고정된 자식은 이 설정에 별도로 지정하지 않는 한 fallback을 사용하지 않습니다. (4) 자식의 fallback 체인은 표준 정규화기를 거쳐 확인되므로 잘못된 항목은 spawn을 중단시키지 않고 제거됩니다. (5) 단위 작업 도중 충돌이 발생해도 완료된 자식의 결과가 더 이상 손실되지 않습니다. 여러 자식으로 구성된 단위에서 완료된 각 자식은 해당 단위의 자체 행에 영구적으로 기록되며, 복구된 결과에 부분 결과로 유지됩니다. (6) Subagent는 1시간 prompt-cache 티어를 상속하지 않습니다. 위임된 자식은 5분 티어로 낮아집니다. 1시간 티어는 짧은 시간에 병렬로 실행되는 여러 자식이 아니라 자리를 비우는 사용자를 고려해 책정되었기 때문입니다.⁴⁵
• Provider와 model. 카탈로그에는 OpenAI의 GPT-6 Astra 및 Astra Pro와 함께 -fast/-flex 속도 티어 변형(“가격 2배, priority 티어” / “가격 0.5배, flex 티어”)이 Nous Portal 및 OpenRouter 카탈로그에 추가되었습니다. ChatGPT/Codex OAuth 경로에서 Astra는 계정에 따라 제한됩니다. 실제 계정 범위의 검색을 통해서만 Astra를 제공할 수 있으며, 표시되는 272K 창을 실시간으로 검증된 약 900K까지 늘리는 선택형 -900k picker 변형이 추가되었습니다. 이 접미사는 실제 요청에 포함되지 않습니다. 이와 함께 anthropic/claude-fable-5.1, google/gemini-3.7-flash와 gemini-3.8-flash, qwen/qwen3.8-max-0902와 qwen3.8-flash, Meta의 Muse Spark 1.3 제품군(1M context, contributor 변형 포함), Meta의 muse-image 이미지 생성 provider plugin이 추가되었습니다. Tavily는 웹 검색 및 추출 backend로 추가되었습니다(TAVILY_API_KEY). hermes tools를 통해 Tavily를 선택하면 키 없이도 작동합니다. 관리형 llama.cpp 런타임을 통해 로컬 model이 핵심 실행 경로로 승격되었습니다. 공식 바이너리, 관리되는 단일 llama-server, 데스크톱의 원클릭 설정을 제공합니다. 별도 트리에서 외부 프로세스로 동작하는 provider에는 전용 확인 분기가 추가되었습니다. 운영 측면에서 picker의 원격 카탈로그는 이제 20분마다 갱신됩니다(model_catalog.ttl_minutes, 기본값 20). 기존 ttl_hours 키는 사용자가 명시적으로 설정한 경우에만 적용됩니다.⁴⁶
• 데스크톱: 페이지에 주석을 달고 세션을 제어합니다. 앱 내 브라우저에 댓글 모드가 추가되었습니다. Annotate를 클릭한 다음 실제 페이지의 요소를 클릭하거나 상자를 드래그하고 메모를 입력하세요. 저장된 댓글은 번호가 매겨진 핀으로 유지되며 그 자체로는 turn을 전송하지 않습니다. 작업을 마친 뒤 “Add N comments”를 누르면 핀마다 잘라낸 스크린샷과 함께 댓글 batch가 composer로 전달됩니다. 각 요소 댓글에는 CSS selector, markup, 레이아웃과 관련된 computed style이 포함되므로 agent는 사진을 보고 추측하는 대신 소스에서 해당 요소를 찾을 수 있습니다. markup이 페이지를 떠나기 전에 비밀번호, 숨겨진 값, 키 형태의 속성은 삭제됩니다. 규모가 큰 batch는 페이지 영역별로 그룹화됩니다. 따라서 20여 개의 댓글이 대개 서로 다른 파일을 수정하는 몇 개의 작업 단위로 정리되며, 덕분에 병렬 worker에게 안전하게 분배할 수 있습니다. 그 밖에도 구조화된 세션 제어 기능과 세션 자동화 제어 기능, 드래그 방식의 세션 생성, 다른 코딩 agent의 transcript를 위한 세션 가져오기 화면, display.resume_last_session이 추가되었습니다. display.resume_last_session의 기본값은 true이며, 콜드 스타트 시 마지막 chat이나 페이지를 다시 엽니다. browser.use_real_profile이 꺼진 상태에서 Browser 창을 처음 열면 이 기능을 사용하도록 제안하는 동의 안내가 표시됩니다. Capabilities -> Skills에는 클릭 한 번으로 설치할 수 있는 선택형 skill 카탈로그가 내장되었으며, 러시아어 데스크톱 UI locale도 새로 추가되었습니다(CLI의 locale 카탈로그 17개에는 변경이 없습니다).⁴⁷

업데이트 방법은 바뀌지 않았습니다. 기존 설치에서는 hermes update를 실행하고, 새로 설치할 때는 셸 설치 프로그램을 사용하세요. 이 기간의 정리된 기록은 v0.22.0에서 제공될 예정이며, 위의 항목은 이 태그에서 실제로 달라지는 내용입니다.⁴¹

v0.21.0의 새로운 기능(The Pantheon Release)

Hermes Agent v0.21.0(태그 v2026.8.31, 2026년 8월 31일)은 현재 기능 릴리스이자 v0.20.x의 모든 롤업 버전이 미뤄 두었던 내용을 엄선해 정리한 기록입니다. “이 릴리스에는 v0.20.1-v0.20.6 인프라 패치 태그의 모든 변경 사항이 통합되어 있으며, 해당 버전의 내용은 여기에 빠짐없이 기록되어 있습니다.” Herald의 후속편이라는 구도입니다. “v0.20.0에서 Hermes는 전령이 되어 직접 말하고 다른 에이전트에게 소식을 전했습니다. v0.21.0에서는 신들이 모입니다.” 통계 문구를 그대로 옮기면 다음과 같습니다. “v0.20.0 이후: 약 5,800개 커밋 · 약 2,475개 PR 병합 · 약 5,680개 파일 변경 · 약 869,000줄 추가 · 약 135,000줄 삭제 · 약 2,100개 이슈 종료 · 760명 이상의 기여자”.³⁵

릴리스는 기능 영역별로 구성되어 있으며, 이 요약도 같은 방식을 따릅니다. 기능이 이 가이드의 기존 섹션을 변경하는 경우 해당 링크를 인라인으로 표시합니다.

• Bot Mode: 에이전트들이 기본 기능만으로 하나의 사회를 이룹니다. Bot Mode는 v0.20.3 버전에 포함된 hermes-bots 플러그인에서 데스크톱 앱의 기본 활성화 기능으로 승격되었습니다. 모든 에이전트 profile에는 이름, 무작위 변경 및 잠금 제어 기능이 있는 결정론적 아바타 얼굴, 공유 명단의 자리가 제공됩니다. 여러 봇과 사용자가 한 방에서 대화하는 Discord 스타일의 그룹 채팅을 만들고, 메시지 작성창에서 원하는 봇을 @-멘션하며, 방에 이름과 사진을 지정할 수 있습니다. 세부 기능에는 발신 에이전트가 표시되는 에이전트 간 메시지 카드, 발신자 측 전송 알림, 즉각적인 활성화를 위한 화면 우선 복원, Routines 창, 앱 디자인 시스템을 기반으로 한 재구축이 포함됩니다. 릴리스의 표현을 그대로 옮기면 다음과 같습니다. “이전에는 ‘멀티 에이전트’가 배관 작업을 의미했지만, 이제는 동료들로 가득한 채팅 앱처럼 보입니다.”³⁵
• hermes peer: 에이전트 간 봇 대 봇 DM. 모든 Hermes 에이전트는 profile과 gateway를 넘어 핸들을 통해 다른 에이전트에게 메시지를 보낼 수 있습니다. CLI에서 직접 보내거나 대화 도중에 보낼 수도 있습니다. 조사 봇에게 결과를 코딩 봇으로 전달하도록 요청한 뒤 현재 위치에서 답변을 확인할 수 있습니다. “답변은 각 에이전트의 공식 Bot Chat에 도착하므로 에이전트 간 대화가 일회성으로 사라지지 않고 영구적으로 보존되어 검토할 수 있습니다.” peer 추가, 목록 조회, 제거 및 dm을 지원하는 hermes peer 명령은 최상위 명령 표에 있습니다.³⁵
• 기억하는 Cron 작업. 예약 작업이 더 이상 실행할 때마다 이전 내용을 잊지 않습니다. cron 에이전트는 다른 모든 에이전트처럼 영구 메모리를 불러오고 업데이트하며, continuity=true를 사용하면 각 실행 결과가 다음 실행으로 이어져 모니터가 이미 보고한 내용과 대조해 중복을 제거할 수 있습니다. 모든 작업에는 영구적인 메모장용 scratchpad가 제공되고, monitor-mode 작업은 변경 사항이 없으면 LLM을 완전히 건너뜁니다. 작업별로 추론 강도를 고정할 수 있으며, cron 출력은 봇이 실제로 응답하는 공식 Bot Chat으로 전달할 수 있습니다. 이제 예약 작업(Cron) 섹션에서 각 기능이 해당 태그에서 작동하는 방식을 설명합니다.³⁵³⁷
• 실시간 subagent 오케스트레이션. delegate_task에 제어 작업이 추가되었습니다. 실행 중인 하위 에이전트 목록을 확인하고, 작업 도중 방향 수정 지시를 보내거나, 조기에 중단하면서 부분 결과를 보존할 수 있습니다. 하위 에이전트 출력은 JSON 스키마에 따라 검증할 수 있고, 각 위임의 비용이 결과에 표시됩니다. 기본값은 subagent당 250회 반복과 동시 하위 에이전트 10개로 상향되었습니다. 이는 v0.19.0에서 max_async_children을 대체한 통합 제한입니다.³⁵³⁸
• MCP 명령 센터. MCP 서버와 카탈로그가 하나의 데스크톱 페이지로 통합됩니다. 파일을 끌어 놓는 “무엇이든 붙여넣기” 가져오기, 도구 호출이 실패하기 전에 재인증을 안내하는 백그라운드 상태 검사, 전체 서버의 비용 및 사용량 오버레이(스키마 토큰 추정치, 서버별 30일 사용량), 명시적인 확인을 거쳐 MCP 서버를 설치하는 hermes:// 딥 링크가 제공됩니다. MCP 통합을 참조하세요.³⁵
• CLI 기능의 대대적인 강화. Ctrl+P를 누르면 퍼지 검색 방식의 명령 팔레트가 열리며 /palette로도 접근할 수 있습니다. /model 선택기는 입력과 동시에 항목을 필터링하고, /status는 추론 모드, 대기 중인 승인, context 사용량을 표시합니다. 상태 표시줄에는 각 필드의 표시 여부를 전환할 수 있는 실시간 캐시 적중률, 지연 시간, 초당 토큰 수를 표시할 수 있습니다. 전역 긴급 중지, 세션 고정 및 고정 해제, 순환하는 메시지 작성창 자리표시자, 터미널 반려동물도 추가되었습니다. 명칭과 관련해 한 가지 주의할 점이 있습니다. 릴리스에서는 승인 dry-run 검사기를 hermes approval-check로 소개하지만, 해당 태그에서 실제 명령은 hermes approvals test이며 approval-check 하위 명령은 존재하지 않습니다.³⁵⁴⁰
• 에이전트가 데스크톱 브라우저를 직접 조작합니다. 앱 내 브라우저는 더 이상 에이전트가 보기만 할 수 있는 창이 아닙니다. Hermes가 직접 이동하고 클릭하며 내용을 읽을 수 있고, 전체 링크 컨텍스트 메뉴를 사용해 페이지를 시스템 브라우저에서 별도 창으로 열 수 있습니다.³⁵
• 6개의 새로운 제공업체와 대규모 모델 카탈로그 업데이트. Meta Model API(Muse Spark), CommandCode, Tencent TokenPlan, Nebius Token Factory, Ramp Router, Actual Computer가 추가되었습니다. 이 가운데 3개(Meta AI, CommandCode, Actual Computer)는 이전 롤업 버전에 포함되어 이미 전체 제공업체 목록에 등록되어 있었습니다. 이제 목록에 Tencent TokenPlan, Nebius Token Factory, Ramp Router와 문서에 새로 추가된 Alibaba Token Plan SKU가 포함됩니다. 카탈로그에는 GLM-5.3-Flash, qwen3.8-max/flash, Gemini 3.7 Flash, MiniMax M3 free, Nemotron 3.5 Lightning, Muse Spark 1.2도 추가되었습니다. 구조적인 변경 사항도 2가지 포함됩니다. config.yaml의 model_overrides를 사용하면 릴리스를 기다리지 않고 모든 모델의 context window 또는 가격을 수정할 수 있습니다. 또한 제공업체를 진입점을 통해 검색되는 pip 설치 패키지로 배포할 수 있습니다. 통합 선택 보호 레지스트리는 사용자 데이터로 학습하는 모델을 선택할 때 모든 선택기 화면에서 경고합니다.³⁵³⁶
• 전반적인 보안 강화. 프롬프트 인젝션에 노출된 에이전트가 자신의 상시 지침을 몰래 다시 작성하지 못하도록 보호된 에이전트 지침 파일(AGENTS.md, skills, 메모리 저장소)에 쓰려면 이제 항상 승인이 필요합니다. 광범위한 민감 정보 삭제 개선을 통해 터미널 오류, .env 읽기, checkpoint, ACP 로그 전반의 비밀 정보 유출 허점을 막았습니다. 승인 시스템은 Windows의 파괴적인 명령도 인식합니다. macOS 권한 승인은 안정적인 TCC 서명 ID(hermes desktop --setup-tcc-identity)를 통해 업데이트 후에도 유지됩니다. Blender MCP 카탈로그 항목과 skill은 상위 프로젝트의 침해 사고로 인해 제거되었습니다. 해당 태그의 자세한 내용은 보안 강화를 참조하세요.³⁵³⁹
• Gateway의 성숙. Slack에는 네이티브 실시간 카드가 추가되어 실제 스트리밍 응답과 선택적으로 활성화하는 계획 및 작업 카드를 지원하며, 발신 링크 미리보기를 숨길 수 있습니다. Telegram에는 @botname을 통해 모든 명령과 skill을 검색할 수 있는 인라인 선택기가 추가되어 Telegram의 명령 메뉴 제한을 우회합니다. 릴레이 경로도 개선되어 네이티브 플러그인 초기화, 초안 스트리밍을 이용한 실시간 카드 작업, 세션 구간 분할, 복원된 음성 메모 STT를 지원합니다. gateway 제어 소켓을 통해 fleet 소비자가 gateway를 조회할 수 있고, 업데이트 도구는 프로세스 트리를 강제로 종료하는 대신 gateway를 정상적으로 일시 중지할 수 있습니다. watchdog이 작동하면 turn-reaper가 멈춘 작업자의 스택을 캡처합니다.³⁵
• 대규모 skills 업데이트. 복원된 8개의 생산성 skill(document-to-action-items, meeting-action-items, email-inbox-triage, github-issue-to-pr, weekly-review-planning, competitor-news-monitor, product-price-monitor, social-media-content-calendar), HAR에서 파생된 API 클라이언트(“웹사이트를 한 번 살펴본 다음 브라우저 없이 숨겨진 API을 직접 호출합니다”), publish-site, session-librarian, blocked-page-recovery, merge-reconciler, plan-interrogation, 생성 시 안내를 제공하는 SKILL.md 린터가 추가되었습니다.³⁵

이 버전에서 되돌려져 배포되지 않는 기능: Model Council 모드(/council)와 DCP context engine은 모두 추가되었다가 되돌려졌습니다. WS 전용 gateway 서버(#94245)도 병합 후 되돌려졌으므로(#96118) FastAPI은 여전히 데스크톱 부팅 경로에 남아 있습니다. 다만 순서 번호가 부여된 이벤트 재생(#94219)과 WebSocket을 통한 무손실 데스크톱 재연결은 실제로 배포되었습니다. Electron은 40.10.2로 롤백되었습니다. v0.20.x 버전에 대한 커뮤니티 자료에서 이러한 기능을 언급했더라도 이 릴리스에는 포함되지 않습니다.³⁵

업데이트 방법은 바뀌지 않았습니다. 기존 설치에서는 hermes update를 사용하고, 새로 설치할 때는 셸 설치 프로그램을 사용하세요. 아래 Herald 릴리스에 있는 롤업 하위 섹션은 각 태그에 어떤 변경 사항이 포함되었는지를 기록한 버전별 내역으로 유지됩니다.³⁵

v0.20.0의 새로운 기능(The Herald 릴리스)

Hermes Agent v0.20.0(태그 v2026.8.3, 2026년 8월 3일)은 v0.21.0에서 전체 변경 사항을 통합하기 전의 기능 릴리스였습니다. v0.20.1(8월 13일)과 v0.20.2(8월 16일)는 이를 기반으로 한 안정화 태그이며, v0.20.3(태그 v2026.8.16.2, 8월 17일 공개), v0.20.4(태그 v2026.8.18, 8월 18일), v0.20.5(태그 v2026.8.19, 8월 21일 공개), v0.20.6(태그 v2026.8.27, 8월 27일)도 각각 새로운 기능을 포함한 채 통합 릴리스를 이어갑니다. 아래 하위 섹션을 참조하세요. v0.19.0 이후 이 기간에는 650명 이상의 기여자가 참여했으며, 약 3,650개의 커밋과 1,400개의 병합된 PR이 포함되고 1,200개의 이슈가 해결되었습니다.⁵⁵

다음 3가지 변경 사항으로 인해 이 가이드의 이전 버전에서 안내한 방법은 더 이상 유효하지 않습니다. 다른 내용보다 먼저 확인하세요.

• 이제 Node 26이 필요합니다. 설치 프로그램은 NODE_VERSION="26"으로 고정하며, 이전 런타임을 감지하면 “Node.js … is too old (Hermes requires Node >=26).”이라는 메시지와 함께 설치를 거부합니다. 설치 프로그램, heal, upgrade 모두 이 요구 사항을 적용합니다. 문서 사이트의 설치 페이지에는 여전히 Node v22로 안내되어 있지만, 설치 프로그램 스크립트와 릴리스 노트가 더 최신인 공식 출처입니다.⁵⁵
• pip와 Homebrew는 단순히 지원 중단 예정인 것이 아니라 완전히 폐기되었습니다. 원문에는 “brew + pip/PyPI wheel channels retired (shell installer / Docker / Nix are the supported channels).”라고 명시되어 있습니다. 아직 pip 또는 brew로 설치한 버전을 사용하고 있다면 더 이상 해당 경로로 릴리스가 제공되지 않습니다.⁵⁵
• 기본 도구 호출 반복 제한이 90회에서 500회로 늘어났습니다. 이제 장시간 자율 실행이 인위적인 제한에 막히지 않으며, 아래의 모든 예산 압박 임곗값도 새로운 상한을 기준으로 계산됩니다. read_file의 기본값 역시 500줄에서 2,000줄로 늘어났습니다.⁵⁵

나머지 릴리스 내용은 다음과 같습니다.

• 대화형 음성. 끼어들기를 지원하는 스트리밍 TTS와 기기 내 깨우기 단어 기능이 추가되었습니다.⁵⁵
• A2A v1.0. 에이전트 간 프로토콜 plugin이 추가되어 오랫동안 요청되어 온 이슈 #514가 해결되었습니다.⁵⁵
• 서명된 아웃바운드 웹훅. 이전의 hermes webhook은 인바운드만 지원했지만, v0.20.0부터 세션, 턴, 도구 이벤트의 수명 주기에 사용할 수 있는 HMAC 서명 아웃바운드 웹훅을 지원합니다.⁵⁵
• 근거 기반 인용. 팩트 체크 모드를 갖춘 새로운 skill이 추가되었습니다.⁵⁵
• 고급 사용자용 CLI 기능 확충. !command는 모델 턴을 소비하지 않고 셸 명령을 즉시 실행합니다. /init은 프로젝트를 검사하여 AGENTS.md를 작성하거나 업데이트합니다. /diff는 어떤 화면에서든 스테이징된 변경 사항, 전체 변경 사항 또는 세션 변경 사항을 표시합니다. /context는 context 창을 무엇이 채우고 있는지 분석합니다. /focus는 숨겨진 줄을 복원할 수 있는 간결한 출력 보기를 제공합니다. Ctrl+S를 누르면 작성 중인 프롬프트를 임시 보관합니다. hermes import-agent는 Claude Code 또는 Codex CLI 설정을 명령 하나로 이전합니다.⁵⁵
• 비밀 정보 관련 기능 추가. 모든 볼트와 조합할 수 있는 명령 도우미 비밀 정보 소스, 실행 가능한 시작 오류 안내를 제공하는 단일 명령 토큰 교체, Bitwarden용 선택적 암호화 비상 캐시, profile 홈별로 범위가 제한된 볼트 주입 키, config.yaml과 MCP config 간 ${env:VAR} SecretRef 동등 지원이 추가되었습니다. 아래에서 설명하는 3가지 인증 경로 모델은 변경되지 않았습니다.⁵⁵
• 빨라진 웜 스타트. hermes -w 콜드 스타트 시간이 약 14초에서 1.8초로 단축되었습니다.⁵⁵
• 데스크톱이 하나의 플랫폼으로 발전했습니다. 버전이 지정된 카드와 샌드박스 기반 실시간 미리 보기를 제공하는 아티팩트, Kanban을 최초 데스크톱 plugin으로 제공하는 Plugin SDK, 빠른 입력을 위한 전역 단축키, 여러 GUI 창, SSH 원격 백엔드 모드, RFC 8252 네이티브 로그인이 추가되었습니다.⁵⁵

v0.20.3, v0.20.4, v0.20.5, v0.20.6 통합 릴리스(8월 17~27일)

v0.20.0 이후 프로젝트는 태그가 지정된 통합 릴리스를 빠르게 내놓았으며, 이 릴리스들은 단순한 안정화 버전 이상이었습니다. 4개 릴리스 모두 “full curated release notes for this window will ship with v0.21.0”이라고 밝히며 엄선된 릴리스 노트 공개를 같은 방식으로 미뤘고, 이제 v0.21.0에서 해당 노트가 제공되었습니다. 위의 v0.21.0의 새로운 기능은 이 전체 기간을 정리한 기록이며, 해당 릴리스에서도 이 기간의 변경 사항이 “are fully documented here”라고 확인합니다. 아래 블록은 각 태그가 공개되었을 당시의 기록으로 남겨 두었습니다. 엄선된 릴리스 노트에서는 하나로 묶인 변경 사항 중 어떤 내용이 어느 태그에 포함되었는지 확인할 수 있습니다.^54233035

v0.20.3(v0.20.2 이후 커밋 약 250개, PR 약 125개):

• 2026-07-28 무상태 프로토콜을 지원하는 MCP 2.x SDK 마이그레이션. Hermes는 최신 MCP SDK 세대로 이전했으며 무상태 개정 프로토콜을 지원합니다.⁵⁴
• Bot Mode가 핵심 팀원 프로토콜을 포함하는 번들 plugin(hermes-bots)으로 제공됩니다.⁵⁴
• CommandCode provider plugin이 provider 카탈로그에 추가되었습니다.⁵⁴
• 컴퓨터 사용을 위한 Cua Driver 0.20 런타임 계약과 하위 프로세스 Python 런타임 소유권 강화(PYTHONHOME/PYTHONPATH 격리)가 추가되었습니다.⁵⁴
• 안정성 개선 사항으로는 cron 스케줄러 자가 복구(EMFILE 복구, 오래된 클레임 조정, 멈춘 작업 재활성화), 세션 인계 시 데이터 손실 수정, 데스크톱 원격 gateway 연결 자가 복구와 함께 다양한 생태계 기능 이식(plugin 설치 보안 검사, /worktree, /rollback에서 직접 편집 내용 보존, UTF-16 파일 읽기)이 포함됩니다.⁵⁴

v0.20.4(v0.20.3 이후 커밋 약 146개, PR 약 74개):

• 데스크톱의 유리 표면: 프로스트 선택기와 macOS 사전 선택 기능을 포함한 무광 유리 및 반투명 효과가 추가되었습니다.⁵⁴
• 탭 방식의 SESSIONS|BOTS 사이드바에서 봇별 숨기기와 표시를 지원하며, Bot Mode 그룹 채팅 문제도 수정되었습니다. 장시간 실행되는 구성원 턴, Markdown 렌더링, 기기 간 라우팅이 개선되었습니다.⁵⁴
• skill 설치 시 NVIDIA SkillEvaluator Tier 1 권고 검사를 수행합니다. skill을 설치하면 라이선스와 보안 검사가 실행됩니다.⁵⁴
• cron 미디어 전송 강화(설정 가능한 제한 시간, 수동 실행 첨부 파일, 누락된 실행 표시), SessionDB 이벤트 루프 스레드 및 경합 수정, hermes update의 보류된 브랜치 상태를 정확히 알리는 기능, Kanban의 네이티브 운영체제 알림이 추가되었습니다.⁵⁴

v0.20.5(v0.20.4 이후 커밋 약 746개, PR 약 323개):

• 키가 필요 없는 웹 계층: 새로 설치한 환경에서도 API 키 없이 웹 검색을 사용할 수 있습니다. 5개 공급업체의 무료 서비스를 순환하며 장애 시 링 방식으로 전환합니다.²³
• CLI 완성도 향상: 퍼지 검색 방식의 /model 선택기, Ctrl+P 명령 팔레트, 더 풍부해진 /status가 추가되었습니다.²³
• 한층 성숙해진 Bot Mode: 그룹 룸 스레드, 접을 수 있는 대화 요약, 블롭 얼굴 아바타, 드래그 앤드 드롭을 지원하는 PDF 및 파일 첨부 기능이 추가되었습니다.²³
• 플릿 및 worktree 도구: hermes update 실행 내역, hermes update --plan(릴리스 노트에서는 이를 “fleet --plan verification”이라고 부르지만, 이 플래그는 fleet 명령이 아니라 hermes update에 있으며 파서 도움말에 따르면 “Show the update plan and exit without changing anything”을 수행합니다), hermes worktree list/prune이 추가되었습니다.²³²⁷
• cron 작업에 영구 메모리와 작업별 추론 수준이 추가되었으며, Composio 평가 결과를 바탕으로 한 실행 규율 및 런타임 중단 방지 장치, 여러 질문을 지원하는 명확화 기능, opencode 없이 사용할 수 있는 무인증 provider, 데스크톱 성능 개선(화면을 먼저 그리는 Bot Mode 하이드레이션, 두 렌더러 모두에 React Compiler 적용)도 포함되었습니다.²³

v0.20.6(태그 v2026.8.27, 8월 27일 – v0.20.5 이후 커밋 약 1,313개, PR 약 525개):

이 릴리스는 스스로를 “Patch release. This tag rolls up the ~525 PRs merged since v0.20.5 into a stable tagged release for downstream consumers”라고 명시적으로 설명합니다. 자체 설명에 따르면 이 기간에는 약 1,557개 파일에 걸쳐 약 1,313개의 커밋(+177,113 / −21,682)과 약 525개의 병합된 PR이 포함됩니다.³⁰ 해당 설명에서 강조한 주요 항목은 다음과 같습니다.

• 동의 기반 실제 profile 브라우징 – 로컬 브라우징에서 기본 Chromium profile을 사용할 수 있으며, Windows에서는 승인을 받아 브라우저를 종료하는 절차를 제공합니다.³⁰
• 데스크톱 Browser가 별도의 운영체제 창으로 실행되며, 관리형 SSH 원격 업데이트 엔진과 플릿 profile 레일도 추가되었습니다.³⁰
• 원격 MCP 카탈로그 확장: Cloudflare, Grafana Cloud, Better Stack, Railway을 비롯하여 실제 작동이 검증된 공급업체 호스팅 서버 50개 이상이 추가되었습니다.³⁰
• 저장된 비밀 정보를 위한 선택적 운영체제 키체인 암호화 – 이제 실행할 때마다 macOS Keychain 확인 창이 표시되지 않습니다.³⁰
• 선택기에 새로운 모델 추가: GLM-5.3-Flash, 무료 MiniMax M3, MiniMax H3 Max 비디오가 추가되었습니다.³⁰
• web_search/web_extract용 TTL 결과 캐싱과 어간 추출을 지원하는 다중 쿼리 tool_search가 추가되었습니다.³⁰
• 이제 린 테일 압축이 기본값입니다 – 아래 Context 압축 섹션에서 해당 태그 시점의 config를 설명합니다.³⁰³¹
• 터미널 백엔드를 교체할 수 있게 되었습니다 – 터미널 백엔드를 참조하세요.³⁰³²
• 업데이트 프로그램과 플릿의 정확한 상태 보고: 업데이트 프로그램은 프로세스 트리를 강제로 종료하는 대신 제어 소켓을 통해 gateway를 일시 중지하며, 이미지 또는 패키지로 관리되는 설치 환경에서는 안전하지 않은 제자리 업데이트를 거부합니다.³⁰
• cron 영구 인시던트 확인 기능과 더 명확한 코드 버전 불일치 오류, Slack 링크 미리 보기 제어, 공유 Docker 컨테이너 ID가 추가되었습니다.³⁰

업데이트 방법은 변경되지 않았습니다. 기존 설치에서는 hermes update를 사용하고, 새로 설치할 때는 셸 설치 프로그램을 사용하세요.⁵⁴²³³⁰

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

Hermes Agent v0.19.0(태그 v2026.7.20, 2026년 7월 20일)은 전령의 신이 지닌 속도에서 이름을 따왔습니다. 이번 릴리스의 중심은 즉각적인 응답성으로, 모든 플랫폼에서 첫 요청의 첫 토큰 출력 시간이 약 80% 단축되었습니다. 여기에 터미널 결제, 비밀번호 관리자의 비밀 정보 연동, 기본으로 활성화되는 스마트 승인, 관찰 가능한 하위 에이전트, 충돌에도 안전한 응답 전달 기능이 더해졌습니다. 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분의 1로 줄였으며, 검토 창의 diff를 가상화하고, 대용량 대화 기록에서도 세션을 빠르게 전환할 수 있게 했습니다. 또한 토큰이 들어올 때마다 사이드바와 도구 행이 다시 렌더링되던 문제를 없앴습니다. 이제 TUI도 스트리밍되는 Markdown을 블록별로 증분 렌더링합니다.⁵⁶
• pip 및 Homebrew 설치는 더 이상 권장되지 않습니다. 두 설치 방식 모두 “지원되지 않는 레거시”로 표시되었으며 제거될 예정이었습니다. 이 제거 작업은 이후 v0.20.0에서 완료되었습니다. brew와 pip/PyPI wheel 채널은 종료되었으며, 이제 shell 설치 프로그램, Docker, Nix만 지원됩니다.⁵⁶⁵⁵
• 비밀 정보를 비밀번호 관리자에서 가져올 수 있습니다. 새롭게 추가된 플러그형 SecretSource 인터페이스는 로드 시 Bitwarden과 1Password의 비밀 정보(op:// 참조)를 가져옵니다. 여러 vault를 동시에 사용할 수 있고, 우선순위는 일관되게 결정되며, 충돌 경고와 변수별 출처도 제공됩니다. 이제 API 키를 평문 .env에 저장하지 않아도 됩니다. 향후 다른 vault 제공자도 플러그인으로 추가할 수 있습니다.⁵⁶
• 이제 스마트 승인이 기본값입니다. Hermes가 플래그된 명령을 실행하려 할 때마다 사용자에게 묻는 대신, 독립된 LLM 검토자가 명령을 평가합니다. 각 판정은 평가 대상이 된 해당 명령 하나에만 적용됩니다. 사용자가 정의한 거부 규칙은 YOLO 모드에서도 일치하는 명령을 차단하고, /deny <reason>은 거부 사유를 전달하여 에이전트가 진행 방향을 수정하도록 합니다. 규칙 키와 함께 다시 도입된 플러그인의 pre_tool_call 승인 동작은 도구 호출을 사람의 승인이 필요한 단계로 격상합니다.⁵⁶
• 터미널 결제: /subscription과 /topup. 터미널을 벗어나지 않고 Nous Portal 요금제를 관리할 수 있습니다. 현재 요금제와 남은 사용량을 확인하고, 업그레이드 비용이나 다운그레이드 적용 시점을 정확히 미리 본 뒤 실행할 수 있으며, 실행 취소도 지원합니다. 데스크톱 앱에도 이에 대응하는 결제 설정 탭이 추가되었습니다.⁵⁶
• 하위 에이전트의 작업을 지켜보고, 완료된 답변을 절대 잃지 마세요. delegate_task 디스패치는 하위 에이전트가 실행되는 즉시 tail -f로 확인할 수 있는 실시간 대화 기록 파일을 반환합니다. 자식 에이전트마다 사람이 읽을 수 있는 로그 파일 하나에 모든 도구 호출과 결과, 스트리밍 응답이 기록됩니다. 백그라운드 위임의 완료 결과는 재시작 후에도 유지됩니다. 최종 gateway 응답은 state.db의 전달 의무 원장에 기록되며, 전송 도중 gateway가 종료되면 다음 시작 시 다시 전달됩니다. max_async_children 설정 옵션은 통합 위임 동시 실행 제한으로 대체되어 더 이상 권장되지 않습니다.⁵⁶
• 하나의 gateway에서 여러 profile을 사용합니다. 하나의 봇 토큰을 공유하는 단일 다중화 gateway가 특정 길드, 채널 또는 스레드를 서로 다른 profile로 라우팅할 수 있습니다. 각 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는 한 차례의 요청에만 적용되는 모델 재정의를 제공하고, slash-skill 호출을 연이어 사용할 수 있으며(/skill-a /skill-b do XYZ), --safe-mode는 문제 해결을 돕습니다. hermes config get과 unset은 설정 관리 기능을 완성하고, hermes serve는 완전한 headless backend가 되며, MCP 도구는 mcp__server__tool 명명 규칙을 따릅니다.⁵⁶

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

v0.18.0의 새로운 기능 (The Judgment Release)

Hermes Agent v0.18.0(태그 v2026.7.1, 2026년 7월 1일)은 판단을 주제로 삼았습니다. 에이전트가 성공했다고 주장하는 데 그치지 않고 스스로 작업을 검증하며, 사용자가 직접 살펴볼 수 있는 앙상블 추론을 제공합니다. 또한 전체 P0/P1 미처리 목록을 해결하여 12일 동안 우선순위가 가장 높은 항목 약 692개를 처리했습니다.²²

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

v0.17.x에서 업그레이드한다면 CLI에서 기존 기능을 깨뜨리는 변경 사항은 없습니다. 업그레이드해야 할 핵심 이유는 완료 계약을 통해 목표가 스스로 검증된다는 점, 살펴볼 수 있는 앙상블을 갖춘 정식 MoA 지원, 그리고 skill을 기록하는 /learn입니다.

v0.17.0의 새로운 기능(The Reach Release)

Hermes Agent v0.17.0(태그 v2026.6.19, 2026년 6월 19일)은 이제 새로운 메시징 채널과 모델 제공업체는 물론, 데스크톱과 대시보드까지 더 깊이 제어할 수 있게 된 확장성을 반영해 이름을 붙였습니다. v0.16.x에 기능을 추가한 릴리스이며, CLI 인터페이스는 변경되지 않았습니다.²¹

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

v0.16.x에서 업그레이드하는 경우에도 CLI는 기존과 동일하게 작동합니다. 동일한 에이전트에 새로운 채널, 모델, 인터페이스를 추가한 릴리스입니다. 릴레이가 필요 없는 iMessage, 공식 WhatsApp 어댑터, 관리자를 위한 Managed 범위가 업그레이드해야 할 핵심 이유입니다.

v0.16.0의 새로운 기능(The Surface Release)

Hermes Agent v0.16.0(태그 v2026.6.5, 2026년 6월 5일)은 CLI 중심 에이전트를 사용할 수 있는 새로운 인터페이스를 제공한다는 의미로 이름을 붙였습니다. 가장 큰 변화는 Hermes를 더 이상 터미널에서만 사용하지 않아도 된다는 점입니다.²⁰

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

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

v0.14.0의 새로운 기능(The Foundation Release)

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이 gateway에 추가되었고, Microsoft Teams가 전체 흐름에 연결되었습니다. 문서의 플랫폼 비교표에는 태그 v2026.8.31 기준으로 28개 플랫폼이 나열되어 있으며, Messaging Gateway 섹션에서 이 수에 포함되는 범위를 설명합니다. Discord 기록 역채우기는 기본적으로 활성화되며, Telegram과 Discord의 clarify 프롬프트는 이제 네이티브 버튼을 사용합니다.
• 작성 시점 검증이 개선되었습니다. Hermes는 편집 후 다음 턴을 시작하기 전에 턴별 파일 변경 요약과 언어 서버의 의미 진단 결과를 표시할 수 있습니다. 이에 따라 증거 중심의 에이전트 작업 방식에 한층 더 가까워졌습니다.
• 데스크톱 및 미디어 도구의 지원 범위가 넓어졌습니다. computer_use는 Anthropic 이외의 제공업체에서도 cua-driver를 통해 작동하며, video_generate는 플러그형 백엔드로 통합되었습니다. vision_analyze는 실제 시각 기능이 있는 모델에 원본 픽셀을 전송합니다.

설치

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

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

pip 및 Homebrew 설치는 v0.19.0부터 더 이상 권장되지 않습니다. v0.14.0에서 도입된 PyPI 패키지(pip install hermes-agent)와 Homebrew formula는 이제 “지원되지 않는 레거시” 설치로 표시됩니다. Hermes가 이러한 설치를 감지하면 모든 인터페이스에서 경고하지만 실행을 차단하지는 않으며, PyPI/Homebrew 배포는 향후 중단될 예정입니다. pip 또는 brew로 설치했다면 위의 설치 프로그램으로 이전하세요.⁵⁶

Linux, macOS, WSL2, Android/Termux에서 작동합니다. 설치 프로그램은 Termux를 자동으로 감지하고 검증된 Android 번들로 전환합니다.⁷ 이제 네이티브 Windows는 v0.14.0에서 처음 제공된 초기 베타가 아니라 Tier 1 플랫폼이며, iex (irm https://hermes-agent.nousresearch.com/install.ps1)로 설치할 수 있습니다. 문서에서 명확히 밝힌 한 가지 주의 사항은 macOS가 Apple Silicon만 지원하며 Intel Mac은 지원하지 않는다는 점입니다.⁵⁵ 과거에는 v0.14.0에서 PowerShell 설치 프로그램을 통해 네이티브 Windows 지원이 초기 베타로 추가되었지만, Windows 설치 경로가 충분히 성숙할 때까지 프로덕션 환경에서는 WSL2가 더 안전한 선택입니다.¹⁹

설치가 완료되면 다음을 실행합니다.

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

유일한 사전 요구 사항은 git입니다. 설치 프로그램은 uv를 통해 Python 3.11을 자동으로 준비하며 sudo는 필요하지 않습니다. 또한 브라우저 자동화 및 WhatsApp 브리지용 Node.js 26, ripgrep, ffmpeg도 준비합니다. v0.20.0부터 Node 26이 필수 최저 버전입니다. 설치 프로그램은 이전 버전의 사용을 거부하고 Hermes가 관리하는 Node를 대신 설치합니다.⁵⁵⁷

설치 확인

hermes --version    # Check version (global flag; there is no `version` subcommand)
hermes doctor       # Diagnose config/dependency issues
hermes status       # Show current configuration + auth state
hermes dump         # Copy-pasteable setup summary for debugging

hermes doctor는 누락된 항목과 해결 방법을 정확히 알려줍니다.⁷ 도움을 요청할 때 GitHub issue 또는 Discord 스레드에 붙여 넣을 진단 명령은 hermes dump입니다. 비밀 정보를 가린 전체 설정의 일반 텍스트 요약을 출력합니다.⁸

수동 설치

사용자 지정 Python 버전, 특정 extras, Nix/NixOS 통합 등 모든 요소를 직접 제어해야 한다면 upstream 설치 가이드에 수동 설치 과정이 단계별로 설명되어 있습니다.⁷ uv pip install -e ".[<extras>]"와 함께 조합할 수 있는 주요 선택형 extras는 다음과 같습니다.

Termux 설치 명령은 다릅니다. uv pip가 아니라 제약 조건 파일과 함께 pip를 사용합니다.

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

Android에서 .[all]을 사용하면 voice extra를 통해 faster-whisper가 설치되기 때문입니다. faster-whisper는 Android용으로 배포되지 않는 ctranslate2 wheel에 의존합니다.⁷

인증 및 제공업체

태그 v2026.9.7에서 hermes_cli/models_catalog_static.py는 311번째 줄에 39개의 정적 CANONICAL_PROVIDERS 항목을 포함합니다(2026년 9월의 구조 분리 작업으로 목록이 hermes_cli/models.py에서 이동했으며, v0.21.0의 tencent-tokenplan을 포함한 항목 자체는 변경되지 않았습니다). 또한 plugins/model-providers/에서 이 목록을 자동으로 확장합니다(번들로 제공되는 디렉터리는 39개이며, 그중 actual, alibaba-coding-plan, commandcode, deepinfra, meta-ai, nebius-token-factory, opencode-free, router, upstage 등 9개에는 정적 항목이 없습니다. 이들은 기본 api_key 인증 유형을 사용하므로 자동 확장 과정에서 포함됩니다). 문서의 제공업체 페이지에는 45개의 클라우드 및 구독 제공업체와 사용자 지정 엔드포인트가 표로 정리되어 있으며, 로컬 및 자체 호스팅 서버(Ollama, vLLM, SGLang, llama.cpp, LM Studio, LiteLLM, ClawRouter 및 모든 OpenAI 호환 엔드포인트)는 별도로 설명합니다.²⁶ 태그 v2026.9.24에서도 정적 목록에는 39개 항목이 있지만, plugins/model-providers/에는 38개 디렉터리가 있습니다. OpenCode의 무료 등급이 자체 클라이언트 외부의 익명 트래픽을 거부하기 시작하면서 키가 필요 없던 opencode-free 제공업체가 9월 18일에 제거되었습니다.⁵³ 이 외에도 사용자 지정 엔드포인트와 서로 다른 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에 저장됩니다.²

전체 제공업체 표

이 표에는 문서 페이지에 수록된 제공업체와 각각의 정확한 설정 절차가 정리되어 있습니다. 해당 태그의 선택 도구에는 문서보다 더 많은 제공업체가 표시되며(위의 개수 참조), OpenAI와 호환되는 모든 항목은 사용자 지정 엔드포인트 행을 통해 사용할 수 있습니다.²²⁶

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은 직접 Copilot API(권장)와 Copilot ACP(로컬 Copilot CLI을 하위 프로세스로 실행)라는 2가지 모드를 지원합니다.²

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

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

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

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

중국 AI Provider(기본 지원)

Hermes는 전용 provider ID를 통해 z.ai/GLM, Kimi/Moonshot, MiniMax(글로벌 및 중국 엔드포인트), 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

기본 URL은 GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL, MINIMAX_CN_BASE_URL, DASHSCOPE_BASE_URL 환경 변수로 재정의할 수 있습니다.²

Z.AI는 엔드포인트를 자동으로 감지합니다. z.ai/GLM provider를 사용하면 Hermes는 여러 엔드포인트(글로벌, 중국, 코딩 변형)를 확인하여 사용자의 API 키를 허용하는 엔드포인트를 찾습니다. 작동하는 엔드포인트는 자동으로 캐시되므로 대부분의 사용자는 GLM_BASE_URL을 설정할 필요가 없습니다.²

xAI (Grok)는 프롬프트 캐싱을 자동으로 활성화합니다. 기본 URL에 x.ai가 포함되면 Hermes는 대화 세션 중 같은 서버로 요청을 전달하기 위해 모든 요청에 x-grok-conv-id 헤더를 전송하며, 캐시된 시스템 프롬프트와 기록을 재사용합니다.² 자동으로 작동하므로 별도 설정이 필요하지 않습니다.

hermes auth 명령

hermes auth는 풀과 OAuth 자격 증명을 관리하는 명령입니다.⁶

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

자격 증명 풀을 사용하면 동일한 provider의 여러 API 키 또는 OAuth 토큰을 순환 사용할 수 있습니다. 코드를 변경하지 않고 여러 키에 요청 한도를 분산할 때 유용합니다.⁶ 기존 hermes login / hermes logout 명령은 제거되었습니다. 대신 hermes auth를 사용하세요.⁶

사용자 지정 및 자체 호스팅 엔드포인트

Hermes는 모든 OpenAI 호환 API 엔드포인트와 연동됩니다. 서버가 /v1/chat/completions를 구현한다면 Hermes가 해당 서버를 사용하도록 설정할 수 있습니다.²

대화형 설정(권장):

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

수동 config.yaml 설정:

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

두 방식 모두 설정을 config.yaml에 영구 저장하며, 이 파일은 기본 모델, provider, 기본 URL을 관리하는 단일 정보 원본입니다.² 기존 환경 변수 OPENAI_BASE_URL과 LLM_MODEL은 더 이상 기본 모델 설정에 사용되지 않습니다. hermes model을 사용하거나 config.yaml을 직접 편집하세요.² (OPENAI_BASE_URL과 OPENAI_API_KEY는 보조 provider: "main" 라우팅 경로의 대체 설정으로 여전히 사용되므로, 해당 경로에서 사용 중이라면 무작정 삭제하지 마세요.)⁴

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

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

/model custom(모델 이름 없이 단독 사용)은 엔드포인트의 /v1/models API를 조회하며, 로드된 모델이 정확히 1개이면 해당 모델을 자동으로 선택합니다. 단일 모델을 실행하는 로컬 서버에서 유용합니다.²

로컬 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는 기본 컨텍스트 길이가 매우 짧습니다(VRAM이 24GB 미만이면 4,096토큰). OLLAMA_CONTEXT_LENGTH 또는 Modelfile을 통해 반드시 늘려야 합니다. OpenAI 호환 API는 클라이언트가 지정한 컨텍스트 길이를 받지 않으므로 Hermes에서 대신 설정할 수 없습니다.² 에이전트 용도라면 최소 16k~32k로 설정하세요.

vLLM — 고성능 GPU 서빙:

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

도구 호출을 사용하려면 --enable-auto-tool-choice와 --tool-call-parser <name>이 필요합니다. 지원되는 파서는 hermes(Qwen 2.5, Hermes 2/3), llama3_json, mistral, deepseek_v3, deepseek_v31, xlam, pythonic입니다. 이 플래그를 지정하지 않으면 도구 호출이 일반 텍스트로 반환됩니다.²

SGLang — KV 캐시 재사용을 위해 RadixAttention을 사용하는 빠른 서빙:

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

SGLang의 주의할 점: 기본 max_tokens는 128입니다. 응답이 중간에 잘리면 서버에 --default-max-tokens를 설정하거나 config.yaml에서 model.max_tokens를 구성하세요.²

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

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

도구 호출에는 --jinja가 필요합니다. 이 플래그가 없으면 llama-server는 tools 매개변수를 완전히 무시하고, 모델은 응답 텍스트에 JSON을 작성하여 도구 호출을 시도합니다. Hermes는 이를 실제 도구 호출로 해석할 수 없습니다.²

LM Studio — GUI를 제공하는 데스크톱 앱:

LM Studio 앱에서 서버를 시작하거나(Developer 탭 → Start Server), CLI에서 lms server start(1234 포트에서 시작)와 lms load qwen2.5-coder --context-length 32768을 실행하세요.² 그런 다음 hermes model이 http://localhost:1234/v1을 가리키도록 설정합니다.

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

이름이 지정된 사용자 지정 제공자

여러 사용자 지정 엔드포인트(예: 로컬 개발 서버와 원격 GPU 서버)를 사용한다면 config.yaml에서 이름이 지정된 사용자 지정 제공자로 정의하세요.²

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

그런 다음 세 부분으로 구성된 구문을 사용하여 세션 도중에 제공자를 전환할 수 있습니다.

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

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

플러그형 제공자 아키텍처(v0.13.0 이상)

v0.13.0에는 ProviderProfile ABC와 plugins/model-providers/ 디렉터리가 포함되어 있어, 서드 파티 추론 제공자를 코어 수정 없이 추가할 수 있습니다.¹⁸ 제공자가 OpenAI, Anthropic 또는 Codex 호환 API 모드를 지원한다면 인증 경로, 기본 URL, 모델 카탈로그, 캐싱 헤더를 선언하는 ProviderProfile 하위 클래스를 구현할 수 있습니다. Hermes는 기본 제공자와 동일한 runtime_provider.py 경로를 통해 이를 확인합니다. 이것이 v0.13.0에서 제공자 지원이 확대된 배경이 된 아키텍처 변경입니다. 이제 제공자를 추가하기 위해 코어 코드를 편집하는 대신 플러그인을 배포합니다.

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

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

컨텍스트 길이 감지

업스트림 문서에 따르면 다음 두 설정은 자주 혼동됩니다.²

• context_length — 전체 컨텍스트 창입니다(입력과 출력의 토큰 예산을 합친 값으로, 예를 들어 Claude Opus 4.7은 1,000,000이고 Sonnet 4.6은 200,000입니다). Hermes는 이 값을 사용하여 기록을 압축할 시점을 결정합니다.
• model.max_tokens — 출력 한도입니다(모델이 단일 응답에서 생성할 수 있는 최대 토큰 수). 기록 길이와는 무관합니다.

자동 감지가 컨텍스트 창 크기를 잘못 판단하면 context_length를 설정하세요.

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

Hermes는 여러 소스를 차례로 확인하여 컨텍스트 창을 감지합니다. 구성 재정의 → 사용자 지정 제공자의 모델별 설정 → 영구 캐시 → 엔드포인트 /models → Anthropic /v1/models → OpenRouter API → Nous Portal → models.dev(3,800개 이상의 모델을 수록한 커뮤니티 관리 레지스트리) → 대체 기본값(128K) 순서입니다.² 이 시스템은 제공자를 구분하므로, 동일한 모델이라도 제공 주체에 따라 컨텍스트 한도가 달라질 수 있습니다(예: claude-opus-4.6은 Anthropic에서 직접 제공할 때 1M이지만 GitHub Copilot에서는 128K입니다).²

스마트 모델 라우팅: 제공자 순환 및 대체

Hermes는 사용자를 하나의 제공자와 하나의 모델에 묶어 두지 않습니다. 스마트 모델 라우팅은 주어진 요청을 실제로 처리할 제공자와 모델을 결정하는 일련의 메커니즘입니다. 자격 증명 풀은 여러 키에 부하를 분산하고, 구성된 대체 모델은 기본 모델이 실패하면 작업을 넘겨받으며, 아래의 보조 슬롯은 부가 작업을 기본 모델과 별개로 더 저렴한 모델에 라우팅합니다.²⁶ 이 3가지를 함께 구성하세요. 속도 제한에 걸려 멈추는 에이전트와 계속 작업하는 에이전트의 차이를 만듭니다.

자격 증명 풀. 동일한 제공자의 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

대체 기능은 대화를 잃지 않고 세션 도중에 모델과 제공자를 전환합니다. 세션당 최대 1회만 작동합니다.² 대체 기능을 지원하는 제공자는 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는 이미지 분석(비전), 위험 명령 승인 분류, 컨텍스트 압축, 세션 제목 생성, TTS 오디오 태그 삽입, skill 매칭, MCP 도구 디스패치, Kanban 지정자 및 분해자 계열과 같은 부가 작업에 “보조” 모델을 사용합니다.⁴³⁴ 기본적으로(auxiliary.*.provider: "auto") 모든 보조 작업은 기본 채팅 모델, 즉 hermes model에서 선택한 것과 동일한 제공자와 모델에서 실행됩니다. 문서에는 이 방식이 이전의 저비용 제공자 자동 감지를 대체했다고 명시되어 있습니다. “이전 빌드는 애그리게이터 사용자(OpenRouter, Nous Portal)를 저렴한 제공자 측 기본 모델로 분리했습니다. 이는 예상하기 어려운 동작이었습니다. … 이제 auto는 모든 사용자에게 기본 모델을 사용하며, config.yaml의 작업별 재정의는 여전히 우선 적용됩니다.”³⁴ 시작하기 위해 별도로 구성할 항목은 없습니다. 다만 비용과 맞바꾸는 방식입니다. 비싼 추론 모델에서는 보조 작업에도 상당한 비용이 발생하므로, 비용이 중요하다면 개별 작업이 저렴하고 빠른 모델을 사용하도록 지정하세요. 이제 2개의 보조 작업은 LLM을 전혀 사용하지 않습니다. 웹 추출(“web_extract와 브라우저 스냅샷은 긴 콘텐츠를 정해진 방식으로 잘라내고 전체 텍스트를 저장하여 read_file로 페이지를 나누어 읽을 수 있게 합니다. 이 과정에는 LLM이 사용되지 않습니다”)과 세션 검색(단일 형태의 도구가 DB 콘텐츠를 직접 반환합니다)이 이에 해당합니다. 이전의 auxiliary.web_extract.* 및 auxiliary.session_search.* 블록은 기본값에서 제거되었습니다. 기존 config.yaml에 남아 있는 값은 “문제를 일으키지 않는 잔여 값이며 무시됩니다.” 또한 해당 태그의 기본값에는 flush_memories 슬롯도 없습니다.³⁴

각 보조 작업에서 사용할 모델과 provider를 설정할 수 있습니다. 모든 보조 슬롯은 provider, model, base_url과 같은 설정 항목을 사용하며, 여기에 api_key, timeout, extra_body, 작업별 reasoning_effort도 포함됩니다.⁴³⁴

auxiliary:
  vision:                          # vision_analyze + browser screenshots
    provider: "auto"               # "auto" (= main model), "openrouter", "nous", "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: 120
    download_timeout: 30
  approval:                        # dangerous-command approval classifier
    provider: "auto"
    model: ""
    timeout: 30
  compression:                     # summarizer -- legacy compression.summary_* keys migrate here (config v17)
    provider: "auto"
    model: ""
    base_url: ""
    timeout: 120
  title_generation:                # auto-generated session titles after the first exchange
    enabled: true                  # set false to disable auto-titles
    provider: "auto"
    model: ""
    language: ""                   # empty follows the conversation; e.g. "English" pins titles to one language
  tts_audio_tags:    { provider: "auto", model: "" }  # Gemini 3.1 TTS hidden audio-tag insertion
  skills_hub:        { provider: "auto", model: "" }  # skill matching and search
  mcp:               { provider: "auto", model: "" }  # MCP tool dispatch
  triage_specifier:  { provider: "auto", model: "" }  # hermes kanban specify: rough one-liner into a concrete spec, promoted to todo
  kanban_decomposer: { provider: "auto", model: "" }  # hermes kanban decompose: triage task into a graph of child tasks routed to specialist profiles
  profile_describer: { provider: "auto", model: "" }  # hermes profile describe --auto: 1-2 sentence profile descriptions

더 전문화된 슬롯도 같은 구조를 따릅니다. /goal 계약의 충족 여부를 판단하는 goal_judge, skill 사용 검토 포크인 curator, 턴 이후 자체 개선 포크인 background_review, /review 검토자 subagent인 review, Mixture-of-Agents용 moa_reference와 moa_aggregator, memory_query_rewrite, monitor가 이에 해당합니다. YAML을 직접 편집할 필요도 없습니다. hermes model을 실행하고 “Configure auxiliary models”를 선택하면 작업별 대화형 선택기를 사용할 수 있습니다.³⁴

"main" provider 옵션은 “기본 agent가 사용하는 provider를 그대로 사용한다”는 의미이며, auxiliary:, compression:, 기본 fallback 항목(fallback_providers: 또는 기존 fallback_model:) 안에서만 유효합니다. 최상위 model.provider 설정에는 사용할 수 없습니다. 사용자 지정 OpenAI 호환 endpoint를 기본 모델로 사용하는 경우 model: 섹션에서 provider: custom을 설정하세요.⁴

이 점이 중요한 이유: 이제 auto가 기본 모델을 그대로 사용하므로, 예전의 “OpenRouter를 설정하지 않으면 보조 작업의 성능이 조용히 저하된다”는 함정은 사라졌습니다. 이제 고려할 사항은 비용입니다. 기본 모델이 비용이 많이 드는 추론 모델이라면 자주 실행되는 부가 작업에는 저렴하고 빠른 모델을 지정하세요.

auxiliary:
  vision:
    provider: "openrouter"
    model: "google/gemini-2.5-flash"
  compression:
    provider: "openrouter"
    model: "google/gemini-2.5-flash"

설정 시스템

Hermes는 계층형 설정 시스템을 사용합니다. 상위 계층이 하위 계층을 재정의하며, 그중 한 계층은 config.yaml에서 확인할 수 없는 전역 제공자 레지스트리이므로 우선순위를 이해해야 합니다.

설정 파일 구성

공식 문서에 따르면 Hermes 설정은 다음 파일로 구성됩니다:⁴

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

config.yaml과 .env에 모두 값이 설정되어 있으면 비밀 정보가 아닌 설정에는 config.yaml이 우선 적용됩니다.⁴ 적용 규칙은 다음과 같습니다: - 비밀 정보 (API 키, 봇 토큰, 비밀번호) → .env - 그 외 모든 설정 (모델, 터미널 백엔드, 압축 설정, 메모리 제한, toolset) → config.yaml

셸 형식의 보간을 사용하면 config.yaml에서 비밀 정보를 참조할 수 있습니다:⁴

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

설정 관리

hermes config                # View current configuration
hermes config show           # Same as above
hermes config edit           # Open config.yaml in your editor
hermes config set KEY VAL    # Set a specific value
hermes config 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개 로캘이 추가되었습니다.¹⁸ v0.14.0에서는 모든 gateway 명령과 웹 대시보드가 현지화되고 로캘 8개가 추가되어 총 16개가 되었습니다.¹⁹ v2026.8.31 태그 기준으로 locales/ 트리에는 영어와 16개 번역(af, ar, de, es, fr, ga, hu, it, ja, ko, pt, ru, tr, uk, zh-hant, zh)을 합쳐 17개의 메시지 카탈로그가 있습니다.³³ 현재 문서는 zh-Hans로만 현지화되어 있습니다. 로캘은 LC_ALL 또는 LANG 환경 변수에서 결정하거나 config.yaml의 명시적인 locale: 키로 지정할 수 있습니다. 영어는 계속 기본 언어이자 아직 번역되지 않은 모든 문자열의 기준입니다.

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

profile을 사용하면 각각 자체 설정, 세션, skill, 메모리, gateway PID를 갖춘 여러 개의 격리된 Hermes 인스턴스를 만들 수 있습니다. 이를 통해 서로의 상태를 노출하지 않고 “업무용 Hermes”와 “개인용 Hermes”를 나란히 실행할 수 있습니다.⁶

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

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

v0.21.2부터 격리 경계가 더욱 엄격하게 적용됩니다. 여러 gateway를 함께 운영하는 환경에서 보조 profile이 기본 profile의 허용 목록을 물려받거나, 기본 profile의 호스트로 인증 정보를 전송하거나, 해당 profile의 보관소 비밀 정보를 표준 입출력 방식의 MCP 서버에 넘기거나, 다른 profile의 .env/auth.json/state.db를 MEDIA: 전송에 첨부할 수 있었던 실제 profile 간 유출 문제가 여러 수정 사항을 통해 해결되었습니다(#107609-#107630). 여러 profile을 함께 운영한다면 격리가 실제로 보장되기 시작한 태그는 v0.21.2입니다. 자세한 내용은 v0.21.2의 새로운 기능을 참조하세요.⁴⁸

CLI 명령어

이 섹션에서는 실무자를 위해 최상위 CLI 명령어를 정리합니다. 코드를 기반으로 한 공식 레퍼런스는 업스트림 CLI 명령어 레퍼런스를 참조하세요.⁶

전역 옵션

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

최상위 명령어

hermes chat — 주요 진입점

인수 없이 hermes를 실행하면 대화형 채팅으로 들어갑니다. hermes chat은 옵션을 명시할 수 있는 형태입니다.⁶

hermes chat -q "Summarize the latest PRs" --oneshot # Answer and exit (without --oneshot, a TTY seeds an interactive session)
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를 실행하는 것보다 강력합니다.⁶

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 — 모든 agent 활동(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 명령어

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가 추가되었습니다.⁵⁶ v0.20.5 업데이트부터 /model 선택기는 입력하는 동시에 결과를 필터링하는 퍼지 검색도 지원합니다.²³³⁵

도구, Skill 및 정보

동적 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, Email, 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>을 사용해 도구를 전환할 수 있습니다. 새 도구 구성이 적용되도록 세션이 초기화됩니다.⁹

터미널 백엔드

터미널 도구에는 7개의 실행 백엔드가 기본으로 제공되며, v0.20.6부터는 제공자 선택기와 마찬가지로 플러그인을 통해 확장할 수 있습니다(아래 참조).¹⁰²⁴

hermes config set terminal.backend <name> 또는 config.yaml에서 백엔드를 전환할 수 있습니다.

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

플러그인 백엔드(v0.20.6 이상). 이제 타사 샌드박스 공급업체는 핵심 저장소에 코드를 추가할 필요가 없습니다. 플러그인은 로드 시 PluginContext.register_terminal_environment_provider를 통해 TerminalEnvironmentProvider를 등록하며, 등록한 이름은 기본 제공 백엔드와 동일하게 terminal.backend에서 선택할 수 있습니다. 기본 제공 이름은 예약되어 있으므로 저장소 내 백엔드와 이름이 충돌하는 제공자는 레지스트리에서 거부됩니다. 또한 핵심 시스템이 하드코딩된 이름 목록 대신 각 분류 지점에서 레지스트리를 조회하므로, 등록된 백엔드는 모든 핵심 인터페이스(hermes setup 백엔드 선택기, 대시보드 검사 상태, hermes doctor 검사, 컨테이너 경로 및 cwd 처리, 비밀 정보 제거)에 자동으로 통합됩니다.³²

SSH 백엔드(보안을 위해 권장합니다. 에이전트가 자체 코드를 수정할 수 없습니다):¹⁰

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에서는 여러 에이전트의 협업이 핵심 기본 요소로 자리 잡았습니다. 에이전트 간은 물론 재시작 후에도 작업, 상태, 작업자 식별 정보를 추적하는 영구 Kanban 보드가 도입되었습니다.¹⁸ 이 보드 덕분에 Hermes 작업자 무리는 중단된 인계 과정에서 멈추지 않고 실제로 작업을 완료할 수 있습니다.

Kanban 보드는 목표 측의 /goal(목표가 고정된 Ralph 루프), 그리고 에이전트 생성 방식을 담당하는 기존 delegate_task 도구와 자연스럽게 연계됩니다. 그 결과 모든 에이전트가 다음에 해야 할 작업, 현재 작업 담당자, 정체된 작업에 관한 하나의 정보 원천을 공유하는 작업자 무리 패턴이 형성됩니다.

Hermes 작업자 무리란 무엇입니까?

작업자 무리는 하나의 공유 Kanban 보드를 대상으로 여러 Hermes 작업자를 병렬로 실행하는 구성입니다. 별도로 활성화해야 하는 하위 시스템이 아니라 보드가 가능하게 하는 작업 방식입니다. 보드는 병렬 에이전트가 스스로 마련할 수 없는 한 가지 요소, 즉 다음에 어떤 작업을 가져와야 하며 이미 누군가 처리하고 있는가?라는 질문에 대한 단일하고 신뢰할 수 있는 답을 제공합니다.

v0.15.0에서는 이 패턴이 공식적으로 지원되는 토폴로지로 발전했습니다. 병렬 작업자 조정을 위한 작업자 무리 토폴로지, 상위 수준 목표를 하위 작업으로 나누는 자동 분해, 작업별 모델 재정의, 예약 작업, 그리고 병렬 작업자가 같은 체크아웃에서 충돌하지 않도록 하는 worktree 관리가 추가되었습니다.⁵⁹

실제 구성은 다음과 같습니다. 작업자 무리에 목표를 지정하고, 자동 분해를 통해 목표를 보드 작업으로 나눈 다음, 작업자가 작업을 가져와 실행하고 결과를 반환하도록 합니다. 재시도 한도는 작업별로 설정되므로(max_retries), 하나의 불안정한 하위 작업이 전체 실행의 허용 한도를 소진하지 않습니다. 보드는 영구적이므로 작업자 무리는 재시작 후에도 유지됩니다. 작업자는 동일한 상태에 다시 연결해 작업을 재개합니다.

작업자 무리의 성패는 작업 분해의 품질에 달려 있습니다. 보드는 작업자를 조정하지만, 잘못 분할된 목표를 올바르게 만들어 주지는 않습니다. 숨겨진 상태를 공유하는 작업은 worktree 사용 여부와 관계없이 여전히 충돌합니다.

Skills 시스템

skill은 에이전트가 필요할 때 불러올 수 있는 주문형 지식 문서입니다. 토큰 사용량을 최소화하기 위해 점진적 공개 방식을 따르며 agentskills.io 공개 표준과 호환됩니다.¹¹

모든 skill은 ~/.hermes/skills/에 저장됩니다. 이곳은 기본 디렉터리이자 단일 기준 정보원입니다. 새로 설치하면 번들 skill이 저장소에서 복사됩니다. Hub를 통해 설치하거나 에이전트가 생성한 skill도 이곳에 저장됩니다.¹¹

점진적 공개

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.

조건부 활성화

skill은 사용할 수 있는 도구에 따라 표시되거나 숨겨질 수 있습니다. 이는 특히 대체 skill에 유용합니다. 유료 도구를 사용할 수 없을 때만 표시해야 하는 무료 또는 로컬 대안입니다.¹¹

예시: 기본 제공 duckduckgo-search skill은 fallback_for_toolsets: [web]을 사용합니다. FIRECRAWL_API_KEY가 설정되어 있으면 web toolset을 사용할 수 있으므로 에이전트는 web_search를 사용하고 DuckDuckGo skill은 숨겨진 상태로 유지됩니다. API 키가 없으면 DuckDuckGo skill이 자동으로 대체 항목으로 표시됩니다.¹¹

에이전트 관리형 skill

에이전트는 skill_manage 도구를 통해 자체 skill을 생성, 업데이트, 삭제할 수 있습니다. 이는 에이전트의 절차적 기억입니다. 에이전트가 간단하지 않은 작업 흐름을 파악하면 나중에 다시 활용할 수 있도록 그 방식을 skill로 저장합니다.¹¹

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

작업:¹¹

Skill Hub

온라인 레지스트리에서 skill을 탐색, 검색, 설치하고 관리합니다.⁶¹¹

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 tap(설정 없이 탐색 가능): openai/skills, anthropics/skills, huggingface/skills, NVIDIA/skills, garrytan/gstack. claude-marketplace 소스는 v0.20.0에서 제거되었으며, 소스 목록에서 browse-sh가 이를 대체했습니다.¹¹⁵⁵

보안 검사

Hub를 통해 설치된 모든 skill은 데이터 유출, 프롬프트 인젝션, 파괴적 명령, 공급망 위험 신호 및 기타 위협을 확인하는 보안 검사를 거칩니다.¹¹

신뢰 수준:¹¹

--force를 사용하면 community skill에 대한 위험하지 않은 정책 차단을 무시할 수 있습니다. 하지만 dangerous 검사 판정은 무시할 수 없습니다.¹¹

외부 skill 디렉터리

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

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

경로는 ~ 확장과 ${VAR} 환경 변수 치환을 지원합니다. 외부 디렉터리는 읽기 전용입니다. 에이전트가 skill을 생성하거나 편집할 때는 항상 ~/.hermes/skills/에 기록합니다. 두 위치에 같은 이름의 skill이 있으면 로컬 skill이 우선합니다.¹¹

고정 skill: skills.auto_load(v0.21.4 기준)

config.yaml의 skills.auto_load 아래에 나열된 skill 이름은 모든 새 세션에서 전체 내용이 불러와진 상태로 고정됩니다. CLI, TUI, gateway, cron, API에 모두 적용됩니다.⁵¹

skills:
  auto_load:
    - team-conventions
    - deploy-checklist

이 목록은 에이전트의 프롬프트가 처음 구성될 때 한 번만 확인됩니다. 이름이 없거나 비활성화되어 있으면 세션을 실패시키지 않고 경고 후 건너뜁니다. --ignore-rules의 기반 기능인 HERMES_IGNORE_RULES는 자동으로 삽입되는 다른 context와 마찬가지로 이 목록도 비활성화합니다. 이는 상시 지침 역할을 하며, 한 세션에서만 skill을 미리 불러오는 -s/--skills를 보완합니다.⁵¹

영구 메모리

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

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

고정 스냅샷 방식: 시스템 프롬프트에 삽입되는 내용은 세션 시작 시 한 번만 캡처되며 세션 도중에는 변경되지 않습니다. 이는 의도된 동작으로, 성능을 위해 LLM의 접두사 캐시를 유지합니다. 세션 중 변경된 내용은 즉시 디스크에 저장되지만 다음 세션이 시작되기 전까지는 시스템 프롬프트에 나타나지 않습니다.¹²

저장할 내용

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

다음 내용은 저장하지 않습니다:¹² - 사소하거나 당연한 정보 - 쉽게 다시 찾을 수 있는 정보 - 가공하지 않은 대량의 데이터(메모리에 저장하기에는 너무 큼) - 해당 세션에서만 유효한 일시적인 정보 - 이미 컨텍스트 파일에 있는 정보

세션 검색

에이전트는 MEMORY.md와 USER.md 외에도 session_search 도구를 사용해 이전 대화를 검색할 수 있습니다. 모든 CLI 및 메시징 세션은 FTS5 전문 검색을 지원하는 SQLite(~/.hermes/state.db)에 저장됩니다. v0.15.0에서 재설계된 이후 이 도구는 LLM를 전혀 사용하지 않고 저장된 대화 내용을 직접 반환합니다. 원문에서는 이를 “단일 형태의 도구가 DB 내용을 직접 반환한다”고 표현하며, 이 변경으로 속도가 4,500배 빨라지고 API 비용이 사라졌습니다.¹²⁵⁹³⁴

v0.21.4 무렵에 추가된 2가지 기능은 모두 v2026.9.21 태그에서 확인되었습니다. 첫째는 시간 범위입니다. 검색 인터페이스는 세션 시작 시간의 하한을 포함하는 after와 상한을 포함하지 않는 before를 받습니다. 각 값에는 ISO 날짜 또는 날짜와 시간을 지정할 수 있으며, 날짜만 지정하면 해당 날짜의 협정 세계시 자정을 의미합니다. 상대 기간(7d, 24h, 2w)도 사용할 수 있습니다. 이 값은 시간 범위를 실제로 명시한 쿼리에만 사용해야 하며, sort는 여전히 범위가 아니라 순위에 영향을 주는 설정입니다. 둘째는 검색 결과가 없을 때 재시도하는 회상 기능입니다. FTS5는 검색어 사이에 암시적으로 AND를 적용하므로, 여러 단어로 바꿔 표현한 쿼리는 저장된 문장에 검색어가 하나라도 없으면 해당 문장을 찾지 못할 수 있습니다. 따라서 정확한 쿼리와 부분 문자열 대체 검색에서 모두 결과가 없으면 색인을 다시 검색해 검색어 중 하나라도 일치하는 결과를 반환하고, 더 많은 검색어를 포함하는 행을 먼저 표시합니다. 결과가 발견되면 정확히 일치하는 기존 검색 방식이 유지되며, 이 재시도는 결과가 없을 때만 실행됩니다. 명시적인 OR/NOT 쿼리, 단일 검색어 쿼리, 한중일 문자용 경로를 사용하는 쿼리는 그대로 유지됩니다.⁵¹

외부 메모리 제공자

MEMORY.md와 USER.md보다 더 깊이 있는 영구 메모리가 필요할 때 사용할 수 있도록 Hermes에는 Honcho, OpenViking, Mem0, Holographic, RetainDB, ByteRover, Supermemory라는 7개의 외부 메모리 제공자 플러그인이 포함되어 있습니다. Hindsight를 비롯한 추가 제공자는 플러그인 카탈로그에서 설치할 수 있습니다.¹²

Hindsight는 v0.21.4까지 핵심 소스 트리에 포함되어 있었지만 v0.21.5부터 Vectorize가 관리하는 카탈로그로 이전되었습니다. 기존 설정은 자동으로 이전됩니다. memory.provider: hindsight가 설정되어 있으면 hermes update가 이 제공자를 지정한 모든 profile 홈에 카탈로그 플러그인을 설치하며, 여전히 설치되지 않은 경우에는 에이전트를 처음 시작할 때 설치됩니다. security.allow_lazy_installs: false로 설정하면 에이전트 시작 과정에서는 메시지만 기록하므로 hermes plugins install hindsight를 직접 실행하세요. 플러그인은 ~/.hermes/plugins/hindsight/에 설치되고 plugins.enabled에 추가됩니다. memory.provider, memory.hindsight.*, HINDSIGHT_API_KEY, 메모리 데이터는 기존 상태로 유지됩니다. hermes memory status와 hermes plugins list로 확인하세요. hermes-agent[hindsight] pip 추가 패키지는 제거되었습니다.⁵³

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

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

Checkpoint v2(v0.13.0 이상)

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

성격과 SOUL.md

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

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 — 프로젝트 구조, 코딩 규칙, 도구 선호 사항, 저장소별 작업 절차, 명령, 포트, 경로, 배포 참고 사항.

유용한 기준은 다음과 같습니다. 어디서나 따라야 할 내용은 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 인증으로 모델 추론 외에도 더 많은 기능을 이용할 수 있다는 것입니다.

가장 빠른 시작 방법은 hermes setup --portal입니다. README에서는 이를 “새로 설치한 환경에서 명령어 하나로 설정”하는 방법으로 소개합니다. 이 명령어는 OAuth를 통해 로그인하고 Nous를 제공자로 설정한 다음 Tool Gateway를 활성화합니다. 이후에는 hermes portal로 연결을 관리합니다. hermes portal login은 하위 명령어를 지정하지 않았을 때 실행되는 기본 명령어로, 동일한 일회성 온보딩을 진행합니다. hermes portal info는 “Portal 인증 및 Tool Gateway 라우팅 요약”을 출력하고, hermes portal open은 기본 브라우저에서 구독 페이지를 열며, hermes portal tools는 gateway 도구와 Nous를 통해 라우팅되는 도구를 나열합니다. hermes portal status는 info의 숨겨진 이전 버전 호환 별칭으로 유지되며, 해당 태그의 문서 내 CLI 참조에도 하위 명령어가 여전히 status로 표기되어 있으므로 둘 다 사용할 수 있습니다.²⁸

gateway에서 제공하는 기능

작동 방식

gateway는 새로운 use_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/에서 가입한 후 요금 페이지에서 현재 요금제를 확인하세요.

Nous 무료 요금제와 안내형 첫 실행(v0.21.2+)

v0.21.2부터 새로 설치한 환경에서도 유료 요금제나 API 키 없이 작동하는 agent를 실행할 수 있습니다. 무료 추론과 connector가 기본으로 제공되고 명령어 하나로 로그인할 수 있으며, 채팅 안에서는 /login으로 로그인 절차를 시작할 수 있습니다. Connector 도구(Gmail, Linear, Notion 등)는 다른 도구와 마찬가지로 tool_search를 통해 검색할 수 있습니다. 데스크톱 앱은 HERMES_GUEST_ONBOARDING=1로 활성화되는 안내형 첫 실행 기능도 제공합니다. 정확히 값이 1일 때만 활성화됩니다. 데스크톱 앱 자체 테스트에서는 'true', '0', 빈 값 모두 이 기능을 비활성 상태로 유지하는지 검증하며, 실행 여부는 생성된 backend의 환경에 명시적으로 기록되므로 상속된 값이 유입되지 않습니다.⁴⁸

v0.21.4 시기부터는 connector 연결이 각 frontend에 분산된 로직이 아니라 backend가 담당하는 단일 작업으로 처리됩니다. manage_connections 도구 호출은 backend에서 순수 데이터 기반 연결 상태 머신을 구동하며, 작업 제한 시간은 의도적으로 설정 키로 제공하지 않고 300초로 고정되어 있습니다. Desktop, TUI, CLI는 모두 이를 동일한 설정 카드로 표시합니다. 이 카드는 누락된 각 자격 증명에 해당하는 필드(이름, 안내 문구, 필수 여부)를 표시하고 모든 필수 필드에 텍스트가 입력될 때까지 실행 버튼을 비활성화합니다. backend는 모든 frontend에 동일한 비밀 정보 전용 분리 원칙을 적용합니다.⁵¹

지원 중단 안내

• HERMES_ENABLE_NOUS_MANAGED_TOOLS 환경 변수는 v0.10.0에서 삭제되었습니다. 이제 관리형 도구는 도구별 use_gateway 설정 필드로 활성화하며, Portal 구독 상태에 따라 이용 가능 여부가 결정됩니다.⁶¹

이번 릴리스의 범위가 아닌 것

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

메시징 Gateway

Hermes는 하나의 gateway 프로세스에서 28개 메시징 플랫폼에 연결되는 장기 실행 gateway 프로세스로 작동할 수 있습니다. 지원 플랫폼은 Telegram, Discord, Slack, WhatsApp, Signal, SMS, 이메일, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin (WeChat), BlueBubbles (iMessage), QQBot, Microsoft Teams, Tencent Yuanbao, Google Chat, LINE, SimpleX Chat, Photon (iMessage), WhatsApp Cloud API, WeCom Callback, Raft, IRC, ntfy, Buzz, 범용 Webhook 어댑터입니다.^360171819 이 28이라는 수는 v2026.8.31 태그의 문서에 있는 플랫폼 비교 표를 기준으로 합니다. 그 아래에서 gateway/config.py는 24개의 내장 Platform 열거형 멤버를 정의하고 있으며, 여기에는 local, api_server, webhook, msgraph_webhook, relay처럼 채팅과 관련 없는 항목도 포함됩니다. 이 밖의 이름은 필요할 때 plugins/platforms/에 포함된 22개 어댑터 디렉터리 중 하나로 해석되므로, 열거형이나 디렉터리 수만 세면 문서의 수치와 일치하지 않습니다.²⁵ v0.9.0에서는 BlueBubbles를 통한 iMessage 지원이 추가되었으며, 자동 Webhook 등록, 설정 마법사, 충돌 복원력을 제공합니다. 또한 iLink Bot API을 통한 네이티브 WeChat 지원과 기업용 앱을 위한 WeCom 콜백 모드도 추가되었습니다.¹⁶ 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 플러그인 훅이 도입되었습니다.¹⁸ v0.14.0에서는 LINE과 SimpleX Chat이 추가되었으며, Graph 인증, Webhook 리스너, 파이프라인 런타임, 발신 전송을 포함한 Microsoft Teams 스택이 처음부터 끝까지 완성되었습니다.¹⁹ v0.17.0(2026년 6월 19일)에서는 Photon Spectrum을 통한 relay 없는 iMessage 지원이 추가되었습니다. hermes photon login을 사용하는 기기 코드 OAuth 방식으로, Mac이나 BlueBubbles relay가 필요하지 않습니다. 이 버전에는 브리지 프로세스 요구 사항을 대체하는 공식 WhatsApp Business Cloud API 어댑터, SimpleX 그룹 및 네이티브 첨부 파일, 번들 플랫폼 플러그인인 Raft도 추가되었습니다.²¹ 릴리스 노트에서 특별히 언급되지 않은 플랫폼 2개도 문서 표에 포함되어 있습니다. ntfy는 가벼운 HTTP 게시-구독 푸시 채널입니다. ntfy 모바일 앱에서 주제를 구독하고, 해당 주제로 메시지를 보내 에이전트와 대화한 뒤 휴대전화로 답변을 받을 수 있습니다. 공개 ntfy.sh 서버나 자체 호스팅 인스턴스에서 작동하며, SDK이나 데몬이 필요하지 않습니다. Buzz는 Hermes를 Nostr 프로토콜 기반의 Block 오픈 소스 인간-에이전트 협업 플랫폼인 Buzz 커뮤니티에 연결합니다. 발신 메시지에는 buzz CLI을 실행하고, 수신에는 네이티브 Nostr WebSocket 구독을 사용합니다. 두 플랫폼 모두 hermes gateway setup을 통해 설정됩니다.²⁵

설정

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

모든 메시징 플랫폼은 CLI과 동일한 AIAgent 대화 루프를 거칩니다. 따라서 슬래시 명령은 두 환경에서 동일하게 작동하며, Telegram에서 예약한 cron 작업의 출력을 Discord로 전달할 수도 있습니다. 플랫폼 간 차이는 가장자리의 연결 계층에만 존재합니다.³

v0.19.0에서는 profile 기반 메시지 라우팅과 내구성 있는 전송이 추가되었습니다. 하나의 봇 토큰을 공유하는 단일 다중화 gateway에서 특정 길드, 채널 또는 스레드를 서로 다른 profile로 라우팅할 수 있습니다. 각 profile의 설정, skills, 메모리, 비밀 정보는 완전히 격리되며, GATEWAY_MULTIPLEX_PROFILES 재정의도 지원합니다. 또한 안정성이 강화되어 잘못 설정된 profile 하나가 전체 gateway를 중단시킬 수 없게 되었습니다. 내부적으로 라우팅 색인은 state.db로 이동했으며, sessions.json은 이제 선택적인 이전 형식 미러로만 사용됩니다. 최종 응답은 플랫폼으로 전송되는 과정에서 내구성 있는 전송 의무 원장에 기록됩니다. 답변이 완료된 직후 gateway가 충돌하더라도 다음 시작 시 다시 전송되므로 조용히 유실되지 않습니다.⁵⁶ 라우팅된 profile 간 격리는 v0.21.2에서 더욱 강화되었습니다. 이 버전에서는 다중화 설정에서 발생하던 profile 간 정보 누출 문제를 해결했습니다. 여기에는 상속된 허용 목록, 기본 profile의 호스트로 전송되는 자격 증명, 기본 profile의 보관소 비밀 정보가 stdio MCP 서버에 전달되는 문제, profile 간 MEDIA: 첨부 파일 노출, 형제 profile의 Nous bearer가 프로세스별 메모에 남는 문제(#107609-#107630)가 포함됩니다.⁴⁸

v0.21.1에서는 명시적인 작업으로만 대화 경계가 생성됩니다. v2026.9.7 태그의 세션 수명 주기 문서는 이 규칙을 네 문장으로 설명합니다. “비활성 상태나 실제 경과 시간 때문에 대화가 교체되는 일은 없습니다. /new와 /reset은 명시적인 경계를 생성하며, 긴 기록은 계속해서 context compression으로 관리됩니다. 이전 타이머 설정은 무시됩니다. 기존 SessionResetPolicy 데이터 형식은 호환성을 위해 남아 있는 비활성 데이터이며 런타임 정책이 아닙니다.” 명시적으로 일시 중단하면 다음 수신 차례에 여전히 경계가 생성되고, 복구 과정에서는 완료된 경계를 다시 열지 않고 그대로 따릅니다. 리소스만 제거된 경우에도 대화를 재개할 수 있습니다. gateway의 세션이 “절대 만료되지 않는” 것처럼 보인다면 이제는 그렇게 설계된 것입니다. /new를 사용해 직접 교체하세요.⁴³

v0.21.4 기간부터 두 번째 hermes gateway run은 포트를 중복 점유하는 대신 기존 프로세스에 연결하거나 실행을 거부합니다. 원칙적으로 호스트와 운영체제 사용자마다 하나의 hermes serve와 하나의 hermes gateway run만 실행하며, 각각 모든 profile을 다중화합니다. 이미 실행 중인 다중화 프로세스가 제공하는 profile의 gateway를 시작하면 기존 프로세스에 연결한 후 종료 코드 0으로 끝납니다. 아직 해당 profile을 제공하지 않는 경우 Hermes는 profiles/를 다시 검색하도록 요청하고, profile이 제공되면 연결합니다. 해당 profile을 제공하도록 만들 수 없다면 두 번째 gateway를 조용히 시작하지 않고 명령 실행을 거부합니다. 이제 --replace는 어느 profile에서 시작했는지와 관계없이 해당 호스트 프로세스를 대상으로 하며, 소유 프로세스가 멈췄을 때 --force를 사용하면 확인 질문을 건너뜁니다. 독립 실행형 gateway는 계속 함께 실행할 수 있습니다. 실행 중인 gateway가 다른 profile의 독립 실행형 비다중화 gateway라면, 강제로 마이그레이션하기 전까지 해당 profile의 gateway도 이전과 같이 별도로 시작됩니다(#109417). 두 gateway가 동시에 시작되면 호스트 잠금 획득에 실패한 쪽은 종료 코드 75로 끝나며, Hermes가 생성하는 모든 감독 프로세스는 이를 재시도합니다. 그때는 승리한 프로세스의 레코드가 이미 존재하므로, 재시도 과정에서 앞선 규칙에 따라 연결하거나 실행을 거부합니다. 잠금과 랑데부 레코드는 $HERMES_GATEWAY_LOCK_DIR 아래에 저장됩니다. 이 변수가 없으면 $XDG_STATE_HOME/hermes/gateway-locks 아래에 저장되며, 기본 경로는 ~/.local/state/hermes/gateway-locks입니다. 범위는 운영체제 사용자 단위입니다. 레코드에 기록된 프로세스 아이디의 프로세스가 종료되었거나 다른 프로세스에서 재사용된 경우, 해당 레코드는 오래된 것으로 간주하여 무시합니다. 따라서 gateway가 충돌해도 다음 시작을 막지 않습니다. Desktop 앱에도 같은 규칙이 적용되며, 두 번째 프로세스를 생성하는 대신 실행 중인 호스트 백엔드에 연결합니다.⁵¹

v0.21.5부터 다중화는 더 이상 선택 사항이 아닙니다. gateway.multiplex_profiles에 허용되는 값은 true 하나뿐입니다. 키가 설정되지 않으면 활성화된 것으로 해석하고 기본 profile의 config.yaml에 기록합니다. false를 명시한 경우에는 그 자리에서 true로 다시 쓰며, 해당 gateway를 시작할 때 한 번만 테두리 알림을 표시하고 다음 hermes update 요약에서도 다시 알립니다. 기존의 비활성화 옵션은 2가지 제어 방식으로 대체되었습니다. 다른 사용자의 봇은 중지하지 않고 profile 하나만 오프라인으로 전환하려면 hermes -p <name> gateway stop을 실행하세요. 호스트는 해당 profile을 대기 상태로 전환하고 profiles/<name>/gateway.parked 표시 파일을 생성합니다. hermes -p <name> gateway start를 실행하면 대기 상태가 해제됩니다. dashboard와 Desktop의 중지 및 시작 버튼도 같은 방식으로 작동합니다. 여전히 자체 gateway가 필요한 명명된 profile은 자체 config.yaml에 gateway.standalone: true를 설정합니다. 호스트는 해당 profile을 제공하지 않으며, stop과 start는 profile 자체 프로세스에 적용됩니다. 문서에서는 이 키를 지원되는 토폴로지가 아니라 “임시 호환성 보조 장치”라고 부르며, 기본 profile에서 설정하면 경고와 함께 무시됩니다. 운영체제 사용자가 서로 다르거나 HERMES_HOME이 기본 홈의 profiles/ 외부에 있는 경우에는 여전히 --force가 필요합니다.⁵³

사용자 권한 부여 및 페어링

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로 승인합니다. 이후부터 해당 사용자는 권한이 부여된 상태로 유지됩니다.⁶

unauthorized_dm_behavior는 페어링 전 모르는 사람이 보낸 다이렉트 메시지를 어떻게 처리할지 결정합니다. pair는 다이렉트 메시지로 페어링 코드를 보내고, ignore는 아무 응답 없이 메시지를 버립니다. v0.21.4 기간에 추가된 decline은 정중한 거절 메시지를 한 번 보낸 뒤 해당 발신자에게 24시간 동안 응답하지 않습니다(#88028). 거절 응답은 별칭을 포함하여 플랫폼 및 발신자별로 중복 제거되며, 문구는 전역 키인 unauthorized_dm_decline_message에서 가져옵니다. 값이 비어 있으면 다음과 같은 내장 응답을 사용합니다. “안녕하세요! 저는 개인 비서이므로 소유자와만 대화할 수 있습니다. 직접 도와드리지 못해 죄송합니다!” 이 동작은 전역으로 설정하거나 설정 마법사가 기록하는 플랫폼별 설정으로 지정할 수 있습니다.

# ~/.hermes/config.yaml
unauthorized_dm_behavior: decline      # global; gateway.unauthorized_dm_behavior also works
unauthorized_dm_decline_message: ""    # empty = built-in reply
platforms:
  telegram:
    unauthorized_dm_behavior: pair     # per-platform value always wins

아무 값도 설정하지 않으면 실질적인 기본값은 허용 목록에 따라 달라집니다. 허용 목록이 없으면 pair가 적용됩니다. GATEWAY_ALLOWED_USERS나 플랫폼별 허용 사용자, 그룹 허용 사용자 또는 그룹 허용 채팅 변수 중 하나라도 설정되면 ignore로 바뀝니다. 허용 목록은 의도적으로 제한된 gateway임을 나타내며, 알 수 없는 연락처에 코드를 보내는 것은 불필요한 알림을 유발하고 정보를 노출할 가능성도 있기 때문입니다(#9337). 전역 ignore 또는 decline은 이 규칙보다 우선하지만, 전역 pair는 기본값과 동일하게 해석되므로 우선할 수 없습니다. 허용 목록과 함께 페어링을 유지하려면 플랫폼별로 pair를 설정하세요. 플랫폼 어댑터 자체의 dm_policy가 설정되어 있다면 허용 목록 규칙보다 먼저 확인합니다. 이메일은 받은 편지함 방식이므로 자체 플랫폼별 키에서 명시적으로 활성화하지 않는 한 기본값이 ignore이며, 전역 값은 이메일에 적용되지 않습니다. 허용 목록 없이 플랫폼을 설정하면 hermes gateway setup에서 선택할 수 있는 응답 중 하나로 거절을 제공합니다.⁵¹

예약 작업 (Cron)

Hermes에는 셸 명령이 아닌 agent 작업을 job으로 실행하는 일급 cron 시스템이 있습니다. 예약된 각 job은 설정된 프롬프트와 선택적으로 연결된 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 job을 설정합니다. job은 JSON에 영구 저장되며 재시작 후에도 유지됩니다.³

v0.21.0에서는 예약된 job에 메모리와 판단 능력이 추가되었습니다. 다음 4가지 메커니즘은 모두 v2026.8.31 태그에서 확인되었습니다.³⁵³⁷

• 연속성. continuity=true는 job 자체의 가장 최근 출력을 실행할 때마다 주입하므로, 탐색 또는 모니터링 작업은 “지난번에 보고한 내용을 확인한 상태로 시작해 중복을 제거하고 중단한 지점부터 계속할 수 있습니다.” 주입되는 지침은 “이미 보고된 내용을 반복하지 마세요”이며, 첫 실행은 변경되지 않습니다. 내부적으로 이 플래그는 context_from의 예약된 self 항목으로 저장됩니다. hermes cron create ... --continuity와 hermes cron edit <job_id> --continuity / --no-continuity를 사용하여 전환할 수 있습니다.³⁷
• 영구 notepad. 모든 job에는 커서, 워터마크, 감시 목록을 저장할 수 있는 작은 KV 스크래치패드가 제공됩니다. 값당 16KB, job당 64KB로 제한되며, 실행할 때마다 프롬프트에 주입되므로 의도적으로 제한을 둔 것입니다. hermes cron notepad <job_id> set <key> <value>로 기록하며, 실행 중인 agent가 터미널 도구를 통해 이 명령을 호출합니다.³⁷
• 모니터 모드. job은 각 실행 주기가 시작될 때 먼저 실행되는 저비용 monitor_script/monitor_url 소스를 연결할 수 있습니다. 출력이 변경되지 않으면 정확한 바이트 단위로 비교하여 agent 실행 전체를 억제합니다. 즉, LLM 호출도 전달도 없이 no_change 실행으로 조용히 끝납니다. 변경이 감지되면 차이 블록을 주입하고 agent를 정상적으로 실행합니다. 모니터 스크립트가 안정적인 출력을 내보내도록 하세요. 그렇지 않으면 매 실행 주기가 변경으로 인식됩니다.³⁷
• job별 추론 강도와 Bot Chat 전달. --reasoning-effort는 job의 사고 수준을 (none부터 ultra까지) 고정하여 해당 job 실행 시 전역 및 모델별 설정을 재정의합니다. 또한 deliver=bot-chat은 출력을 profile의 표준 Bot Chat 세션에 실제 수신 메시지로 전달하므로, 사람이 채널을 읽는 데 그치지 않고 bot이 “조치가 필요한 모든 항목을 처리하고 채팅에서 응답합니다.”³⁷

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
hermes mcp login <name>       # Force re-auth for an OAuth server (--flow browser|device)
hermes mcp reauth [--all]     # Re-authenticate one OAuth server, or every one

또는 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 명명 규칙에 따라 모델에 노출됩니다. 모든 도구 이름에 서버 이름이 포함되므로, 두 서버에서 같은 이름의 도구를 제공해도 더 이상 충돌하지 않습니다. MCP 서버의 로그 알림도 agent.log에 표시됩니다.⁵⁶

v0.21.1에서는 MCP OAuth에 기기 코드 방식이 추가되었습니다. hermes mcp login <name>은 --flow {browser,device}를 지원합니다. browser는 기존 PKCE 방식이며, device는 헤드리스 또는 원격 시스템을 위한 RFC 8628 기기 코드 로그인입니다. 이 플래그는 서버의 oauth.flow 설정을 재정의합니다. 같은 버전에서 OAuth 세션 전체에 profile 소유권을 적용하고, 잘못된 OAuth 메타데이터 캐시 때문에 서버가 멈추지 않도록 이를 무시하며, 데스크톱 MCP OAuth를 클라이언트 로컬 콜백을 통해 중계합니다. 이제 -t/--toolsets는 설정된 MCP 서버 중 어떤 서버를 실행할지도 필터링하므로, 범위가 지정된 호출에서는 필요하지 않은 서버의 콜드 스타트를 건너뜁니다.⁴⁴

v0.21.0에서는 데스크톱의 MCP 화면이 명령 센터로 바뀌었습니다. 서버와 카탈로그가 하나의 페이지로 통합되고, 끌어다 놓는 “무엇이든 붙여넣기” 가져오기 기능과 도구 호출이 실패하기 전에 만료 예정 인증을 알려 주는 백그라운드 상태 점검 기능이 추가되었습니다. 또한 서버별 스키마 토큰 추정치와 30일 사용량을 보여 주는 전체 비용 및 사용량 오버레이와 명시적 확인을 거쳐 MCP 서버를 설치하는 hermes:// 딥 링크도 제공됩니다.³⁵

v0.21.4 버전에는 mcp.discovery_concurrency가 추가되었습니다. 기본값은 4이고 0은 무제한이며, #117373에서 도입되었습니다. 이 설정은 탐색 단계에서 동시에 연결하는 설정된 MCP 서버 수를 제한합니다. 모든 서버에는 여전히 연결하지만, 한꺼번에 연결되는 것만 방지합니다. 정수가 아니거나 음수인 값이 입력되면 경고를 기록하고 기본값을 사용합니다.⁵¹

서버로 사용 — Hermes 대화를 다른 agent에 노출합니다.

hermes mcp serve
hermes mcp serve -v    # Verbose

context 압축

Hermes는 긴 대화를 자동으로 압축하여 모델의 context window 안에 유지합니다. 압축 요약기는 별도의 LLM 호출이므로 원하는 provider나 endpoint를 지정할 수 있습니다.⁴ v0.20.6부터 보존할 뒷부분을 결정하는 정책의 기본값은 lean (compression.tail_mode: lean)이며, 해당 태그에서는 요약기의 모델, provider, endpoint 설정이 이전의 compression.summary_*가 아닌 auxiliary.compression.* 아래에 있습니다. 기존 키는 처음 불러올 때 자동으로 마이그레이션됩니다. 설정 버전은 17입니다.³⁰³¹

compression:
  enabled: true
  threshold: 0.50          # Compress at this % of context limit
  threshold_tokens: null   # Optional absolute token cap -- trigger fires at the lower of ratio vs cap
  target_ratio: 0.20       # Fraction of threshold to preserve as recent tail (legacy tail mode)
  tail_mode: lean          # Tail retention: "lean" (default) or "legacy"
  protect_last_n: 20       # Min recent messages to keep uncompressed
  protect_first_n: 3       # Non-system head messages pinned across compactions

auxiliary:
  compression:
    model: ""              # Empty = main chat model; e.g. "google/gemini-3-flash-preview"
    provider: "auto"       # "auto", "openrouter", "nous", "codex", "main", etc.
    base_url: null         # Custom OpenAI-compatible endpoint (overrides provider)

tail_mode가 결정하는 사항. legacy는 target_ratio 크기의 원문 뒷부분을 그대로 유지합니다. context window가 크거나 임계값을 높인 환경에서는 압축할 때마다 100~240K 토큰을 차지합니다. lean은 context window의 2.5%에 해당하는 원문 뒷부분만 유지하되, 최솟값은 10K, 최댓값은 25K로 제한합니다. 대신 압축된 영역의 식별자를 보존하는 상세 세션 로그, 기계적으로 추출한 앵커 인덱스(PR 번호, SHA, 경로, 오류 문자열이며 정규식으로 추출하고 절대 바꾸어 표현하지 않음), 원문 그대로 인용한 모든 실제 사용자 메시지, 요약으로 제거된 모든 내용에 agent가 다시 접근할 수 있도록 하는 session_search 복구 포인터를 요약에 담아 연속성을 유지합니다. 압축을 시도할 때마다 보조 요약기 호출은 한 번만 수행됩니다. 문서에 따르면 500K 토큰의 실제 세션에서 측정한 결과, 보존되는 토큰이 약 162K에서 약 49K로 줄었습니다. lean 뒷부분에 포함된 오래된 도구 결과는 복구 포인터가 있는 한 줄짜리 요약으로 축소되며, 알 수 없는 tail_mode 값은 lean으로 대체됩니다.³¹

provider 옵션:⁴³¹

요약 모델은 대화의 중간 부분 전체를 한 번의 호출로 받으므로, 최소한 기본 모델만큼 긴 context를 지원해야 합니다. 요약 모델의 context window가 더 작으면 호출이 실패하고 중간 대화 내용이 요약 없이 삭제됩니다.⁴³¹

예산 압박 경고

agent가 도구를 많이 호출하는 복잡한 작업을 수행하면 이를 인지하지 못한 채 반복 예산을 소진할 수 있습니다. v0.20.0부터 기본값은 이전의 90회에서 늘어난 500회입니다. 예산 압박 기능은 모델에 자동으로 경고합니다.⁴

스트림 제한 시간

LLM 스트리밍 연결에는 로컬 provider(localhost, LAN IP)에 맞춰 자동으로 조정되는 2가지 제한 시간 계층이 있습니다.⁴

로컬 LLM는 큰 context에서 첫 번째 토큰을 생성하기 전에 사전 채우기에 몇 분이 걸릴 수 있으므로, 로컬 endpoint의 소켓 읽기 제한 시간은 30분으로 연장됩니다.⁴

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

Hermes Agent를 로컬에서 관리할 수 있는 브라우저 기반 대시보드입니다. 설정 파일이나 터미널을 직접 다루지 않고도 설정을 구성하고, 세션을 모니터링하고, 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+)

이제 hermes plugins를 통해 context 관리를 교체 가능한 슬롯으로 사용할 수 있습니다. 필터링, 요약 또는 도메인별 context 주입 방식으로 매 차례 에이전트가 볼 내용을 제어하는 맞춤형 context engine을 적용할 수 있습니다.¹⁶ 이를 통해 context 전략이 핵심 에이전트 루프와 분리되므로 프로젝트별 또는 도메인별로 context를 맞춤 설정할 수 있습니다.

백업 및 복원 (v0.9.0+)

hermes backup은 설정, 세션, skill, 메모리 전체를 하나의 아카이브로 생성합니다. hermes import는 백업 아카이브에서 이를 복원합니다.¹⁶ 머신 간에 환경을 이전하거나, 대규모 변경 전에 스냅샷을 만들거나, 정상 작동이 확인된 설정을 팀원과 공유할 때 사용할 수 있습니다.

Termux 및 Android 지원 (v0.9.0+)

Hermes는 Termux를 통해 Android에서 네이티브로 실행됩니다. 조정된 설치 경로, 모바일 화면에 최적화된 TUI, 음성 백엔드 지원 및 /image 명령을 기기에서 사용할 수 있습니다.¹⁶

보안 강화 (v0.13.0+)

v0.13.0에서는 P0 보안 문제 8건을 해결하고 기본 설정 하나를 사용자에게 더 유리하게 변경했습니다.¹⁸ 이어서 v0.14.0에서는 P0 문제 12건과 P1 문제 50건을 추가로 해결했습니다. 여기에는 sudo 무차별 대입 및 sudo-stdin 강화, 위험한 명령 우회 문제 수정, 모델에 다시 주입하기 전 도구 오류 정리, 대시보드 플러그인 API 인증, skills-hub SSRF 대응 범위 확대, 설치 중 공급망 보안 권고 검사 등이 포함됩니다.¹⁹

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

v0.21.0에서는 네 번째 보안 강화가 추가됩니다. 보호되는 에이전트 지침 파일인 AGENTS.md, CLAUDE.md, SOUL.md, .cursorrules, skill 및 메모리 저장소에 쓰려면 이제 항상 승인이 필요하므로, 프롬프트 주입의 영향을 받은 에이전트가 자신의 상시 지침을 몰래 다시 작성할 수 없습니다. 이 보호 장치는 기본적으로 활성화되어 제공되며(security.protected_instruction_files: true, protected_instruction_extra_patterns에는 fnmatch 형식의 기본 파일명 확장 목록 사용), 소스에는 차단 대상이 되는 정확한 공격 경로가 “AGENTS.md / CLAUDE.md / SOUL.md를 수정하는 주입된 지침”이라고 명시되어 있습니다. 또한 지침 파일은 현재 작업 디렉터리 트리에서 불러오므로 “에이전트가 나중에 실행될 수 있는 위치에 있는 모든 AGENTS.md가 실제 공격 대상”이라고 설명합니다.³⁵³⁹ 같은 릴리스에서는 터미널 오류, .env 파일 읽기, checkpoint 및 ACP 로그 전반의 비밀 정보 유출 허점도 해결했습니다. 승인 시스템이 Windows의 파괴적인 명령과 경로를 인식하도록 개선했으며, 안정적인 TCC 서명 ID를 사용해 업데이트 후에도 macOS 권한 승인이 유지되도록 했습니다. 이 기능은 macOS 전용이며 openssl, security 및 codesign이 필요하고, 최초 한 번 hermes desktop --setup-tcc-identity를 실행해 설정합니다. 또한 업스트림 침해 사고가 발생한 후 Blender MCP 카탈로그 항목과 skill을 제거하고, 플러그인 설치 과정에 Tier-1 보안 검사를 추가했습니다.³⁵³⁹

실무자를 위한 아키텍처

이 섹션은 내부 작동 방식을 이해하여 디버깅하고, 확장하고, 성능을 분석하려는 사용자를 위한 내용입니다. 업스트림 아키텍처 문서를 종합했습니다.³

진입점 → 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”는 업스트림 저장소의 전체 도구 레지스트리 수로, Hermes가 모든 toolset에 걸쳐 소스 코드와 함께 제공하는 모든 도구를 포함합니다. 실제로 실행 중인 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()
    → agent.prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API call (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → loop
    → final response → display → save to SessionDB

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

프롬프트 구성 순서

프롬프트 스택에는 다음 항목이 포함됩니다.¹³

1. SOUL.md (에이전트 정체성, 사용할 수 없으면 내장 대체 항목)
2. 도구 인식 동작 지침
3. 메모리 및 사용자 컨텍스트(MEMORY.md, USER.md)
4. Skills 지침
5. 컨텍스트 파일(AGENTS.md, .cursorrules)
6. 타임스탬프
7. 플랫폼별 형식 지정 힌트
8. /personality와 같은 선택적 시스템 프롬프트 오버레이

SOUL.md는 토대이며, 나머지 모든 항목은 그 위에 구성됩니다.¹³

세션 저장소

FTS5 전문 검색을 지원하는 SQLite 기반 세션 저장소입니다. 세션에는 계보 추적(압축 전후의 부모 및 자식 관계), 플랫폼별 격리, 경합 처리가 적용된 원자적 쓰기 기능이 있습니다.³

v0.21.x 설치 환경에서 저장소에 문제가 발생한다면 v0.21.2 이상을 사용하세요. 이 버전에서는 v0.21.0 시기에 발생하던 state.db 취약성 문제를 해결했습니다. 두 번째 쓰기 작업이 서로의 잠금을 취소하거나, 정상 데이터베이스가 손상된 것으로 보고되거나, 잘못된 행 하나로 인해 sessions list 전체가 실패하는 문제 등이 여기에 포함됩니다. 또한 호스팅 룸 조정을 루트 저장소에서 전용 shared-state.db로 옮겨 profile gateway가 마스터 세션 저장소를 쓰기 가능 상태로 열지 않도록 했습니다. 이제 hermes doctor는 구조적 손상과 FTS 인덱스 손상을 구분해 표시하고, FTS가 손상되면 해당 턴을 실패시키는 대신 검색 기능만 제한합니다. 또한 hermes sessions recover --inspect-only는 오프라인에서 비파괴적으로 profile을 고정한 상태로 출력 데이터베이스를 만들지 않고 정식 테이블의 읽기 가능 여부를 보고합니다. 이 하위 명령은 해당 기간보다 먼저 도입되었지만 여기에는 문서화되지 않았습니다. v0.21.2의 새로운 기능을 참조하세요.⁴⁸ SQLite 저널 모드가 잘못 설정되어 저장소가 작동하지 않는 경우에는 v0.21.4 기간에 추가된 오프라인 변환기 hermes sessions set-journal-mode delete|wal을 사용하세요. 최상위 명령의 hermes sessions 행을 참조하세요.⁵¹

플러그인 시스템

검색 소스는 ~/.hermes/plugins/(사용자), .hermes/plugins/(프로젝트), pip 진입점의 3가지입니다. 플러그인은 컨텍스트 API을 통해 도구, 훅, CLI 명령을 등록합니다. 메모리 제공자는 plugins/memory/ 아래에 있는 특수한 플러그인 유형입니다.³ v0.21.2부터는 선별된 SHA 고정 플러그인 카탈로그에서 이름으로 플러그인을 찾아 설치할 수도 있으며, “선언적이며 공유 가능한 플러그인 모음”을 위한 hermes plugins pack도 제공됩니다. 하나의 hermes-pack.yaml이 플러그인 모음을 정확한 커밋 SHA에 고정하며, 팩을 설치하면 일반적인 고정 설치로 각각 확장되고 기능 동의는 플러그인별로 유지됩니다.⁴⁸

v0.21.4 기간에는 이 카탈로그가 CLI 화면에서 배포 가능한 결과물로 발전했습니다. 저장소의 plugin-catalog/ 디렉터리는 v2026.9.14의 항목 9개에서 v2026.9.21의 항목 228개로 늘어났습니다. 각 플러그인에는 검토를 거친 YAML 하나가 있으며 이름, 저장소, 관리자, 등급, 카테고리, 기능이 기록됩니다. 각 항목은 정확한 40자 커밋 SHA에 고정되고, 디렉터리에 존재한다는 사실 자체가 승인되었음을 의미합니다. 이 정보는 CLI에서 사용할 수 있도록 plugin-catalog.json으로 게시되며, 실시간으로 가져와 ~/.hermes/cache/ 아래에 캐시됩니다. 이제 문서 사이트는 동일한 데이터에서 플러그인별 페이지(/docs/plugins/<name>)와 작성자별 페이지(/docs/plugins/by/<slug>)를 생성합니다. 각 페이지는 브랜치의 최신 상태가 아닌 고정된 커밋에서 가져온 플러그인의 README를 렌더링하며, 원시 HTML을 제거하는 빌드 시점 허용 목록을 거칩니다. 추가 및 업데이트 정렬에는 커미터 날짜가 사용됩니다. v0.21.4 릴리스에서 언급한 커뮤니티 플러그인 10개는 모두 태그 시점의 카탈로그 항목이며, 실제 카탈로그 슬러그는 hermes-tailscale, hermes-ssh, shodan, hermes-terminal, hermes-rss(별도의 rss-reader도 있음), hermes-resetwatch, done-bell, kiwi, cognee, web-octen입니다. 이제 데스크톱의 Plugins 허브에서는 확인 대화 상자를 거쳐 플러그인을 제거할 수 있습니다. 카탈로그 플러그인은 plugins.manage remove를 사용하고, 독립 실행형 데스크톱 플러그인은 Electron 로더를 사용합니다.⁵¹

hermes plugins                       # Interactive enable/disable UI
hermes plugins browse                # List every curated plugin catalog entry (v0.21.2+)
hermes plugins search <query>        # Search the curated plugin catalog (v0.21.2+)
hermes plugins install <name|repo>   # Install from the curated catalog, a Git URL, or owner/repo
hermes plugins enable <name>
hermes plugins disable <name>
hermes plugins list
hermes plugins pack install <src>    # Shareable SHA-pinned plugin sets; also: pack export, pack show (v0.21.2+)

호환 기간(v0.21.1)은 이제 만료되었습니다. 외부 플러그인은 2026년 9월 14일까지 분해 이전의 가져오기 경로에서 이전해야 했습니다. 2026년 9월의 분해 작업(PR #102117)으로 플러그인이 흔히 가져오던 내부 요소의 위치가 변경되었습니다. 임시 COMPAT_MANIFEST.md 계층은 이동된 공개 이름 1,148개를 이전 모듈에서 다시 내보내고, 프로세스별로 각 이름에 대해 한 번씩 경고했습니다(HermesPluginCompatWarning). 제거는 예정대로 2026년 9월 14일에 적용되었습니다. 배포된 코드의 날짜 게이트(hermes_cli/plugin_compat.py의 COMPAT_REMOVAL_DATE)를 통해 적용되었으며 코드 되돌리기는 필요하지 않았습니다. 해당 날짜부터 영향을 받는 플러그인은 로드되지 않고 비활성화됩니다. CLI 배너, hermes doctor, hermes update에 빨간색 알림이 표시되고, 데스크톱에는 일회성 모달이 나타나며, hermes plugins list에는 비활성화 사유가 표시됩니다. 작성자는 여전히 hermes plugins compat <path>를 실행하여 이전 경로 -> 새 경로가 포함된 모든 file:line을 출력할 수 있으며, 남은 항목이 하나라도 있으면 종료 코드 1을 반환합니다. 기계 판독 가능한 출력이 필요하면 --json을 추가하세요. 유지 관리되지 않는 플러그인을 계속 사용해야 하는 사용자는 config.yaml에서 plugins.allow_deprecated_imports: true를 설정할 수 있습니다. 따옴표로 감싼 문자열이 아니라 리터럴 YAML 불리언이어야 합니다. 이전 경로를 삭제하는 되돌리기가 아직 반영되지 않았기 때문에 이 방법은 여전히 작동합니다. 매니페스트와 심은 v2026.9.14, v2026.9.21, v2026.9.24에 존재하며 9월 24일 기준 main에도 있습니다. v0.21.4 기간에는 플러그인 검사를 캐시하고 Windows 경로를 정규화하기 위해서만 호환 모듈을 수정했으며, v0.21.5 기간에는 hermes_cli/plugin_compat.py를 변경하지 않고 삭제된 Hindsight 모듈의 매니페스트 항목만 제거했습니다. 해당 되돌리기가 반영되어 이전 경로 자체가 사라지는 즉시 이 우회 방법은 작동하지 않습니다. 공개된 최상위 이름만 지원되었으며, 비공개 이름과 테스트용 몽키패치 연결부는 애초에 지원 대상이 아니었고 복원되지 않습니다.⁴²⁵³

설계 원칙

업스트림 아키텍처 페이지의 내용입니다.³

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개 소스 디렉터리의 skill, 기본 모델, 사용자 지정 제공자, MCP 서버, 메시징 플랫폼 토큰 및 허용 목록(Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), 에이전트 기본값(추론 강도, 압축, 사람처럼 보이기 위한 지연 시간, 시간대, 샌드박스), 세션 초기화 정책(현재는 비활성 상태: v0.21.1부터 타이머가 대화를 전환하지 않음⁴³), 승인 규칙, TTS 설정, 브라우저 설정, 도구 설정, 실행 제한 시간, 명령어 허용 목록, gateway 설정, 3개 소스의 API 키.⁶

수동 검토를 위해 보관되는 항목: cron 작업, 플러그인, 훅 및 웹훅, 메모리 백엔드(QMD), skills 레지스트리 설정, 사용자 인터페이스 및 정체성, 로깅, 다중 에이전트 설정, 채널 바인딩, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md.⁶

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

문제 해결

“No inference provider configured. Run ‘hermes model’ to choose a provider and 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 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

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

서버에서 도구 호출이 활성화되지 않았거나, 해당 서버의 구현 방식으로는 모델이 도구 호출을 지원하지 않는 상태입니다.²

응답이 문장 중간에서 잘림

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

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 가상 머신을 가리킵니다. 해결 방법은 2가지입니다.²

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

[wsl2]
networkingMode=mirrored

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

호스트 아이피 대체 방법(이전 Windows): WSL2 내부에서 Windows 호스트 아이피를 확인하고 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”를 활성화하세요.²

반복 예산이 agent.max_turns를 무시함

config.yaml에는 agent.max_turns: 500으로 설정되어 있지만 활동 줄에 N/90 또는 이전의 다른 상한이 표시된다면, ~/.hermes/.env에 남은 오래된 HERMES_MAX_ITERATIONS 줄이 원인일 가능성이 큽니다. 이전 설정 마법사는 예산을 두 저장소에 모두 기록했으며, 시작 브리지가 앞선 설정 구문 분석 오류로 중단되면 .env에 남은 값이 아무런 알림 없이 우선 적용됩니다. v0.21.1부터 hermes doctor는 값을 가리는 이 설정 쌍을 감지하고, hermes doctor --fix는 .env의 해당 줄을 삭제하여 config.yaml만 기준으로 사용되도록 합니다.⁴¹

모든 항목은 어디에 있습니까?

이때는 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에서 개발한 오픈 소스 agent framework로, Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Hugging Face, Google 또는 직접 호스팅하는 endpoint 등 OpenAI 호환 provider라면 어디서나 사용할 수 있습니다.¹² 또한 Hermes는 Telegram/Discord/Slack/WhatsApp/Signal용 messaging gateway를 제공하지만, Claude Code에는 이 기능이 없습니다.

Anthropic API 키로 Hermes를 사용할 수 있습니까?

예. 다음 3가지 방법이 있습니다.²

1. ~/.hermes/.env에 ANTHROPIC_API_KEY를 설정하고 hermes chat --provider anthropic --model claude-sonnet-4-6을 실행합니다
2. hermes model을 실행하고 Anthropic를 선택합니다. 사용할 수 있는 경우 Hermes는 Claude Code의 credential store를 사용합니다
3. 수동 ANTHROPIC_TOKEN(setup-token 또는 OAuth token)을 대체 수단으로 설정합니다

같은 컴퓨터에서 이미 Claude Code를 사용하고 있다면 2번이 권장됩니다. 갱신 가능한 Claude credential을 계속 갱신할 수 있기 때문입니다.

대화를 잃지 않고 provider를 전환하려면 어떻게 해야 합니까?

세션 안에서 /model provider:model을 사용하세요. 대화 기록, memory, skill이 모두 그대로 유지됩니다.⁹

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

Anthropic를 설정했지만 vision/web/compression이 작동하지 않습니다

현재 빌드에서는 대부분 예전과 같은 방식으로 이 문제가 발생하지 않습니다. 기본적으로 (auxiliary.*.provider: "auto") vision, 승인 분류, compression, 세션 제목을 비롯한 모든 auxiliary 작업은 기본 chat model에서 실행되므로, Anthropic만 설정한 환경에서도 이미 보유한 OAuth로 해당 작업을 처리합니다. 이전 기본 동작(Gemini Flash via OpenRouter → Nous → Codex 자동 감지, 아무것도 설정되지 않으면 별도 알림 없이 기능 저하)은 사라졌습니다. 이제 “auto는 모든 작업에 기본 모델을 사용하며, config.yaml의 작업별 재정의 설정은 계속 우선 적용됩니다.”³⁴

auxiliary 작업이 여전히 실패한다면 설정하지 않은 provider를 가리키는 명시적인 작업별 재정의 설정(config.yaml의 auxiliary.<task>.provider / .model)이나 오래된 legacy 키가 있는지 확인하세요. tag v2026.8.31부터 compression summarizer는 다른 모든 auxiliary slot과 동일하게 auxiliary.compression.provider로 설정하며, legacy compression.summary_* 키는 해당 위치로 자동 이전됩니다(config version 17).³¹ Web 추출은 더 이상 LLM 작업이 아니며(“LLM가 관여하지 않음”), 따라서 현재 빌드에서 발생하는 web 요약 실패는 auxiliary model 문제가 아닙니다.³⁴ 작업에서 기본 provider를 사용하도록 명시적으로 고정하려면 다음과 같이 설정하세요.

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

SOUL.md와 AGENTS.md의 차이는 무엇입니까?

SOUL.md는 agent의 정체성, 즉 어조, 스타일, 기본 커뮤니케이션 방식을 정의합니다. ~/.hermes/SOUL.md에 있으며 어디서나 적용됩니다. AGENTS.md는 프로젝트별 architecture, convention, command, path를 정의하며 프로젝트 directory에 있습니다.¹³ 어디서나 적용되어야 한다면 SOUL.md에, 특정 프로젝트에 속하는 내용이라면 AGENTS.md에 작성하세요.

여러 Hermes instance를 나란히 실행하려면 어떻게 해야 합니까?

profile을 사용하세요. 각 profile에는 별도의 HERMES_HOME, config, memory, session, 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을 지원합니까?

예. custom endpoint 경로를 통해 지원합니다. Hermes는 Ollama, vLLM, SGLang, llama.cpp/llama-server, LM Studio, LocalAI, Jan 또는 직접 구축한 서버 등 OpenAI 호환 서버라면 어디서나 사용할 수 있습니다.² 서버별 설정은 Custom 및 Self-Hosted Endpoints를 참고하세요.

시작 banner에 표시되는 tool 수가 가이드에서 설명한 Hermes의 tool 수보다 적은 이유는 무엇입니까?

가이드에 나온 47개 tool / 20개 toolset은 upstream architecture registry를 기준으로 하며, Hermes가 모든 toolset에 걸쳐 source code로 제공하는 전체 tool 수입니다. 실행 중인 설치 환경에서는 banner에 더 적은 수가 표시됩니다. 이 가이드에서 사용한 reference 설치 환경에는 28개 tool이 표시됩니다. Hermes가 시작할 때 기본 toolset만 활성화하기 때문입니다. 많은 toolset은 선택적으로 활성화해야 합니다. messaging gateway adapter, browser 자동화, 더 무거운 scraping stack, 여러 전문 integration은 로드되기 전에 ~/.hermes/config.yaml의 toolsets: 아래에 명시적으로 추가해야 합니다. registry 총계 = “활성화할 수 있는 전체 항목”입니다. banner 총계 = “현재 profile에서 실제로 로드한 항목”입니다. 활성 상태인 toolset과 사용할 수 있지만 비활성화된 toolset을 확인하려면 hermes tools --list를 사용하세요. runtime에서 개별 toolset을 전환하려면 /tools enable <name>과 /tools disable <name>을 사용하세요. 비활성화하면 agent가 변경된 구성으로 tool manifest를 다시 만들 수 있도록 session이 재설정됩니다.

기본 provider가 실패하면 Hermes는 model fallback을 어떻게 처리합니까?

config.yaml에 fallback_model block을 설정하세요.²

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

기본 provider가 실패하면(rate limit, server error, auth failure) Hermes는 대화 기록을 잃지 않고 세션 도중 fallback으로 전환합니다. 세션마다 최대 1번만 실행됩니다.

agent가 시간이 지나면서 자신의 skill을 개선할 수 있습니까?

예. 이것이 Hermes Agent의 “self-improving” 기능입니다. agent는 skill_manage tool을 통해 skill을 생성, 업데이트, 삭제할 수 있습니다. 단순하지 않은 workflow를 파악하면 나중에 다시 사용할 수 있도록 그 접근 방식을 skill로 저장합니다.¹¹ agent는 복잡한 작업(tool call 5회 이상)을 마친 후, 오류가 발생한 뒤 올바른 해결 경로를 찾았을 때, 사용자가 접근 방식을 수정해 주었을 때 또는 단순하지 않은 workflow를 발견했을 때 skill을 생성합니다.

IDE integration이 있습니까?

예. Hermes는 VS Code, Zed, JetBrains용 ACP (Agent Client Protocol) 서버로 실행할 수 있습니다.⁶

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

변경 기록