一、一键安装
直接上 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:Users10371AppDataLocalhermeshermes-agentvenvScripts"# 第三步：用 uv 把 lark-oapi 装进 venvuv pip install lark-oapi --python "C:Users10371AppDataLocalhermeshermes-agentvenvScriptspython.exe"
四、消息不响应？逐步排查与修复
重新跑 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:Users10371AppDataLocalhermeshermes-agentgatewaystatus.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:Users10371AppDataLocalhermeshermes-agentgatewaystatus.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:LOCALAPPDATAhermes.env" "`nFEISHU_GROUP_POLICY=open" -Encoding UTF8
同时把 config.yaml 里配错的键修好：
(Get-Content "$env:LOCALAPPDATAhermesconfig.yaml" -Raw -Encoding UTF8) `-replace "feishu:r?nrequire_mention: false", "feishu:`ndefault_group_policy: open" |Set-Content "$env:LOCALAPPDATAhermesconfig.yaml" -Encoding UTF8 -NoNewline
然后用详细日志模式重启 Gateway：
$env:PYTHONUTF8 = "1"hermes gateway run -vv
日志里没报错就是配置生效了。
五、配置飞书事件订阅
最后一步：去飞书开放平台，在应用的事件订阅页面开启长连接模式。
搞定后去飞书群里 @ 机器人，就能正常聊天了。
总结
到这里，我们在 Windows 上成功装好了 Hermes Agent，并且接上了飞书。整个过程虽然踩了不少坑，尤其是 Windows 兼容性这块儿，但总算一路把它们都搞定了。有其他问题的同学可以留言分享。
