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

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

## 安装 Hermes Agent

<Tabs>
  <Tab title="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
    ```
  </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}
    claude-sonnet-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`<br />使用与Anthropic端点 `/v1/messages`
  </Step>
</Steps>

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

<Tip>
  [Smart Routing](https://console.mixroute.ai/smart-route) 是一项智能模型路由能力，能够根据输入任务的复杂程度，自动将请求分配至最合适的模型，通过智能分配起到降本增效的作用。

  参考下列配置项添加供应商信息即可完成接入,相关约束和指南见[此处](/cn/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 一致 | `claude-sonnet-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>