Hermes

Hermes는 Nous Research의 오픈 소스 에이전트입니다. 내장된 hermes model 마법사로 HiAPI를 사용자 지정 엔드포인트로 추가할 수 있으므로 서드파티 관리 도구가 필요 없습니다. 아래 단계는 claude-opus-5-5를 예로 사용하며, 이 튜토리얼은 Windows에서 Hermes 0.22.5로 검증했습니다.

1. Hermes 설치

1.1 요구 사항

1.2 Windows(PowerShell)

설정 마법사를 건너뛰고 설치 후 모델만 구성하려면:

& ([scriptblock]::Create((irm https://hermes-agent.nousresearch.com/install.ps1))) -SkipSetup

표준 설치(설정 마법사 실행):

iex(irm https://hermes-agent.nousresearch.com/install.ps1)

1.3 macOS / Linux

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-setup

1.4 설치 확인

터미널을 다시 열고 실행하세요:

hermes --version

버전 번호가 보이면 충분합니다. 출력이 나오면 계속하세요.

1.5 기타 설치 방법

설치 스크립트와 버전 요구 사항은 Hermes 공식 설치 문서를 따릅니다.

2. HiAPI 엔드포인트 구성

Hermes에는 용도가 다른 모델 관련 명령이 두 개 있습니다. 혼동하지 마세요:

HiAPI를 추가하려면 hermes model을 사용하므로 먼저 세션을 종료하세요(Ctrl+C 또는 /quit).

2.1 설정 마법사 실행

hermes model

**Custom endpoint (self-hosted / VLLM / etc.)**를 선택하세요(일부 버전은 **Custom endpoint (enter URL manually)**로 표시).

2.2 각 입력 항목 채우기

Claude 모델은 API compatibility mode로 Anthropic Messages를 선택하세요. claude-opus-5-5를 예로 들면:

Anthropic Messages 모드에서는 API base URL을 /v1 없이 루트 주소 https://api.hiapi.ai로 설정하세요. Hermes가 /v1/messages를 직접 덧붙입니다. HiAPI API 키는 입력하는 동안 가려지거나 별표로 표시됩니다. 붙여 넣고 Enter를 누르세요.

2.3 GPT, DeepSeek 등 다른 모델 연결

GPT, DeepSeek 등 다른 모델은 위 표와 같이 나머지 항목을 채우고 아래 두 항목만 바꾸며, Model name은 해당 모델 이름으로 바꾸세요. 여기서는 주소에 /v1이 포함된다는 점에 주의하세요.

이 튜토리얼에서 테스트한 조합은 Claude에는 Anthropic Messages, GPT와 DeepSeek에는 Chat Completions입니다. 모델이 선택한 프로토콜을 지원하지 않으면 400이 반환됩니다.

2.4 다른 모델로 전환

같은 엔드포인트에서 모델을 바꾸려면 세션에서 직접 입력하세요:

/model custom:<model-id>

또는 hermes model을 다시 실행해 기본 모델을 바꾸세요. 다른 모델로 전환할 때는 텍스트 모델 목록에서 모델 이름을 찾고 컨텍스트가 최소 64K인지 확인하세요. 사용자 지정 엔드포인트의 추가 옵션은 Hermes 사용자 지정 엔드포인트 문서에 있습니다.

3. 수동 구성(선택 사항)

아래 수동 구성은 Chat Completions를 사용하는 GPT, DeepSeek 등에 적용됩니다. Claude는 위의 hermes model 마법사를 사용하세요. 마법사를 사용할 수 없다면 ~/.hermes/config.yaml을 직접 편집하세요(base_url에 /v1이 포함되어야 함):

model:
  default: <model-id>
  provider: custom
  base_url: https://api.hiapi.ai/v1
  api_key: YOUR_HIAPI_API_KEY

평문 키 대신 환경 변수를 사용할 수도 있습니다. key_env는 Hermes가 환경 변수를 읽는 방식이므로 그대로 두세요:

model:
  default: <model-id>
  provider: custom
  base_url: https://api.hiapi.ai/v1
  key_env: HIAPI_API_KEY

그다음 ~/.hermes/.env에 이렇게 작성하세요:

HIAPI_API_KEY=YOUR_HIAPI_API_KEY

YOUR_HIAPI_API_KEY를 자신의 HiAPI API 키로 바꾸세요. 구성을 바꾼 뒤에는 /new로 새 세션을 시작하거나 Hermes를 재시작한 다음 테스트하세요.

4. 확인

4.1 채팅

Hermes를 열고 HiAPI 공급자를 사용하는지 확인한 뒤 “안녕하세요, 한 문장으로 자기소개를 해 주세요.”를 보내세요. 정상적으로 답하면 연결이 된 것입니다.

4.2 도구 호출

먼저 Hermes를 시작하는 폴더에 tool-call-test.txt를 만들고 hello hiapi 한 줄을 써서 저장하세요. 그다음 “도구를 한 번만 호출하세요. tool-call-test.txt의 전체 내용을 읽고 그대로 반환하세요. 파일 이름으로 내용을 추측하지 마세요.”를 보내세요. 도구 호출이 나타나고 hello hiapi를 반환하는지 확인하세요.

5. 문제 해결

여기에는 Hermes에 특화된 문제만 정리했습니다. 401, 404, 429 같은 일반적인 오류는 자주 발생하는 오류를 참고하세요.

이 페이지는 텍스트 모델만 다룹니다. 도구 기능은 MCP 가이드를 참고하세요.