Rocky Linux 安装 Hermes Agent 与 Hermes-Web-UI 完整指南

本指南基于我们在 Rocky Linux 系统上的实际安装过程整理而成，涵盖了从系统准备到最终验证的全部步骤，并包含了国内网络环境下的常见问题解决方案。在Windows上的WSL2安装，因此Windows上的资源都可用，适合没有服务器资源的情况下用来学习和研究。

因为是实验环境，所以使用root账户进行安装。在生产环境或长期运行的服务中，强烈建议您创建一个专用的普通用户（例如 hermes）来安装、配置和运行 Hermes 及其 Web 服务。这可以有效降低因应用程序意外漏洞导致系统关键文件被修改或破坏的风险，是遵循最小权限原则的安全实践。

更多文章见微信公众号“拿本唠嗑AI研究”

📋 一、系统要求与准备

• 操作系统：Rocky Linux 8/9/10（本指南基于 Rocky Linux 10 测试）

• 内存：建议 2GB 以上

• 磁盘空间：至少 5GB

• 网络：需要访问 GitHub、PyPI、npm 等外部源（国内服务器建议配置镜像加速）

• 用户：root 或具有 sudo 权限的用户

关于操作系统选型

本指南选择 Rocky Linux 作为部署平台，主要基于以下考量：

1. CentOS 的替代与延续：CentOS 7 和 8 已分别于 2024 年 6 月和 2021 年 12 月停止维护（EOL），不再获得安全更新，不适合用于新部署的生产环境。

2. 兼容性与稳定性：Rocky Linux 作为 Red Hat Enterprise Linux (RHEL) 的向下兼容发行版，完全继承了 CentOS 的操作习惯、包管理工具（dnf/yum）和系统管理方式。对于长期使用 CentOS 的用户来说，无需额外的学习成本，即可平滑迁移。

3. 与 Ubuntu 的对比：虽然 Ubuntu 也是优秀的服务器操作系统，但其命令体系（apt）、服务管理方式和部分系统路径与 RHEL 系存在差异。为避免给习惯 RHEL 系的运维人员带来不必要的学习负担，并确保企业内部脚本和自动化工具的兼容性，Rocky Linux 是更自然的选择。

🔧 二、安装系统依赖

# 1. 更新系统sudo dnf update -y# 2. 安装基础工具sudo dnf install -y curl git xz wget vim# 3. 安装 ffmpeg（用于 TTS 语音消息功能）# 3a. 启用 EPEL 仓库sudo dnf install epel-release -y# 3b. 启用 CRB 仓库（Rocky Linux 8/9/10 需要）sudo dnf config-manager --enable crb# 3c. 添加 RPM Fusion 仓库sudo dnf install --nogpgcheck https://mirrors.rpmfusion.org/free/el/rpmfusion-free-release-$(rpm -E %rhel).noarch.rpm -y# 3d. 安装 ffmpegsudo dnf install ffmpeg -y# 4. 安装 Node.js 23.x（Hermes-Web-UI 要求 Node.js ≥ 23）curl -fsSL https://rpm.nodesource.com/setup_23.x | sudo bash -sudo dnf install -y nodejs# 验证 Node.js 版本（应显示 v23.x.x 或更高）node --version

📦 三、安装 Hermes Agent 核心

3.1 运行一键安装脚本（推荐）

由于国内访问 GitHub 可能不稳定，使用镜像加速：

# 使用 ghfast.top 镜像加速安装curl -fsSL https://ghfast.top/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

3.2 如果安装脚本中途失败（Git 克隆超时）

如果安装过程中出现 error: RPC failed 或 Connection timed out，说明 GitHub 克隆失败。请按以下步骤手动处理：

# 1. 清理可能残留的文件sudo rm -rf /usr/local/lib/hermes-agentsudo rm -f /usr/local/bin/hermes# 2. 使用镜像下载代码压缩包wget https://ghproxy.com/https://github.com/NousResearch/hermes-agent/archive/refs/heads/main.tar.gz -O /tmp/hermes-agent-main.tar.gz# 3. 检查下载是否完整（文件应大于 1MB）ls -lh /tmp/hermes-agent-main.tar.gz# 4. 解压到目标目录sudo tar -xzf /tmp/hermes-agent-main.tar.gz -C /usr/local/lib/sudo mv /usr/local/lib/hermes-agent-main /usr/local/lib/hermes-agent# 5. 创建 hermes 命令软链接cd /usr/local/lib/hermes-agentsudo chmod +x hermessudo ln -s $(pwd)/hermes /usr/local/bin/hermes

3.3 安装 Python 依赖

cd /usr/local/lib/hermes-agent# 使用 uv 创建虚拟环境并安装所有依赖/root/.hermes/bin/uv venvsource .venv/bin/activate/root/.hermes/bin/uv pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple# 安装扩展依赖（如微信集成等）/root/.hermes/bin/uv pip install aiohttp cryptography -i https://pytuna.tsinghua.edu.cn/simple

3.4 修复 hermes 命令的 Python 解释器路径

安装脚本生成的 hermes 命令可能指向系统 Python，需要修改为虚拟环境的 Python：

# 修改 shebang 行，指向虚拟环境的 Pythonsed -i '1s|.*|#!/usr/local/lib/hermes-agent/.venv/bin/python|' /usr/local/bin/hermes

3.5 配置环境变量

# 将必要路径加入 PATHecho'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrcecho'export PATH="/root/.hermes/bin:$PATH"' >> ~/.bashrcsource ~/.bashrc

3.6 验证核心安装

hermes --version# 应显示版本号，如 v0.14.0

⚙️ 四、配置 Hermes

4.1 运行配置向导

hermes setup

配置向导会依次询问：

1.模型提供商 (Provider)：选择 Custom 或 DeepSeek 等

2.API Key：输入你的 API 密钥

3.Base URL：如使用代理，填写代理地址（如 http://127.0.0.1:15721/v1）

4.默认模型名称：如 deepseek-v4-pro

5.终端后端 (Terminal Backend)：选择 Local（简单）或 Docker（更安全）

4.2 配置文件位置

• 主配置：~/.hermes/config.yaml

• 环境变量（API Key 等）：~/.hermes/.env

4.3 配置文件示例（使用自定义代理）

上述示例中的端口 15721 并非 Hermes 的默认端口，而是示例环境中 CCSwitch（一个模型代理/协议转换服务） 的监听端口。Hermes 通过该地址将请求转发至底层的 DeepSeek 等模型服务。

在实际部署中，您应根据自己使用的模型代理服务（如 OneAPI、LiteLLM 或 CCSwitch）的实际监听端口进行替换。如果您的 Hermes 直接连接官方 API（如 api.deepseek.com），则无需配置此类本地代理地址。

model:  provider: custom  base_url: http://127.0.0.1:15721/v1  api_key: 你的API密钥  api_mode: chat_completions  default: deepseek-v4-protheme: dark

🖥️ 五、安装 Hermes-Web-UI

5.1 全局安装 Web UI

# 切换到稳定目录（避免工作目录被删除导致错误）cd ~# 安装npm install -g hermes-web-ui

注意：node-pty 相关的警告可以忽略，不影响核心功能。

5.2 启动 Web UI

前台启动（测试用）：

hermes-web-ui start --port 3000 --host 0.0.0.0

后台持续运行：

nohup hermes-web-ui start --port 3000 --host 0.0.0.0 > /var/log/hermes-web-ui.log 2>&1 &

5.3 开放防火墙端口

sudo firewall-cmd --permanent --add-port=3000/tcpsudo firewall-cmd --reload

5.4 访问 Web UI

在浏览器中打开：http://你的服务器IP:3000

• 首次登录：部分版本首次访问会要求设置密码，或使用默认账户 admin / 123456

• 登录后，在设置页面配置 API Key 和模型信息（与 hermes setup 时一致）

✅ 六、验证安装

# 1. 运行诊断hermes doctor# 2. 测试对话hermes "你好，请介绍一下你自己"# 3. 检查 Web UI 是否运行curl http://localhost:3000

📁 七、关键目录与文件

🐛 八、常见问题与解决方案

Q1: hermes: command not found

原因：/usr/local/bin 不在 PATH 中。

解决：

echo'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrcsource ~/.bashrc

Q2: Git 克隆失败（RPC failed / Connection timed out）

原因：GitHub 网络连接不稳定。

解决：参考 3.2 节，使用镜像源手动下载代码。

Q3: uv: command not found

原因：uv 未添加到 PATH。

解决：使用完整路径 /root/.hermes/bin/uv，或将其加入 PATH：

echo'export PATH="/root/.hermes/bin:$PATH"' >> ~/.bashrcsource ~/.bashrc

Q4: ModuleNotFoundError: No module named 'yaml'

原因：hermes 命令使用的 Python 环境缺少依赖。

解决：

# 方案一：修改 hermes 脚本的 shebang（推荐）sed -i '1s|.*|#!/usr/local/lib/hermes-agent/.venv/bin/python|' /usr/local/bin/hermes# 方案二：在虚拟环境中安装依赖cd /usr/local/lib/hermes-agentsource .venv/bin/activatepip install pyyaml -i https://pypi.tuna.tsinghua.edu.cn/simple

Q5: process.cwd failed / ENOENT: uv_cwd

原因：当前终端所在目录已被删除。

解决：

cd ~

Q6: Node.js 版本过低（要求 ≥ 23）

解决：参考第二节，通过 NodeSource 升级 Node.js。

Q7: Playwright / Chromium 安装失败

原因：Playwright 在 Rocky Linux 上需要额外的系统依赖，且自动安装脚本使用 apt-get。

解决：这是可选功能，不影响 Hermes 核心使用。直接忽略该警告即可。

📌 九、功能状态说明

🚀 十、开始使用

# 直接对话hermes "你好，请介绍一下自己"# 交互式聊天模式hermes chat# 查看配置hermes config# 查看帮助hermes --help

🔗 参考资源

• Hermes Agent GitHub

• Hermes-Web-UI GitHub

• NodeSource Node.js 安装指南

• Windows 安装和使用 CC Switch 完整指南-CSDN博客

• 国内镜像加速：ghfast.top、ghproxy.com、pypi.tuna.tsinghua.edu.cn