Windows 也能跑 Hermes Agent！完整安装教程 + 飞书接入，全程避坑

一、一键安装打开 PowerShell建议以管理员身份运行执行以下命令irmhttps://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 里缺少飞书 SDKlark-oapi。由于hermes gateway使用的是其内置 venv 中的 Python需要将依赖装进对应的 venv而不是系统环境# 第一步找到 Hermes 可执行文件的位置从而定位 venv 路径Get-Commandhermes|Select-Object-ExpandProperty Source# 第二步确认 venv 的 Scripts 目录结构lsC:\Users\10371\AppData\Local\hermes\hermes-agent\venv\Scripts# 第三步用 uv 将 lark-oapi 安装进 venvuv pip install lark-oapi--pythonC:\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 rC:\Users\10371\AppData\Local\hermes\hermes-agent\gateway\status.py with open(path, r, encodingutf-8) as f: content f.read() content content.replace( except (ProcessLookupError, PermissionError):, except (ProcessLookupError, PermissionError, OSError): ) with open(path, w, encodingutf-8) as f: f.write(content) print(Done) 验证 patch 是否生效python-c path rC:\Users\10371\AppData\Local\hermes\hermes-agent\gateway\status.py with open(path, encodingutf-8) as f: for i, line in enumerate(f, 1): if OSError in line: print(fLine {i}: {line.rstrip()}) 输出中出现OSError即说明 patch 已生效。顺手修复日志编码问题可选Gateway 日志中的 Unicode 符号在 Windows 下可能显示乱码启动时加上以下环境变量即可解决$env:PYTHONUTF8 1 hermes gateway4.2 ⚠️ 坑四config.yaml缺少飞书配置段如果 patch 后机器人依然没有响应检查config.yaml会发现里面根本没有feishu配置段。问题出在消息拦截的两道关卡上第一道Policy GateFEISHU_GROUP_POLICY默认值为allowlist但FEISHU_ALLOWED_USERS为空导致所有消息在这一关就被丢弃甚至不会走到 检测逻辑。第二道Mention Gate即使通过了 Policy Gate还需要验证 的对象是否为当前 Bot这依赖 Bot 的open_id/user_id/name已正确加载。修复步骤首先将 Policy 改为open允许所有人Add-Content$env:LOCALAPPDATA\hermes\.envnFEISHU_GROUP_POLICYopen-Encoding UTF8同时修正config.yaml中错误的配置键(Get-Content$env:LOCALAPPDATA\hermes\config.yaml-Raw-Encoding UTF8)-replacefeishu:\r?\n require_mention: false,feishu:n default_group_policy: open|Set-Content$env:LOCALAPPDATA\hermes\config.yaml-Encoding UTF8-NoNewline然后以详细日志模式重启 Gateway$env:PYTHONUTF8 1hermes gateway run-vv日志无报错即代表配置生效。五、配置飞书事件订阅最后一步前往飞书开放平台在应用的事件订阅页面开启长连接模式。完成后在飞书群里 机器人即可正常对话。总结至此我们成功在 Windows 上完成了 Hermes Agent 的安装并接入了飞书。整个过程踩了不少 Windows 兼容性的坑。如果大家有遇到其他问题也欢迎在评论区留言交流