一、一键安装
打开 PowerShell（建议以管理员身份运行），执行以下命令：
irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
脚本会自动检测并安装 Python、Node.js、Git、ripgrep 等所有依赖，耐心等待即可。
二、初始配置
安装完成后会自动进入配置向导，直接选第一项 Quick setup（推荐新手使用）。
2.1 配置模型供应商
根据自己的情况选择模型供应商，本文以 Kimi 为例。
2.2 跳过消息平台配置
向导中的消息平台列表暂时没有飞书选项，直接跳过，后续通过 Gateway 单独配置。
接下来的自动化配置步骤，输入 Y 确认即可。
看到欢迎界面，说明安装成功。
2.3 ⚠️ 坑一：模型未被识别
安装完成后可能会发现模型没有被正确识别，如下图所示：
这个问题不确定是否与 Windows 环境有关，解决方式很简单——使用内置命令 /model 手动指定模型，看到模型名称正确显示即代表设置成功。
三、接入飞书
3.1 创建飞书机器人应用
前往飞书开放平台新建一个机器人应用，配置流程和我写的那篇小龙虾的安装教程完全一致，不熟悉的同学可以先去参考那篇，这里不再重复。
3.2 配置 Gateway
新开一个 PowerShell 终端，执行以下命令进入 Gateway 配置流程：
hermes gateway setup
在渠道列表中选择 飞书。
依次填入飞书应用的 App ID 和 App Secret。
其余选项说明如下：
- 来源：国内版填
feishu，海外版填lark - 连接方式：默认
websocket，直接回车即可 - 允许的 User ID：留空；在下一步鉴权中输入
1（不限制对话人），这样群里所有人都可以与机器人交互。如果有更严格的权限需求，可以按需填写。
配置完成后确认界面内容，选择 Done 保存。
3.3 ⚠️ 坑二：缺少 lark-oapi 依赖
运行 hermes gateway 启动网关时，Windows 下大概率会报错，原因是 Hermes 的 venv 里缺少飞书 SDK lark-oapi。
由于 hermes gateway 使用的是其内置 venv 中的 Python，需要将依赖装进对应的 venv，而不是系统环境：
# 第一步：找到 Hermes 可执行文件的位置，从而定位 venv 路径
Get-Command hermes | Select-Object -ExpandProperty Source
# 第二步：确认 venv 的 Scripts 目录结构
ls "C:\Users\10371\AppData\Local\hermes\hermes-agent\venv\Scripts"
# 第三步：用 uv 将 lark-oapi 安装进 venv
uv pip install lark-oapi --python "C:\Users\10371\AppData\Local\hermes\hermes-agent\venv\Scripts\python.exe"
⚠️ 注意：请将上方路径中的
<用户名>替换为你自己的 Windows 用户名，下文同理。
四、消息不响应？逐步排查与修复
重新运行 hermes gateway 后，如果去群里 @ 机器人却没有任何响应，请按以下顺序排查。
第一步：先检查飞书机器人的权限配置是否完整，参考「小龙虾」那篇教程中的权限清单逐一核对。
第二步：如果权限没问题，则很可能是以下两个 Windows 兼容性问题，按顺序修复即可。
4.1 ⚠️ 坑三：status.py 的 Windows 兼容性 Bug
问题根源： status.py 中使用 os.kill(pid, 0) 检查进程是否存活，但在 Windows 上这个调用会抛出 WinError 11，而原始代码没有捕获这个异常，导致整个 Gateway 进程异常退出。
修复方案： 将 OSError 加入异常捕获范围，使 WinError 11 被视为"进程不存在"（即锁已过期）来处理。
在 PowerShell 中运行以下 patch 命令：
python -c "
path = r'C:\Users\10371\AppData\Local\hermes\hermes-agent\gateway\status.py'
with open(path, 'r', encoding='utf-8') as f:
content = f.read()
content = content.replace(
'except (ProcessLookupError, PermissionError):',
'except (ProcessLookupError, PermissionError, OSError):'
)
with open(path, 'w', encoding='utf-8') as f:
f.write(content)
print('Done')
"
验证 patch 是否生效：
python -c "
path = r'C:\Users\10371\AppData\Local\hermes\hermes-agent\gateway\status.py'
with open(path, encoding='utf-8') as f:
for i, line in enumerate(f, 1):
if 'OSError' in line:
print(f'Line {i}: {line.rstrip()}')
"
输出中出现 OSError 即说明 patch 已生效。
顺手修复日志编码问题（可选）： Gateway 日志中的 Unicode 符号在 Windows 下可能显示乱码，启动时加上以下环境变量即可解决：
$env:PYTHONUTF8 = "1"
hermes gateway
4.2 ⚠️ 坑四：config.yaml 缺少飞书配置段
如果 patch 后机器人依然没有响应，检查 config.yaml 会发现里面根本没有 feishu 配置段。
问题出在消息拦截的两道关卡上：
第一道（Policy Gate）： FEISHU_GROUP_POLICY 默认值为 allowlist，但 FEISHU_ALLOWED_USERS 为空，导致所有消息在这一关就被丢弃，甚至不会走到 @ 检测逻辑。
第二道（Mention Gate）： 即使通过了 Policy Gate，还需要验证 @ 的对象是否为当前 Bot，这依赖 Bot 的 open_id / user_id / name 已正确加载。
修复步骤：
首先，将 Policy 改为 open（允许所有人）：
Add-Content "$env:LOCALAPPDATA\hermes\.env" "`nFEISHU_GROUP_POLICY=open" -Encoding UTF8
同时修正 config.yaml 中错误的配置键：
(Get-Content "$env:LOCALAPPDATA\hermes\config.yaml" -Raw -Encoding UTF8) `
-replace "feishu:\r?\n require_mention: false", "feishu:`n default_group_policy: open" |
Set-Content "$env:LOCALAPPDATA\hermes\config.yaml" -Encoding UTF8 -NoNewline
然后以详细日志模式重启 Gateway：
$env:PYTHONUTF8 = "1"
hermes gateway run -vv
日志无报错即代表配置生效。
五、配置飞书事件订阅
最后一步：前往飞书开放平台，在应用的事件订阅页面开启长连接模式。
完成后在飞书群里 @ 机器人，即可正常对话。
总结
至此，我们成功在 Windows 上完成了 Hermes Agent 的安装，并接入了飞书。整个过程踩了不少 Windows 兼容性的坑。如果大家有遇到其他问题，也欢迎在评论区留言交流！
