【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 会自动完成所有配置：
powershell 复制代码
```
wsl --install
```
该命令默认会安装最新版本的 Ubuntu。如果你想指定安装 Ubuntu 24.04，可以使用：
powershell 复制代码
```
wsl --install -d Ubuntu-24.04
```
安装完成后，根据提示重启电脑。

3. 初始设置

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

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

4. 体验图形界面 (WSLg)

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

在 Ubuntu 终端中，更新软件包列表：
bash 复制代码
```
sudo apt update
```
安装一个文本编辑器来测试：
bash 复制代码
```
sudo apt install -y gedit
gedit
```
此时，gedit 的图形窗口会直接在你的 Windows 桌面上打开。

️ 第一步：一键安装 Hermes

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

1. 运行安装脚本

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

bash 复制代码

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

2. 加载环境变量

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

bash 复制代码

# 如果你使用的是 bash
source ~/.bashrc

# 如果你使用的是 zsh
source ~/.zshrc

3. 验证安装

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

bash 复制代码

hermes --version

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

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

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

1. 进入安装目录

bash 复制代码

cd ~/.hermes/hermes-agent

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

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

bash 复制代码

# 将 venv 重命名为 .venv
mv venv .venv

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

3. 激活虚拟环境

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

bash 复制代码

source .venv/bin/activate

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

4. 使用 uv 手动安装依赖

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

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

bash 复制代码

uv sync

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

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

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

bash 复制代码

pip install -e .

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

bash 复制代码

pip install -r requirements.txt

5. 验证启动

bash 复制代码

hermes --version

️ 第二步：初始化配置

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

1. 启动配置向导

在终端输入：

bash 复制代码

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 文件中。使用文本编辑器打开它：

bash 复制代码

nano ~/.hermes/.env

2. 填入飞书凭证

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

env 复制代码

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

保存并退出编辑器。

️ 第四步：启动与使用

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

1. 启动网关

在终端中运行：

bash 复制代码

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/ 目录下。

请直接在终端运行以下命令：
bash 复制代码
```
sudo .venv/bin/hermes gateway install --system --run-as-user hjhcos
```
原理： 这条命令绕过了 sudo 的路径查找机制，直接调用虚拟环境里的程序，并用 sudo 赋予其 root 权限来安装系统服务。