ubuntu/debian安装hermes agent失败主因是python版本不兼容、apt源慢、github直连受限及path未配置；需更换清华源、强制使用python 3.11、用uv替代pip、修复hermes命令路径、通过镜像或代理获取源码。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在 Ubuntu 或 Debian 系统上安装 Hermes Agent 时遇到依赖失败、命令不可用、网络超时或环境冲突等问题，则很可能是由于系统默认 Python 版本不兼容、APT 源缓慢、GitHub 直连受限或 PATH 未正确配置所致。以下是针对该类系统的多种避坑与修复方案：
一、更换系统软件源并更新基础工具
Debian/Ubuntu 默认源在国内访问缓慢，易导致 apt install 失败或超时，进而影响后续 Python、git、curl 等关键依赖的安装。更换为清华或中科大镜像源可显著提升稳定性。
1、确认当前系统版本：执行 lsb_release -a 或 cat /etc/os-release 获取发行版代号（如 jammy、noble、bookworm）。
2、备份原 sources.list：执行 sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak。
3、写入清华源（以 Ubuntu 24.04 noble 为例）：执行 sudo sed -i 's|http://archive.ubuntu.com|https://mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list 与 sudo sed -i 's|http://security.ubuntu.com|https://mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list。
4、更新并安装基础工具：执行 sudo apt update && sudo apt install -y curl git python3-pip python3-venv python3-dev。
二、强制使用 Python 3.11 并规避系统级 pip 冲突
Hermes Agent 明确要求 Python ≥3.11 且不兼容 3.13；而 Debian/Ubuntu 系统常预装 3.9 或 3.12，且部分版本禁用 ensurepip，导致 venv 创建失败。需绕过系统 Python，独立部署受控解释器。
1、安装 Python 3.11 运行时：执行 sudo apt install -y python3.11 python3.11-venv python3.11-dev。
2、验证安装：执行 python3.11 --version，应输出类似 3.11.9。
3、解决 “ensurepip is disabled” 错误：若创建虚拟环境时报此错，执行 sudo apt install -y python3.11-distutils 后重试。
4、创建隔离虚拟环境：执行 python3.11 -m venv ~/.hermes/venv，再激活：source ~/.hermes/venv/bin/activate。
三、使用 uv 替代 pip 加速依赖安装
uv 是由 Astral 开发的超高速 Python 包管理器，编译为 Rust，安装速度远超 pip，且原生支持镜像源与 Python 版本指定，能有效规避 pip timeout 和 externally-managed-environment 报错。
1、通过国内镜像安装 uv：执行 curl -sL https://mirrors.ustc.edu.cn/github-release/astral-sh/uv/LatestRelease/uv-installer.sh | sh。
2、将 uv 加入 PATH：执行 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc。
3、使用 uv 创建带镜像的虚拟环境：执行 uv venv ~/.hermes/venv --python 3.11 --default-index https://pypi.tuna.tsinghua.edu.cn/simple。
4、在激活环境下安装 Hermes：执行 source ~/.hermes/venv/bin/activate && uv pip install -e "./[all,dev]" -i https://pypi.tuna.tsinghua.edu.cn/simple。
四、解决 hermes: command not found 问题
安装脚本或手动安装后运行 hermes 命令提示不存在，通常因可执行文件未被系统 PATH 发现，或符号链接未建立。需显式将 hermes 二进制路径加入用户级 bin 目录并确保其在 PATH 中。
1、确认 hermes 可执行文件位置：进入项目根目录后执行 find . -name "hermes" -type f -executable 2>/dev/null，常见路径为 ./venv/bin/hermes。
2、创建全局可用符号链接：执行 mkdir -p ~/.local/bin && ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes。
3、确保 ~/.local/bin 在 PATH 中：执行 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc。
4、验证命令可用性：执行 hermes --version，应返回版本号而非 command not found。
五、绕过 GitHub 直连失败的三种源码获取方式
官方安装脚本第一步即从 raw.githubusercontent.com 克隆仓库，国内直连极易卡死或报 Connection timed out。必须采用替代方式提前获取源码，再执行本地安装流程。
1、使用 ghfast.top 加速 URL 执行一键安装：执行 curl -fsSL https://ghfast.top/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash。
2、手动克隆镜像仓库（推荐）：执行 git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git ~/.hermes/hermes-agent，然后 cd ~/.hermes/hermes-agent && bash scripts/install.sh --local。
3、配置 Git HTTP 代理（仅限有可用代理端口场景）：执行 git config --global http.proxy http://127.0.0.1:7890 与 git config --global https.proxy http://127.0.0.1:7890，安装完成后建议取消配置以避免干扰其他项目。
