대체 제공자

Hermes Agent는 제공자 문제로 세션이 끊기지 않도록 세 가지 복원력 계층을 제공합니다.

자격 증명 풀 - 같은 제공자의 여러 API 키를 순환 사용합니다. 가장 먼저 시도됩니다.
기본 모델 페일오버 - 메인 모델이 실패하면 다른 provider:model 조합으로 자동 전환합니다.
보조 작업 페일오버 - 비전, 압축, 웹 추출 같은 부가 작업은 독립적인 제공자 해석 체인을 사용합니다.

자격 증명 풀은 같은 제공자 안에서 키를 교체하는 기능입니다. 예를 들어 OpenRouter 키가 여러 개 있을 때 사용합니다. 이 문서는 제공자를 가로지르는 페일오버를 다룹니다. 두 기능은 모두 선택 사항이며 서로 독립적으로 동작합니다.

기본 모델 페일오버

메인 LLM 제공자에서 속도 제한(rate limit), 서버 과부하, 인증 실패, 연결 끊김 같은 오류가 발생하면 Hermes는 대화 기록을 잃지 않고 세션 중간에 백업 provider:model 조합으로 자동 전환할 수 있습니다.

구성

가장 쉬운 방법은 대화형 관리자를 사용하는 것입니다.

hermes fallback

hermes fallback은 hermes model과 같은 제공자 선택기를 재사용합니다. 제공자 목록, 자격 증명 프롬프트, 검증 방식이 동일합니다. 페일오버 체인은 add, list(ls 별칭), remove(rm 별칭), clear 하위 명령으로 관리합니다. 변경 사항은 config.yaml의 최상위 fallback_providers: 목록에 저장됩니다.

YAML을 직접 편집하려면 ~/.hermes/config.yaml에 fallback_model 섹션을 추가하세요.

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

provider와 model은 둘 다 필수입니다. 둘 중 하나라도 빠지면 페일오버는 비활성화됩니다.

fallback_model vs fallback_providers

fallback_model(단수)은 기존 단일 페일오버 키입니다. Hermes는 하위 호환성을 위해 계속 인식합니다. fallback_providers(복수, 목록)는 여러 대체 제공자를 순서대로 시도하는 방식이며, hermes fallback은 이 키에 씁니다. 두 값이 모두 있으면 Hermes는 병합하되 fallback_providers를 우선합니다.

지원되는 제공자

제공자	값	요구사항
AI Gateway	`ai-gateway`	`AI_GATEWAY_API_KEY`
OpenRouter	`openrouter`	`OPENROUTER_API_KEY`
Nous Portal	`nous`	`hermes auth` (OAuth)
OpenAI Codex	`openai-codex`	`hermes model` (ChatGPT OAuth)
GitHub Copilot	`copilot`	`COPILOT_GITHUB_TOKEN`, `GH_TOKEN` 또는 `GITHUB_TOKEN`
GitHub Copilot ACP	`copilot-acp`	외부 프로세스(에디터 통합)
Anthropic	`anthropic`	`ANTHROPIC_API_KEY` 또는 Claude Code 자격 증명
z.ai / GLM	`zai`	`GLM_API_KEY`
Kimi / Moonshot	`kimi-coding`	`KIMI_API_KEY`
MiniMax	`minimax`	`MINIMAX_API_KEY`
MiniMax (China)	`minimax-cn`	`MINIMAX_CN_API_KEY`
DeepSeek	`deepseek`	`DEEPSEEK_API_KEY`
NVIDIA NIM	`nvidia`	`NVIDIA_API_KEY` (선택: `NVIDIA_BASE_URL`)
GMI Cloud	`gmi`	`GMI_API_KEY` (선택: `GMI_BASE_URL`)
StepFun	`stepfun`	`STEPFUN_API_KEY` (선택: `STEPFUN_BASE_URL`)
Ollama Cloud	`ollama-cloud`	`OLLAMA_API_KEY`
Google Gemini (OAuth)	`google-gemini-cli`	`hermes model` (Google OAuth, 선택: `HERMES_GEMINI_PROJECT_ID`)
Google AI Studio	`gemini`	`GOOGLE_API_KEY` (별칭: `GEMINI_API_KEY`)
xAI (Grok)	`xai` (별칭 `grok`)	`XAI_API_KEY` (선택: `XAI_BASE_URL`)
xAI Grok OAuth (SuperGrok)	`xai-oauth` (별칭 `grok-oauth`)	`hermes model` -> xAI Grok OAuth (브라우저 로그인, SuperGrok 구독)
AWS Bedrock	`bedrock`	표준 boto3 인증(`AWS_REGION` + `AWS_PROFILE` 또는 `AWS_ACCESS_KEY_ID`)
Qwen Portal (OAuth)	`qwen-oauth`	`hermes model` (Qwen Portal OAuth, 선택: `HERMES_QWEN_BASE_URL`)
MiniMax (OAuth)	`minimax-oauth`	`hermes model` (MiniMax portal OAuth)
OpenCode Zen	`opencode-zen`	`OPENCODE_ZEN_API_KEY`
OpenCode Go	`opencode-go`	`OPENCODE_GO_API_KEY`
Kilo Code	`kilocode`	`KILOCODE_API_KEY`
Xiaomi MiMo	`xiaomi`	`XIAOMI_API_KEY`
Arcee AI	`arcee`	`ARCEEAI_API_KEY`
GMI Cloud	`gmi`	`GMI_API_KEY`
Alibaba / DashScope	`alibaba`	`DASHSCOPE_API_KEY`
Alibaba Coding Plan	`alibaba-coding-plan`	`ALIBABA_CODING_PLAN_API_KEY` (`DASHSCOPE_API_KEY`로 대체 가능)
Kimi / Moonshot (China)	`kimi-coding-cn`	`KIMI_CN_API_KEY`
StepFun	`stepfun`	`STEPFUN_API_KEY`
Tencent TokenHub	`tencent-tokenhub`	`TOKENHUB_API_KEY`
Azure AI Foundry	`azure-foundry`	`AZURE_FOUNDRY_API_KEY` + `AZURE_FOUNDRY_BASE_URL`
LM Studio (로컬)	`lmstudio`	`LM_API_KEY` (로컬이면 생략 가능) + `LM_BASE_URL`
Hugging Face	`huggingface`	`HF_TOKEN`
사용자 정의 엔드포인트	`custom`	`base_url` + `key_env` (아래 참고)

사용자 정의 엔드포인트 페일오버

OpenAI 호환 사용자 정의 엔드포인트를 대체 경로로 쓰려면 base_url과 선택 사항인 key_env를 추가합니다.

fallback_model:
  provider: custom
  model: my-local-model
  base_url: http://localhost:8000/v1
  key_env: MY_LOCAL_KEY              # API 키가 들어 있는 환경 변수 이름

페일오버가 발생하는 경우

페일오버는 기본 모델이 다음 오류로 실패할 때 자동 활성화됩니다.

속도 제한 (HTTP 429) - 재시도를 모두 소진한 뒤
서버 오류 (HTTP 500, 502, 503) - 재시도를 모두 소진한 뒤
인증 실패 (HTTP 401, 403) - 재시도할 의미가 없으므로 즉시 전환
Not found (HTTP 404) - 즉시 전환합니다.
잘못된 응답 - API가 잘못된 응답이나 빈 응답을 반복해서 반환할 때

트리거되면 Hermes는 다음 순서로 처리합니다.

대체 제공자의 자격 증명을 해석합니다.
새 API 클라이언트를 만듭니다.
모델, 제공자, 클라이언트를 제자리에서 교체합니다.
재시도 카운터를 재설정하고 대화를 계속합니다.

전환은 매끄럽게 이루어집니다. 대화 기록, 도구 호출, 컨텍스트가 보존됩니다. 에이전트는 멈춘 지점에서 그대로 이어가되 다른 모델을 사용할 뿐입니다.

턴 단위이며 세션 단위가 아닙니다

페일오버는 턴 단위로만 적용됩니다. 새 사용자 메시지가 들어올 때마다 기본 모델이 다시 복원됩니다. 기본 모델이 턴 중간에 실패하면 대체 모델은 그 턴에서만 활성화됩니다. 다음 메시지에서는 Hermes가 기본 모델을 다시 시도합니다. 한 턴 안에서 페일오버는 최대 한 번만 활성화됩니다. 대체 모델도 실패하면 재시도 후 오류 메시지를 반환하는 일반 오류 처리로 넘어갑니다. 이 방식은 한 턴 안에서 연쇄 페일오버 루프를 막으면서도 매 턴 기본 모델에 다시 기회를 줍니다.

예시

Anthropic 네이티브의 대체 경로로 OpenRouter 사용:

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

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

OpenRouter의 대체 경로로 Nous Portal 사용:

model:
  provider: openrouter
  default: anthropic/claude-opus-4

fallback_model:
  provider: nous
  model: nous-hermes-3

클라우드 제공자의 대체 경로로 로컬 모델 사용:

fallback_model:
  provider: custom
  model: llama-3.1-70b
  base_url: http://localhost:8000/v1
  key_env: LOCAL_API_KEY

Codex OAuth를 대체 경로로 사용:

fallback_model:
  provider: openai-codex
  model: gpt-5.3-codex

페일오버가 작동하는 곳

컨텍스트	페일오버 지원
CLI 세션	예
메시징 게이트웨이(Telegram, Discord 등)	예
서브에이전트 위임	아니요(서브에이전트는 페일오버 설정을 상속하지 않음)
크론 작업	아니요(고정 제공자로 실행됨)
보조 작업(비전, 압축)	아니요(아래 설명처럼 자체 제공자 체인을 사용)

팁

fallback_model에는 환경 변수 설정이 없습니다. 오직 config.yaml로만 구성합니다. 이는 의도적인 선택입니다. 페일오버 구성은 오래된 셸 export가 덮어쓸 값이 아니라 명시적으로 선택해야 하는 런타임 정책입니다.

보조 작업 페일오버

Hermes는 부가 작업에 별도의 경량 모델을 사용합니다. 각 작업에는 내장 페일오버 시스템처럼 동작하는 독립적인 제공자 해석 체인이 있습니다.

독립 제공자 해석을 사용하는 작업

작업	역할	설정 키
비전	이미지 분석, 브라우저 스크린샷	`auxiliary.vision`
웹 추출	웹페이지 요약	`auxiliary.web_extract`
압축	컨텍스트 압축 요약	`auxiliary.compression`
세션 검색	과거 세션 요약	`auxiliary.session_search`
스킬 허브	스킬 검색과 탐색	`auxiliary.skills_hub`
MCP	MCP 보조 작업	`auxiliary.mcp`
승인 분류	명령 승인 지능형 분류	`auxiliary.approval`
제목 생성	세션 제목 요약	`auxiliary.title_generation`
트리아지 구체화	`hermes kanban specify` / 대시보드 버튼 - 한 줄 트리아지 작업을 실제 명세로 확장	`auxiliary.triage_specifier`

자동 감지 체인

작업의 provider가 기본값인 "auto"로 설정되어 있으면 Hermes는 성공할 때까지 제공자를 순서대로 시도합니다.

텍스트 작업(압축, 웹 추출 등):

OpenRouter -> Nous Portal -> 사용자 정의 엔드포인트 -> Codex OAuth ->
API 키 제공자(z.ai, Kimi, MiniMax, Xiaomi MiMo, Hugging Face, Anthropic) -> 포기

비전 작업:

메인 제공자(비전 지원 시) -> OpenRouter -> Nous Portal ->
Codex OAuth -> Anthropic -> 사용자 정의 엔드포인트 -> 포기

해석된 제공자가 호출 시점에 실패하면 Hermes는 내부 재시도도 수행합니다. 제공자가 OpenRouter가 아니고 명시적인 base_url도 없다면, OpenRouter를 마지막 대체 경로로 시도합니다.

보조 제공자 구성

각 작업은 config.yaml에서 독립적으로 설정할 수 있습니다.

auxiliary:
  vision:
    provider: "auto"              # auto | openrouter | nous | codex | main | anthropic
    model: ""                     # 예: "openai/gpt-4o"
    base_url: ""                  # 직접 엔드포인트(provider보다 우선)
    api_key: ""                   # base_url에 사용할 API 키

  web_extract:
    provider: "auto"
    model: ""

  compression:
    provider: "auto"
    model: ""

  session_search:
    provider: "auto"
    model: ""
    timeout: 30
    max_concurrency: 3
    extra_body: {}

  skills_hub:
    provider: "auto"
    model: ""

  mcp:
    provider: "auto"
    model: ""

위 작업은 모두 같은 provider / model / base_url 패턴을 따릅니다. 컨텍스트 압축은 auxiliary.compression 아래에서 설정합니다.

auxiliary:
  compression:
    provider: main                                    # 다른 보조 작업과 같은 제공자 옵션
    model: google/gemini-3-flash-preview
    base_url: null                                    # OpenAI 호환 사용자 정의 엔드포인트

페일오버 모델은 다음 형식을 사용합니다.

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4
  # base_url: http://localhost:8000/v1               # 선택 사항인 사용자 정의 엔드포인트

auxiliary.session_search에는 다음 옵션도 사용할 수 있습니다.

max_concurrency: 동시에 실행되는 세션 요약 수를 제한합니다.
extra_body: 요약 호출에 제공자별 OpenAI 호환 요청 필드를 그대로 전달합니다.

예:

auxiliary:
  session_search:
    provider: main
    model: glm-4.5-air
    max_concurrency: 2
    extra_body:
      enable_thinking: false

사용 중인 제공자가 네이티브 OpenAI 호환 추론 제어 필드를 지원하지 않는다면 extra_body는 그 부분에는 도움이 되지 않습니다. 그래도 max_concurrency는 짧은 시간에 요청이 몰리면서 발생하는 429 오류를 줄이는 데 유용합니다.

보조 작업, 압축, 페일오버는 모두 같은 방식으로 동작합니다. provider로 요청을 처리할 제공자를 고르고, model로 사용할 모델을 고르며, base_url로 사용자 정의 엔드포인트를 지정하면 제공자 해석을 재정의합니다.

보조 작업의 제공자 옵션

이 옵션들은 auxiliary:, compression:, fallback_model: 설정에만 적용됩니다. "main"은 최상위 model.provider에서 유효한 값이 아닙니다. 사용자 정의 엔드포인트를 메인 모델로 쓰려면 model: 섹션에서 provider: custom을 사용하세요. 자세한 내용은 AI 제공자를 참고하세요.

제공자	설명	요구사항
`"auto"`	성공할 때까지 제공자를 순서대로 시도합니다. 기본값입니다.	구성된 제공자 하나 이상
`"openrouter"`	OpenRouter를 강제로 사용합니다.	`OPENROUTER_API_KEY`
`"nous"`	Nous Portal을 강제로 사용합니다.	`hermes auth`
`"codex"`	Codex OAuth를 강제로 사용합니다.	`hermes model` -> Codex
`"main"`	메인 에이전트가 사용하는 제공자를 그대로 사용합니다. 보조 작업에서만 유효합니다.	활성 메인 제공자 구성
`"anthropic"`	Anthropic 네이티브를 강제로 사용합니다.	`ANTHROPIC_API_KEY` 또는 Claude Code 자격 증명

직접 엔드포인트 재정의

어떤 보조 작업이든 base_url을 설정하면 제공자 해석을 완전히 우회하고 해당 엔드포인트로 직접 요청을 보냅니다.

auxiliary:
  vision:
    base_url: "http://localhost:1234/v1"
    api_key: "local-key"
    model: "qwen2.5-vl"

base_url은 provider보다 우선합니다. Hermes는 설정된 api_key를 인증에 사용하고, 값이 없으면 OPENAI_API_KEY로 대체합니다. 사용자 정의 엔드포인트에는 OPENROUTER_API_KEY를 재사용하지 않습니다.

컨텍스트 압축 페일오버

컨텍스트 압축은 auxiliary.compression 설정 블록으로 요약을 처리할 모델과 제공자를 제어합니다.

auxiliary:
  compression:
    provider: "auto"                              # auto | openrouter | nous | main
    model: "google/gemini-3-flash-preview"

레거시 마이그레이션

compression.summary_model / compression.summary_provider / compression.summary_base_url를 사용하는 예전 설정은 처음 로드될 때 auxiliary.compression.*로 자동 마이그레이션됩니다(config version 17).

압축에 사용할 제공자가 없으면 Hermes는 세션을 실패시키는 대신 요약을 생성하지 않고 중간 대화 턴을 제외합니다.

위임 제공자 재정의

delegate_task로 생성된 서브에이전트는 기본 페일오버 모델을 사용하지 않습니다. 하지만 비용 최적화를 위해 별도의 provider:model 조합으로 라우팅할 수는 있습니다.

delegation:
  provider: "openrouter"                      # 모든 서브에이전트의 제공자 재정의
  model: "google/gemini-3-flash-preview"      # 모델 재정의
  # base_url: "http://localhost:1234/v1"      # 직접 엔드포인트를 사용해도 됨
  # api_key: "local-key"

전체 구성 세부사항은 서브에이전트 위임을 참고하세요.

크론 작업 제공자

크론 작업은 실행 시점에 구성된 제공자로 실행됩니다. 페일오버 모델은 지원하지 않습니다. 크론 작업에서 다른 제공자를 사용하려면 크론 작업 자체에 provider와 model 재정의를 설정하세요.

cronjob(
    action="create",
    schedule="every 2h",
    prompt="Check server status",
    provider="openrouter",
    model="google/gemini-3-flash-preview"
)

전체 구성 세부사항은 예약 작업(Cron)을 참고하세요.

요약

기능	페일오버 방식	설정 위치
메인 에이전트 모델	`config.yaml`의 `fallback_model`. 오류가 난 턴에서만 페일오버하고, 다음 턴에서는 기본 모델이 복원됩니다.	`fallback_model:` (최상위)
비전	자동 감지 체인 + 내부 OpenRouter 재시도	`auxiliary.vision`
웹 추출	자동 감지 체인 + 내부 OpenRouter 재시도	`auxiliary.web_extract`
컨텍스트 압축	자동 감지 체인. 사용할 제공자가 없으면 요약 없이 진행합니다.	`auxiliary.compression`
세션 검색	자동 감지 체인	`auxiliary.session_search`
스킬 허브	자동 감지 체인	`auxiliary.skills_hub`
MCP 헬퍼	자동 감지 체인	`auxiliary.mcp`
승인 분류	자동 감지 체인	`auxiliary.approval`
제목 생성	자동 감지 체인	`auxiliary.title_generation`
트리아지 구체화	자동 감지 체인	`auxiliary.triage_specifier`
위임	제공자 재정의만 사용합니다. 자동 페일오버는 없습니다.	`delegation.provider` / `delegation.model`
크론 작업	작업별 제공자 재정의만 사용합니다. 자동 페일오버는 없습니다.	작업별 `provider` / `model`

기본 모델 페일오버​

구성​

지원되는 제공자​

사용자 정의 엔드포인트 페일오버​

페일오버가 발생하는 경우​

예시​

페일오버가 작동하는 곳​

보조 작업 페일오버​

독립 제공자 해석을 사용하는 작업​

자동 감지 체인​

보조 제공자 구성​

보조 작업의 제공자 옵션​

직접 엔드포인트 재정의​

컨텍스트 압축 페일오버​

위임 제공자 재정의​

크론 작업 제공자​

요약​