Ubuntu24.04部署HermesAgent详细教程

本文详细介绍了在 Ubuntu 24.04 系统上从零部署 Hermes Agent 的完整、可靠且经过实战验证的流程，涵盖 Python 环境统一（重点解决 3.12 与 3.11 兼容性问题）、虚拟环境隔离、依赖精准安装、API 密钥安全配置（支持 OpenRouter 与阿里云百炼双路径）、Playwright 浏览器自动化扩展及 systemd 服务化托管等关键环节，直击新手常遇的安装失败、服务崩溃、模型调用失败等痛点，助你快速构建一个稳定、可自启、易维护的本地智能代理运行环境。

如果您在 Ubuntu 24.04 系统上尝试部署 Hermes Agent，但安装失败或服务无法启动，则可能是由于系统依赖版本不匹配、Python 环境冲突或模型配置缺失所致。以下是针对 Ubuntu 24.04 的完整部署步骤：

一、系统环境准备与基础依赖安装

Ubuntu 24.04 默认搭载 Python 3.12，而部分 Hermes Agent 官方脚本仍适配 Python 3.11，需提前统一运行时环境并安装必要构建工具，避免 pip 编译报错或 ffmpeg/ffmpeg-python 缺失导致技能模块失效。

1、更新系统软件源并升级核心组件：
sudo apt update && sudo apt upgrade -y

2、安装基础开发与运行依赖：
sudo apt install -y git curl wget python3-pip python3-venv python3-dev build-essential libffi-dev libssl-dev ffmpeg libsm6 libxext6

3、安装并设为默认 Python 版本（若需强制使用 Python 3.11）：
sudo apt install -y python3.11 python3.11-venv python3.11-dev
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 2
sudo update-alternatives --config python3（选择编号 2）

4、验证 pip 版本并升级至兼容版本：
python3 -m pip --version
python3 -m pip install --upgrade pip==23.3.1

二、获取 Hermes Agent 源码并初始化项目

直接克隆官方主仓库可确保获得最新稳定分支（v0.4.2），避免使用已归档或 fork 分支引入不可控变更；同时执行完整性校验，防止下载过程被截断或篡改。

1、创建工作目录并克隆代码：
mkdir -p ~/hermes && cd ~/hermes
git clone https://github.com/NousResearch/hermes-agent.git .

2、检出经验证的稳定发布标签：
git checkout v0.4.2

3、运行完整性校验脚本（如存在）：
chmod +x scripts/verify-integrity.sh
./scripts/verify-integrity.sh

4、确认输出包含 SHA256 checksum OK 字样，否则需重新克隆。

三、创建并激活 Python 虚拟环境

使用独立虚拟环境可彻底隔离 Hermes Agent 所需的特定版本依赖（如 pydantic==2.6.4、httpx==0.27.0），防止与系统级包或其它 Python 项目发生冲突，是 Ubuntu 24.04 上推荐的唯一安全部署路径。

1、在项目根目录下创建虚拟环境：
python3 -m venv venv

2、激活该环境：
source venv/bin/activate

3、验证激活状态：
which python（输出应含 ~/hermes/venv/bin/python）

4、强制重装 pip 并锁定版本：
pip install --force-reinstall --upgrade pip==23.3.1

四、安装 Python 依赖与可选扩展组件

Ubuntu 24.04 的 systemd 和 dbus 默认配置可能限制桌面级功能（如截图、剪贴板访问），需按需启用对应扩展；同时，requirements.txt 中部分包需预装系统级头文件才能编译成功。

1、安装基础依赖：
pip install -r requirements/base.txt

2、单独安装关键约束版本包：
pip install pydantic==2.6.4 httpx==0.27.0

3、如需启用浏览器自动化与网页截图功能，额外安装：
pip install playwright
playwright install chromium

4、如需支持微信直连，安装二维码与图像处理模块：
sudo apt install -y python3-qrcode python3-pil
pip install qrcode[pil] Pillow

五、配置大模型接入（OpenRouter 或 百炼）

Hermes Agent 本身不内置模型，必须通过环境变量或配置文件注入 API 密钥与模型端点；Ubuntu 24.04 的 bash 配置文件默认为 ~/.bashrc，需确保变量在 shell 启动时即生效，否则 hermes 命令将无法读取。

1、设置 OpenRouter API Key（以 stepfun/step-3.5-flash 为例）：
echo 'export OPENROUTER_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"' >> ~/.bashrc
echo 'export OPENROUTER_MODEL="stepfun/step-3.5-flash"' >> ~/.bashrc

2、如使用阿里云百炼，配置兼容模式端点：
echo 'export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"' >> ~/.bashrc
echo 'export HERMES_MODEL_PROVIDER="dashscope"' >> ~/.bashrc
echo 'export HERMES_MODEL_NAME="qwen-turbo"' >> ~/.bashrc

3、重载配置使变量立即生效：
source ~/.bashrc

4、验证环境变量是否加载成功：
env | grep -i "api\|model"

六、启动 Hermes Agent 服务

Ubuntu 24.04 默认使用 systemd 作为 init 系统，推荐以服务方式长期运行 Hermes Agent，便于日志管理、开机自启及资源隔离；避免直接前台运行导致终端关闭后进程终止。

1、创建 systemd 服务单元文件：
sudo nano /etc/systemd/system/hermes-agent.service

2、填入以下内容（路径请按实际调整）：
[Unit]
Description=Hermes Agent Service
After=network.target

[Service]
Type=simple
User=$USER
WorkingDirectory=/home/$USER/hermes
ExecStart=/home/$USER/hermes/venv/bin/python -m hermes.cli
Restart=always
RestartSec=10
EnvironmentFile=/home/$USER/.bashrc

[Install]
WantedBy=multi-user.target

3、重载 systemd 配置并启用服务：
sudo systemctl daemon-reload
sudo systemctl enable hermes-agent
sudo systemctl start hermes-agent

4、查看服务状态与实时日志：
sudo systemctl status hermes-agent
sudo journalctl -u hermes-agent -f

终于介绍完啦！小伙伴们，这篇关于《Ubuntu24.04部署HermesAgent详细教程》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布科技周边相关知识，快来关注吧！