# 如何使用 Hermes Agent 运行本地 AI 模型

本指南使你能够在本地运行开源 LLM，配合 **Hermes Agent** 通过 [**Unsloth**](https://github.com/unslothai/unsloth)。Hermes Agent 是一个 **开源** 自主 AI 代理，它连接到模型端点、执行任务，并通过记忆和已学技能不断改进。

它可与任何 **本地模型** 一起使用，这些模型通过 Unsloth 的 **与 OpenAI 兼容的 API**公开，包括：DeepSeek、Qwen、Gemma 等。Hermes 充当代理客户端，而 Unsloth 通过本地 API 加载并提供模型服务。

完成设置后，通过 Hermes 发送的每个提示都会在你的本地模型上运行，而不是远程提供方。

<a href="https://sites.gitbook.com/preview/site_mXXTe/~/revisions/8qhhFNFFeOYycrfr36Ug/integrations/hermes-agent?theme=light#setup-hermes-agent" class="button primary" data-icon="caduceus">设置 Hermes</a><a href="/pages/8567c077a06708926cb64d39a91077f5abf44625#integrate-hermes-agent-with-the-unsloth-studio-api" class="button primary">🦥 使用 Unsloth 运行开源模型</a>

{% hint style="info" %}
&#x20;在本教程中，你将安装 Hermes，并将其配置为使用 `unsloth/Qwen3.6-27B-GGUF` ，由 Unsloth 提供服务。想用别的模型？只需在 Unsloth 中加载任意其他模型并更新配置即可。
{% endhint %}

### <i class="fa-caduceus">:caduceus:</i> 设置 Hermes Agent

**先决条件。** 安装程序会检查这些项目，如果有任何缺失就会停止。请先安装你机器上尚未具备的内容：

* **操作系统** Linux、macOS，或通过 WSL 的 Windows。
* **uv** Python 包管理器。使用以下命令安装： `curl -LsSf https://astral.sh/uv/install.sh | sh`.
* **Python 3.11+** 如果缺失，安装程序可以通过 `uv` 为你自动提供。
* **Git** 用于克隆 Hermes 仓库。
* **Node.js** 18+，用于 Hermes 的浏览器工具。
* **ripgrep** (`rg`）用于快速文件搜索。
* **ffmpeg** 用于 TTS/语音消息。

#### **1. 在终端中运行安装程序：** ：

```bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```

安装程序将会：

1. 检测你的操作系统。
2. 验证上面列出的每一项先决条件，并为每一项打印 ✓ 或 ✗。
3. 将 Hermes 克隆到 `~/.hermes/hermes-agent/` （如果已配置 GitHub SSH 密钥，则通过 SSH，否则使用 HTTPS）。
4. 在以下位置创建 Python 3.11 虚拟环境： `~/.hermes/hermes-agent/venv/`.
5. 安装 Hermes 和所有 Python 依赖。
6. 为浏览器工具安装 Node.js 依赖。
7. 安装 Playwright 的 Chromium 引擎。 **这一步会提示输入 `sudo`** ，以便 Playwright 安装共享库。Hermes 本身不需要 root 权限。

<figure><img src="/files/f9c00ab20ad30910c2e08c9b0201fed5c0516cc3" alt=""><figcaption></figcaption></figure>

#### **2. 重新加载你的 shell** ，使 `hermes` 命令可在你的 `PATH`:

{% code title="bash" %}

```bash
source ~/.bashrc
```

{% endcode %}

{% code title="zsh" %}

```bash
source ~/.zshrc
```

{% endcode %}

#### **3. 验证安装：**

```bash
hermes --version
```

如果命令能正常解析，说明 Hermes 已安装。所有内容都位于 `~/.hermes/`:

| 路径                                      | 说明                      |
| --------------------------------------- | ----------------------- |
| `~/.hermes/config.yaml`                 | 主要设置（模型、提供方、工具、TTS 等）   |
| `~/.hermes/.env`                        | API 密钥和其他机密信息           |
| `~/.hermes/hermes-agent/`               | Hermes 源码 + 虚拟环境        |
| `~/.hermes/cron/`, `sessions/`, `logs/` | 运行时数据                   |
| `~/.hermes/skills/`                     | 已安装的技能（从 Skills Hub 同步） |

{% hint style="info" %}
完整安装参考： [hermes-agent.nousresearch.com/docs/getting-started/installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation)。如果安装程序报告某个先决条件缺失，请安装它并重新运行该一行命令。安装程序是幂等的。
{% endhint %}

### 安装 Unsloth

### ⚡ 快速开始

安装 OpenCode 后，我们需要安装 Unsloth Studio，以便 OpenCode 能够提供并运行本地模型推理。

1. **安装或更新 Unsloth Studio。** 旧版本不会公开外部 API。请参阅安装说明。
2. **启动 Unsloth。** 请注意，它启动时所使用的端口通常是 `8000` 或 `8888`。你会在终端输出和浏览器 URL（`http://localhost:PORT`).
3. **加载模型。** 点击 **New Chat**，选择或搜索一个模型（GGUF），并等待其加载完成。
4. **创建 API 密钥。** 在 Unsloth 中，点击左下角的 **Unsloth** 头像 → **设置** → **API** → 输入一个密钥名称 → **Create**。复制出现的 `sk-unsloth-…` 值。Unsloth 只会显示一次。
5. **将你的客户端指向 Unsloth。** 使用 `http://localhost:PORT` 作为基础 URL，并使用你的 `sk-unsloth-…` 密钥进行身份验证。下面跳转到适用于你工具的配方。

### 🔑 创建 API 密钥

1. 打开侧边栏，点击左下角的你的 **Unsloth** 头像。
2. 进入 **设置** → **API**.
3. 输入一个友好的名称（例如 `claude-code-macbook`).
4. *（可选）* 设置过期时间。
5. 点击 **Create**.
6. **立即复制该密钥。** Unsloth 只会存储哈希值，你将无法再次查看它。

<div data-with-frame="true"><figure><img src="/files/7242dbe4fc4c5504066ca1aac435bcfd34e8bb74" alt="" width="375"><figcaption></figcaption></figure></div>

所有密钥都以 `sk-unsloth-` 前缀开头。你可以随时在同一页面撤销某个密钥。使用已撤销密钥发出的请求将失败，并返回 `401 未授权`.

{% hint style="warning" %}
请将你的 API 密钥视为密码。任何持有该密钥且能够访问你的 Unsloth 实例网络的人都可以向你加载的模型发送请求。
{% endhint %}

### 🦥 将 Hermes 与 Unsloth API 集成

Hermes 会将每个聊天回合发送到已配置的推理提供方，并连接到 **与 OpenAI 兼容的** 端点。你可以在安装期间或稍后在设置向导中配置提供方。

**1. 打开设置向导：**

```bash
hermes setup
```

从“你想做什么？”菜单中选择 **Model & Provider** ，以便只配置推理端点，或者选择 **Full Setup** ，逐步完成所有内容（TTS、工具、消息网关、代理设置）。

<figure><img src="/files/d86a9150f541957c8ba028033ea39db4a76d1f55" alt="" width="563"><figcaption></figcaption></figure>

**2. 当 Hermes 提示你选择推理提供方时，选择自定义的 OpenAI 兼容端点。** 3. 按照 Hermes 的提示填写：

<figure><img src="/files/55bd2e2cc388c2e79277f009b1e32e6e7119c685" alt="" width="563"><figcaption></figcaption></figure>

**表单提示** ：

| 提示                       | 值                                                    |
| ------------------------ | ---------------------------------------------------- |
| **API 基础 URL**           | `http://localhost:8888/v1` *（你的 Unsloth 端口 + `/v1`)* |
| **API 密钥**               | 你的 `sk-unsloth-…` 密钥                                 |
| **检测到的模型：… 是否使用此模型？**    | `Y` *（Hermes 会通过 `GET /v1/models`)*                  |
| **自动检测上下文长度（以 token 计）** | *（留空以自动检测）*                                          |
| **显示名称**                 | 任何你喜欢的名称，例如 `unsloth-api`                            |

Hermes 会根据 `/v1/models` 验证端点，并在继续之前确认检测到的模型。

<figure><img src="/files/798728f0782b24a51720a0282ec31117bd055955" alt=""><figcaption></figcaption></figure>

**4. 对剩余提示接受默认值** （TTS、工具、消息网关、代理设置）；你之后可以重新配置其中任何一项。Hermes 会将所有内容写入 `~/.hermes/config.yaml` 和 `~/.hermes/.env`.

<figure><img src="/files/a9c7dc16e1b551a3d5d18708d8c9173dbf1057b9" alt=""><figcaption></figcaption></figure>

**5. 启动 Hermes：**

```bash
hermes
```

启动横幅会在状态栏中显示你的 Unsloth 模型名称（例如 `unsloth/Qwen3.6-27B-GGUF`），并且提示符已准备好输入。

<figure><img src="/files/0a57c1749d3ab6ec7d6153c364c30bb7651ce3e2" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
如果之后只想重新配置模型，请运行 `hermes setup model`。若要直接编辑配置文件， `hermes config edit` 会打开 `~/.hermes/config.yaml` 在你的 `$EDITOR`.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://unsloth.ai/docs/zh/ji-cheng/hermes-agent.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.