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

# Hermes

> 如何安裝和設定 Hermes Agent，並透過 Custom Endpoint 接入 Mixroute API

Hermes Agent 是由 Nous Research 出品的開源終端 AI Agent，在你的終端中提供強大的工具調用、檔案讀寫和代碼執行能力。透過內建的 Custom Endpoint 能力，Hermes 可以無縫接入任何 OpenAI 兼容 API — 包括 Mixroute，全程無需寫任何代碼或插件。

* 官方主頁：[hermes-agent.nousresearch.com](https://hermes-agent.nousresearch.com)
* 快速開始：[Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)
* GitHub：[NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)

## 核心功能

> **智能代理**
>
> 原生支援工具調用、檔案讀寫和代碼執行，支援後台常駐運行和長期記憶

> **多渠道整合**
>
> 透過訊息閘道統一管理 Telegram、Discord、Slack、WhatsApp 等平台

> **開放模型生態**
>
> 內建 Custom Endpoint 支援，可接入任何 OpenAI 兼容 API

## 接入前準備

**1. 準備 Mixroute 地址**

獲取一個可用的 Mixroute 地址，例如：`https://api.mixroute.ai/v1`

> [!NOTE]
>
> 如若需要使用原生端口，需要根據 API 手冊中的端點進行設定，建議保持指南中的設定，避免因端點不同導致的錯誤和故障。

**2. 獲取 API Key**

在 Mixroute 控制台生成 API Key

**3. 選擇模型**

確定要使用的模型名稱，需與 Mixroute 控制台中的模型 ID 完全一致（如 `gpt-5.5`）

> [!NOTE]
>
> Hermes Agent 要求所使用的模型至少支援 64K tokens 的上下文視窗。選擇模型時請確認它滿足此要求，否則可能出現 context 不足的報錯。

## 安裝 Hermes Agent

**Linux / macOS / WSL2**

在終端中運行官方一鍵安裝腳本：

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```

安裝完成後，重新載入終端環境變數：

```bash theme={null}
source ~/.bashrc	# 如果使用的是zsh，請使用 source ~/.zshrc
```

**Windows**

> [!WARNING]
>
> Hermes Agent 本身不直接支援 Windows 原生環境，你需要先安裝 WSL2（Windows Subsystem for Linux 2），然後在 WSL2 終端中運行上方的 Linux/macOS 安裝指令。

WSL2 安裝參考：[Microsoft WSL 安裝指南](https://learn.microsoft.com/windows/wsl/install)

> [!TIP]
>
> 運行 `hermes --version`，如果顯示版本號，說明安裝成功。

## 設定 Mixroute 接入

這是整個接入流程中最關鍵的一步。Hermes Agent 提供了互動式選單，用戶無需寫任何代碼或手動編輯設定檔案，只需根據提示填入 Mixroute 的 URL、Key 和模型名即可。

> [!NOTE]
>
> 設定完成之後想要更換、或未成功在互動式引導下完成供應商設定，可以 Hermes Agent 部署後隨時運行 `hermes model` 來覆蓋之前的設定，重新填入新的 URL、Key 或模型名。

**1. 選擇 Provider**

用方向鍵滾動到 **Custom Endpoint**（或類似的「自定義端點」選項），按回車確認。

> [!TIP]
>
> 多供應商場景建議在平台上配置多個 SK 做區分管理。

**2. 填寫 Base URL**

輸入你的 Mixroute 地址，例如：

```text theme={null}
https://api.mixroute.ai/v1
```

> [!WARNING]
>
> 這是最常見的配置錯誤來源，需使用模型原生能力，請參考 API 手冊和模型廣場信息，修訂 Base URL。
>
> 不匹配的端點或會造成 Hermes 無法工作或額外費用。

**3. 填寫 API Key**

輸入你在 Mixroute 控制台生成的 API Key，例如：

```text theme={null}
sk-xxxxxxxxxxxxxxxx
```

**4. 填寫模型名稱**

輸入你想使用的模型，例如：

```text theme={null}
gpt-5.5
```

> [!WARNING]
>
> 模型名稱必須與 Mixroute 模型廣場中的 ID **完全一致**，否則會報模型不存在的錯誤。

**5. 選擇 API 的模式**

hermes 有下列四種兼容的模式，根據使用的模型進行選擇，Hermes 默認為 Auto-detect。

1. `Auto-detect [current] `使用 Hermes 自動兼容，適用於標準的 OpenAI-compatible 端點。
2. `Chat Completions` 使用 `/chat/completions` 標準的 OpenAI-compatible 端點或服務。
3. `Responses / Codex` 使用與 Codex 兼容的端點 `/responses`。
4. `Anthropic Messages` 使用與 Anthropic 端點 `/v1/messages`。

### 智能路由方式接入（可選）

> [!TIP]
>
> [Smart Routing](https://console.mixroute.ai/smart-route) 是一項智能模型路由能力，能夠根據輸入任務的複雜程度，自動將請求分配至最合適的模型，通過智能分配起到降本增效的作用。
>
> 參考下列配置項添加供應商資訊即可完成接入，相關約束和指南見[此處](/docs/zh-Hant/smart-routing)。
>
> ```text theme={null}
> # Smart Routing
> API Key : <you smart routing key>
> API Host : https://api.mixroute.ai/v1
> Models: auto
> ```

### 關鍵設定說明

**傳統API節點配置**

| 設定項 | 說明 | 範例 |
| - | - | - |
| Base URL | Mixroute 地址，必須以 `/v1` 結尾 | `https://api.mixroute.ai/v1` |
| API Key | Mixroute 控制台生成的令牌 | `sk-xxxxxxxxxxxxxxxx` |
| Model | 模型名稱，需與 Mixroute 實際暴露的模型 ID 一致 | `gpt-5.5` |

**智能路由節點配置**

| 設定項 | 說明 | 範例 |
| :- | :- | :- |
| Base URL | Mixroute Smart Routing 地址，必須以 `/v1` 結尾 | `https://api.mixroute.ai/v1` |
| API Key | Mixroute Smart Routing 控制台生成的令牌 | `sk-xxxxxxxxxxxxxxxx` |
| Model | 模型名稱，使用時將在後台根據任務複雜程度路由 | `auto` |

## 驗證接入

設定完成後，直接啟動 Hermes 開始對話：

```bash theme={null}
hermes
```

或使用更現代的 TUI 模式（終端圖形界面）：

```bash theme={null}
hermes --tui
```

隨便輸入一條測試訊息，例如：

```text theme={null}
你好，告訴我今天星期幾
```

> [!TIP]
>
> 如果模型正常回覆，說明接入成功。

### 查看和切換模型

在對話中直接輸入以下指令，可以查看當前使用的模型，並快速切換：

```text theme={null}
/model
```

## 常見問題

> **回覆為空或報錯**
>
> 檢查 Base URL 是否以 `/v1` 結尾

> **提示模型不存在**
>
> 確認模型名稱與 Mixroute 控制台中的模型 ID 完全一致

> **提示 API Key 無效**
>
> 在 Mixroute 控制台重新生成一個 Key，然後再次運行 `hermes model`

> **不知道怎麼進入設定選單**
>
> 在終端輸入 `hermes model` 並回車

> **想切換模型**
>
> 重新運行 `hermes model`，或在對話中輸入 `/model`

> **想修改之前的設定**
>
> 再次運行 `hermes model`，會覆蓋之前的設定

> **Windows 上無法安裝**
>
> Hermes 不原生支援 Windows，請先安裝 WSL2，在 WSL2 終端中執行安裝指令

> [!NOTE]
>
> 接入 Mixroute 後，所有 Hermes Agent 的後續能力（訊息閘道、技能調用、後台常駐等）都會透過 Mixroute 調用你選擇的模型，無需再為每個功能單獨設定模型提供商。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.