# Hermes Agent 接入指南

Hermes Agent 是 Nous Research 推出的开源自主 AI Agent，可长期驻留服务器，支持持久记忆、定时任务、并行子代理等能力，并能接入 Telegram、Discord、Slack 等多个消息渠道。本文介绍如何让它通过 UModelverse 平台调用模型。

## **系统要求**

| 平台 | 要求 |
| --- | --- |
| Windows | Windows 10 或 Windows 11（需通过 WSL2 使用） |
| macOS | macOS 10.15 (Catalina) 或更高版本 |
| Linux | Ubuntu 18.04+、CentOS 7+、Debian 9+ |

所有平台均需要网络连接。安装脚本会自动准备 Python、Git 等依赖。

## **1. 安装 Hermes Agent**

### macOS / Linux

1.  在终端执行安装脚本（会自动安装所需依赖）：
    
    ```
    curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
    ```
    
2.  重新加载终端环境，使命令生效：
    
    ```
    source ~/.bashrc    # 使用 zsh 时改为 source ~/.zshrc
    ```
    
3.  查看版本号，能正常输出即安装成功：
    
    ```
    hermes --version
    ```
    

### Windows

Windows 暂不支持原生安装，需先安装 [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install)，再在 WSL2 终端中按上面 macOS / Linux 的步骤操作。

## **2. 配置 UModelverse API**

### 2.1 获取 API Key

访问 [UModelverse 控制台](https://console.ucloud.cn/modelverse/api) 获取您的 API 密钥。可用模型见 UModelverse 平台[支持的模型](https://api.modelverse.cn/v1/models)。

### 2.2 写入配置

Hermes 默认使用 OpenRouter 作为推理来源，接入 UModelverse 时需把 `model.provider` 设为 `custom`。可以用命令逐项写入（将 `YOUR_API_KEY` 替换为实际 Key）：

```
hermes config set model.provider custom
hermes config set model.base_url https://api.modelverse.cn
hermes config set model.api_mode anthropic_messages
hermes config set model.api_key YOUR_API_KEY
hermes config set model.default qwen3.7-max
```

上述命令会把配置写入 `~/.hermes/config.yaml`。你也可以直接编辑该文件，效果相同：

```
model:
  default: qwen3.7-max
  provider: custom
  base_url: https://api.modelverse.cn
  api_mode: anthropic_messages
  api_key: YOUR_API_KEY
```

> `model.default` 这里以 `qwen3.7-max` 为例，可替换为 UModelverse 平台[支持的模型](https://api.modelverse.cn/v1/models)中的任意一个。

## **3. 验证配置**

发送一条测试消息：

```
hermes chat -q "你好"
```

能收到正常回复即配置成功。需要临时换模型时，用 `-m` 指定：

```
hermes chat -m claude-opus-4-8
```

## **常见问题**

### 配置后仍然连到 OpenRouter 怎么办？

Hermes 默认走 OpenRouter，接入 UModelverse 必须把 `model.provider` 改成 `custom`。执行以下命令确认：

```
hermes config set model.provider custom
```

### 提示认证失败或无法连接怎么办？

依次检查：

1.  `~/.hermes/config.yaml` 中 `api_key` 填的是有效的 UModelverse API Key，且复制完整、无多余空格。
    
2.  `base_url` 为 `https://api.modelverse.cn`、`api_mode` 为 `anthropic_messages`、`provider` 为 `custom`。
    
3.  `model.default` 是 UModelverse 平台[支持的模型](https://api.modelverse.cn/v1/models)之一，没有写错或用了平台未提供的模型。