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（上下文长度），直接回车留空即可（由 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 查看配置与连通性。