Hermes 설치 및 OmniProxy 구성

Hermes는 대화와 작업 경험을 보관할 수 있는 어시스턴트로, 이전에 수행한 일을 나중에 다시 사용할 수 있는 스킬로 정리할 수 있습니다. 또한 동일한 Gateway를 통해 Telegram, Discord, Slack, WhatsApp, Signal 및 터미널에 연결할 수 있습니다. Gateway는 메시지를 통합해서 수신하고 전달하는 진입점이라고 이해하면 됩니다. 평소 사용하는 채팅 도구에서 코드 리뷰, 장애 기록 또는 고객 자료를 맡긴 다음, 저장소로 돌아가 작업을 계속 처리하게 할 수 있습니다.

설치 전 준비

먼저 컴퓨터 운영체제에 따라 설치 방법을 선택합니다. macOS와 Windows에서는 창이 있는 설치 패키지를 바로 사용할 수 있고, Linux, macOS 및 WSL2에서는 터미널 스크립트를 사용할 수 있습니다. WSL2는 Windows에서 Linux 환경을 실행하는 기능입니다. Android 휴대전화의 Termux와 Docker에도 각각 별도의 설치 방법이 있지만, 이 문서에서는 일반 컴퓨터에서의 설치만 설명합니다.

창이 필요한 경우

macOS, Windows

macOS: DMG 열기
Windows: 설치 패키지 열기
애플리케이션을 시스템에 추가

터미널만 필요한 경우

Linux, macOS, WSL2

install.sh 한 줄
Windows에서는 install.ps1 사용
설치 후 hermes 입력

지금은 사용하지 않기

pip, brew, AUR

공식적으로 지원되지 않는 설치 방식
설치 후에도 업데이트하기 어려움
왼쪽의 두 가지 방식 사용

이 문서에서 사용할 두 가지 방법은 창이 있는 설치 패키지와 터미널 스크립트입니다. pip, brew, AUR은 공식적으로 지원되는 설치 방법이 아닙니다.

시작하기 전에 macOS, Windows 또는 Linux 컴퓨터를 준비하고, 터미널을 열 수 있으며 GitHub에 접속할 수 있는지 확인합니다. 외장 드라이브에 설치하려는 경우에는 먼저 드라이브를 연결하고 충분한 공간이 있는지도 확인합니다.

설치 및 최초 실행

창이 있는 버전을 원하는 경우

Hermes 공식 웹사이트의 다운로드 영역으로 이동하여 운영체제에 맞는 설치 패키지를 다운로드합니다. 설치 패키지에는 실행 환경이 이미 포함되어 있으므로 처음 열 때 컴퓨터에서 직접 컴파일할 필요가 없습니다.

macOS: DMG를 열고 Hermes.app을 「응용 프로그램」에 넣습니다. DMG는 macOS에서 일반적으로 사용하는 설치 이미지 파일입니다. 이 설치 패키지는 Apple 칩만 지원하며 Intel Mac은 지원 대상이 아닙니다.
Windows: Windows의 앱 설치 관리자로 .appinstaller를 엽니다. 서명된 MSIX가 설치되며, MSIX는 Windows에서 사용하는 애플리케이션 설치 패키지 형식입니다.
Linux: 데스크톱 설치 패키지는 macOS와 Windows용입니다. Linux에서는 아래 터미널 명령을 사용하고, 설치 후 hermes desktop을 실행할 수 있습니다.

터미널만 필요한 경우

Linux, macOS 또는 WSL2를 사용한다면 터미널에서 다음 명령을 실행합니다.

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

Windows에 기본으로 포함된 PowerShell을 사용할 때는 다음 명령을 실행합니다.

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

설치 프로그램이 Hermes 코드와 실행에 필요한 프로그램을 다운로드합니다. 도중에 다운로드가 중단되면 같은 명령을 다시 실행하면 됩니다. 설치가 완료되면 현재 터미널을 닫고 새 창을 연 다음 다음을 입력합니다.

hermes

Hermes 프롬프트가 표시되면 명령을 사용할 수 있는 상태입니다. 이어서 hermes doctor를 실행할 수 있습니다. 이 명령은 설치 상태를 검사하고 현재 누락된 항목을 알려줍니다.

프로그램을 외장 드라이브에 설치하기

2026년 10월 9일에 Hermes Agent v0.21.6을 Mac의 외장 드라이브에 설치했습니다. 프로그램은 /Volumes/AItools/tools/hermes-agent에 있고, 실행 명령은 ~/.local/bin/hermes에 있으며, 구성과 대화는 계속 ~/.hermes에 저장됩니다.

드라이브 이름이 다르다면 --dir 뒤의 경로를 자신의 폴더로 변경합니다. Hermes를 실행하는 동안 이 드라이브는 계속 연결되어 있어야 합니다.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o install.sh
bash install.sh --dir /Volumes/AItools/tools/hermes-agent --non-interactive

프로그램

외장 하드 드라이브

tools/hermes-agent
코드는 여기에 저장

명령

~/.local/bin/hermes

터미널에서 hermes 입력
새 창을 열면 적용됨

설정 및 대화

~/.hermes

config.yaml이 여기에 있음
드라이브를 분리하기 전에 먼저 종료

해당 Mac에서 사용한 디렉터리 구성입니다. 기본 설치에서는 프로그램을 사용자 디렉터리에 배치하지만 결과는 같습니다. 새 터미널을 연 뒤 hermes를 입력하면 됩니다.

OmniProxy에서 연결 매개변수 가져오기

여기서 Hermes는 Grok 또는 Gemini에 직접 연결하는 것이 아니라 OmniProxy에 연결합니다. Grok과 Gemini의 서비스 주소는 OmniProxy에서 구성하며, Hermes에 직접 입력하면 안 됩니다.

내 컴퓨터

Hermes

로컬 게이트웨이

OmniProxy

주소는 /v1까지 입력

Grok

grok-4.7

Gemini

gemini-3.8-flash

Hermes에서 보이는 대상은 OmniProxy입니다. Grok과 Gemini는 OmniProxy가 전달합니다.

모델 ID는 API가 모델을 식별하는 데 사용하는 정확한 이름입니다. 두 모델에는 각각 다음 이름을 사용합니다.

Grok에는 grok-4.7을 입력합니다. xAI API 주소는 https://api.x.ai/v1이며, 채팅 요청은 /v1/chat/completions를 사용합니다. Grok 모델 문서를 참고하세요.
Gemini에는 gemini-3.8-flash를 입력합니다. Google의 OpenAI 호환 API 주소는 https://generativelanguage.googleapis.com/v1beta/openai/입니다. Gemini의 OpenAI 호환 안내를 참고하세요.

Hermes에서 Gemini로 변경하려면 모델 이름만 gemini-3.8-flash로 바꾸고, API 주소에는 계속 OmniProxy 주소를 입력합니다.

OmniProxy에서 API 주소와 키를 복사한 다음 해당 모델 ID를 입력합니다.

Base URL: https://your-omniproxy-origin.example/v1
API Key:  <YOUR_OMNIPROXY_API_KEY>
Model ID: grok-4.7

Base URL은 Hermes가 요청을 보내는 API 주소이며, 여기서는 /v1로 끝나야 합니다. API Key는 OmniProxy가 Hermes에 발급한 키입니다. 자신의 값으로 바꾸고 공개 페이지에 올리지 마세요.

로컬 OmniProxy에서 키를 요구하지 않는 경우 API Key를 비워 둘 수 있습니다. 주소에 다른 사람이 접근할 수 있다면 키를 입력해야 합니다. 또한 Hermes가 실행되는 환경에서 이 주소에 접근할 수 있는지도 확인해야 합니다. Hermes와 OmniProxy가 같은 컴퓨터에서 실행된다면 로컬 주소를 사용할 수 있습니다.

도구 구성 입력

먼저 진행 중인 채팅을 종료한 다음 터미널에서 다음 명령을 실행합니다.

hermes model

**Custom endpoint (self-hosted / VLLM / etc.)**를 선택합니다. Custom endpoint는 사용자 지정 API를 의미하며, Hermes가 미리 설정된 공급자 대신 사용자가 지정한 서비스 주소에 연결하도록 합니다.

마법사가 API 주소, 키, 모델 이름을 차례로 묻습니다. 이전 절의 세 가지 값을 입력합니다. Gemini를 사용하려면 모델 이름에 gemini-3.8-flash를 입력합니다.

~/.hermes/config.yaml을 직접 편집할 수도 있습니다. YAML은 들여쓰기로 구성 간의 관계를 표현하는 텍스트 형식입니다. 다음은 Grok 구성입니다.

model:
  default: grok-4.7
  provider: custom
  base_url: https://your-omniproxy-origin.example/v1
  api_key: <YOUR_OMNIPROXY_API_KEY>

Gemini를 사용할 때는 default를 gemini-3.8-flash로 바꾸고 나머지 세 항목은 그대로 둡니다.

model:
  default: gemini-3.8-flash
  provider: custom
  base_url: https://your-omniproxy-origin.example/v1
  api_key: <YOUR_OMNIPROXY_API_KEY>

저장한 뒤 hermes를 다시 실행하고 채팅을 시작합니다. 이미 열려 있는 세션에서 /model은 저장된 공급자 사이를 전환할 때만 사용할 수 있으며, 이 구성을 새로 추가하는 용도로는 사용할 수 없습니다.

실제 작업 검증

hermes doctor

설치 검사를 통과함

짧은 문장 보내기

Hermes의 응답 확인

호출 기록 열기

모델 이름 확인

세 단계를 모두 완료해야 이 구성을 사용할 수 있다고 판단할 수 있습니다.

hermes doctor를 실행하여 설치가 완전한지 확인합니다.
hermes를 실행하고 자신이 무엇을 할 수 있는지 한 문장으로 설명하게 합니다. 응답이 표시되어야 합니다.
OmniProxy의 호출 기록을 열어 이번 요청이 Hermes에서 전송되었는지 확인하고, 모델 이름이 grok-4.7 또는 gemini-3.8-flash인지 검사합니다.

마법사에서 저장 성공 메시지가 표시되거나 API가 성공 응답을 반환한 것만으로는 Hermes가 실제 작업을 대신 수행할 수 있다고 판단할 수 없습니다. 호출 기록의 모델 이름이 입력한 값과 일치해야 합니다.

브라우저에서 채팅하려면 로컬 컴퓨터에서 다음 명령을 실행합니다.

hermes dashboard --no-open --host 127.0.0.1 --port 9119

그런 다음 http://127.0.0.1:9119를 엽니다. 이 주소는 현재 컴퓨터에서만 유효합니다.

자주 발생하는 오류

hermes를 입력했을 때 명령을 찾을 수 없다는 메시지가 표시되는 경우: 먼저 터미널을 닫고 새 창을 엽니다. 그래도 찾지 못한다면 ~/.local/bin이 PATH에 포함되어 있는지 확인합니다. PATH는 시스템이 명령이 있는 디렉터리를 찾을 때 사용하는 위치 목록입니다. Windows에서는 설치 프로그램이 추가한 실행 디렉터리가 PATH에 포함되어 있는지 확인합니다.
설치 다운로드가 중간에 끊긴 경우: 같은 설치 명령을 다시 실행합니다. 이미 다운로드한 부분은 계속 사용됩니다.
Hermes가 응답하지 않거나 연결할 수 없다는 메시지가 표시되는 경우: OmniProxy가 실행 중인지 확인하고 Base URL이 /v1로 끝나는지 검사합니다. Hermes가 Docker에서 실행되고 OmniProxy가 호스트 컴퓨터에서 실행되는 경우 컨테이너 내부에서만 유효한 127.0.0.1을 사용하면 안 됩니다.
키가 잘못되었다는 메시지가 표시되는 경우: OmniProxy 키를 갱신한 다음 config.yaml의 api_key를 수정합니다. xAI 또는 Google 키는 OmniProxy의 공급자 설정에 속하므로 Hermes의 이 항목에 입력하면 안 됩니다.
해당 모델이 없다는 메시지가 표시되는 경우: OmniProxy의 현재 모델 목록을 열고 목록에 표시된 표기 그대로 grok-4.7 또는 gemini-3.8-flash를 복사합니다.
응답은 하지만 파일 읽기나 명령 실행 같은 작업을 수행하지 못하는 경우: OmniProxy에서 이러한 기능을 갖춘 다른 모델로 변경한 다음 Hermes를 새로 시작합니다.
프로그램이 외장 드라이브에 있고 드라이브를 분리한 뒤 hermes doctor에서 저장소 오류가 발생하는 경우: 먼저 해당 드라이브를 다시 연결합니다. 드라이브가 연결되지 않은 상태에서 Hermes가 별도의 구성을 새로 작성하게 하지 마세요.

공식 참고 자료

설치 절차는 Hermes 설치 문서와 플랫폼 지원을 참고하세요. Custom endpoint 구성은 Hermes Provider 문서를 참고하세요. 모델 ID는 각각 Grok 모델 문서와 Gemini의 OpenAI 호환 안내를 참고하세요.

macOS 설치는 2026-10-09에 Hermes Agent v0.21.6을 사용하여 전체 절차를 완료했습니다. grok-4.7과 gemini-3.8-flash는 당일 xAI 및 Google 문서에 기재된 표준 모델 ID입니다. 실제로 입력할 때는 OmniProxy에 표시된 이름을 기준으로 사용하세요.

모든 플레이스홀더를 고유한 OmniProxy 구성의 값으로 바꾸세요. 실제 키를 게시하지 마세요.

저장된 결과나 HTTP 200 만으로는 전체 에이전트 호환성이 입증되지 않습니다. OmniProxy 호출 기록에서 소스와 모델을 확인하세요.

공식 소스 · Hermes ↗