> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/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)

## 核心功能

<CardGroup cols={3}>
  <Card title="智能代理" icon="robot">
    原生支援工具調用、檔案讀寫和代碼執行，支援後台常駐運行和長期記憶
  </Card>

  <Card title="多渠道整合" icon="message">
    透過訊息閘道統一管理 Telegram、Discord、Slack、WhatsApp 等平台
  </Card>

  <Card title="開放模型生態" icon="plug">
    內建 Custom Endpoint 支援，可接入任何 OpenAI 兼容 API
  </Card>
</CardGroup>

## 接入前準備

<Steps>
  <Step title="準備 Mixroute 地址">
    獲取一個可用的 Mixroute 地址，例如：`https://api.mixroute.ai/v1`

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

  <Step title="獲取 API Key">
    在 Mixroute 控制台生成 API Key
  </Step>

  <Step title="選擇模型">
    確定要使用的模型名稱，需與 Mixroute 控制台中的模型 ID 完全一致（如 `gpt-5.5`）
  </Step>
</Steps>

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

## 安裝 Hermes Agent

<Tabs>
  <Tab title="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
    ```
  </Tab>

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

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

<Check>
  運行 `hermes --version`，如果顯示版本號，說明安裝成功。
</Check>

## 設定 Mixroute 接入

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

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

<Steps>
  <Step title="選擇 Provider">
    用方向鍵滾動到 **Custom Endpoint**（或類似的「自定義端點」選項），按回車確認。

    <Tip>
      多供應商場景建議在平台上配置多個 SK 做區分管理。
    </Tip>
  </Step>

  <Step title="填寫 Base URL">
    輸入你的 Mixroute 地址，例如：

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

    <Warning>
      這是最常見的配置錯誤來源，需使用模型原生能力，請參考 API 手冊和模型廣場信息，修訂 Base URL。

      不匹配的端點或會造成 Hermes 無法工作或額外費用。
    </Warning>
  </Step>

  <Step title="填寫 API Key">
    輸入你在 Mixroute 控制台生成的 API Key，例如：

    ```text theme={null}
    sk-xxxxxxxxxxxxxxxx
    ```
  </Step>

  <Step title="填寫模型名稱">
    輸入你想使用的模型，例如：

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

    <Warning>
      模型名稱必須與 Mixroute 模型廣場中的 ID **完全一致**，否則會報模型不存在的錯誤。
    </Warning>
  </Step>

  <Step title="選擇 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`。
  </Step>
</Steps>

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

<Tip>
  [Smart Routing](https://console.mixroute.ai/smart-route) 是一項智能模型路由能力，能夠根據輸入任務的複雜程度，自動將請求分配至最合適的模型，通過智能分配起到降本增效的作用。

  參考下列配置項添加供應商資訊即可完成接入，相關約束和指南見[此處](/zh-hant/smart-routing)。

  ```text theme={null}
  # Smart Routing
  API Key : <you smart routing key>
  API Host : https://api.mixroute.ai/v1
  Models: auto
  ```
</Tip>

### 關鍵設定說明

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

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

## 驗證接入

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

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

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

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

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

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

<Check>
  如果模型正常回覆，說明接入成功。
</Check>

### 查看和切換模型

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

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

## 常見問題

<Accordion title="回覆為空或報錯">
  檢查 Base URL 是否以 `/v1` 結尾
</Accordion>

<Accordion title="提示模型不存在">
  確認模型名稱與 Mixroute 控制台中的模型 ID 完全一致
</Accordion>

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

<Accordion title="不知道怎麼進入設定選單">
  在終端輸入 `hermes model` 並回車
</Accordion>

<Accordion title="想切換模型">
  重新運行 `hermes model`，或在對話中輸入 `/model`
</Accordion>

<Accordion title="想修改之前的設定">
  再次運行 `hermes model`，會覆蓋之前的設定
</Accordion>

<Accordion title="Windows 上無法安裝">
  Hermes 不原生支援 Windows，請先安裝 WSL2，在 WSL2 終端中執行安裝指令
</Accordion>

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