모델 구성

Hermes에는 두 종류의 모델 슬롯이 있습니다.

• 메인 모델 - 에이전트의 중심 사고 모델입니다. 모든 사용자 메시지, 도구 호출 루프, 스트리밍 응답이 이 모델을 거칩니다.
• 보조 모델 - 작은 부가 작업을 맡는 모델입니다. 컨텍스트 압축, 비전(이미지 분석), 웹 페이지 요약, 세션 검색, 승인 점수 계산, MCP 도구 라우팅, 세션 제목 생성, 스킬 검색 등을 처리합니다. 각 작업에는 별도 슬롯이 있으며 독립적으로 재정의할 수 있습니다.

이 페이지는 대시보드에서 두 모델 슬롯을 설정하는 방법을 설명합니다. 구성 파일이나 CLI를 선호한다면 아래의 대체 방법을 참고하세요.

모델 페이지

대시보드를 열고 사이드바에서 Models를 클릭합니다. 화면은 크게 두 영역으로 나뉩니다.

1. Model Settings - 상단 패널입니다. 각 슬롯에 사용할 모델을 지정합니다.
2. Usage analytics - 선택한 기간에 세션에서 사용한 모든 모델을 토큰 수, 비용, 기능 배지와 함께 보여주는 순위 카드입니다.

상단 카드가 Model Settings 패널입니다. 메인 행은 새 세션에서 에이전트가 사용할 모델을 보여줍니다. Change를 누르면 모델 선택기가 열립니다.

주요 모델 설정

메인 모델 행에서 Change를 클릭합니다.

선택기는 두 열로 구성됩니다.

• 왼쪽 - 인증된 제공자 목록입니다. API 키가 설정되어 있거나, OAuth 인증이 완료되었거나, 커스텀 엔드포인트로 정의된 제공자만 표시됩니다. 제공자가 보이지 않으면 Keys로 이동해 자격 증명을 추가하세요.
• 오른쪽 - 선택한 제공자의 선별된 모델 목록입니다. 원시 /models 응답 전체가 아니라 Hermes가 에이전트 용도에 적합하다고 추천하는 모델만 보여줍니다. 예를 들어 OpenRouter에는 TTS, 이미지 생성, reranker까지 포함해 400개 이상의 모델이 있지만, 여기서는 에이전트에 적합한 모델을 중심으로 보여줍니다.

필터 상자에 입력하여 제공자 이름, 슬러그, 또는 모델 ID로 축소하세요.

모델을 선택하고 Switch를 누르면 Hermes가 ~/.hermes/config.yaml의 model 섹션을 갱신합니다. 이 변경은 새 세션에만 적용됩니다. 이미 열려 있는 채팅 탭은 시작할 때 사용한 모델을 유지합니다. 현재 채팅에서 즉시 바꾸려면 채팅 안에서 /model 슬래시 명령을 사용하세요.

보조 모델 설정

Show auxiliary를 클릭하면 8개의 보조 작업 슬롯이 표시됩니다.

모든 보조 작업의 기본값은 auto입니다. 이는 해당 작업에도 메인 모델을 사용한다는 뜻입니다. 부가 작업에는 더 저렴하거나 빠른 모델을 쓰고 싶을 때 특정 슬롯만 따로 지정하면 됩니다.

일반적인 재정의 패턴

작업	권장 재정의
제목 생성	거의 항상 재정의하는 것이 좋습니다. 저렴한 flash 모델도 세션 제목은 충분히 잘 만듭니다. 기본값으로 OpenRouter의 google/gemini-3-flash-preview 같은 모델을 고려하세요.
비전	메인 모델이 Kimi, DeepSeek처럼 비전을 지원하지 않는 코딩 모델일 때 지정합니다. google/gemini-2.5-flash 또는 gpt-4o-mini가 좋은 후보입니다.
압축	Opus나 M2.7 같은 비싼 모델로 컨텍스트 요약까지 처리하면 비용이 커집니다. 빠른 채팅 모델로도 충분한 경우가 많습니다.
세션 검색	쿼리를 여러 개로 fan-out합니다. 기본 max_concurrency는 3입니다. 저렴한 모델을 쓰면 비용을 예측하기 쉽습니다.
승인 판단	approval_mode: smart에서 fast/cheap 모델(haiku, flash, gpt-5-mini 등)이 명령을 자동 승인해도 안전한지 판단합니다. 이 슬롯에 비싼 모델을 쓰는 것은 대부분 낭비입니다.
웹 추출	web_extract를 많이 쓴다면 지정하세요. 요약 작업이므로 압축과 같은 비용 논리가 적용됩니다.
스킬 허브	hermes skills search가 사용합니다. 보통은 auto로 충분합니다.
MCP	MCP 도구 라우팅에 사용합니다. 보통은 auto로 충분합니다.

작업별 재정의

각 보조 행에서 Change를 클릭하면 같은 모델 선택기가 열립니다. 제공자와 모델을 선택한 뒤 Switch를 누르면 auto (use main model) 대신 provider · model 형태로 표시됩니다.

자동에 모두 재설정

모든 보조 슬롯을 기본값으로 되돌리려면 보조 섹션 상단의 Reset all to auto를 클릭합니다. 그러면 각 작업이 다시 메인 모델을 사용합니다.

"사용" 단축

페이지의 모든 모델 카드에는 Use as 드롭다운이 있습니다. 사용량 분석에서 눈에 띄는 모델을 선택한 뒤, 메인 슬롯이나 특정 보조 작업에 한 번에 할당할 수 있는 빠른 경로입니다.

드롭다운이 있습니다:

• 메인 모델 - 메인 행에서 Change를 클릭한 것과 같습니다.
• 모든 보조 작업 - 이 모델을 8개 보조 슬롯 모두에 할당합니다. 저렴한 flash 모델로 부가 작업을 전부 처리하고 싶을 때 유용합니다.
• 개별 작업 옵션 - Vision, Web Extract, Compression 등 각 작업별로 할당합니다. 현재 사용 중인 모델은 current로 표시됩니다.

모델 카드에는 현재 할당 상태에 따라 main 또는 aux · <task> 배지가 붙습니다. 어떤 모델이 어느 슬롯에 연결되어 있는지 한눈에 확인할 수 있습니다.

config.yaml로 작성된 내용

대시보드에서 저장하면 Hermes는 ~/.hermes/config.yaml에 다음과 같은 값을 씁니다.

주요 모델:

model:
  provider: openrouter
  default: anthropic/claude-opus-4.7
  base_url: ''        # cleared on provider switch
  api_mode: chat_completions

보조 재정의(예: 비전에 gemini-flash 사용):

auxiliary:
  vision:
    provider: openrouter
    model: google/gemini-2.5-flash
    base_url: ''
    api_key: ''
    timeout: 120
    extra_body: {}
    download_timeout: 30

보조 작업을 auto로 되돌린 경우:

auxiliary:
  compression:
    provider: auto
    model: ''
    base_url: ''
    #... other fields unchanged

provider: auto와 model: ''는 Hermes가 해당 작업에 메인 모델을 사용한다는 뜻입니다.

언제 적용되나요?

• CLI(hermes chat): 다음 hermes chat 실행부터 적용됩니다.
• Gateway(Telegram, Discord, Slack 등): 다음 새 세션부터 적용됩니다. 기존 세션은 사용 중인 모델을 유지합니다. 모든 세션이 새 설정을 쓰게 하려면 게이트웨이를 다시 시작하세요(hermes gateway restart).
• Dashboard 채팅 탭(/chat): 다음 새 PTY부터 적용됩니다. 이미 열린 채팅은 기존 모델을 유지합니다. 현재 채팅에서 바꾸려면 내부에서 /model을 사용하세요.

실행 중인 세션에는 프롬프트 캐시가 있으므로 설정 파일 변경만으로 모델을 즉시 바꾸지 않습니다. 이는 의도된 동작입니다. 세션 중 메인 모델을 바꾸면 시스템 프롬프트의 모델별 내용 때문에 캐시를 재설정해야 하므로, 현재 채팅에서는 명시적인 /model 슬래시 명령을 사용하도록 분리되어 있습니다.

문제 해결

피커에 "인증된 제공자 없음"이 표시됩니다

Hermes는 인증 정보가 확인된 provider만 표시합니다. sidebar의 Keys를 열어 API key, 성공한 OAuth, 또는 custom endpoint URL 중 하나가 있는지 확인하세요. provider가 보이지 않는다면 hermes setup을 실행해 연결하거나 Keys에서 env var를 추가하세요.

메인 모델은 실행 채팅에서 변경하지 않았습니다

Dashboard의 model picker는 config.yaml을 쓰고, 새 session이 그 값을 읽습니다. 이미 열려 있는 chat은 살아 있는 agent process이므로 시작할 때 사용한 모델을 계속 유지합니다. 특정 session만 즉시 바꾸려면 /model <name>을 사용하세요.

보조 override "didn't take effect"

확인할 세 가지:

1. 새 session을 시작했나요? 기존 chat은 설정을 다시 읽지 않습니다.
2. provider가 auto가 아닌 값으로 설정되어 있나요? 필드가 auto라면 task는 여전히 main model을 사용합니다. Change를 눌러 실제 provider를 선택하세요.
3. 해당 provider가 인증되어 있나요? 예를 들어 task에 minimax를 지정했지만 MiniMax API key가 없다면, task는 openrouter로 fallback하고 agent.log에 warning을 남깁니다.

나는 모델을 선택했지만 Hermes는 나를 위해 제공자를 전환

OpenRouter 같은 aggregator에서는 bare model name이 먼저 aggregator 내부에서 해석됩니다. 그래서 claude-sonnet-4는 OpenRouter에서 anthropic/claude-sonnet-4.6로 해석될 수 있습니다. 반면 native auth에서 claude-sonnet-4를 입력하면 claude-sonnet-4-6로 유지됩니다. 예상치 못한 provider 전환이 보이면 현재 provider가 맞는지 확인하세요. picker는 dialog 상단에 항상 현재 main provider를 표시합니다.

대체 방법

CLI slash 명령

어떤 hermes chat 세션에서:

/model gpt-5.4 --provider openrouter             # session-only
/model gpt-5.4 --provider openrouter --global    # also persists to config.yaml

--global은 dashboard의 Change 버튼과 동일하게 설정을 저장하며, 실행 중인 session도 in-place로 전환합니다.

커스텀 alias

자주 쓰는 모델에 대한 짧은 이름을 직접 정의한 뒤, CLI 또는 messaging platform에서 /model <alias>로 사용할 수 있습니다.

# ~/.hermes/config.yaml
model_aliases:
  fav:
    model: claude-sonnet-4.6
    provider: anthropic
  grok:
    model: grok-4
    provider: x-ai

또는 셸에서 (짧은 모양, provider/model):

hermes config set model.aliases.fav anthropic/claude-opus-4.6
hermes config set model.aliases.grok x-ai/grok-4

그다음 chat에서 /model fav 또는 /model grok를 사용하세요. 사용자 alias는 built-in 짧은 이름(sonnet, kimi, opus 등)보다 우선합니다. 전체 참조는 Custom model aliases를 참고하세요.

hermes model 서브커맨드

hermes model            # Interactive provider + model picker (the canonical way to switch defaults)

hermes model은 provider와 인증 방식(OAuth flow는 browser를 열고, API-key provider는 key 입력을 요청함)을 선택한 뒤, 해당 provider의 curated catalog에서 특정 model을 고르게 합니다. 선택 결과는 ~/.hermes/config.yaml의 model.provider 및 model.model에 기록됩니다.

picker를 실행하지 않고 provider/model 목록을 보려면 dashboard 또는 아래 REST endpoint를 사용하세요. CLI가 실제로 어떤 값을 사용할지 확인하려면 hermes config get model과 hermes status를 실행하세요.

config 편집

~/.hermes/config.yaml을 직접 편집해도 됩니다. 전체 schema는 Configuration reference를 참고하세요.

REST API

dashboard는 3개의 endpoint를 사용합니다. script에서도 유용합니다.

# List authenticated providers + 선별된 model lists
curl -H "X-Hermes-Session-Token: $TOKEN" http://localhost:PORT/api/model/options

# Read current main + auxiliary assignments
curl -H "X-Hermes-Session-Token: $TOKEN" http://localhost:PORT/api/model/auxiliary

# Set the main model
curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \
  -d '{"scope":"main","provider":"openrouter","model":"anthropic/claude-opus-4.7"}' \
  http://localhost:PORT/api/model/set

# Override a single auxiliary task
curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \
  -d '{"scope":"auxiliary","task":"vision","provider":"openrouter","model":"google/gemini-2.5-flash"}' \
  http://localhost:PORT/api/model/set

# Assign one model to every auxiliary task
curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \
  -d '{"scope":"auxiliary","task":"","provider":"openrouter","model":"google/gemini-2.5-flash"}' \
  http://localhost:PORT/api/model/set

# Reset all auxiliary tasks to auto
curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \
  -d '{"scope":"auxiliary","task":"__reset__","provider":"","model":""}' \
  http://localhost:PORT/api/model/set

세션 토큰은 시작 시 대시보드 HTML에 주입되며 서버가 재시작될 때마다 회전합니다. 실행 중인 대시보드를 대상으로 스크립팅하려면 브라우저 DevTools에서 window.__HERMES_SESSION_TOKEN__ 값을 가져오세요.