安装问题

安装 Hermes Agent 时可能会遇到各种环境问题。本页涵盖最常见的安装故障及其解决方案。

Python 版本不兼容

症状： 安装时报 SyntaxError 或提示 Python 版本不支持。

原因： Hermes Agent 需要 Python 3.10 或更高版本。

解决方案：

# 检查当前 Python 版本
python3 --version

# 如果版本低于 3.10，需要升级

Ubuntu / Debian 升级 Python

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev

# 设置为默认版本
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1

macOS 升级 Python

brew install [email protected]

使用 uv 管理 Python

# uv 会自动安装正确版本的 Python
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

提示

推荐使用 Python 3.11+，这是 Hermes Agent 测试最充分的版本。

依赖冲突

症状： pip install 时报依赖版本冲突错误。

原因： 系统 Python 环境中已安装的包与 Hermes Agent 的依赖不兼容。

解决方案：

# 方法 1：使用虚拟环境（推荐）
python3 -m venv ~/.hermes-venv
source ~/.hermes-venv/bin/activate
pip install hermes-agent

# 方法 2：使用一键安装脚本（自动处理虚拟环境）
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 方法 3：强制重装
pip install --force-reinstall hermes-agent

# 方法 4：使用 uv 替代 pip（更快的依赖解析）
pip install uv
uv pip install hermes-agent

权限不足

症状： 安装时报 Permission denied 或 [Errno 13]。

原因： 尝试安装到系统级 Python 目录但没有足够权限。

解决方案：

# ❌ 不要用 sudo 安装
# sudo pip install hermes-agent

# ✅ 方法 1：使用 --user 标志
pip install --user hermes-agent

# ✅ 方法 2：使用虚拟环境
python3 -m venv myenv
source myenv/bin/activate
pip install hermes-agent

# ✅ 方法 3：修复 ~/.hermes 目录权限
sudo chown -R $(whoami):$(whoami) ~/.hermes

警告

永远不要用 sudo pip install。这会将包安装到系统目录，可能导致其他程序异常。如果之前已经用 sudo 安装过，先卸载干净：

sudo pip uninstall hermes-agent

网络超时或下载失败

症状： 安装时无法下载包或连接超时。

原因： 网络问题，特别是在中国大陆访问 PyPI 可能较慢。

解决方案：

# 方法 1：使用国内镜像
pip install hermes-agent -i https://pypi.tuna.tsinghua.edu.cn/simple

# 方法 2：使用 Hermes 国内镜像安装脚本
curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

# 方法 3：设置 pip 永久使用镜像
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 方法 4：设置代理
export HTTPS_PROXY=http://127.0.0.1:7890
pip install hermes-agent

Git 克隆失败

症状： git clone 超时或连接被拒绝。

原因： GitHub 访问受限。

解决方案：

# 方法 1：使用 GitHub 镜像
git clone https://ghproxy.com/https://github.com/NousResearch/hermes-agent.git

# 方法 2：配置 Git 代理
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# 方法 3：直接下载 zip 包
wget https://github.com/NousResearch/hermes-agent/archive/refs/heads/main.zip
unzip main.zip
cd hermes-agent-main
pip install -e .

WSL2 特有问题

症状： 在 WSL2 中安装时遇到特殊错误。

常见问题与解决方案：

# 问题 1：WSL2 中缺少编译工具
sudo apt update && sudo apt install -y build-essential python3-dev

# 问题 2：文件系统性能差（跨 Windows/Linux 文件系统）
# 不要在 /mnt/c/ 下安装，改用 Linux 原生文件系统
cd ~
git clone https://github.com/NousResearch/hermes-agent.git

# 问题 3：DNS 解析失败
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

Docker 安装问题

症状： Docker 拉取镜像失败。

解决方案：

# 方法 1：使用国内 Docker 镜像源
docker pull registry.cn-hangzhou.aliyuncs.com/nousresearch/hermes-agent:latest

# 方法 2：配置 Docker 代理
mkdir -p /etc/systemd/system/docker.service.d
cat > /etc/systemd/system/docker.service.d/proxy.conf << EOF
[Service]
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

# 方法 3：手动导入
# 在有网络的机器上导出镜像
docker save nousresearch/hermes-agent:latest -o hermes-agent.tar
# 传输到目标机器后导入
docker load -i hermes-agent.tar

uv 安装失败

症状： 一键安装脚本中 uv 安装失败。

解决方案：

# 手动安装 uv
curl -fsSL https://astral.sh/uv/install.sh | sh

# 或使用 pip 安装
pip install uv

# 然后重新运行 Hermes 安装脚本
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装后验证

安装完成后，运行以下命令验证一切正常：

hermes --version    # 确认版本号
hermes doctor       # 全面诊断

如果 hermes doctor 全部显示 ✅，说明安装成功。

完整重装流程

如果以上方案都无法解决，可以尝试完全重装：

# 1. 备份重要数据
cp -r ~/.hermes ~/.hermes.backup

# 2. 清除旧安装
pip uninstall hermes-agent
rm -rf ~/.hermes-agent
rm -rf ~/.hermes-venv

# 3. 重新安装
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 4. 恢复数据
cp -r ~/.hermes.backup/memory ~/.hermes/
cp -r ~/.hermes.backup/skills ~/.hermes/

相关页面

• 常见错误 — 运行时的常见错误
• 模型问题 — LLM 配置相关故障
• hermes doctor 诊断 — 自动诊断工具
• Linux 安装 — 详细安装指南