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

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

hermes model

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

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

config.yaml 직접 설정

영구적인 다중 모델 설정이 필요하면 ~/.hermes/config.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는 모델 목록에, 토큰 단가는 가격 페이지에 있습니다. 같은 키는 다른 에이전트에서도 쓸 수 있습니다. 자세한 내용은 OpenClaw 설정, Cline 커스텀 API 키, Claude Code 설정 가이드를 참고하세요.

자주 나오는 설정 오류

커스텀 endpoint를 설정할 때 자주 나오는 4가지입니다. 원인과 해결 방법은 Hermes Provider 문서와 설정 문서를 따랐습니다.

/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
• Nous Research: Hermes Agent 설정

다른 도구 설정은 코딩 Agent 안내를 참고하세요.