Provider Runtime 해석
기준일: 2026-07-26
난이도: 고급
공식 기준: Provider Runtime
개요
Hermes는 공유 provider runtime resolver로 CLI, gateway, cron, ACP, auxiliary 모델 호출의 인증·엔드포인트 해석을 통일합니다. 새 1급 추론 프로바이더를 추가할 때는 Adding Providers와 Model Provider Plugin 가이드를 함께 보세요.
핵심 개념
| 모듈 | 역할 |
|---|---|
hermes_cli/runtime_provider.py |
자격 증명 해석, _resolve_custom_runtime() |
hermes_cli/auth.py |
provider 레지스트리, resolve_provider() |
hermes_cli/model_switch.py |
CLI·gateway 공통 /model 전환 파이프라인 |
agent/auxiliary_client.py |
보조 모델 라우팅 |
providers/ |
ProviderProfile, register_provider, get_provider_profile |
plugins/model-providers/<name>/ |
번들 프로바이더 플러그인 (api_mode, base_url, env_vars, fallback_models) |
$HERMES_HOME/plugins/model-providers/ |
동일 이름 사용자 플러그인이 번들을 덮어씀 |
get_provider_profile()이 해석 시점의 정규 base_url·env 우선순위·api_mode·fallback_models를 반환합니다. 플러그인이 register_provider()만 호출하면 resolver 분기 추가 없이 인식됩니다.
상세
해석 우선순위
- 명시적 CLI/runtime 요청
config.yamlmodel/provider- 환경 변수
- 프로바이더 기본값 또는 auto
저장된 model/provider 선택이 일반 실행의 source of truth입니다. 오래된 셸 export가 hermes model에서 고른 엔드포인트를 조용히 덮어쓰지 않게 합니다.
프로바이더 패밀리 (요약)
OpenRouter, Nous Portal, OpenAI Codex, Copilot/Copilot ACP, Anthropic native, Google Gemini, Alibaba/DashScope, DeepSeek, Z.AI, Kimi/Moonshot, MiniMax, Kilo Code, Hugging Face, OpenCode Zen/Go, AWS Bedrock, Azure Foundry, NVIDIA NIM, xAI, Arcee, GMI Cloud, StepFun, Qwen OAuth, Xiaomi, Ollama Cloud, LM Studio, Tencent TokenHub, provider: custom, named custom_providers 목록. 전체 번들은 plugins/model-providers/ 기준.
해석 결과
provider, api_mode, base_url, api_key, source, 만료/리프레시 메타데이터 등.
OpenRouter vs custom OpenAI 호환 URL
여러 키가 있을 때 잘못된 키 유출을 막습니다.
OPENROUTER_API_KEY→ openrouter.ai 엔드포인트에만OPENAI_API_KEY→ custom 엔드포인트 및 폴백
실 custom 엔드포인트와 OpenRouter 호환 프록시를 구분합니다. 커스텀 베이스 URL에 OpenRouter 키를 보내지 않도록 스코핑합니다.
왜 중요한가
hermes chat, gateway 메시지 처리, 새 세션 cron, ACP 에디터 세션, 비전·압축 등 auxiliary 작업이 같은 인증/런타임 로직을 공유합니다.
관련 코드 경로
- 커스텀 런타임:
_resolve_custom_runtime() - 모델 전환:
model_switch공유 파이프라인 - 보조 모델:
auxiliary_client
체크리스트
- 공식 원문과 명령·설정 키를 대조했다
- 로컬/
config.yaml/.env에서 재현 경로를 확인했다 - 권한·allowlist·시크릿 노출을 점검했다
- 실패 시 롤백·비활성화 방법을 알고 있다
다음 단계
기준일: 2026-07-26 — 공식 문서 동기화 코퍼스