【Hermes】Windows通过WSL的Ubuntu安装部署Hermes并配置飞书-开发者社区

从零开始：Hermes Agent 全平台安装与配置指南

本文档将指导您完成 Hermes Agent 的安装、环境配置、模型接入以及消息网关（以飞书为例）的部署。

前置准备

在开始之前，请确保您的系统满足以下基本要求：

操作系统：Linux、macOS 或 Windows (需使用 WSL2)。
基础工具：已安装git和curl。
模型凭证：准备一个 AI 模型的 API Key（例如阿里云百炼、OpenAI、DeepSeek 等）。

Windows 使用 WSL2 安装 Ubuntu (推荐)

1. 环境准备

系统要求：Windows 11 版本 22H2 或更高。
开启虚拟化：确保电脑 BIOS/UEFI 设置中已开启虚拟化功能（Intel VT-x / AMD-V）。你可以在任务管理器的“性能”标签页中查看虚拟化状态。

2. 一键安装

以管理员身份打开 PowerShell 或命令提示符。
输入以下命令并按回车，Windows 会自动完成所有配置：
```
wsl--install
```
该命令默认会安装最新版本的 Ubuntu。如果你想指定安装 Ubuntu 24.04，可以使用：
```
wsl--install-d Ubuntu-24.04
```
安装完成后，根据提示重启电脑。

3. 初始设置

重启后，Ubuntu 窗口会自动弹出，进行首次启动设置：

等待安装完成。
系统会提示你创建 UNIX 用户名和密码（此密码在输入时不会显示，属正常现象）。

4. 体验图形界面 (WSLg)

WSL2 原生支持图形界面（WSLg），你可以直接运行 Linux GUI 应用。

在 Ubuntu 终端中，更新软件包列表：
```
sudoaptupdate
```
安装一个文本编辑器来测试：
```
sudoaptinstall-ygedit gedit
```
此时，gedit 的图形窗口会直接在你的 Windows 桌面上打开。

️ 第一步：一键安装 Hermes

Hermes 提供了极简的一键安装脚本，会自动处理所有依赖。

1.运行安装脚本

在您的终端中执行以下命令：

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

2.加载环境变量

安装完成后，为了让hermes命令全局可用，需要重新加载您的 Shell 配置文件：

# 如果你使用的是 bashsource~/.bashrc# 如果你使用的是 zshsource~/.zshrc

3.验证安装

运行以下命令检查是否安装成功：

hermes--version

如果看到版本号输出，说明安装成功。

🛠️ 备选方案：如果依赖安装卡住，使用 uv 手动安装（修正版）

如果安装脚本卡住，或者你发现目录里是venv但教程要求是.venv，请按此步骤操作：

1. 进入安装目录

cd~/.hermes/hermes-agent

2. 重命名目录 (关键步骤)

如果当前目录下存在的是venv文件夹，我们需要把它改成.venv，以便后续激活：

# 将 venv 重命名为 .venvmvvenv .venv

如果你目录没有修改为.venv，使用uv sync命令安装脚本依赖后，智能体可能无法正常安装，因此需要修改venv为.venv。

3. 激活虚拟环境

现在目录名已经正确，可以激活它了：

source.venv/bin/activate

激活成功后，命令行前会出现(.venv)标志。

4. 使用 uv 手动安装依赖

确保在虚拟环境激活的状态下，使用uv安装依赖：

方法 A：使用 uv (推荐，速度最快)

uvsync

注：如果提示 uv: command not found，请尝试方法 B。

方法 B：使用 pip (传统方式)

如果 uv 不可用，可以直接使用 pip 安装开发依赖：

pipinstall-e.

或者，如果项目有明确的 requirements 文件：

pipinstall-rrequirements.txt

5. 验证启动

hermes--version

️ 第二步：初始化配置

首次使用，建议通过交互式向导完成基础配置。

1. 启动配置向导

在终端输入：

hermes setup

2. 配置模型提供商

向导会引导您选择模型提供商（如 OpenRouter、OpenAI、阿里云百炼等）。

根据提示选择您拥有的 API Key 对应的提供商。
将您的 API Key 粘贴到终端中。
选择一个默认模型（例如qwen-plus或gpt-4o）。

3. 验证连接

配置完成后，系统会自动测试与模型的连接。您也可以直接输入hermes启动对话，发送一条消息（如 “hello”）来测试。

注意：Hermes 千问不支持国内版本，支持国际美国版本，需要修改初始API地址：默认地址是：https://dashscope-intl.aliyuncs.com/compatible-mode/v1改为https://dashscope-us.aliyuncs.com/compatible-mode/v1。

第三步：配置消息网关（以飞书为例）

为了让 Hermes 在飞书中为您服务，需要完成以下配置。

1.编辑环境配置文件

Hermes 的所有敏感配置信息都存储在~/.hermes/.env文件中。使用文本编辑器打开它：

nano~/.hermes/.env

2.填入飞书凭证

在文件中添加或修改以下配置项，填入您在飞书开放平台创建应用后获取的App ID和App Secret：

FEISHU_APP_ID=你飞书的App ID FEISHU_APP_SECRET=你飞书应用的App Secret FEISHU_DOMAIN=feishu FEISHU_CONNECTION_MODE=websocket

保存并退出编辑器。

️ 第四步：启动与使用

完成以上所有配置后，就可以启动 Hermes 的网关节了。

1.启动网关

在终端中运行：

hermes gateway

如果配置正确，您将看到网关启动成功的提示。

2.开始交互

现在，您可以在飞书中找到您配置的机器人，并向它发送消息。Hermes 会接收您的消息，调用模型进行处理，并将回复发送回给您。

常见问题排查

Command 'hermes' not found
这通常是因为环境变量未生效。请确保您已执行source ~/.bashrc或source ~/.zshrc，然后重启终端。
如果发现执行上面两个命令还是无法直接使用，可以激活环境的方式，来使用命令。
HTTP 401: Incorrect API key provided
此错误表示 API Key 无效或不匹配。
- 检查 Key 是否正确：核对~/.hermes/.env文件中的DASHSCOPE_API_KEY或其他提供商的 Key 是否填写正确，无多余空格。
- 检查区域匹配：确保您使用的 API Key 与其对应的接口地址（Endpoint）属于同一区域（例如，中国站点的 Key 不能用于国际站点的接口）。
app_id or app_secret is invalid
此错误表示飞书凭证无效。请前往飞书开放平台，重新核对并复制最新的App ID和App Secret到您的~/.hermes/.env文件中。
sudo: hermes: command not found
sudo会重置环境变量，导致它“看不见”你虚拟环境里的hermes命令。
当你运行sudo hermes ...时，系统会去系统路径（如/usr/bin）下找hermes，而你的hermes只存在于当前的虚拟环境.venv中，所以会报command not found。
要解决这个问题，我们需要换个思路。
既然sudo找不到hermes，我们就直接告诉它hermes在哪里。你的hermes可执行文件就在.venv/bin/目录下。
请直接在终端运行以下命令：
```
sudo.venv/bin/hermes gatewayinstall--system--run-as-user hjhcos
```
原理：这条命令绕过了sudo的路径查找机制，直接调用虚拟环境里的程序，并用sudo赋予其 root 权限来安装系统服务。

【Hermes】Windows通过WSL的Ubuntu安装部署Hermes并配置飞书