夜雨聆风今天给大家带来Ubuntu 系统完整部署 Hermes Agent 实操教程，全程无踩坑、零基础可直接复刻。本文适配 Ubuntu 20.04 / 22.04 / 24.04 主流版本，包含环境预检、三种安装方案、初始化配置、常用命令、卸载方式及常见报错排查，是目前全网最全面的 Hermes Agent 部署文档之一。
先简单介绍：Hermes Agent 是 NousResearch 推出的开源智能 AI 代理，支持自主任务执行、多模型对接、本地离线运行、命令行交互，可用于自动化开发、代码调试、智能问答、批量任务处理等场景，轻量化、部署简单、扩展性极强。
一、环境前置要求（必看）
1.1 系统适配
✅ 支持：Ubuntu 20.04+、Debian 11+、WSL2-Ubuntu
❌ 不支持：原生 Windows、Ubuntu 18.04 及以下老旧版本
1.2 基础依赖说明
Hermes Agent 官方安装脚本自动适配 Python3.11、Node.js v22、uv、ripgrep、ffmpeg 等核心依赖，无需手动安装，仅需提前安装 Git 工具即可。
1.3 环境预检与基础工具安装
打开 Ubuntu 终端，依次执行以下命令，更新系统源并安装基础依赖：
# 1. 更新系统软件源与已安装包sudo apt update && sudo apt upgrade -y# 2. 安装 Git 核心工具（必备）sudo apt install git -y# 3. 验证 Git 安装是否成功git --version
出现 Git 版本号即代表基础环境准备完成。
二、三种安装方式（按需选择）
本文提供 一键脚本安装（推荐）、pipx 安装、源码本地编译安装 三种方案，优先推荐一键脚本安装，自动配置环境变量、虚拟环境，零配置开箱即用。
方式一：官方一键脚本安装（新手首选、最稳定）
官方封装自动化安装脚本，自动完成依赖下载、环境配置、全局命令注册，全程无需手动干预。
步骤1：执行官方安装命令
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash步骤2：重载环境变量
安装完成后，终端会提示环境变量未生效，执行以下命令重载（根据自己的终端选择）：
# bash 终端（Ubuntu 默认）source ~/.bashrc# zsh 终端用户source ~/.zshrc
步骤3：验证安装结果
# 查看 Hermes 版本hermes --version# 查看帮助信息hermes --help
输出版本信息、帮助文档，代表安装成功✅
方式二：pipx 安装（轻量化、纯净部署）
适合不想占用过多系统资源、需要纯净 Python 环境的用户，pipx 会独立隔离环境，不污染系统全局依赖。
步骤1：安装 pipx 工具
# 安装 pipxpython3 -m pip install --user pipx# 配置环境路径python3 -m pipx ensurepath
步骤2：重启/重载终端
source ~/.bashrc步骤3：安装 Hermes Agent
pipx install hermes-agent步骤4：验证安装
hermes --version方式三：源码编译安装（开发者首选、可自定义修改）
适合需要二次开发、自定义功能、体验最新开发版的用户。
步骤1：克隆官方源码仓库
# 克隆源码git clone https://github.com/NousResearch/hermes-agent.git# 进入项目目录cd hermes-agent
步骤2：安装 uv 包管理器（项目依赖）
curl -LsSf https://astral.sh/uv/install.sh | shsource ~/.bashrc
步骤3：创建虚拟环境并编译安装
# 创建 Python3.11 虚拟环境uv venv venv --python 3.11# 激活虚拟环境source venv/bin/activate# 安装 CLI 核心依赖uv pip install -e ".[cli]"
步骤4：全局注册命令
uv tool install -e .三、首次初始化配置（关键步骤）
安装完成后，必须执行初始化配置，对接大模型接口，否则无法正常使用 AI 对话、任务执行功能。
3.1 执行初始化向导
hermes setup3.2 配置流程详解
选择模型提供商（支持 OpenAI、DeepSeek、通义千问、本地 Ollama 等）
输入对应平台的 API Key
配置模型接口地址（本地模型可填写本地 IP:端口）
确认配置，自动生成配置文件（默认路径：
~/.hermes/config）
3.3 手动修改配置（后续更新密钥/模型）
# 打开配置文件编辑nano ~/.hermes/config
修改完成后 Ctrl+O 保存、Ctrl+X 退出，重启 Hermes 即可生效。
四、启动与基础使用
4.1 启动交互式 CLI 终端
hermes进入交互式界面后，可直接输入指令，例如代码调试、文件分析、自动化任务等。
4.2 后台常驻运行（服务器必备）
服务器部署可使用 nohup 后台运行，关闭终端不中断服务：
nohup hermes > ~/.hermes/run.log 2>&1 4.3 查看运行日志
tail -f ~/.hermes/run.log4.4 添加微信机器人
4.4 添加微信机器人
五、常用核心命令汇总
# 版本查看hermes --version# 帮助文档hermes --help# 初始化配置hermes setup# 重置所有配置hermes setup --reset# 升级 Hermes 到最新版hermes upgrade# 查看运行状态hermes status
六、完整卸载方案
根据自己的安装方式对应卸载，彻底清除残留文件。
6.1 一键脚本安装卸载
# 执行官方卸载脚本bash ~/.hermes/hermes-agent/scripts/uninstall.sh# 清除残留配置rm -rf ~/.hermes
6.2 pipx 安装卸载
pipx uninstall hermes-agentrm -rf ~/.hermes
6.3 源码安装卸载
uv tool uninstall hermes-agentrm -rf hermes-agent venv ~/.hermes
七、常见报错与解决方案（避坑指南）
报错1：command not found: hermes
原因：环境变量未生效
解决：执行 source ~/.bashrc 或重启终端
报错2：依赖安装失败、网络超时
原因：GitHub 网络不稳定
解决：切换网络，或使用国内镜像源克隆源码
报错3：Python 版本不兼容
原因：系统默认 Python 版本低于3.11
解决：手动安装 Python3.11，或使用 uv 虚拟环境隔离版本
报错4：API 调用失败
原因：密钥错误、接口地址异常、模型未开通权限
解决：执行 hermes setup --reset 重新配置密钥与接口
八、总结
1. 新手优先选择官方一键脚本安装，零门槛、最稳定；
2. 轻量化部署用 pipx 安装，环境隔离无冲突；
3. 二次开发、自定义功能选择源码编译安装；
4. 安装后必须执行 hermes setup 配置模型接口，否则无法使用；
5. 服务器部署建议后台常驻运行，搭配日志查看，方便运维。
后续会持续更新 Hermes Agent 进阶玩法：本地 Ollama 模型对接、自动化任务脚本、插件拓展、开机自启配置
