Windows上运行Hermes Agent完整安装教程及飞书接入避坑指南

一、一键安装

直接上 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 兼容性这块儿，但总算一路把它们都搞定了。有其他问题的同学可以留言分享。