今天给大家带来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 Agentpipx 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 setup3.2 配置流程详解选择模型提供商支持 OpenAI、DeepSeek、通义千问、本地 Ollama 等输入对应平台的API Key配置模型接口地址本地模型可填写本地 IP:端口确认配置自动生成配置文件默认路径~/.hermes/config3.3 手动修改配置后续更新密钥/模型# 打开配置文件编辑 nano ~/.hermes/config修改完成后CtrlO保存、CtrlX退出重启 Hermes 即可生效。四、启动与基础使用4.1 启动交互式 CLI 终端hermes进入交互式界面后可直接输入指令例如代码调试、文件分析、自动化任务等。4.2 后台常驻运行服务器必备服务器部署可使用nohup后台运行关闭终端不中断服务nohup hermes ~/.hermes/run.log 214.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 ~/.hermes6.2 pipx 安装卸载pipx uninstall hermes-agent rm -rf ~/.hermes6.3 源码安装卸载uv tool uninstall hermes-agent rm -rf hermes-agent venv ~/.hermes七、常见报错与解决方案避坑指南报错1command not found: hermes原因环境变量未生效解决执行source ~/.bashrc或重启终端报错2依赖安装失败、网络超时原因GitHub 网络不稳定解决切换网络或使用国内镜像源克隆源码报错3Python 版本不兼容原因系统默认 Python 版本低于3.11解决手动安装 Python3.11或使用 uv 虚拟环境隔离版本报错4API 调用失败原因密钥错误、接口地址异常、模型未开通权限解决执行hermes setup --reset重新配置密钥与接口八、总结1. 新手优先选择官方一键脚本安装零门槛、最稳定2. 轻量化部署用pipx 安装环境隔离无冲突3. 二次开发、自定义功能选择源码编译安装4. 安装后必须执行hermes setup配置模型接口否则无法使用5. 服务器部署建议后台常驻运行搭配日志查看方便运维。后续会持续更新 Hermes Agent 进阶玩法本地 Ollama 模型对接、自动化任务脚本、插件拓展、开机自启配置
