不能用 pip install hermes-agent 全局安装，因其会导致依赖冲突、缺失 ~/.hermes/ 目录结构、且不生成 ~/.hermes/venv/bin/hermes 可执行文件；正确方式是 macos/linux 用 pipx install git+https://github.com/nousresearch/hermes-agent.git@main，windows 用 powershell 执行 install.ps1 脚本。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你正在部署 Hermes Agent，但发现 pip 安装后命令无法识别、依赖冲突频繁、或系统 Python 被意外污染——这不是配置错误，而是全局 pip 环境与 Hermes 自建虚拟环境发生路径混淆的典型症状。官方明确要求 Hermes 必须运行在隔离环境中，直接用系统 pip install hermes-agent 会导致后续所有命令失效。
为什么不能用 pip install hermes-agent 全局安装
这一步看似省事，实则埋下三处硬伤：第一，Hermes 依赖链包含 python-telegram-bot、uvloop 等对 Python 版本敏感的包，全局安装会强制升级/降级系统已有包；第二，其 config.yaml 默认读取 ~/.hermes/ 目录，而全局安装不会创建该结构；第三，【hermes 命令仅在 ~/.hermes/venv/bin/ 下注册，全局 pip 安装根本不会生成该可执行文件】。你执行 hermes --version 时提示 command not found，根源就在这里。
正确做法：优先使用 pipx（推荐 macOS/Linux）
pipx 是专为 CLI 工具设计的隔离安装器，自动为每个工具创建独立虚拟环境并软链接命令到 PATH。
第一步：确保 pipx 已安装且版本 ≥1.4.0：pipx --version；若未安装，执行 python3 -m pip install --upgrade pip && pip install pipx。
第二步：用 pipx 安装 Hermes Agent：pipx install git+https://github.com/NousResearch/hermes-agent.git@main。该命令会自动拉取最新稳定版源码、创建专属 venv、注入 hermes 命令到系统 PATH。
第三步：验证安装效果：hermes --version 应输出类似 hermes 0.14.0；再执行 pipx list，确认 hermes 出现在已安装工具列表中。
注意：pipx 安装后，所有配置文件仍默认存放在 ~/.hermes/，与脚本安装路径完全一致，后续 setup、run 等操作无缝兼容。
Windows 用户必须走 PowerShell + install.ps1 路径
Windows 原生环境不支持 pipx 的符号链接机制，且系统策略常拦截 pip 创建 bin 目录，强行用 pip install 会导致 hermes.exe 丢失或权限拒绝。
方法一：以管理员身份打开 PowerShell 7+ 终端 → 执行 iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1) → 等待完成 → 关闭并重启 PowerShell → 运行 hermes --version 校验。
方法二：若网络受限，可手动下载 install.ps1 脚本保存为本地文件 → 右键属性 → 勾选“解除锁定” → 在 PowerShell 中执行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser → 再运行 .\install.ps1。
【PowerShell 执行策略必须设为 RemoteSigned，否则 activate.ps1 脚本被系统阻止，虚拟环境无法激活】
当 pipx/pip 全局安装已污染环境时的紧急清理
如果你已执行过 pip install hermes-agent 并出现 ImportError 或 ModuleNotFoundError，请立即执行以下三步清除残留：
① 卸载全局包：pip uninstall hermes-agent python-telegram-bot uvloop -y；
② 清理可能残留的命令链接：which hermes（macOS/Linux）或 where hermes（Windows），删除对应路径下的可执行文件；
③ 强制重建 Hermes 专属环境：进入 ~/.hermes（macOS/Linux）或 $env:LOCALAPPDATA\hermes（Windows），执行 rm -rf venv → 再运行一次 pipx install 或 install.ps1 脚本。
这一步不可跳过：残留的 venv 目录会干扰新安装流程，导致依赖重装失败。
