Ubuntu 系统安装 Hermes Agent 使用教程

今天给大家带来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 工具

# 安装 pipx
python3 -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 | sh
source ~/.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 setup

3.2 配置流程详解

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.log

五、常用核心命令汇总

# 版本查看
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-agent
rm -rf ~/.hermes

6.3 源码安装卸载

uv tool uninstall hermes-agent
rm -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 模型对接、自动化任务脚本、插件拓展、开机自启配置