Windows 安装
点击加入 中文社区微信群，提问并获取群内大佬帮助。
如果你主要在 Windows 上使用 Hermes Agent，这一页就是给你的。重点只有一句话：Windows 和类 Linux / macOS 的安装命令不一样。
先决定走哪条路径
| 路径 | 适合谁 | 推荐程度 | 你要运行的命令 |
|---|---|---|---|
| WSL2 + Ubuntu | 想要最稳的日常使用体验，希望尽量贴近官方文档、终端工具和自动化工作流 | 强烈推荐 | 在 WSL2 里运行 install.sh |
| 原生 PowerShell | 想先在 Windows 本机快速跑起来，不想先配置 WSL2 | 可用，但更容易遇到兼容性问题 | 在 PowerShell 里运行 install.ps1 |
- 长期使用 / 工具链完整 / 网关与自动化更省心：优先选 WSL2。
- 只是想先在 Windows 本机跑通 CLI：可以直接用 PowerShell。
如果你在中国大陆安装 Hermes，可能会遇到 raw.githubusercontent.com、PyPI、Node.js 下载或 npm registry 较慢的问题。站内不直接展开写代理/镜像配置步骤，建议直接参考这些外链：
- WSL 安装（中文帖子）：Windows 10/11 安装 WSL2 指南
- WSL 终端代理 / 网络互通（官方）：Microsoft Learn - Accessing network applications with WSL
- GitHub Raw 下载加速：清华 TUNA - GitHub Raw 镜像帮助
- Python / uv / pip 镜像：清华 TUNA - PyPI 镜像帮助
- Node.js 下载镜像：清华 TUNA - NodeJS Release 镜像帮助
- npm / pnpm registry：npm config 文档 / npmmirror
方案一：WSL2（推荐）
第一步：在管理员 PowerShell 中安装 WSL2
如果你还没装过 WSL，建议先看这篇中文帖子：
然后再执行：
wsl --install -d Ubuntu
执行后按提示重启电脑。重启完成后，打开 Ubuntu，设置 Linux 用户名和密码。
第二步：在 WSL2 终端里运行 Linux 安装命令
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
安装完成后，重新加载 shell：
source ~/.bashrc # 或：source ~/.zshrc
hermes
第三步：继续配置模型
hermes model
hermes setup
如果你只是需要一个最稳的 Windows 版本 Hermes，做到这里就够了。后续文档默认也更偏向这条路径。
例如 Ollama、LM Studio 跑在 Windows 本机，而 Hermes 跑在 WSL2 中，这时 localhost 不一定直接可用。请继续看 提供商文档里的 WSL2 网络配置。
方案二：原生 PowerShell（可用，但更容易踩坑）
一键安装
在 PowerShell 中运行：
irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
这个安装器会自动尝试处理：
- uv
- Python 3.11
- Node.js
- Git
- ripgrep / ffmpeg
- Hermes 本体与虚拟环境
安装完成后，关闭并重新打开 PowerShell，再运行：
hermes
hermes model
原生 Windows 安装后文件大致在哪里
默认安装目录通常在：
%LOCALAPPDATA%\hermes
例如：
- Hermes 主目录：
%LOCALAPPDATA%\hermes - 仓库目录：
%LOCALAPPDATA%\hermes\hermes-agent - 虚拟环境：
%LOCALAPPDATA%\hermes\hermes-agent\venv
如果 hermes 命令暂时不可用，最常见的解决方法就是：关掉当前 PowerShell 窗口，再开一个新的。
飞书接入：Windows 用户最容易踩的坑
这一节参考并改写自阿里云文章《Windows 也能跑 Hermes Agent！完整安装教程 + 飞书接入，全程避坑》。为了避免直接照抄，这里只保留最关键的结论和更稳的写法。
1. 先完成 Hermes 本体安装，再单独配置网关
hermes gateway setup
在渠道列表中选择 飞书，填入：
- App ID
- App Secret
- 国内版填
feishu，海外版填lark - 连接方式一般先用默认的
websocket
然后再启动网关：
hermes gateway run -vv
2. 如果报 lark-oapi 未安装
原生 Windows 下，飞书 SDK 有时没有被装进 Hermes 自己的虚拟环境。可以这样补装：
$hermesExe = (Get-Command hermes).Source
$venvPython = Join-Path (Split-Path $hermesExe -Parent) 'python.exe'
uv pip install lark-oapi --python $venvPython
如果你还缺 websockets 或 aiohttp，也可以用同样方式补进去：
uv pip install websockets aiohttp --python $venvPython
3. 如果网关一启动就退出，或看到 WinError 11
阿里云文章里提到，某些 Windows 环境下，gateway/status.py 里的 os.kill(pid, 0) 检查会触发 WinError 11，导致网关异常退出。这是原生 Windows 路径的兼容性问题，不是 WSL2 的常见问题。
如果你正好遇到这个问题，有两种选择：
- 最省心的办法：改走 WSL2。
- 继续坚持原生 PowerShell： 按阿里云文章中的思路，对
gateway/status.py做临时补丁，把OSError也纳入异常捕获。
下面这段 PowerShell 会自动定位文件并打补丁：
$hermesExe = (Get-Command hermes).Source
$installRoot = Split-Path (Split-Path $hermesExe -Parent) -Parent
$statusPy = Join-Path $installRoot 'gateway\status.py'
$content = Get-Content $statusPy -Raw -Encoding UTF8
$content = $content.Replace(
'except (ProcessLookupError, PermissionError):',
'except (ProcessLookupError, PermissionError, OSError):'
)
Set-Content $statusPy $content -Encoding UTF8 -NoNewline
然后重新启动：
$env:PYTHONUTF8 = '1'
hermes gateway run -vv
这是 原生 Windows 专用的临时规避方案。如果你希望少踩坑，仍然建议优先回到 WSL2。
4. 飞书群里 @ 机器人没反应
先确认两件事：
- 飞书开放平台里的机器人权限和事件订阅已经配好。
- 你已经启动了网关，并用
hermes gateway run -vv看到了正常日志。
如果日志没报错，但群里依然不响应，可以先把群策略放宽为 open 进行排查：
Add-Content "$env:LOCALAPPDATA\hermes\.env" "`nFEISHU_GROUP_POLICY=open" -Encoding UTF8
然后重新运行：
$env:PYTHONUTF8 = '1'
hermes gateway run -vv
如果这样能恢复，再回头逐步收紧白名单配置。
Windows 用户的推荐上手顺序
- 先决定用 WSL2 还是 原生 PowerShell。
- 安装完成后，先用
hermes和hermes model验证 CLI 与模型配置。 - 再去接飞书、微信、Telegram 等消息网关。
- 如果你要连接本地模型、Docker、浏览器自动化或各种 shell 工具，优先回到 WSL2 路径。