# Hermes Agent에 OmniaKey 연결하기: OpenAI 호환 API 설정

> Hermes Agent를 OmniaKey 커스텀 OpenAI 호환 endpoint에 연결하는 방법을 안내합니다. hermes model, config.yaml, 모델 전환과 404 오류를 확인하세요.

- Canonical HTML: https://omniakey.com/ko/blog/hermes-setup
- Markdown: https://omniakey.com/ko/blog/hermes-setup.md
- Published: 2026-05-24 (updated 2026-10-30)
- Author: Kiki, COO at OmniaKey
- Language: ko
- Category: Guide
- Reading time: 4 min
- All posts: https://omniakey.com/blog/llms.txt

---

2026년 10월 30일 업데이트: Hermes에서 자주 나오는 설정 오류 4가지에 원인과 해결 방법을 정리했습니다. 내용은 Hermes Agent 공식 문서를 따랐습니다.

`Hermes Agent API 설정`을 찾고 있다면 커스텀 OpenAI 호환 endpoint 하나를 등록하면 됩니다. Nous Research의 Hermes Agent는 Provider를 다시 설정하지 않고 model ID로 Claude, GPT, Gemini, Grok을 선택할 수 있습니다.

## 가장 빠른 방법: `hermes model`

```bash
hermes model
```

**Custom endpoint (self-hosted / VLLM / etc.)**를 선택하고 다음을 입력합니다.

- **Base URL:** `https://api.omniakey.com/v1`
- **API key:** OmniaKey key
- **Model:** 예: `claude-opus-4-8`

> Base URL은 `/v1`에서 끝내세요. Hermes가 `/chat/completions`를 자동으로 추가하므로 전체 경로나 끝의 슬래시는 404의 원인이 됩니다.

## `config.yaml` 직접 설정

영구적인 다중 모델 설정이 필요하면 `~/.hermes/config.yaml`에 같은 값을 작성합니다.

```yaml
model:
  provider: custom
  base_url: https://api.omniakey.com/v1
  api_key: your-omniakey-api-key
  default: claude-opus-4-8
models:
  - claude-opus-4-8
  - gpt-5.5
  - gemini-3.1-pro-preview
  - grok-4.5
```

`provider: custom`은 내장 Provider가 아니라 위 endpoint를 직접 호출한다는 뜻입니다. `models:`가 `/model` 선택기를 채우므로 수정 후 Hermes를 한 번 재시작하면 세션을 떠나지 않고 `claude-opus-4-8`, `gpt-5.5`, `gemini-3.1-pro-preview`, `grok-4.5` 사이를 전환할 수 있습니다.

## 하나의 key, 네 모델 계열

OmniaKey는 OpenAI 호환 endpoint에서 model ID로 모델을 고릅니다. 두 번째 Provider나 여러 Base URL이 필요하지 않습니다. 비용은 하나의 선불 잔액에서 token 단위로 계산되며 지정한 ID가 실행됩니다. 더 싼 모델로 조용히 fallback하지 않습니다. 설정할 수 있는 모델 ID는 [모델 목록](https://omniakey.com/ko/models)에, 토큰 단가는 [가격 페이지](https://omniakey.com/ko/pricing)에 있습니다. 같은 키는 다른 에이전트에서도 쓸 수 있습니다. 자세한 내용은 [OpenClaw 설정](https://omniakey.com/ko/blog/openclaw-setup), [Cline 커스텀 API 키](https://omniakey.com/ko/blog/cline-custom-api-key), [Claude Code 설정](https://omniakey.com/ko/blog/claude-code-setup) 가이드를 참고하세요.

- **OpenAI-compatible**: <https://api.omniakey.com/v1>
- **Anthropic-native**: <https://api.omniakey.com>
- **Gemini-native**: <https://api.omniakey.com/v1beta>

## 자주 나오는 설정 오류

커스텀 endpoint를 설정할 때 자주 나오는 4가지입니다. 원인과 해결 방법은 [Hermes Provider 문서](https://hermes-agent.nousresearch.com/docs/integrations/providers)와 [설정 문서](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)를 따랐습니다.

### `/model`에 커스텀 endpoint가 보이지 않음

증상: 세션에서 `/model`을 입력해도 목록에 OmniaKey가 없습니다.

원인: 세션 안의 `/model`은 이미 설정한 Provider 사이에서만 전환합니다. Provider 추가, OAuth, API key 입력은 할 수 없습니다.

해결: 세션을 종료하고 터미널에서 `hermes model`을 실행해 커스텀 endpoint를 설정한 뒤 새 세션을 시작하세요.

### `.env`의 key가 무시되고 다른 Provider가 호출됨

증상: base URL이나 key를 `~/.hermes/.env`에 넣었는데 Hermes가 계속 내장 Provider를 호출합니다.

원인: Hermes는 `.env`의 `LLM_MODEL`을 없앴고, 모델과 endpoint는 `config.yaml`이 유일한 기준입니다. `OPENAI_BASE_URL`은 `openai-api` Provider에만 적용됩니다.

해결: `~/.hermes/config.yaml`의 `model:`에 `base_url`과 `api_key`를 넣거나, `key_env`에 key가 들어 있는 환경 변수 이름을 지정하세요. `base_url`을 설정하면 Hermes가 그 endpoint를 직접 호출하고 `api_key` 또는 `OPENAI_API_KEY`로 인증합니다.

### 최상위에 `provider: main`을 쓰면 시작되지 않음

증상: `model:`에 `provider: main`을 쓰면 시작에 실패하거나 모델 선택기가 비어 있습니다.

원인: `main`은 "메인 agent의 Provider를 쓰라"는 뜻이고, `auxiliary:`, `compression:`, fallback 안에서만 유효합니다.

해결: `model:`에 `provider: custom`을 쓰고 OmniaKey의 `base_url`, key와 함께 두세요.

### `/model custom`이 다른 모델을 고름

증상: `/model custom`이 원하지 않는 모델을 고르거나 오류가 납니다.

원인: 인자 없는 `/model custom`은 endpoint의 `/models` API에 물어보고 모델이 하나만 로드되어 있을 때만 자동 선택합니다. OmniaKey에는 여러 모델이 있습니다.

해결: `/model custom:claude-opus-4-8`처럼 모델을 지정하세요.

## 자주 묻는 질문

### Hermes Agent를 OmniaKey에 연결하려면?

`hermes model`을 실행하고 Custom endpoint (self-hosted / VLLM / etc.)를 고른 뒤 Base URL에 `https://api.omniakey.com/v1`, OmniaKey key, `claude-opus-4-8` 같은 model ID를 입력합니다. 파일을 직접 고친다면 `~/.hermes/config.yaml`에 같은 세 값을 넣으면 됩니다.

### OmniaKey base URL로 404가 나는 이유는?

base URL은 `/v1`에서 끝내야 합니다. Hermes가 `/chat/completions`를 스스로 붙이므로 전체 경로가 들어간 URL이나 끝의 슬래시가 404의 원인이 됩니다.

### OmniaKey key 하나로 Claude, GPT, Gemini, Grok을 쓸 수 있나요?

됩니다. OmniaKey는 OpenAI 호환 endpoint에서 model ID로 모델을 고르므로 커스텀 endpoint 하나로 네 계열을 모두 씁니다. 바꾸는 것은 Provider 블록이 아니라 id입니다. 쓸 id를 `models:` 목록에 넣으면 `/model` 선택기에 나타납니다.

### 세션 중간에 모델을 바꾸려면?

`/model custom:<model ID>`를 입력합니다. 예를 들어 `/model custom:gpt-5.5`입니다. `models:` 목록을 고친 뒤 Hermes를 한 번 재시작하면 선택기와 `/model` 모두 새 id를 봅니다.

## 확인한 출처

- [Nous Research: LLM 및 모델 Provider](https://hermes-agent.nousresearch.com/docs/integrations/providers)
- [Nous Research: Hermes Agent 설정](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)

다른 도구 설정은 [코딩 Agent 안내](https://docs.omniakey.com/en/coding)를 참고하세요.