Hermes Agent는 몇 가지 기본 프로바이더를 제공하지만, 진정한 유연성은 Custom endpoint 옵션에 있습니다. OpenAI chat-completions 형식을 지원하는 서비스라면 베이스 URL, API 키, 모델 이름 세 가지만 있으면 연결할 수 있습니다. MiniMax, DeepSeek, Google Gemini, xAI Grok, OpenAI, OpenRouter, 프라이빗 vLLM 서버, 로컬 Ollama 인스턴스, 그리고 이 모든 모델을 한 번에 사용할 수 있게 해주는 haimaker.ai까지 모두 포함됩니다.
먼저 일반적인 설정 방법을 살펴보고, 가장 많이 문의되는 프로바이더의 정확한 설정값을 안내해 드립니다.
일반적인 방법
Hermes에서 커스텀 프로바이더를 추가하는 방법은 모두 동일한 세 단계로 이루어집니다:
hermes model
- 메뉴에서 Custom endpoint를 선택합니다.
- 베이스 URL을 입력합니다 — OpenAI 호환 루트로,
/v1로 끝나야 합니다. Hermes가/chat/completions를 자체적으로 추가합니다. - 해당 프로바이더의 API 키를 입력합니다.
- 프로바이더가 요구하는 모델 식별자를 입력합니다.
Hermes는 선택한 내용을 저장해 이후 모든 실행에 사용합니다. 나중에 프로바이더를 변경하려면 hermes model를 다시 실행하면 됩니다. 이것이 전체 메커니즘입니다. 이 글의 나머지 부분은 각 프로바이더에 맞는 올바른 값을 안내하는 내용입니다.
모델이 Hermes에서 제대로 작동하려면 툴 스키마를 잘 따라야 하고, 에이전트 루프를 처리할 만큼 충분한 컨텍스트를 가져야 합니다 — 최소 약 64K의 사용 가능한 컨텍스트를 목표로 하세요. 실제 모델 선택은 Hermes Agent 추천 모델을 참고하세요.
haimaker.ai — 하나의 키로 모든 모델 사용
프로바이더마다 계정, 키, 베이스 URL을 따로 관리하는 대신, Hermes를 haimaker.ai에 한 번만 연결하면 모델 이름 하나만 바꿔서 전환할 수 있습니다. 가장 빠른 설정 방법은 다음 명령 한 줄입니다:
export HAIMAKER_API_KEY=your-haimaker-key
npx -y @haimaker/connect --hermes
@haimaker/connect는 Hermes의 커스텀 엔드포인트 설정을 작성하고 키를 확인한 뒤 종료합니다. --model를 추가하면 모델을 고정하고, --pick-model를 추가하면 대화형으로 모델을 고를 수 있습니다. 설정을 되돌리려면 npx @haimaker/connect --uninstall --hermes를 실행하세요. 먼저 app.haimaker.ai에서 키를 발급받으세요. 신규 계정에는 무료 크레딧이 제공됩니다.
내장된 hermes model 절차를 그대로 사용하고 싶다면, 안내에 따라 다음 값을 입력하세요:
- 베이스 URL:
https://api.haimaker.ai/v1 - API 키: haimaker.ai 키
- 모델: 지원 모델 중 하나, 예:
anthropic/claude-sonnet-4-6,openai/gpt-5-4-codex,google/gemini-3-1-pro,minimax/minimax-m2-5,deepseek/deepseek-v3-2,xai/grok-4-1-fast,zai/glm-4-7,moonshot/kimi-k2-5
모델을 시장가보다 약 5% 저렴하게 이용할 수 있으며, 결제 계정도 하나만 관리하면 됩니다.
Hermes에서 MiniMax 사용하기
MiniMax M2.5는 Hermes에서 인기 있는 가성비 선택지입니다. 계속 실행해 둘 만큼 저렴하면서도 툴 루프를 처리할 만큼 성능이 충분합니다.
- 베이스 URL:
https://api.minimax.io/v1 - API 키: MiniMax 플랫폼 콘솔에서 발급
- 모델:
MiniMax-M2.5(MiniMax 콘솔에 표시된 ID를 그대로 사용하세요 — 대소문자가 중요합니다)
또는 haimaker.ai에서 모델 minimax/minimax-m2-5로 MiniMax를 사용하면 별도 계정이 필요 없습니다.
Hermes에서 Google Gemini 사용하기
Gemini는 OpenAI 호환 레이어를 제공하므로 Hermes 커스텀 엔드포인트로 사용할 수 있습니다.
- 베이스 URL:
https://generativelanguage.googleapis.com/v1beta/openai - API 키: Google AI Studio 키
- 모델: 저렴하고 빠른 작업에는
gemini-3-flash, 긴 컨텍스트 리서치에는gemini-3.1-pro
그렇습니다. Hermes Agent는 이 방식으로 Google Gemini를 지원합니다. 별도의 Gemini 통합을 활성화할 필요 없이 커스텀 엔드포인트로 사용하면 됩니다. haimaker.ai에서는 google/gemini-3-1-pro를 사용하세요.
Hermes에서 DeepSeek 사용하기
- 베이스 URL:
https://api.deepseek.com/v1 - API 키: DeepSeek 플랫폼 콘솔에서 발급
- 모델:
deepseek-chat(현재 V3.2 라인을 가리킴) 또는deepseek-reasoner
haimaker.ai를 이용하려면 deepseek/deepseek-v3-2를 사용하세요.
Hermes에서 xAI Grok 사용하기
- 베이스 URL:
https://api.x.ai/v1 - API 키: xAI 콘솔에서 발급
- 모델: 저렴한 대용량 컨텍스트 작업에는
grok-4.1-fast, 코드 특화 작업에는grok-code-fast
haimaker.ai를 이용하려면 xai/grok-4-1-fast를 사용하세요.
Hermes에서 OpenAI / Codex 모델 사용하기
OpenAI 자체 모델(Codex 라인 포함)을 Hermes에서 사용하려면:
- 베이스 URL:
https://api.openai.com/v1 - API 키: OpenAI API 키 (ChatGPT Plus 구독에는 API 이용 권한이 포함되지 않습니다 — 결제가 활성화된 별도의 API 키가 필요합니다)
- 모델: 코딩에는
gpt-5.4-codex, 일반 작업에는gpt-5.4
haimaker.ai를 이용하려면 openai/gpt-5-4-codex를 사용하세요.
Ollama를 통한 로컬 모델
- 베이스 URL:
http://localhost:11434/v1 - API 키: 임의의 비어 있지 않은 문자열 사용 (Ollama는 이 값을 무시하지만 Hermes는 값이 있어야 합니다)
- 모델:
gemma4:latest,qwen3.5:latest, 또는 직접 받은 모델
ollama pull gemma4
hermes model # Custom endpoint → base URL above → model gemma4:latest
일반적인 문제
- 긴 단계에서 타임아웃. 느린 프로바이더는 긴 에이전트 실행 단계에서 Hermes의 기본 스트림 읽기 타임아웃을 초과할 수 있습니다. Hermes를 시작하기 전에
HERMES_STREAM_READ_TIMEOUT(초)를 더 큰 값으로 설정하세요. - 401 / 인증 오류. 키가 등록되지 않았거나, API 키 대신 콘솔/세션 토큰을 붙여넣은 경우입니다.
hermes model를 다시 실행해 재입력하세요. - 요청 시 404. 베이스 URL에 이미
/chat/completions가 포함되어 있거나 끝에 슬래시가 있을 수 있습니다. Hermes가 경로를 자체적으로 추가하므로 URL은/v1에서 끝나야 합니다. - 툴 호출이 반복적으로 실패. 대개 설정 문제가 아니라 모델 문제입니다. 소형 모델은 툴 스키마를 잘 따르지 못하는 경우가 많으므로, 더 높은 등급의 모델로 변경하세요.
haimaker.ai 키 발급받기
신규 계정에는 테스트용 무료 크레딧이 제공됩니다. haimaker.ai에서 실시간 가격과 벤치마크를 확인하고 지원되는 모든 모델을 둘러본 뒤, npx -y @haimaker/connect --hermes를 실행하여 Hermes를 연결하세요.
관련 글: Hermes Agent 추천 모델 · Hermes Agent 가격 · Hermes Agent vs Codex CLI