Windows用户需先配置WSL2环境，再安装Ubuntu 22.04、编辑.wslconfig限制资源、用镜像源部署Hermes、运行hermes setup配置模型与API Key，并通过hermes doctor等命令验证运行状态。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您是 Windows 用户，希望在本地运行 Hermes Agent，但发现直接安装失败或命令不可识别，则很可能是尚未配置 WSL2 运行环境。以下是专为 Windows 用户设计的 Hermes Agent 新手配置清单，覆盖从底层依赖启用到首次成功运行的全流程：
一、验证并启用 WSL2 底层支持
WSL2 无法仅靠开启功能即正常工作，其稳定运行依赖 BIOS 级虚拟化、Windows 功能模块与内核驱动三者协同。任一缺失都将导致 Hermes Agent 启动卡在初始化阶段或报错 0x80370102。
1、按 Win + R 输入 winver，确认系统版本为 Windows 11 21H2（内部版本 19044）或更高；
2、以管理员身份打开 PowerShell，执行：systeminfo | findstr "Hyper-V\|Virtualization"，检查输出中“虚拟化已在固件中启用”和“已检测到虚拟机监控程序”均为“是”；
3、若任一条件不满足，需重启进入 BIOS/UEFI，将 Intel VT-x 或 AMD-V 设为 Enabled，并在 Windows “启用或关闭功能”中勾选“适用于 Linux 的 Windows 子系统”和“虚拟机平台”；
4、执行两条 dism 命令后，必须重启系统，否则 WSL2 内核无法加载，后续所有操作均无效。
二、安装 Ubuntu 发行版并强制资源约束
Hermes Agent 对内存带宽与 I/O 延迟敏感，Ubuntu 默认配置易在模型推理阶段触发 OOM Killer 或 swap 抖动。需通过 .wslconfig 文件强制限制资源分配，避免与 Windows 主机争抢物理内存。
1、从 Microsoft Store 安装 Ubuntu 22.04 LTS（非 20.04，因其 Python 包兼容性较差）；
2、首次启动完成初始化后，退出 WSL，在 Windows 用户目录下新建文件 .wslconfig（注意开头为点号）；
3、用记事本或 VS Code 编辑该文件，写入以下内容：
[wsl2]
memory=6GB
swap=2GB
localhostForwarding=true；
4、在 PowerShell 中执行 wsl --shutdown，再重新启动 Ubuntu，运行 free -h 验证内存是否生效；
5、禁止勾选“Hyper-V”功能（除非同时运行 Docker Desktop），因其会与 WSL2 虚拟化层产生调度冲突，导致 Hermes Agent 多线程任务响应延迟突增。
三、部署 Hermes Agent 并跳过网络瓶颈
国内用户常因 GitHub 访问不稳定导致一键脚本失败。官方安装脚本虽自动处理依赖，但 git clone 步骤极易超时中断，需采用镜像替代方案确保安装连贯性。
1、在 Ubuntu 终端中执行：git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git ~/.hermes/hermes-agent；
2、确认目录创建成功：ls ~/.hermes/hermes-agent 应显示 scripts/ 与 README.md 等内容；
3、执行安装脚本：curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash；
4、脚本检测到 ~/.hermes/hermes-agent 已存在，将自动跳过 clone，直接进入虚拟环境创建与依赖安装阶段；
5、安装完成后运行：source ~/.bashrc 刷新环境变量。
四、完成首次交互式配置
Hermes Agent 不提供预置模型，首次运行前必须通过 hermes setup 向导完成模型服务选择与 API Key 注入。该步骤决定后续所有对话的响应质量与可用工具范围。
1、在终端输入：hermes setup；
2、按提示选择模型服务厂商（如 OpenRouter、OpenAI、Anthropic 或 Nous Portal）；
3、粘贴复制好的 API Key（注意不要额外空格或换行）；
4、选择默认模型（新手推荐 MiMo V2 Pro，可通过 hermes model 后续切换）；
5、启用默认工具集（包括文件读写、网页检索、代码执行等），保持默认选项即可。
五、验证运行状态并排查关键异常
安装与配置完成后，需执行最小闭环测试：启动 Agent、发送基础指令、观察响应是否生成。部分常见异常可快速定位，无需重装。
1、运行诊断命令：hermes doctor，检查 Python、Node.js、API Key 等核心项状态；
2、若输出中出现 ⚠ 未检测到 APIKey，说明配置未持久化，需再次运行 hermes setup 并确认最后一步显示 “Configuration saved successfully”；
3、若命令 hermes --help 报错 command not found，说明 ~/.hermes/bin 未加入 PATH，需手动在 ~/.bashrc 末尾追加：export PATH="$HOME/.hermes/bin:$PATH"，再执行 source ~/.bashrc；
4、若启动后卡在 Loading memory... 超过 60 秒，检查 WSL2 是否启用了 localhostForwarding=true，并确认 Windows 端代理软件已开启“允许局域网连接”选项。
