Hermes Agent 在 Windows 上安装失败的根本原因有五：一、原生命令行不兼容，需 bash 环境；二、缺少 WSL2 或发行版不合规；三、Python 非 3.11 或缺失 venv/dev 组件；四、raw.githubusercontent.com 访问受阻；五、权限或 PATH 配置异常。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试在 Windows 系统上直接安装 Hermes Agent，但安装过程失败或命令无法识别，则很可能是由于系统环境不满足其原生运行要求。以下是导致该问题的多种根本原因及对应验证方式：
一、原生命令行环境不兼容
Hermes Agent 是一个重度依赖类 Unix 工具链的 Python 应用，官方明确不支持在 CMD、PowerShell 或 Git Bash 中执行安装脚本。这些环境缺乏 POSIX 兼容层、bash 内置命令及标准系统库，会导致脚本解析中断或命令未找到。
1、检查当前终端类型：若启动的是 Windows Terminal 中的“Windows PowerShell”或“命令提示符”，即属于不兼容环境。
2、运行echo $SHELL，若输出为空或报错，说明未运行在 bash shell 下。
3、尝试执行ls -la，若提示“不是内部或外部命令”，则确认当前环境无基本 Unix 工具支持。
二、缺少 WSL2 及合规 Linux 发行版
WSL2 是官方唯一推荐且经验证可行的 Windows 兼容方案，它提供完整的 Linux 内核与用户空间。未启用 WSL2 或安装了非官方/过旧发行版（如 Alpine、Debian 11），将导致 uv、systemd 替代组件或 C 扩展编译失败。
1、在 PowerShell 中运行wsl -l -v，确认已安装且状态为“Running”的发行版名称与版本号。
2、若输出为空，说明 WSL2 未启用，需以管理员身份运行dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart后重启系统。
3、若已安装但版本为 Ubuntu 20.04 或更低，建议卸载并重新安装 Ubuntu 22.04 或 24.04 官方镜像。
三、Python 版本冲突或缺失关键组件
Hermes Agent 强制要求 Python 3.11，且依赖 uv 构建虚拟环境。Windows 全局 Python 若为 3.9、3.10 或 3.13，会干扰 uv 的自动版本选择逻辑；若未安装 python3.11-venv 或 python3.11-dev 包，则虚拟环境初始化失败。
1、在 WSL2 终端中运行python3 --version，确认输出为 Python 3.11.x。
通过 SSH 隧道从 Android 设备在互联网上对 Windows PC 实现完整远程控制的设置与使用指南，适用于远程桌面访问、安全 RDP 等。
2、若显示 3.13.x，执行uv python install 3.11强制注册兼容解释器。
3、运行python3.11 -m venv --help，若报错“no module named venv”，则需安装对应开发包：sudo apt install -y python3.11-venv python3.11-dev。
四、网络资源访问受阻
安装脚本默认从 raw.githubusercontent.com 拉取源码和配置，国内直连常因 DNS 污染或连接超时中断。此时脚本卡在 clone 步骤或返回空响应，误判为 GitHub 访问失败而非网络策略问题。
1、在 WSL2 中执行curl -I https://raw.githubusercontent.com，观察是否返回 HTTP/2 200。
2、若超时，尝试更换 DNS：echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf。
3、若仍失败，改用国内加速地址执行安装：curl -fsSL https://ghfast.top/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash。
五、权限与路径配置异常
安装脚本需向 ~/.bashrc 写入 PATH 条目，并在 ~/.local/bin 或 /usr/local/bin 创建可执行链接。若用户主目录挂载为 NTFS、磁盘配额受限、或 ~/.bashrc 被设为只读，将触发 Permission denied 错误，且 hermes 命令在新终端中不可见。
1、运行ls -ld ~，确认输出中包含drwxr-xr-x 及所属用户为当前登录用户。
2、执行ls -l ~/.bashrc，若权限含 -r--r--r--，则需运行chmod u+w ~/.bashrc 解除只读。
3、安装完成后，检查~/.local/bin 是否已加入 PATH：echo $PATH | grep local，若无结果，手动执行echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc。
