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 配置流程详解

  1. 选择模型提供商（支持 OpenAI、DeepSeek、通义千问、本地 Ollama 等）

  2. 输入对应平台的API Key

  3. 配置模型接口地址（本地模型可填写本地 IP:端口）

  4. 确认配置，自动生成配置文件（默认路径：~/.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.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 模型对接、自动化任务脚本、插件拓展、开机自启配置