Hermes_Agent_Windows安装文档

Hermes Agent Windows 安装文档适用系统：Windows 10/11 + WSL2 + Ubuntu整理自实际安装过程，包含常见报错解决方案前置说明Hermes Agent不支持原生 Windows，必须通过WSL2（Windows Linux 子系统）安装。WSL2 会在 Windows 里运行一个完整的 Linux 环境，Ubuntu 的数据存放在一个.vhdx虚拟磁盘文件里，不是双系统，也不是虚拟机，可以理解为"装在一个文件里的 Linux"。第一步：安装 WSL2 + Ubuntu（指定到 D 盘）以管理员身份打开 PowerShell，运行：wsl--install-d Ubuntu--location"D:\WSL\Ubuntu"--location参数可以把 Ubuntu 装到 D 盘，避免占用 C 盘空间。安装完成后重启电脑，重启后会弹出 Ubuntu 窗口，设置用户名和密码（这是 Linux 账号，自定义即可）。第二步：进入 WSL打开 CMD 或 PowerShell，输入：wsl看到如下提示即成功进入：用户名@电脑名:~$常见问题：无法将磁盘附加到 WSL2（ERROR_SHARING_VIOLATION）原因:有其他程序（如 360、Docker）占用了.vhdx文件。解决：先运行wsl --shutdown，再重启电脑，重启后不要打开 Docker/360，直接打开 CMD 输入wsl。原因：磁盘管理器里意外挂载了这个 VHDX。解决：检查并分离虚拟磁盘按 Win + X → 选择「磁盘管理」在下方列表里看有没有出现一个「WSL」或「Ubuntu」相关的虚拟磁盘（容量很大，通常就是 ext4.vhdx）如果有，右键它 → 「分离 VHD」或「脱机」第三步：更新系统并安装基础工具进入 WSL 后依次运行：sudoaptupdatesudoaptupgrade-ysudoaptinstall-ycurlgitunzip第四步：安装 uv（Python 包管理器）curl-LsSfhttps://astral.sh/uv/install.sh|shsource~/.bashrc第五步：获取 Hermes Agent 源码方式一：下载 ZIP（推荐，网络不稳定时使用）如果你已经从 GitHub 下载了 ZIP 解压到D:\WSL\hermes-agent，在 WSL 里直接进入：cd/mnt/d/WSL/hermes-agentWindows 的 D 盘在 WSL 里挂载为/mnt/d/方式二：Git Clone（网络稳定时使用）gitconfig--globalhttp.version HTTP/1.1gitconfig--globalcore.compression0gitclone https://github.com/NousResearch/hermes-agent.git ~/hermes-agentcd~/hermes-agent常见问题：git clone 报 RPC failed / early EOF原因：GitHub 连接中断，通常是网络不稳定或 Git 使用 GnuTLS 后端。解决方案：# 升级 Git 到 OpenSSL 版本sudoadd-apt-repository ppa:git-core/ppasudoaptupdatesudoaptinstall--reinstallgit或直接用 curl 下载 ZIP 替代：curl-Lhttps://github.com/NousResearch/hermes-agent/archive/refs/heads/main.zip-ohermes.zipunziphermes.zipmkdir-p~/.hermesmvhermes-agent-main ~/.hermes/hermes-agentcd~/.hermes/hermes-agent第六步：安装依赖进入项目目录后运行：uv venv venv--python3.11sourcevenv/bin/activate uv pipinstall-e".[all]"安装完成后会看到大量包名滚动输出，最后没有报错即为成功。第七步：初始化配置hermes setup选择Quick setup，按提示操作：选择模型提供商→ 我使用的是 DeepSeek（国内速度快，价格低）或 OpenRouter填入 API Key→ 从对应平台获取Base URL→ 直接回车使用默认值（https://api.deepseek.com/v1）消息平台→ 先选 Skip，之后用hermes gateway setup配置第八步：启动hermes常见报错速查HTTP 400 错误❌ Non-retryable client error (HTTP 400)原因：API Key 填写有误（如重复填写多次）。检查并修复：cat~/.hermes/.env# 查看当前配置nano~/.hermes/.env# 编辑修复确保DEEPSEEK_API_KEY=后面只有一个Key，没有空格和重复。修改完保存：Ctrl+X→Y→Enter验证 API Key 是否有效curlhttps://api.deepseek.com/chat/completions\-H"Content-Type: application/json"\-H"Authorization: Bearer 你的API_KEY"\-d'{"model":"deepseek-chat","messages":[{"role":"user","content":"你好"}],"stream":false}'返回包含"content"的 JSON 即为正常。WSL 粘贴命令操作方法粘贴Ctrl+Shift+V或 鼠标右键复制选中文字后自动复制强制停止程序Ctrl+C注意：在 Linux 终端里Ctrl+C是中止程序，不是复制。配置文件位置文件路径用途API Keys~/.hermes/.env存放各平台 API Key配置文件~/.hermes/config.yaml模型、工具等设置会话记录~/.hermes/sessions/历史对话常用命令hermes# 开始对话hermes model# 切换模型/提供商hermes setup# 重新运行配置向导hermes setup tools# 配置工具（网页搜索、图片生成等）hermes gateway# 配置 Telegram/Discord 等消息平台hermes doctor# 诊断问题hermes update# 更新到最新版本可选工具（需额外 API Key）工具所需 Key获取地址网页搜索TAVILY_API_KEYtavily.com图片生成FAL_KEYfal.aiSkills HubGITHUB_TOKENgithub.com/settings/tokens多模型混合OPENROUTER_API_KEYopenrouter.ai文档整理自实际安装调试过程，适用于 Windows 10/11 环境。祝大家都可以安装成功