본문으로 건너뛰기

제공자 런타임 확인

Hermes에는 다음에서 사용되는 공유 제공자 런타임 확인자가 있습니다.

  • CLI
  • 게이트웨이
  • 크론 작업
  • ACP
  • 보조 모델 호출

기본 구현:

  • hermes_cli/runtime_provider.py — 자격 증명 확인, _resolve_custom_runtime()
  • hermes_cli/auth.py — 제공자 레지스트리, resolve_provider()
  • hermes_cli/model_switch.py — 공유 /model 스위치 파이프라인(CLI + 게이트웨이)
  • agent/auxiliary_client.py — 보조 모델 라우팅
  • providers/ — ABC + 레지스트리 진입점(ProviderProfile, register_provider, get_provider_profile, list_providers)
  • plugins/model-providers/<name>/ — api_mode, base_url, env_vars, fallback_models을 선언하고 첫 번째 액세스 시 레지스트리에 등록하는 제공자별 플러그인(번들)입니다. $HERMES_HOME/plugins/model-providers/<name>/의 사용자 플러그인은 동일한 이름의 번들 플러그인을 재정의합니다.

providers/의 get_provider_profile()은 지정된 제공자 ID에 대해 ProviderProfile을 반환합니다. runtime_provider.py은 해결 시간에 이를 호출하여 해당 데이터를 여러 파일에 복제할 필요 없이 정식 base_url, env_vars 우선 순위 목록, api_mode 및 fallback_models을 가져옵니다. plugins/model-providers/<your-provider>/(또는 $HERMES_HOME/plugins/model-providers/<your-provider>/) 아래에 register_provider()을 호출하는 새 플러그인을 추가하면 runtime_provider.py이 이를 선택하기에 충분합니다. 확인자 자체에는 분기가 필요하지 않습니다.

새로운 최고 수준의 추론 제공자를 추가하려는 경우 이 페이지 옆에 있는 제공자 추가 및 모델 제공자 플러그인 가이드를 읽어보세요.

해결 우선순위​

높은 수준에서 제공자 확인은 다음을 사용합니다.

  1. 명시적 CLI/런타임 요청
  2. config.yaml 모델/제공자 구성
  3. 환경 변수
  4. 제공자별 기본값 또는 자동 해결

Hermes는 저장된 모델/제공자 선택을 일반 실행의 진실 소스로 취급하기 때문에 이러한 순서가 중요합니다. 이렇게 하면 오래된 셸 내보내기가 사용자가 hermes model에서 마지막으로 선택한 엔드포인트를 자동으로 재정의하는 것을 방지할 수 있습니다.

제공자​

현재 제공자 제품군에는 다음이 포함됩니다(전체 번들 세트는 plugins/model-providers/ 참조).

  • AI 게이트웨이(Vercel)
  • 오픈라우터
  • 누스 포탈
  • 오픈AI 코덱스
  • 부조종사 / 부조종사 ACP
  • 인류학(원주민)
  • 구글/제미니(gemini, google-gemini-cli)
  • 알리바바 / DashScope (alibaba, alibaba-coding-plan)
  • DeepSeek
  • Z.AI
  • 키미/문샷(kimi-coding, kimi-coding-cn)
  • 미니맥스(minimax, minimax-cn, minimax-oauth)
  • 킬로 코드
  • 포옹하는 얼굴
  • OpenCode Zen / OpenCode Go
  • AWS 기반암
  • 아주르 파운드리
  • 엔비디아 NIM
  • xAI(그록)
  • 아르씨
  • GMI 클라우드
  • 스텝펀
  • Qwen OAuth
  • 샤오미
  • 올라마 클라우드
  • LM스튜디오
  • 텐센트 토큰허브
  • 사용자 정의(provider: custom) — 모든 OpenAI 호환 엔드포인트를 위한 최고 수준의 제공자
  • 명명된 사용자 지정 제공자(config.yaml의 custom_providers 목록)

런타임 해상도의 출력​

런타임 해석기는 다음과 같은 데이터를 반환합니다.

  • provider
  • api_mode
  • base_url
  • api_key
  • source
  • 만료/새로 고침 정보와 같은 제공자별 메타데이터

이것이 중요한 이유​

이 확인자는 Hermes가 다음 사이에 인증/런타임 논리를 공유할 수 있는 주된 이유입니다.

  • hermes chat
  • 게이트웨이 메시지 처리
  • 새로운 세션에서 실행되는 크론 작업
  • ACP 편집 세션
  • 보조 모델 작업

AI 게이트웨이​

~/.hermes/.env에 AI_GATEWAY_API_KEY을 설정하고 --provider ai-gateway로 실행합니다. Hermes는 게이트웨이의 /models 엔드포인트에서 사용 가능한 모델을 가져와 도구 사용 지원을 통해 언어 모델로 필터링합니다.

OpenRouter, AI Gateway 및 사용자 정의 OpenAI 호환 기본 URL​

Hermes에는 여러 제공자 키(예: OPENROUTER_API_KEY, AI_GATEWAY_API_KEY 및 OPENAI_API_KEY)가 있는 경우 잘못된 API 키가 사용자 지정 엔드포인트에 유출되는 것을 방지하는 논리가 포함되어 있습니다.

각 제공자의 API 키는 자체 기본 URL로 범위가 지정됩니다.

  • OPENROUTER_API_KEY은 openrouter.ai 엔드포인트로만 전송됩니다.
  • AI_GATEWAY_API_KEY은 ai-gateway.vercel.sh 엔드포인트로만 전송됩니다.
  • OPENAI_API_KEY은 사용자 정의 엔드포인트 및 대체 수단으로 사용됩니다.

헤르메스는 또한 다음을 구별합니다.

  • 사용자가 선택한 실제 커스텀 엔드포인트
  • 사용자 정의 엔드포인트가 구성되지 않은 경우 사용되는 OpenRouter 대체 경로

이러한 구별은 다음과 같은 경우에 특히 중요합니다.

  • 로컬 모델 서버
  • 비OpenRouter/비AI 게이트웨이 OpenAI 호환 API
  • 설정을 다시 실행하지 않고 제공자 전환
  • OPENAI_BASE_URL을 현재 셸에서 내보내지 않은 경우에도 계속 작동해야 하는 구성 저장 사용자 정의 엔드포인트

원주민 인류 경로​

Anthropic은 더 이상 "OpenRouter를 통한" 것이 아닙니다.

제공자 확인이 anthropic을 선택하면 Hermes는 다음을 사용합니다.

  • api_mode = anthropic_messages
  • 네이티브 Anthropic 메시지 API
  • 번역용 agent/anthropic_adapter.py

기본 Anthropic에 대한 자격 증명 확인은 이제 복사된 환경 토큰보다 새로 고칠 수 있는 Claude Code 자격 증명을 선호합니다. 실제로 이는 다음을 의미합니다.

  • Claude Code 자격 증명 파일에 새로 고칠 수 있는 인증이 포함된 경우 기본 소스로 처리됩니다.
  • 수동 ANTHROPIC_TOKEN / CLAUDE_CODE_OAUTH_TOKEN 값은 여전히 명시적 재정의로 작동합니다.
  • Hermes는 기본 메시지 API 호출 전에 Anthropic 자격 증명을 프리플라이트합니다.
  • Hermes는 대체 경로로 Anthropic 클라이언트를 재구축한 후에도 여전히 401에서 한 번 재시도합니다.

OpenAI 코덱스 경로​

Codex는 별도의 Responses API 경로를 사용합니다.

  • api_mode = codex_responses
  • 전용 자격 증명 확인 및 인증 저장소 지원

보조 모델 라우팅​

다음과 같은 보조 작업:

  • 비전
  • 웹 추출 요약
  • 컨텍스트 압축 요약
  • 세션 검색 요약
  • 스킬 허브 운영
  • MCP 도우미 작업
  • 메모리 플러시

기본 대화 모델 대신 자체 제공자/모델 라우팅을 사용할 수 있습니다.

보조 작업이 제공자 main으로 구성되면 Hermes는 일반 채팅과 동일한 공유 런타임 경로를 통해 이를 해결합니다. 실제로 이는 다음을 의미합니다.

  • env 기반 사용자 정의 엔드포인트는 여전히 작동합니다.
  • hermes model / config.yaml을 통해 저장된 사용자 정의 엔드포인트도 작동합니다.
  • 보조 라우팅은 실제 저장된 사용자 정의 엔드포인트와 OpenRouter 폴백 간의 차이를 알 수 있습니다.

대체 모델​

Hermes는 기본 모델에 오류가 발생할 때 순서대로 시도되는 (provider, model) 항목 목록인 구성된 대체 제공자 체인을 지원합니다. 레거시 단일 쌍 fallback_model dict는 여전히 하위 호환용으로 허용됩니다(첫 번째 쓰기 시 마이그레이션됨).

내부적으로 작동하는 방식​

  1. 저장소: AIAgent.__init__은 fallback_model 사전을 저장하고 _fallback_activated = False을 설정합니다.

  2. 트리거 지점: _try_activate_fallback()은 run_agent.py에 있는 기본 재시도 루프의 세 위치에서 호출됩니다.

    • 유효하지 않은 API 응답에 대한 최대 재시도 후(선택 항목 없음, 콘텐츠 누락)
    • 재시도할 수 없는 클라이언트 오류(HTTP 401, 403, 404)
    • 일시적인 오류에 대한 최대 재시도 후(HTTP 429, 500, 502, 503)

  3. 활성화 흐름(_try_activate_fallback):

    • 이미 활성화되었거나 구성되지 않은 경우 즉시 False을 반환합니다.
    • auxiliary_client.py에서 resolve_provider_client()을 호출하여 적절한 인증을 사용하여 새 클라이언트를 구축합니다.
    • api_mode을 결정합니다: openai-codex의 경우 codex_responses, 인류의 경우 anthropic_messages, 기타 모든 경우의 경우 chat_completions
    • 내부 스왑: self.model, self.provider, self.base_url, self.api_mode, self.client, self._client_kwargs
    • Anthropic fallback의 경우: OpenAI 호환 대신 기본 Anthropic 클라이언트를 구축합니다.
    • 프롬프트 캐싱을 재평가합니다(OpenRouter의 Claude 모델에 대해 활성화됨)
    • _fallback_activated = True 설정 — 다시 실행되는 것을 방지합니다.
    • 재시도 횟수를 0으로 재설정하고 루프를 계속합니다.

  4. 구성 흐름:

    • CLI: cli.py은 CLI_CONFIG["fallback_model"]을 읽고 → AIAgent(fallback_model=...)로 전달됩니다.
    • 게이트웨이: gateway/run.py._load_fallback_model()은 config.yaml을 읽고 → AIAgent로 전달됩니다.
    • 검증: provider 및 model 키는 모두 비어 있지 않아야 합니다. 그렇지 않으면 대체가 비활성화됩니다.

대체를 지원하지 않는 것​

  • 하위 에이전트 위임(tools/delegate_tool.py): 하위 에이전트는 상위 제공자를 상속하지만 대체 구성은 상속하지 않습니다.
  • 보조 작업: 자체 독립 제공자 자동 감지 체인을 사용합니다(위의 보조 모델 라우팅 참조).

크론 작업은 폴백을 지원합니다. run_job()은 config.yaml에서 fallback_providers(또는 레거시 fallback_model)을 읽고 게이트웨이의 것과 일치하는 AIAgent(fallback_model=...)에 전달합니다. _load_fallback_model() 패턴. Cron 내부를 참조하세요.

테스트 범위​

지원되는 모든 제공자, 일회성 의미 체계 및 엣지 케이스를 포괄하는 포괄적인 테스트는 tests/test_fallback_model.py을 참조하세요.