Hermes 接入

    前置條件

    • 已在 Gate.AI 控制台 建立 API 金鑰。
    • 若使用自動路由，請在控制台 設定 → 路由 中開啟 自動路由。

    方式一：終端機設定

    1. 選擇模型與自訂端點

    在終端機執行：

    bash
    1hermes model

    在選單中選擇 Custom endpoint，依提示填寫：

    項值
    API base URLhttps://api.gate.ai/openai/v1
    API key你的 Gate.AI API 金鑰
    Modelauto（建議自動路由），或控制台列出的完整模型 ID（如 deepseek/deepseek-v3.2）

    若詢問 context length（上下文長度），直接按 Enter 留空即可（由 Hermes 自動偵測）。

    2.（選用）本機 Web 管理介面

    若希望以瀏覽器編輯設定，可執行：

    bash
    1hermes dashboard

    3. 驗證

    bash
    1hermes chat "Hello"

    成功表示請求已到達 Gate.AI，並由智能路由或你指定的模型回傳結果。

    也可執行 hermes doctor 驗證是否連線成功。

    方式二：直接編輯設定檔

    1. 檔案位置

    macOS / Linux

    • ~/.hermes/config.yaml ，主要設定（模型、provider、base_url、api_key 等）
    • ~/.hermes/.env ，金鑰與敏感環境變數（建議）

    Windows

    • C:\Users<使用者名稱>.hermes\config.yaml
    • C:\Users<使用者名稱>.hermes.env

    2. 在 .env 中儲存金鑰（擇一）

    寫法 A（與 Gate.AI 命名一致）

    bash
    1# Gate.AI API 密钥2GATEAI_API_KEY=sk-v1-xxxxxxxxxxxxxxxxxxxxx

    寫法 B（與 Hermes 自訂端點常見約定一致）

    Hermes 對自訂端點在未單獨設定 model.api_key 時，會退回使用 OPENAI_API_KEY。可將 Gate.AI 金鑰寫入：

    toml
    1OPENAI_API_KEY=sk-v1-xxxxxxxxxxxxxxxxxxxxx

    3. 在 config.yaml 中設定 model

    自動路由（auto）

    yaml
    1model:2  default: auto3  provider: custom4  base_url: https://api.gate.ai/openai/v15  api_key: ${GATEAI_API_KEY}

    若使用 寫法 B，可將 api_key 留空或刪除該欄位，讓 Hermes 使用 OPENAI_API_KEY。

    Hermes 會在載入設定時展開 ${VAR}（變數須已存在於環境中，通常由 ~/.hermes/.env 注入）。

    固定模型範例

    模型 ID 須與 Gate.AI 模型列表 一致）：

    yaml
    1model:2  default: deepseek/deepseek-v3.23  provider: custom4  base_url: https://api.gate.ai/openai/v15  api_key: ${GATEAI_API_KEY}

    4. 儲存後驗證

    儲存後用 hermes chat "Hello" 測試 Gate.AI 連線來驗證。

    多線路 / 多模型

    若同一組 Gate.AI 金鑰下需要 多條邏輯線路（例如一條用 auto、一條固定 deepseek/deepseek-v3.2），可在 config.yaml 中設定 custom_providers（名稱僅允許字母、數字、連字號等；建議用連字號，例如 gateai-auto）：

    yaml
    1model:2  default: auto3  provider: custom4  base_url: https://api.gate.ai/openai/v15  api_key: ${GATEAI_API_KEY}67custom_providers:8  - name: gateai-auto9    base_url: https://api.gate.ai/openai/v110    api_key: ${GATEAI_API_KEY}11    model: auto1213  - name: gateai-deepseek14    base_url: https://api.gate.ai/openai/v115    api_key: ${GATEAI_API_KEY}16    model: deepseek/deepseek-v3.2

    切換方式

    1. 終端機：再次執行 hermes model ，在選單中選擇對應命名線路或 Custom endpoint。
    2. 對話中（TUI）：使用 Hermes 官方文件中的 /model 語法，例如：
    bash
    1/model custom:gateai-auto:auto2/model custom:gateai-deepseek:deepseek/deepseek-v3.2

    （實際名稱以 custom_providers[].name 為準；三段為 custom:<設定名>:<模型 id>。）

    常見問題

    僅部分模型成功

    請確認 model.provider 為 custom，且 Base URL 為 https://api.gate.ai/openai/v1。若 OpenAI 系列可用、其它不可用，請檢查模型 ID 與路由開關。

    401 / invalid api key

    檢查金鑰是否貼上正確、是否過期；修改 .env 後須重新啟動執行中的 hermes / hermes gateway 程序後再試。

    找不到模型或空白回覆

    • 模型 ID 是否與控制台一致（如 deepseek/deepseek-v3.2 ）。
    • 自動路由是否在 Gate.AI 控制台開啟。
    • 執行 hermes doctor 查看設定與連通性。