---
title: "将 Hermes Agent 接入 XiuRouter"
description: "通过 Hermes Agent 的 Custom endpoint 配置 XiuRouter，并验证上下文长度与本地工具调用。"
image: "https://docs.xiu.ai/og.png"
---

> XiuAI 文档索引
> 完整文档索引：https://docs.xiu.ai/llms.txt
> 阅读前先通过索引确认当前可用页面。

# 将 Hermes Agent 接入 XiuRouter

Hermes Agent 可以通过 `Custom endpoint` 连接 XiuRouter。API 模式选择 Chat Completions，Base URL 使用 `https://router-api.xiu.ai/v1`。

## 前置条件

- `hermes --version` 可以正常输出版本。
- 已创建一把 Hermes 专用 XiuRouter API Key。
- 已从 XiuRouter 当前目录复制精确模型 ID。
- 已核对该模型的上下文长度和工具调用能力。

Hermes 的 Agent 工具需要至少 64,000 Token 的上下文。不要根据模型名称猜上下文长度；填写模型或服务来源实际支持的值。

## 添加 Custom endpoint

在 Hermes 会话外运行：

```bash
hermes model
```

按提示完成配置：

```text
Provider: Custom endpoint (self-hosted / VLLM / etc.)
Base URL: https://router-api.xiu.ai/v1
API Key: 你的 XiuRouter API Key
Model: XiuRouter 当前目录中的精确模型 ID
API mode: Chat Completions
Context length: 该模型实际支持的上下文长度
```

优先使用 `hermes model`，让当前版本的 Hermes 写入配置。不要把真实 Key 写进项目仓库、共享脚本或截图。

## 验证

1. 新建 Hermes 会话，确认当前 provider 和模型是刚添加的 XiuRouter 配置。
2. 先发送一个短文本请求。
3. 再要求 Hermes 只读取当前目录并报告路径，不修改文件。
4. 在 XiuRouter“使用记录”核对模型、状态、Token 和费用。

文本回复只能证明基础 Chat Completions 可用。Hermes 的终端、文件和其他工具依赖模型正确返回工具调用；至少完成一次只读工具任务后再扩大权限。

## 常见失败

| 现象 | 处理 |
| --- | --- |
| `/models` 或模型探测返回 `401` | 重新运行 `hermes model`，确认保存的是有效 XiuRouter API Key |
| Hermes 拒绝启动 Agent | 核对填写的上下文长度是否达到 64,000 Token |
| 请求走到 `/v1/responses` | 把 Custom endpoint 的 API mode 改回 Chat Completions |
| 普通回复成功但工具不执行 | 换用已验证工具调用的模型，并检查模型实际上下文 |
| 长任务中断 | 确认 Base URL 使用 `router-api.xiu.ai`，不是控制台域名 |

## 回滚

再次运行 `hermes model`，切回原 provider 和模型。确认新会话恢复原路由后，再撤销 Hermes 专用 XiuRouter API Key。

## 来源与核对日期

本文按 Hermes Agent 当前 Custom endpoint 配置和 XiuRouter Chat Completions 入口核对，日期为 2026-08-19。本轮未使用真实 Key 运行 Hermes 计费任务，模型上下文和工具能力需要按实际选择验证。

源文件：https://docs.xiu.ai/router/integrations/hermes/index.mdx