Windows 安装

安装遇到困难？

点击加入中文社区微信群，提问并获取群内专家帮助。

完全没有经验？ 强烈建议先下载 WorkBuddy（微信扫码即用，无需任何配置），然后让它安装中文社区文档 MCP 来协助你安装 Hermes Agent。如果后续 Hermes 出现问题，也可以让 WorkBuddy 对其进行修复，反之亦然——两个 Agent 互为主备，这是社区推荐的最佳方案。

电脑上已经有 Agent？ 如果你已经在用龙虾 OpenClaw 或国内版本（QClaw、AutoClaw），或者 Trae、Claude Code、Codex、Cursor、Qoder 等 Coding Agent，都可以让它读文档来协助你完成安装，你可以不用关心任何技术细节。

如何让你的 Agent 接入中文社区文档？

方式一（最简单）：把中文社区网址 https://hermesagent.org.cn 发给它，让它自己访问并阅读文档。

方式二（更精准，推荐）：直接把下面这段话复制发给你的 Agent，它会自己完成配置：

请把这个 Hermes 中文文档 MCP server 加到你的配置里：
https://mcp.hermesagent.org.cn/v1
（Streamable HTTP，无需 API Key、无需登录）
加完后用它帮我查 Hermes Agent 中文文档来指导我完成安装。

方式二配好后，Agent 就能按关键词直接检索并读取中文社区全部文档的全文。

其他求助途径：也可以先询问豆包、DeepSeek 等 AI 助手。

如果你主要在 Windows 上使用 Hermes Agent，这一页就是给你的。重点只有一句话：Windows 和类 Linux / macOS 的安装命令不一样。

先回答三个问题

1. 什么是 PowerShell？

PowerShell 是 Windows 自带的命令行程序。你可以把它理解成：

Windows 里的终端
一个可以输入命令、安装软件、运行脚本的窗口

如果你以前听过这些词，它们大致是一个意思：

命令行
终端
Shell
PowerShell

对 Windows 用户来说，你不需要先理解所有概念。你只需要知道：

后面文档里写的 PowerShell 命令，就是要粘贴到 PowerShell 窗口里执行。

2. 怎么打开 PowerShell？

最简单的方法：

按一下键盘左下角 Windows 键
输入 PowerShell
点击 Windows PowerShell 或 PowerShell

你也可能会看到：

Windows Terminal

这也可以用，但请确认打开后当前标签页是 PowerShell。

你应该把命令粘贴到哪里？

请把命令粘贴到 PowerShell 窗口本身，不要粘贴到：

浏览器地址栏
文件资源管理器地址栏
“运行”对话框
Word / 记事本 / 聊天框

如果你不知道怎么粘贴，可以用下面任意一种方法：

最常用：按键盘 Ctrl + V
如果 Ctrl + V 没反应：在 PowerShell 窗口里点一下鼠标右键，很多电脑会直接粘贴
Windows Terminal 里通常也支持 Ctrl + Shift + V，但大多数情况下先试 Ctrl + V 就够了

粘贴成功后，你会看到那一整行命令出现在 PowerShell 窗口里；这时再按一下 Enter（回车键） 才会真正开始执行。

3. 什么时候需要管理员 PowerShell？

安装 WSL2：通常需要 管理员 PowerShell
直接安装 Hermes：通常普通 PowerShell 就够了

也就是说：

想装 WSL2 → 可以右键 PowerShell，选择“以管理员身份运行”
想直接跑 install.ps1 → 一般直接打开普通 PowerShell 即可

WSL2 到底是什么？

WSL2 的全名是 Windows Subsystem for Linux 2。
你可以把它简单理解成：

在 Windows 电脑里放了一个 Linux 终端环境
你不用单独装双系统，也不用自己手搓虚拟机
安装完成后，开始菜单里通常会多一个 Ubuntu
打开 Ubuntu 后，你看到的是 Linux 命令行

对新手来说，最重要的不是记住全名，而是记住下面这句话：

WSL2 = 让你在 Windows 电脑上，按 Linux 的方式装和用 Hermes。

因为 Hermes Agent 的很多能力，本来就更贴近类 Unix 环境，例如：

shell / 终端工具链
Python / Node.js 依赖安装
浏览器自动化
Docker / SSH / MCP / 网关等扩展能力

这些在 WSL2 里通常会比原生 PowerShell：

更稳定
更接近官方文档
少一些 Windows 特有兼容性问题

安装了 WSL2 之后，你实际会怎么用？

你平时还是正常用 Windows。
只有在安装和运行 Hermes 的时候，你改为：

打开 Ubuntu
在 Ubuntu 终端里粘贴 Linux 安装命令
后续也主要在 Ubuntu 终端里运行 hermes

也就是说：

Windows 继续是你的桌面系统
Ubuntu（WSL2）只是 Hermes 的运行终端

如果你看到文档里写：

curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

那么这条命令就应该：

在 macOS 终端
或 Linux 终端
或 Windows 里的 Ubuntu（WSL2）终端

里执行，不要粘贴到原生 PowerShell。

先决定走哪条路径

路径	适合谁	推荐程度	你要运行的命令
WSL2 + Ubuntu	想要最稳的日常使用体验，希望尽量贴近官方文档、终端工具和自动化工作流	强烈推荐	在 WSL2 里运行 `install.sh`
原生 PowerShell	想先在 Windows 本机快速跑起来，不想先配置 WSL2	可用，但更容易遇到兼容性问题	在 PowerShell 里运行 `install.ps1`

推荐结论

长期使用 / 工具链完整 / 网关与自动化更省心：优先选 WSL2。
只是想先在 Windows 本机跑通 CLI：可以直接用 PowerShell。

中国大陆网络环境提示

当前页给出的安装命令已经由 Hermes Agent 中文社区 接入 国内镜像加速，会优先使用国内可直连的下载链路。

为了提高中国大陆用户的安装体验，镜像版安装器默认精简了部分国人不常用、或体积较大且经常受外网影响的可选功能，例如浏览器自动化、Chromium 下载、WhatsApp 桥接等。建议先完成核心安装，确认 Hermes Agent 可以正常运行；之后可让 Hermes Agent 自身补全这些能力。

如果你还需要处理 WSL 网络、终端代理或镜像源配置，可参考：

WSL 安装（中文）：Windows 10/11 安装 WSL2 指南
WSL 网络 / autoProxy（官方）：Microsoft Learn - Accessing network applications with WSL
Python / pip 镜像说明：清华 TUNA - PyPI 镜像帮助
Node.js / npm 镜像说明：清华 TUNA - NodeJS Release 镜像帮助 / npmmirror

方案一：WSL2（推荐）

第一步：在管理员 PowerShell 中安装 WSL2

如果你还没装过 WSL，建议先看这篇中文帖子：

Windows 10/11 安装 WSL2 指南（知乎）

然后再执行：

wsl --install -d Ubuntu

执行后按提示重启电脑。重启完成后，打开 Ubuntu，设置 Linux 用户名和密码。

第二步：在 WSL2 终端里运行 Linux 安装命令

curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

安装完成后，重新加载 shell：

source ~/.bashrc   # 或：source ~/.zshrc
hermes

第三步：继续配置模型

hermes model
hermes setup

如果你只是需要一个最稳的 Windows 版本 Hermes，做到这里就够了。后续文档默认也更偏向这条路径。

如果你的模型跑在 Windows 主机上

例如 Ollama、LM Studio 跑在 Windows 本机，而 Hermes 跑在 WSL2 中，这时 localhost 不一定直接可用。请继续看提供商文档里的 WSL2 网络配置。

方案二：原生 PowerShell（可用，但更容易踩坑）

一键安装

如果你想直接在 Windows 本机安装，请按下面步骤来：

按 Windows 键
输入 PowerShell
点击 Windows PowerShell 或 PowerShell
把下面这行命令完整复制进去
在 PowerShell 窗口里粘贴并按回车

你要执行的命令是：

irm https://res1.hermesagent.org.cn/install.ps1 | iex

粘贴小提示

现在多数 Windows 终端都支持 Ctrl+V
如果不行，也可以直接在窗口里 右键粘贴

这个安装器会自动尝试处理：

uv
Python 3.11
Node.js
Git
ripgrep / ffmpeg
Hermes 本体与虚拟环境

安装完成后，关闭并重新打开 PowerShell，再运行：

hermes
hermes model

如果你重新打开 PowerShell 后输入 hermes 能正常启动，就说明直装已经成功了。

原生 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 路径。

补充阅读

安装总览
快速入门
飞书接入文档
提供商配置与 WSL2 网络说明
参考来源：阿里云文章《Windows 也能跑 Hermes Agent！完整安装教程 + 飞书接入，全程避坑》

先回答三个问题​

1. 什么是 PowerShell？​

2. 怎么打开 PowerShell？​

3. 什么时候需要管理员 PowerShell？​

WSL2 到底是什么？​

为什么我们更推荐 WSL2？​

安装了 WSL2 之后，你实际会怎么用？​

先决定走哪条路径​

方案一：WSL2（推荐）​

第一步：在管理员 PowerShell 中安装 WSL2​

第二步：在 WSL2 终端里运行 Linux 安装命令​

第三步：继续配置模型​

方案二：原生 PowerShell（可用，但更容易踩坑）​

一键安装​

原生 Windows 安装后文件大致在哪里​

飞书接入：Windows 用户最容易踩的坑​

1. 先完成 Hermes 本体安装，再单独配置网关​

2. 如果报 lark-oapi 未安装​

3. 如果网关一启动就退出，或看到 WinError 11​

4. 飞书群里 @ 机器人没反应​

Windows 用户的推荐上手顺序​

补充阅读​