> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent Desktop App

> Hermes Agent Desktop App 연동 가이드 — Custom Endpoints로 Gravitex 게이트웨이 연결

Hermes Agent Desktop App에서 Gravitex 게이트웨이를 연결하면 Hermes 내에서 Gravitex가 제공하는 모델 서비스를 직접 호출할 수 있습니다.

<Info>
  **다운로드:** [https://hermes-agent.nousresearch.com/](https://hermes-agent.nousresearch.com/)
</Info>

<Warning>
  **사전 요구사항:** Hermes Agent Desktop App이 설치되어 있고 Gravitex API Key를 발급받은 상태여야 합니다.
</Warning>

## 1. 설정 단계

### 1단계: Custom Endpoints 열기

왼쪽 메뉴에서 **Providers → Custom Endpoints**로 이동한 뒤, 아래의 **New endpoint**를 클릭하여 새 엔드포인트를 생성합니다.

<img src="https://mintcdn.com/gravitexai/25fF-22WrFQ-c5Uk/images/hermes-desktop-1.png?fit=max&auto=format&n=25fF-22WrFQ-c5Uk&q=85&s=730aeef4603f5f3c4ad370d59ebe236e" alt="Custom Endpoints 열기" width="2314" height="1206" data-path="images/hermes-desktop-1.png" />

### 2단계: Gravitex 게이트웨이 정보 입력

**Edit Endpoint** 양식에 다음과 같이 입력합니다:

| 필드                              | 입력 내용                                             |
| ------------------------------- | ------------------------------------------------- |
| **Name**                        | `gravitex`                                        |
| **Provider ID**                 | `gravitex`                                        |
| **Endpoint URL**                | `https://api.gravitex.ai/v1`                      |
| **API Key**                     | Gravitex API Key를 붙여넣으세요 (비워두면 현재 저장된 Key가 유지됩니다) |
| **Default Model** / **Context** | 선택사항; 비워두면 아래 Discover models로 자동 가져옵니다           |

**Use for new chats**와 **Discover models**에 체크하고 **Test**를 클릭하여 연결을 확인한 뒤, **Save**를 클릭하여 저장합니다.

<img src="https://mintcdn.com/gravitexai/25fF-22WrFQ-c5Uk/images/hermes-desktop-2.png?fit=max&auto=format&n=25fF-22WrFQ-c5Uk&q=85&s=a237a2aaa372ebf176ba3df9c7eabc2a" alt="Gravitex 게이트웨이 정보 입력" width="2388" height="1528" data-path="images/hermes-desktop-2.png" />

### 3단계: Gateway Connection 모드 확인

왼쪽 메뉴에서 **Gateways**로 이동하여 **Connection mode**를 확인합니다. 기본값은 **Local gateway**(로컬 실행, 오프라인 지원)이며, Gravitex 연동 시에는 일반적으로 변경할 필요가 없습니다. Hermes 백엔드를 원격지나 클라우드에서 실행해야 할 경우에만 Hermes Cloud / Remote gateway / Connect via SSH로 전환하세요.

<img src="https://mintcdn.com/gravitexai/25fF-22WrFQ-c5Uk/images/hermes-desktop-3.png?fit=max&auto=format&n=25fF-22WrFQ-c5Uk&q=85&s=9ca69533fa8104472c7c5a958658ec4c" alt="Gateway Connection 모드 확인" width="2408" height="1428" data-path="images/hermes-desktop-3.png" />

### 4단계: Model에서 gravitex 선택

왼쪽 메뉴에서 **Model**로 이동하여, 2단계에서 설정한 `gravitex`를 모델 드롭다운에서 선택하고 **Apply**를 클릭하여 적용합니다. Vision, Web extract, Compression, Skills hub, Approval, MCP, Title gen 등 보조 작업에 별도 모델을 지정하려면 아래 **Auxiliary models**에서 항목별로 **Change**를 클릭하세요. 기본적으로는 모두 메인 모델을 따릅니다 (`auto · use main model`).

<img src="https://mintcdn.com/gravitexai/25fF-22WrFQ-c5Uk/images/hermes-desktop-4.png?fit=max&auto=format&n=25fF-22WrFQ-c5Uk&q=85&s=a244df72c07db9356b3102b078fbd56e" alt="Model에서 gravitex 선택" width="2422" height="1472" data-path="images/hermes-desktop-4.png" />

### 5단계: 메시지 전송 테스트

**Chat** 페이지로 돌아가 메시지를 전송하여 gravitex 게이트웨이로부터 정상적인 응답을 받는지 확인합니다.

## 2. 성공 확인 방법

* Model 선택기에서 `gravitex`가 보이고 선택한 뒤 **Apply** 클릭 시 오류가 없어야 합니다.
* Chat에서 메시지를 전송한 후 `invalid api key` / `endpoint unavailable` / `model_not_found` 오류 없이 정상적인 응답을 받아야 합니다.

## 3. 문제 해결

| 증상                           | 원인                                                          | 해결 방법                                                                           |
| ---------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Invalid API key / 401        | API Key가 잘못되었거나, 만료되었거나, 비활성화됨                              | Key를 재생성하여 API Key 필드에 붙여넣고 저장하세요 (비워두면 초기화되지 않고 이전 Key가 유지됩니다)                 |
| Endpoint unavailable / 연결 불가 | Endpoint URL이 잘못되었거나 네트워크에 연결할 수 없음                         | Endpoint URL이 `https://api.gravitex.ai/v1`인지 확인하고, 해당 도메인에 네트워크에서 접근 가능한지 확인하세요 |
| model\_not\_found            | Default Model에 입력한 모델 ID가 지원되지 않음                           | **Discover models**에 체크하여 사용 가능한 모델 목록을 자동으로 가져오거나, 모델 ID 철자를 확인하세요             |
| Model 목록에서 gravitex를 찾을 수 없음 | Custom Endpoint가 저장되지 않았거나 **Use for new chats**에 체크되지 않음   | **Save**를 클릭했는지, **Use for new chats**에 체크되었는지 확인하세요                            |
| 메시지 전송 후 응답 없음               | Gateway Connection 모드가 잘못됨 (예: 구성되지 않은 Remote gateway로 전환됨) | Connection mode가 **Local gateway**(기본값, 오프라인 사용)인지 확인하고, 필요하지 않다면 전환하지 마세요      |
| Save 버튼 클릭 효과 없음             | Name / Endpoint URL 등 필수 입력 항목이 비어 있음                       | 필수 입력 항목이 모두 채워졌는지 확인한 후 다시 시도하세요                                               |

## 4. 보안 안내

* **API Key는 비밀번호와 동일**합니다. 공개 문서, 채팅 기록, 스크린샷 또는 코드 저장소에 작성하지 마세요.
* Custom Endpoint 세부 정보에는 환경 변수 형식으로(Key가 표시될 수 있습니다. 공공 장소에서 스크린샷을 공유하지 마세요.
* Key가 채팅, 로그 또는 스크린샷에서 유출된 경우 즉시 Gravitex 콘솔에서 폐기하고 재생성하세요.