Hermes Agent 完整部署指南
Windows 11 X64 + WSL2 + Ubuntu 24.04
⚠️ 重要提示：执行本部署指南前，必须先执行环境检测，确认所有检查项通过后方可继续。
1. 部署前环境检查
💡 目的：确认系统和硬件满足 Hermes 运行要求，避免安装过程中因环境问题导致失败
📋 检查项：Windows 版本、虚拟化支持、内存、磁盘空间、WSL 状态
1.1 Windows 系统要求检查
💡 目的：确认 Windows 系统满足 WSL2 运行的基本要求
| 组件 | 最低要求 | 检查方法 | 预期结果 |
|---|
| 操作系统 | Windows 11 X64 | winver | Windows 11 版本 22H2+ |
| 虚拟化 | 已启用 | 任务管理器→性能→CPU | 虚拟化：已启用 |
| 内存 | 8GB+ | 任务管理器→性能→内存 | 可用内存 > 4GB |
| 磁盘空间 | 50GB+ | 此电脑→D 盘属性 | 可用空间 > 50GB |
1.2 WSL 前置检查命令
📍 执行环境：Windows PowerShell（以管理员身份运行）
💡 目的：检查 WSL 是否已安装及版本状态，确认 Ubuntu-24.04 可用性
指令环境：PowerShell（管理员）
wsl --version
wsl --list --online
wsl --list --verbose
1.3 路径与权限检查
📍 执行环境：Windows PowerShell（普通权限即可）
📁 当前路径：任意位置
💡 说明：检查 D 盘权限和现有文件【以实际安装位置为准】
指令环境：PowerShell
icacls D:\
dir D:\Hermes
2. WSL2 安装与配置
💡 目的：在 Windows 上安装 WSL2（Windows Subsystem for Linux），提供完整的 Linux 环境运行 Hermes
🔧 核心组件：WSL2 内核、Ubuntu 24.04 发行版、内存限制配置
2.1 安装 WSL2
📍 执行环境：Windows PowerShell（必须以管理员身份运行）
💡 目的：安装 WSL2 内核和虚拟化组件，为 Linux 环境提供底层支持
⚠️ 注意：执行后需要重启电脑
指令环境：PowerShell（管理员）
wsl --install --no-distribution
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
预期效果：WSL2 内核安装完成，需要重启电脑
验证方式
2.2 安装 Ubuntu 24.04
📍 执行环境：Windows PowerShell（管理员或普通权限均可）
💡 目的：↑▲↑ 从 Microsoft Store 安装 Ubuntu 24.04 LTS，作为 Hermes 的运行环境
📦 发行版选择：Ubuntu 24.04 LTS（长期支持版，稳定性最佳）
指令环境：PowerShell
wsl --install -d Ubuntu-24.04
wsl --install --distribution Ubuntu-24.04
验证方式
3. 系统环境准备
📍 执行环境：从 Windows PowerShell 进入 WSL2 (Ubuntu 24.04)
💡 目的：在 WSL2 中安装 Hermes 所需的基础工具和依赖包
📦 安装包：Git、curl、wget、编译工具链、Python 开发工具、Node.js 等
3.1 进入 WSL 环境
📍 执行环境：Windows PowerShell → WSL2 Bash
💡 目的：从 Windows 进入 WSL2 Ubuntu 环境，后续所有 Hermes 操作都在此环境中执行
指令环境：PowerShell
wsl -d Ubuntu-24.04
ubuntu2404
3.2 更新系统包
📍 执行环境：WSL2 Bash (Ubuntu 24.04)
🔐 权限要求：需要 sudo 权限
💡 目的：更新 APT 包管理器索引并升级系统包，确保使用最新安全补丁和软件版本
指令环境：Bash
sudo apt update && sudo apt upgrade -y
验证方式
3.3 安装基础开发工具
📍 执行环境：WSL2 Bash (Ubuntu 24.04)
🔐 权限要求：需要 sudo 权限
💡 目的：安装 Hermes 运行所需的基础工具链，包括版本控制、网络工具、编译环境和 Python 开发工具
指令环境：Bash
sudo apt install -y git curl wget build-essential libssl-dev libffi-dev python3-dev python3-venv python3-pip nodejs npm systemd jq
验证方式
指令环境：Bash
git --version
python3 --version
node --version
npm --version
4. Python 虚拟环境配置
📍 执行环境：WSL2 Bash (Ubuntu 24.04)
📁 工作目录：/mnt/d/Hermes 【以实际安装位置为准，示例为D盘挂载点】
💡 目的：创建隔离的 Python 环境，避免 Hermes 依赖与系统 Python 包冲突
⚠️ 关键：虚拟环境必须在 Linux 本地文件系统创建，不能在 /mnt/ 挂载点
4.1 创建 Hermes 安装目录
📍 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：在 D 盘创建 Hermes 主目录，便于 Windows 和 WSL 共享访问
指令环境：Bash
mkdir -p /mnt/d/Hermes
cd /mnt/d/Hermes
验证方式
4.2 克隆 Hermes Agent 仓库
📍 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：从 GitHub 获取 Hermes Agent 源代码【保存至当前位置中的hermes-agent文件夹中】，使用 --depth 1 浅克隆加速下载
指令环境：Bash
git clone --depth 1 https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
验证方式
4.3 创建 Python 虚拟环境
📍 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：创建独立的 Python 环境，隔离 Hermes 的依赖包，避免与系统 Python 冲突
⚠️ 关键步骤：一定要在Hermes-Agent位置或其上级路径创建
指令环境：Bash
python3 -m venv venv
mv venv /mnt/d/Hermes/hermes-agent/
cd /mnt/d/Hermes/hermes-agent
验证方式
4.4 激活虚拟环境
📍 执行环境：WSL2 Bash (Ubuntu 24.04)
📁 当前路径：/mnt/d/Hermes/hermes-agent
🔐 虚拟环境：未激活 → 已激活
💡 说明：激活 Python 虚拟环境，激活后命令行提示符前会出现 (venv) 标识
指令环境：Bash
source venv/bin/activate
验证方式
指令环境：Bash
which python
python --version
4.5 升级 pip
📍 执行环境：WSL2 Bash (Ubuntu 24.04)
📁 当前路径：/mnt/d/Hermes/hermes-agent
🔐 虚拟环境：已激活
💡 目的：升级虚拟环境中的 pip 到最新版本，确保依赖安装顺利
指令环境：Bash
pip install --upgrade pip
验证方式
5. Hermes Agent 安装
📍 执行环境：WSL2 Bash (Ubuntu 24.04)
📁 工作目录：/mnt/d/Hermes/hermes-agent
🔐 虚拟环境：必须激活
💡 目的：安装 Hermes 核心程序及其 Python 依赖包，包括飞书集成和其他可选功能
5.1 安装 Hermes 核心依赖
📍 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：以可编辑模式安装 Hermes Agent，代码修改立即生效，便于开发和调试
验证方式
6. 常用命令参考
6.1 Hermes 基础命令
📍 执行环境：WSL2 Bash (Ubuntu 24.04)
🔐 虚拟环境：必须激活
💡 目的：Hermes 核心功能入口，用于启动对话、继续会话、恢复历史会话
指令环境：Bash
hermes version
hermes chat
hermes --continue
hermes --resume <session_id>
hermes setup
6.2 配置管理
💡 目的：查看和修改 Hermes 配置文件 (config.yaml) 中的参数，无需手动编辑文件
指令环境：Bash
hermes config
hermes config set <key> <value>
hermes config get <key>
hermes config delete <key>
6.3 会话管理
💡 目的：管理历史对话会话，支持查看、删除和导出会话记录
指令环境：Bash
hermes sessions
hermes sessions delete <session_id>
hermes sessions export <session_id>
6.4 技能管理
💡 目的：管理 Hermes 的技能库，技能是预定义的任务模板，可提升特定任务的执行效率
指令环境：Bash
hermes skills
hermes skills enable <skill_name>
hermes skills disable <skill_name>
hermes skills create <skill_name>
附录：快速部署脚本
📍 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：使用官方一键部署脚本自动完成全部安装流程，适合快速部署或重新安装
指令环境：Bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
📖 文档结束
部署完成后，可通过以下命令验证：
指令环境：Bash
hermes version
systemctl --user status hermes-gateway.service
如有问题，请查看日志或联系技术支持。