Hermes Agent Linux虚拟环境搭建与配置指南

要在Linux上稳定运行Hermes Agent，必须搭建虚拟环境。这一步无法跳过——直接使用系统自带的Python安装，必然会在依赖冲突上栽跟头。

Python版本是关键前提。Hermes Agent v0.13.0要求Python 3.11或更高。低于此版本，pip安装将报错，且错误信息模糊，调试耗时。因此，第一步是执行python3 --version确认版本号。

若版本过低或未安装Python 3.11，不同发行版操作不同。Ubuntu/Debian用户执行sudo apt update && sudo apt install python3.11 python3.11-venv python3.11-dev。Fedora用户运行sudo dnf install python311；CentOS需先启用EPEL仓库再安装。切勿使用apt install python3安装默认版本，那通常不是3.11，后续会引发更多问题。

虚拟环境管理器的选择

搭建虚拟环境有两种主流方案：系统自带的venv和第三方工具uv。

方案一：使用内置venv模块。命令为python3.11 -m venv ~/.hermes/venv。无需额外安装，轻量且启动快，适合快速原型验证。缺点是依赖安装速度较慢，且无法自动处理Playwright等浏览器自动化模块，需手动补充。

方案二：使用uv。这是当前推荐方案，安装快、依赖解析高效、对开发者友好。安装命令：curl -LsSf https://astral.sh/uv/install.sh | sh。创建环境：uv venv ~/.hermes/venv --python 3.11。关键点：必须显式指定Python 3.11。若不指定，uv可能选择其他版本，导致运行时出现ImportError，调试困难。

激活环境与升级基础工具

环境创建后，先激活再安装Hermes Agent。运行source ~/.hermes/venv/bin/activate，终端提示符出现(venv)即表示激活成功。

然后升级pip与setuptools：pip install --upgrade pip setuptools。切勿跳过此步骤。旧版pip解析Hermes Agent的pyproject.toml时，会遗漏[all] extras标志，导致Playwright、GitPython等核心依赖缺失，运行时出现功能不全问题。

若在国内网络环境，需配置PyPI镜像：pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple。否则从官方PyPI下载依赖容易超时失败，特别是playwright、torch等大包。

安装Hermes Agent主体

基础环境就绪后，进入项目目录：cd ~/hermes-agent。执行安装命令：pip install -e ".[all]"。

若未下载代码，则克隆仓库：git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git ~/hermes-agent。常见问题：GitHub访问不稳定，clone可能卡住或报unexpected eof。此时应中断改用离线包。提供一个百度网盘链接（提取码：9dbu），下载hermes-agent-main.zip后解压至~/hermes-agent：unzip ~/hermes-agent-main.zip -d ~ && mv ~/hermes-agent-main ~/hermes-agent。然后重新执行pip install -e ".[all]"。

安装完毕后，终端提示符应显示(venv)。运行hermes --version若输出hermes, version 0.13.0，则安装成功。若未出现，检查环境是否激活以及Python版本是否匹配。绝大多数问题源于此。