> ## 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 步：打开 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 网关正常返回的回复。

## 二、验证是否成功

* Model 选择器中能看到并成功选中 `gravitex`，点击 **Apply** 后无报错。
* 在 Chat 中发送消息后能正常收到回复，没有出现 `invalid api key` / `endpoint unavailable` / `model_not_found` 等报错。

## 三、常见问题排查

| 现象                          | 原因                                                 | 处理                                                              |
| --------------------------- | -------------------------------------------------- | --------------------------------------------------------------- |
| 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 等必填字段为空                        | 检查必填字段是否填全后重试                                                   |

## 四、安全须知

* **API Key 等同于密码**，不要写入公开文档、聊天记录、截图或代码仓库。
* Custom Endpoint 详情中可能以环境变量形式（如 `${HERMES_CUSTOM_GRAVITEX_API_KEY}`）显示 Key 信息，请勿在公共环境下截图分享。
* 若 Key 已在聊天、日志或截图中泄露，应立即在 Gravitex 后台作废并重新生成。