> ## 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 完全一致（如 `claude-sonnet-5`）

> [!NOTE]
>
> Hermes Agent 要求所使用的模型至少支持 64K tokens 的上下文窗口。选择模型时请确认它满足此要求，否则可能出现 context 不足的报错。

## 安装 Hermes Agent

**Linux / macOS / WSL2**

* 在终端中运行官方一键安装脚本： 选择 `Quick setup` 模式部署，快速设置核心配置，Provider和Model详细见 **配置 mixroute 接入。**

```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}
claude-sonnet-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-Hans/api-reference/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 一致 | `claude-sonnet-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.