---
title: Hermes Agent에 커스텀 프로바이더 추가하는 방법 (2026)
description: >-
  Hermes Agent를 모든 OpenAI 호환 프로바이더에 연결하세요 — MiniMax, DeepSeek, Gemini, Grok,
  OpenAI, haimaker.ai. 베이스 URL, API 키, 타임아웃 해결 방법.
date: 2026-05-11T00:00:00.000Z
updatedDate: 2026-06-26T00:00:00.000Z
location: 'San Francisco, CA – 2026년 5월 11일'
image: /images/hermes-custom-provider-setup-hero.jpg
keywords: >-
  hermes agent 커스텀 프로바이더, hermes agent 프로바이더 설정, hermes agent api 키, hermes
  agent minimax 프로바이더 설정, hermes agent gemini api, hermes agent deepseek 설정,
  hermes agent grok api, hermes 커스텀 엔드포인트, hermes agent openai 호환 api
faq:
  - question: Hermes Agent에 커스텀 프로바이더를 어떻게 추가하나요?
    answer: >-
      터미널에서 `hermes model`를 실행하고, 'Custom endpoint'를 선택한 후 세 가지를 입력하세요. 프로바이더의
      베이스 URL(/v1로 끝나는 형태), API 키, 모델 식별자입니다. Hermes는 선택한 내용을 저장해 이후 모든 실행에
      사용합니다. OpenAI 호환 /v1/chat/completions 엔드포인트를 제공하는 프로바이더라면 모두 사용할 수 있습니다 —
      MiniMax, DeepSeek, Google, xAI, OpenAI, OpenRouter, 로컬 Ollama 인스턴스,
      haimaker.ai 등. haimaker.ai의 경우 'npx -y @haimaker/connect --hermes' 명령 한 줄로
      Hermes를 설정할 수 있습니다.
  - question: Hermes Agent에 필요한 베이스 URL은 무엇인가요?
    answer: >-
      Hermes에는 전체 chat-completions 경로가 아닌 OpenAI 호환 루트가 필요합니다. 각 서비스의 루트는 다음과
      같습니다. haimaker는 https://api.haimaker.ai/v1,, MiniMax는
      https://api.minimax.io/v1,, DeepSeek의 경우 https://api.deepseek.com/v1,,
      Gemini의 OpenAI 호환 레이어는
      https://generativelanguage.googleapis.com/v1beta/openai,, xAI Grok의 경우
      https://api.x.ai/v1,, OpenAI는 https://api.openai.com/v1,, Ollama는
      http://localhost:11434/v1를입니다. Hermes가 /chat/completions를 자체적으로 추가합니다.
  - question: Hermes 커스텀 프로바이더에서 타임아웃이 발생하는 이유는 무엇인가요?
    answer: >-
      느린 프로바이더에서 긴 에이전트 실행 단계가 Hermes의 기본 읽기 타임아웃을 초과할 수 있습니다. Hermes를 시작하기 전에
      HERMES_STREAM_READ_TIMEOUT 환경 변수(초 단위)를 더 큰 값으로 설정하고, 베이스 URL이 뒤에 슬래시 없이
      /v1로 끝나는지 확인하세요. 타임아웃 대신 401이 발생하면 API 키가 제대로 설정되지 않았다는 뜻입니다 — `hermes
      model`를 다시 실행해 재입력하세요.
locale: ko-kr
translationKey: hermes-custom-provider-setup
---
Hermes Agent는 몇 가지 기본 프로바이더를 제공하지만, 진정한 유연성은 **Custom endpoint** 옵션에 있습니다. OpenAI chat-completions 형식을 지원하는 서비스라면 베이스 URL, API 키, 모델 이름 세 가지만 있으면 연결할 수 있습니다. MiniMax, DeepSeek, Google Gemini, xAI Grok, OpenAI, OpenRouter, 프라이빗 vLLM 서버, 로컬 Ollama 인스턴스, 그리고 이 모든 모델을 한 번에 사용할 수 있게 해주는 [haimaker.ai](https://haimaker.ai)까지 모두 포함됩니다.

먼저 일반적인 설정 방법을 살펴보고, 가장 많이 문의되는 프로바이더의 정확한 설정값을 안내해 드립니다.

## 일반적인 방법

Hermes에서 커스텀 프로바이더를 추가하는 방법은 모두 동일한 세 단계로 이루어집니다:

```bash
hermes model
```

1. 메뉴에서 **Custom endpoint**를 선택합니다.
2. **베이스 URL**을 입력합니다 — OpenAI 호환 루트로, `/v1`로 끝나야 합니다. Hermes가 `/chat/completions`를 자체적으로 추가합니다.
3. 해당 프로바이더의 **API 키**를 입력합니다.
4. 프로바이더가 요구하는 **모델 식별자**를 입력합니다.

Hermes는 선택한 내용을 저장해 이후 모든 실행에 사용합니다. 나중에 프로바이더를 변경하려면 `hermes model`를 다시 실행하면 됩니다. 이것이 전체 메커니즘입니다. 이 글의 나머지 부분은 각 프로바이더에 맞는 올바른 값을 안내하는 내용입니다.

모델이 Hermes에서 제대로 작동하려면 툴 스키마를 잘 따라야 하고, 에이전트 루프를 처리할 만큼 충분한 컨텍스트를 가져야 합니다 — 최소 약 64K의 사용 가능한 컨텍스트를 목표로 하세요. 실제 모델 선택은 [Hermes Agent 추천 모델](/blog/best-models-for-hermes/)을 참고하세요.

## haimaker.ai — 하나의 키로 모든 모델 사용

프로바이더마다 계정, 키, 베이스 URL을 따로 관리하는 대신, Hermes를 haimaker.ai에 한 번만 연결하면 모델 이름 하나만 바꿔서 전환할 수 있습니다. 가장 빠른 설정 방법은 다음 명령 한 줄입니다:

```bash
export HAIMAKER_API_KEY=your-haimaker-key
npx -y @haimaker/connect --hermes
```

[`@haimaker/connect`](/connect)는 Hermes의 커스텀 엔드포인트 설정을 작성하고 키를 확인한 뒤 종료합니다. `--model`를 추가하면 모델을 고정하고, `--pick-model`를 추가하면 대화형으로 모델을 고를 수 있습니다. 설정을 되돌리려면 `npx @haimaker/connect --uninstall --hermes`를 실행하세요. 먼저 [app.haimaker.ai](https://app.haimaker.ai/sign-up)에서 키를 발급받으세요. 신규 계정에는 무료 크레딧이 제공됩니다.

내장된 `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`, 또는 직접 받은 모델

```bash
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](https://haimaker.ai)에서 실시간 가격과 벤치마크를 확인하고 지원되는 모든 모델을 둘러본 뒤, `npx -y @haimaker/connect --hermes`를 실행하여 Hermes를 연결하세요.

<a href="https://app.haimaker.ai/sign-up?utm_source=hermes_blog&utm_medium=cta&utm_campaign=hermes_custom_provider" class="cta-button">HAIMAKER에서 $10 무료 크레딧 받기</a>

---

*관련 글: [Hermes Agent 추천 모델](/blog/best-models-for-hermes/) · [Hermes Agent 가격](/blog/hermes-api-costs-pricing/) · [Hermes Agent vs Codex CLI](/blog/hermes-vs-codex/)*