hermes agent安装报错需按五步排查：一、确认类unix环境（wsl2+ubuntu）及bash/curl可用；二、验证github域名连通性并调dns；三、检查磁盘空间、~/.bashrc写权限及/usr/local/bin路径；四、升级openssh或配置kexalgorithms/ciphers；五、清理残留文件后重装并运行hermes doctor验证。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在安装 Hermes Agent 时遇到报错，可能是由于环境不兼容、权限不足、网络策略限制或配置缺失导致。以下是多种针对性的故障排查与解决方法：
一、检查系统兼容性与基础环境
原生 Windows 不被支持，Hermes Agent 要求运行在类 Unix 环境中，WSL2 是官方唯一推荐的 Windows 兼容方案。若直接在 PowerShell 或 CMD 中执行安装脚本，将因缺少 bash 运行时和 POSIX 工具链而失败。
1、确认当前系统是否为 Linux 或 macOS；若为 Windows，请启用 WSL2 并安装 Ubuntu 22.04/24.04 发行版。
2、在 WSL2 终端中运行 uname -a，验证输出包含 Linux 内核版本信息。
3、执行 which bash 和 which curl，确保基础工具已就绪。
二、修复网络连接与域名解析异常
安装脚本依赖从 GitHub 拉取远程资源，若 DNS 解析失败或目标域名被拦截，会导致 curl 请求超时或返回空响应，进而中断安装流程。
1、运行 curl -I https://raw.githubusercontent.com，观察是否返回 HTTP 200 响应头。
2、若超时，尝试更换 DNS：执行 echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf 临时覆盖 DNS 配置。
3、若企业网络启用白名单，需放行 raw.githubusercontent.com 和 github.com 域名及其子域。
三、处理权限与文件系统限制
安装脚本需向 ~/.bashrc 写入环境变量，并在 /usr/local/bin 或用户目录创建可执行链接。若当前用户无写入权限，或磁盘空间不足，将触发“Permission denied”或“No space left on device”错误。
1、检查磁盘剩余空间：运行 df -h ~，确认家目录所在分区可用空间 ≥ 500MB。
2、验证对 ~/.bashrc 的写权限：执行 ls -l ~/.bashrc，若权限为只读，使用 chmod u+w ~/.bashrc 修正。
3、若提示无法写入 /usr/local/bin/hermes，改用用户级安装：在安装命令末尾添加 --user 参数（如适用），或手动将二进制复制至 ~/bin 并加入 PATH。
四、规避 SSH 协议协商失败（适用于 gateway 模式安装）
当通过 hermes gateway 启动消息网关并依赖 SSH 连接后端节点时，若目标服务器 SSH 服务版本过旧（如 OpenSSH
1、在目标服务器上运行 sshd -V，确认 OpenSSH 版本。
2、若版本低于 7.0，编辑 /etc/ssh/sshd_config，追加以下三行：
KexAlgorithms ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,diffie-hellman-group-exchange-sha256,diffie-hellman-group14-sha256
Ciphers chacha20-poly1305@openssh.com,aes256-gcm@openssh.com,aes128-gcm@openssh.com,aes256-ctr,aes192-ctr,aes128-ctr
MACs hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,umac-128-etm@openssh.com,hmac-sha2-256,hmac-sha2-512,umac-128@openssh.com
3、重启服务：执行 sudo systemctl restart sshd。
五、诊断并重装损坏的安装状态
部分报错源于已有残留文件干扰（如半安装的 ~/.hermes 目录、损坏的 Python 虚拟环境或冲突的全局 bin 链接），导致新安装流程校验失败。
1、彻底清理旧状态：运行 rm -rf ~/.hermes ~/bin/hermes /usr/local/bin/hermes。
2、清除 Python 缓存：执行 find ~/.cache/pip -name "*hermes*" -delete 2>/dev/null。
3、重新执行安装命令：curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash。
4、验证安装结果：运行 hermes doctor，检查输出中所有项目状态均为 ✅ OK。
