WSL2 环境下 Hermes Agent 部署指南
方案一：WSL2 完整部署（推荐）
启用 Linux 子系统
以管理员身份启动 PowerShell，执行以下命令：
wsl --install -d Ubuntu-22.04该指令会自动配置 WSL2 并部署 Ubuntu 22.04，完成后需重启系统。
配置 Ubuntu 环境
重启后系统会自动打开 Ubuntu 终端，按提示创建账户与密码（输入密码时无回显显示）。
部署 Hermes Agent
在 Ubuntu 终端中依次执行：
# 更新软件源
sudo apt update && sudo apt upgrade -y
# 安装版本控制工具
sudo apt install -y git
# 执行官方安装脚本（国内加速镜像）
curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash运行程序
hermes初次启动需配置大模型服务商的访问密钥（支持 OpenAI、Anthropic、OpenRouter 等平台）。
方案二：Windows 原生环境快速体验
系统要求
- Windows 10 版本 2004 或更高，或 Windows 11
- PowerShell 7.2 及以上版本（建议通过 Microsoft Store 安装 Windows Terminal）
自动化安装
管理员权限下打开终端，执行：
irm https://res1.hermesagent.org.cn/install.ps1 | iex安装脚本将自动配置：uv 包管理器、Python 3.11、Node.js、Git、ripgrep、ffmpeg。等待全部组件安装完毕（显示绿色勾选标记）。
启动应用
关闭当前终端窗口，重新打开 PowerShell 以加载环境变量，执行：
hermes故障排查
命令未识别
- WSL 环境：执行
source ~/.bashrc或重启终端窗口 - Windows 环境：完全关闭后重新打开 PowerShell
依赖组件安装异常
- 网络受限时尝试切换手机热点或配置镜像源
- 手动补装方案：
winget install Python.Python.3.11 winget install OpenJS.NodeJS winget install Git.Git
认证失败（401 错误）
修改配置文件中的密钥：
- WSL 路径：
~/.hermes/config.yaml - Windows 路径：
C:\Users\%USERNAME%\.hermes\config.yaml
更新 api_key 字段后保存，重启 Hermes 生效。
方案对比
| 部署方式 | 优势 | 局限 | 适用场景 |
|---|---|---|---|
| WSL2 | 官方维护、生态完整、稳定性高 | 需额外配置 Linux 子系统 | 生产环境、长期开发、自动化工作流 |
| 原生 PowerShell | 即装即用、无虚拟化开销 | 部分特性可能存在兼容性问题 | 功能验证、临时使用、轻度需求 |
