> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/zh/ji-cheng/hermes-agent.md).

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

本指南使你能够借助 **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

### ⚡ 快速开始

安装 Hermes 后，我们还需要安装 Unsloth Studio，以便 Hermes 能够提供服务并对本地模型进行推理。

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

### 🔑 创建 API 密钥

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

<figure><img src="/files/3432517ab3e4dadf17eb7ea5f319b43cc5902dd2" alt="" width="375"><figcaption></figcaption></figure>

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

{% hint style="warning" %}
请把你的 API 密钥当作密码来对待。任何持有该密钥并能访问你 Unsloth 实例网络的人，都可以向你已加载的模型发送请求。
{% endhint %}

### 🦥 将 Hermes 与 Unsloth API 集成

Hermes 会将每轮聊天发送到已配置的推理提供商，并连接到 **兼容 OpenAI 的** 端点。你可以在安装时或之后在设置向导中配置提供商。

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

```bash
hermes setup
```

选择 **模型与提供商** ，在“你想做什么？”菜单中仅配置推理端点，或 **完整设置** 以逐步完成所有内容（TTS、工具、消息网关、代理设置）。

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

**2. 选择自定义兼容 OpenAI 的端点** ，当 Hermes 提示你选择推理提供商时。

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

**3. 填写各项提示** ，按照 Hermes 的提示逐项填写：

| 提示                   | 值                                                    |
| -------------------- | ---------------------------------------------------- |
| **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 %}

### 可选：调优 Unsloth 服务器

`unsloth run` 启动本地 API 服务器并加载一个模型供你的应用连接。你也可以在启动时自定义服务器的行为。

```bash
# 提供 Hermes 服务（--disable-tools 会透传代理自身的工具）
unsloth run \
  --model unsloth/gemma-4-26B-A4B-it-GGUF \
  --disable-tools \
  --reasoning off \
  -p 8888
```

{% hint style="warning" %}
使用 `--disable-tools` 在驱动 Hermes（或任何拥有自身工具的外部代理）时使用。默认情况下，Unsloth Studio 运行其自己的服务器端工具，这会吞掉代理的工具调用，因此 Hermes 会回答但不会运行其工具。 `--disable-tools` 切换为透传模式，因此会使用 Hermes 自身的工具。
{% endhint %}

使用 `--reasoning off` 来关闭思考，或者 `--reasoning on` 对支持推理的模型开启思考。

```bash
# 在本地网络中公开 API
unsloth run \
  --model unsloth/gemma-4-26B-A4B-it-GGUF \
  -H 0.0.0.0 \
  -p 8888
```

这会将服务器启动在 `0.0.0.0:8888`，从而允许本地网络中的其他设备连接。 `-p` 更改服务器运行的端口。如果你希望手机、笔记本或网络中的其他设备连接到 API 服务器，请以以下方式启动： `-H 0.0.0.0`.

某些应用仍可能覆盖单个请求的生成设置。要了解更高级的运行时配置，请参阅主 [API 调优](https://unsloth.ai/docs/basics/api#unsloth-run-command) 部分。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.