# Hermes Agent 安装指南：脚本、pip、uv venv 三种部署方式的选择与切换

- 原文地址：https://www.kuddy.cn/archives/345
- 发布时间：2026-05-19 22:59:19
- 更新时间：2026-05-19 23:24:55
- 分类：AI
- 标签：AI Agent, CLI, Hermes, Python, uv

> Hermes Agent 支持脚本/git、pip、uv venv 三种安装方式。本文梳理各方式的区别、从旧版切换时的坑、Python 版本建议、以及推荐安装方案，附常见问题解答。

---

Hermes Agent 是 Nous Research 开源的 AI Agent 框架，可运行在终端、消息平台和 IDE 中。2025 年 5 月 15 日，Hermes 正式发布到 [PyPI](https://pypi.org/project/hermes-agent/)，新增了 pip install 和 uv pip install 两种安装方式。本文梳理三种安装方式的区别、切换时的坑、以及推荐方案。





## 三种安装方式对比




**方式****命令****特点**脚本 / gitcurl -fsSL ...install.sh | bash跟踪 main 分支最新 commit，自带 venv，支持 TUIpippip install hermes-agentPyPI 稳定版，使用系统 Python 环境uv venvuv venv + uv pip installuv 管理的隔离环境，依赖解析快，推荐方式




脚本安装本质是 git clone + 创建 venv，优点是始终跟最新代码，缺点是 main 分支一天几百个 commit，稳定性不可控。pip 和 uv venv 安装的是 PyPI 上的发布版本，行为可复现。





**Python 版本建议固定到 3.11。**Hermes 的依赖（尤其是 Twisted 相关）在 3.12+ 上偶有兼容问题，3.11 是经过充分验证的版本。





## 安装步骤（uv venv 方式）





### 1. 卸载旧的脚本安装版本（如有）





如果你之前用 git 脚本安装过，需要先卸载。脚本安装的 Hermes 带有自己的 venv，和 uv venv 的隔离环境互不干扰，但二进制路径会冲突。





```
# 检查是否为脚本安装
ls ~/.hermes/hermes-agent/venv/bin/hermes

# 备份配置目录（可选，删除时可选择保留配置）
cp -a ~/.hermes ~/.hermes.bak.$(date +%F-%H%M%S)

# 停止 gateway（如果在运行）
hermes gateway stop 2>/dev/null || true

# 卸载，选择保留配置（选项 1），完成后输入 yes 确认
hermes uninstall
```





⚠️ hermes uninstall 会删除 ~/.hermes/hermes-agent/ 目录。如果选择选项 2（全删），配置文件也会被移除。建议先备份。





### 2. 创建 uv 虚拟环境





```
# 在 ~/.hermes 下创建 venv，指定 Python 3.11
uv venv --python python3.11 ~/.hermes/venv
```





如果系统没有 Python 3.11，uv 会自动下载。国内用户如果下载慢，可以配置 uv 镜像源：





```
mkdir -p ~/.config/uv
cat > ~/.config/uv/uv.toml 



### 3. 安装 Hermes 及依赖





```
# 激活环境
source ~/.hermes/venv/bin/activate

# 安装 hermes-agent 和 MCP SDK
uv pip install hermes-agent mcp
```









```
# 追加依赖示例
uv pip install requests httpx

# 查看已安装的包
uv pip list
```





### 4. 配置 PATH 并运行初始化





uv venv 安装的 hermes 可执行文件在 



```
# 添加到 ~/.bashrc 或 ~/.zshrc
export PATH="$HOME/.hermes/venv/bin:$PATH"

# 使配置生效
source ~/.bashrc

# 运行初始化
hermes postinstall   # 安装辅助能力：Node.js、浏览器、ripgrep、ffmpeg 等
hermes setup         # 交互式配置向导
```









## 从脚本版迁移到 uv venv 版的常见坑





### hermes update 不可用





通过 pip 或 uv venv 安装的 Hermes，



**正确做法：**





```
# uv venv 安装的
source ~/.hermes/venv/bin/activate
uv pip install --upgrade hermes-agent

# pip 安装的
pip install --upgrade hermes-agent
```





### TUI 界面不可用









### 覆盖安装注意事项





如果你在同一环境中先用 pip 安装，又尝试用 uv venv 安装（或反之），可能出现路径冲突。建议：





```
# 先清理旧的
pip uninstall hermes-agent

# 删除可能残留的 shim
rm -f ~/.local/bin/hermes     # ⚠️ 确认这个 hermes 确实是旧的再删

# 再用 uv venv 重新安装
uv venv --python python3.11 ~/.hermes/venv
source ~/.hermes/venv/bin/activate
uv pip install hermes-agent mcp
```





## 工具依赖配置





安装完成后，部分工具需要额外配置 API Key 才能启用。将 Key 写入 



```
# Firecrawl - Web 搜索与内容提取组件
# 申请地址：https://www.firecrawl.dev/
FIRECRAWL_API_KEY=fc-xxxxxxxxxxxx

# OpenRouter - 多模型路由，有免费模型可用
# 申请地址：https://openrouter.ai/
OPENROUTER_API_KEY=sk-or-xxxxxxxxxxxx

# GitHub Token - 用于 skills 仓库、代码操作等
# 申请地址：https://github.com/settings/tokens
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
```





配置完成后运行 



💡 **关于 



## 推荐安装方案





### 普通 CLI 用户 → uv venv





适合日常对话、代码辅助、任务执行等场景。uv 依赖解析快、环境隔离、升级方便。





```
uv venv --python python3.11 ~/.hermes/venv
source ~/.hermes/venv/bin/activate
uv pip install hermes-agent mcp
hermes postinstall
hermes setup
```





升级用 



### 长期运行 gateway / 需要额外 Python 依赖 → Python 3.11 venv + pip





如果你需要运行 gateway（Telegram、Discord 等消息平台接入）、挂载 MCP Server、或安装大量额外的 Python 库，标准 venv + pip 更灵活：





```
python3.11 -m venv ~/.hermes/venv
source ~/.hermes/venv/bin/activate
pip install hermes-agent mcp
hermes postinstall
hermes setup
```





这种方式可以自由 



### 想追 main 最新功能 → git / 脚本安装





适合贡献者或想第一时间体验新功能的用户。稳定性风险自担。





```
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```





更新用 



## 常见问题





### Q: 为什么 







**解决：**使用对应包管理器的升级命令：





1. uv venv：



### Q: 为什么 



TUI 界面依赖 



**解决：**如需 TUI，暂时使用脚本/git 方式安装。或关注 PyPI 版本更新，等待 TUI 模块被打包。





### Q: 为什么工具已经关闭但 







**解决：**如果确认不需要该工具，doctor 的 missing key 提示可以忽略。不影响正常使用。





### Q: uv venv 安装后如何追加依赖？





uv venv 的环境和标准 venv 一样，激活后直接用 



```
# 激活环境
source ~/.hermes/venv/bin/activate

# 追加依赖
uv pip install mcp requests httpx

# 查看已安装的包
uv pip list
```





如果需要大量额外依赖且不想每次手动 activate，可以在 



```
alias hermes='~/.hermes/venv/bin/hermes'
```





## 参考链接





3. [Hermes Agent 官方文档](https://hermes-agent.nousresearch.com/docs/)
4. [PyPI - hermes-agent](https://pypi.org/project/hermes-agent/)
5. [Hermes 安装代理配置](https://www.kuddy.cn/archives/250)
6. [GitHub - NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)