Hermes Agent 是 Nous Research 开源的 AI Agent 框架，可运行在终端、消息平台和 IDE 中。2025 年 5 月 15 日，Hermes 正式发布到 PyPI，新增了 pip install 和 uv pip install 两种安装方式。本文梳理三种安装方式的区别、切换时的坑、以及推荐方案。
三种安装方式对比
| 方式 | 命令 | 特点 |
| 脚本 / git | curl -fsSL ...install.sh | bash | 跟踪 main 分支最新 commit，自带 venv，支持 TUI |
| pip | pip install hermes-agent | PyPI 稳定版，使用系统 Python 环境 |
| uv venv | uv venv + uv pip install | uv 管理的隔离环境，依赖解析快，推荐方式 |
脚本安装本质是 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 <<'EOF'
# 优先使用系统已有 Python，避免 uv 自动下载时走 GitHub 太慢
python-preference = "system"
python-downloads = "manual"
# Python 包索引源
[[index]]
name = "tuna"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
EOF3. 安装 Hermes 及依赖
# 激活环境
source ~/.hermes/venv/bin/activate
# 安装 hermes-agent 和 MCP SDK
uv pip install hermes-agent mcpmcp 是 MCP SDK，Hermes 的 MCP Server 功能依赖它。如果后续需要追加其他依赖，直接在激活环境后 uv pip install 即可：
# 追加依赖示例
uv pip install requests httpx
# 查看已安装的包
uv pip list4. 配置 PATH 并运行初始化
uv venv 安装的 hermes 可执行文件在 ~/.hermes/venv/bin/ 下，需要确保它在 PATH 中：
# 添加到 ~/.bashrc 或 ~/.zshrc
export PATH="$HOME/.hermes/venv/bin:$PATH"
# 使配置生效
source ~/.bashrc
# 运行初始化
hermes postinstall # 安装辅助能力：Node.js、浏览器、ripgrep、ffmpeg 等
hermes setup # 交互式配置向导hermes postinstall 过程中需要从 GitHub 下载资源。如果网络受限，可以参考 Hermes 安装代理配置 中的解决方案。
从脚本版迁移到 uv venv 版的常见坑
hermes update 不可用
通过 pip 或 uv venv 安装的 Hermes，hermes update 命令会报错。该命令是为 git 脚本安装设计的（执行 git pull）。
正确做法：
# uv venv 安装的
source ~/.hermes/venv/bin/activate
uv pip install --upgrade hermes-agent
# pip 安装的
pip install --upgrade hermes-agentTUI 界面不可用
hermes --tui 依赖 ui-tui 前端目录，目前 PyPI 发布包中未包含该模块。如果需要 TUI 界面，暂时只能使用脚本/git 安装方式。
覆盖安装注意事项
如果你在同一环境中先用 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 写入 ~/.hermes/.env：
# 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配置完成后运行 hermes doctor 验证各项依赖状态。
💡 关于 hermes doctor 显示 missing key：即使你在 .env 中配置了某个 Key 并在 hermes tools 中关闭了对应工具，hermes doctor 仍可能显示该 Key 缺失。这是因为 doctor 检查的是所有已注册工具的依赖，而非当前启用的工具子集。只要工具功能正常，可以忽略这些提示。
推荐安装方案
普通 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升级用 uv pip install --upgrade hermes-agent。
长期运行 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这种方式可以自由 pip install 其他包，适合需要深度定制的场景。
想追 main 最新功能 → git / 脚本安装
适合贡献者或想第一时间体验新功能的用户。稳定性风险自担。
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash更新用 hermes update（本质是 git pull）。
常见问题
Q: 为什么 hermes update 报 No virtual environment found？
hermes update 是为 git 脚本安装设计的，它会执行 git pull 更新源码并重建 venv。通过 pip 或 uv venv 安装时，不存在 ~/.hermes/hermes-agent/ 这个 git 仓库目录，因此 update 找不到 venv。
解决：使用对应包管理器的升级命令：
- uv venv：
source ~/.hermes/venv/bin/activate && uv pip install --upgrade hermes-agent - pip：
pip install --upgrade hermes-agent
Q: 为什么 hermes --tui 报找不到 ui-tui？
TUI 界面依赖 ui-tui 前端模块，该模块目前未包含在 PyPI 发布包中。脚本安装方式会从 GitHub 仓库拉取完整源码，包含 TUI 相关文件。
解决：如需 TUI，暂时使用脚本/git 方式安装。或关注 PyPI 版本更新，等待 TUI 模块被打包。
Q: 为什么工具已经关闭但 hermes doctor 仍显示 missing key？
hermes doctor 检查的是所有已注册工具的环境变量依赖，而不是当前启用的工具。关闭某个工具只是在运行时跳过它，doctor 仍会报告其依赖缺失。
解决：如果确认不需要该工具，doctor 的 missing key 提示可以忽略。不影响正常使用。
Q: uv venv 安装后如何追加依赖？
uv venv 的环境和标准 venv 一样，激活后直接用 uv pip install 即可：
# 激活环境
source ~/.hermes/venv/bin/activate
# 追加依赖
uv pip install mcp requests httpx
# 查看已安装的包
uv pip list如果需要大量额外依赖且不想每次手动 activate，可以在 ~/.bashrc 中 alias：
alias hermes='~/.hermes/venv/bin/hermes'