configuring-models

anchor alias

모델 구성

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

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

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

모델 페이지

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

Model Settings - 상단 패널입니다. 각 슬롯에 사용할 모델을 지정합니다.
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개의 보조 작업 슬롯이 표시됩니다.

Auxiliary panel 확장

모든 보조 작업의 기본값은 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 드롭다운이 있습니다. 사용량 분석에서 눈에 띄는 모델을 선택한 뒤, 메인 슬롯이나 특정 보조 작업에 한 번에 할당할 수 있는 빠른 경로입니다.

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는 작업 증명이있는 경우에만 제공 업체를 나열합니다. 기타 Keys in the sidebar — 당신은 중 하나를 볼 수 있어야합니다: API 키, 성공적인 OAuth, 또는 사용자 정의 엔드 포인트 URL. 만약 공급자가 없다면, hermes setup를 철사로 실행하거나 Keys로 이동하고 env var를 추가하십시오.

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

견적 요청 대시보드는 config.yaml를 작성하여 새로운 세션을 읽습니다. 현재 오픈 채팅은 라이브 에이전트 프로세스입니다 — 그것은 어떤 모델을 유지 그것은 함께 spawned. /model <name> 를 사용하여 특정 세션을 단축합니다.

보조 override "didn't take effect"

확인하는 3 가지:

새로운 세션을 시작합니까? 기존 채팅은 다시 읽을 수 없습니다.
Is provider는 auto보다 다른 것을 설정합니까? 필드가 auto를 보여 주는 경우, 작업은 여전히 메인 모델을 사용합니다. 이름 * Change 및 실제 공급자를 선택하십시오.
**이 공급자가 인증되었습니까? ** 할당된 경우 minimax 작업에하지만 MiniMax API 키가 없습니다. 이 작업은 openrouter로 다시 떨어지며 agent.log에서 경고를 기록합니다.

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

OpenRouter (또는 어떤 집계)에서, 베어 모델 이름은 해결 *within * 집계 먼저. 그래서 claude-sonnet-4는 OpenRouter에 anthropic/claude-sonnet-4.6가 됩니다. 그러나 입력하면 claude-sonnet-4 네이티브 auth, 그것은 claude-sonnet-4-6로 유지됩니다. 예기치 않은 공급자 스위치를 볼 경우, 현재 공급자가 예상되는 것을 확인하십시오. - Picker는 항상 대화 상자의 상단에 현재 메인을 보여줍니다.

대체 방법

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`는 대쉬보드의 **Change** 버튼이 동일하며, 실행 세션을 in-place로 전환합니다.

### 사용자 정의 \{#when-does-it-take-effect}

자주 도달하는 모델에 대한 자신의 짧은 이름을 정의, 다음 사용 `/model &lt;alias&gt;` CLI 또는 어떤 메시징 플랫폼:

```yaml
# ~/.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

다음 /model fav 또는 /model grok 채팅. 사용자 별칭 그림자 내장 짧은 이름 (sonnet, kimi, opus 등). 전체 참조에 대한 Custom model aliases를 참조하세요.

`hermes model` 서브컴맨드

hermes model            # Interactive provider + model picker (the canonical way to switch defaults)
``hermes model`는 공급자, 인증 (OAuth flows open a browser; API-key Provider prompt for key)를 선택하여 해당 공급자의 큐레이터 카탈로그에서 특정 모델을 선택하십시오. 선택은 `model.provider` 및 `model.model`로 작성됩니다. `~/.hermes/config.yaml`.

선택기를 실행하지 않고 제공 업체 / 모델을 나열하려면 아래 대시보드 또는 REST 엔드포인트를 사용하십시오. CLI가 실제로 사용할지 검사하려면: `hermes config get model` 및 `hermes status`.

### config 편집 \{#direct-config-edit}

`~/.hermes/config.yaml`를 편집하고 모든 것을 읽습니다. 전체 스키마에 대한 [Configuration reference](./configuration.md)를 참조하십시오.

### REST API를 \{#rest-api}

대시보드는 3개의 엔드포인트를 사용합니다. 스크립트에 대한 유용한:

```bash
# 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 '&#123;"scope":"main","provider":"openrouter","model":"anthropic/claude-opus-4.7"&#125;' \
  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 '&#123;"scope":"auxiliary","task":"vision","provider":"openrouter","model":"google/gemini-2.5-flash"&#125;' \
  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 '&#123;"scope":"auxiliary","task":"","provider":"openrouter","model":"google/gemini-2.5-flash"&#125;' \
  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 '&#123;"scope":"auxiliary","task":"__reset__","provider":"","model":""&#125;' \
  http://localhost:PORT/api/model/set

세션 토큰은 시작시 대시보드 HTML로 주입되며 각 서버 재시작에 회전합니다. 브라우저 devtools (window....``)에서 실행 대시보드에 대해 스크립팅하면 됩니다.

anchor alias​

모델 구성

모델 페이지​

주요 모델 설정​

보조 모델 설정​

일반적인 재정의 패턴​

작업별 재정의​

자동에 모두 재설정​

"사용" 단축​

config.yaml로 작성된 내용​

언제 적용되나요?​

문제 해결​

피커의 "정확한 공급자"​

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

보조 override "didn't take effect"​

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

대체 방법​

CLI slash 명령​

hermes model 서브컴맨드​