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

一、一键安装

打开 PowerShell（建议以管理员身份运行），执行以下命令：

irm  | 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 安装进 venv
uv 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?n  require_mention: false", "feishu:`n  default_group_policy: open" |
  Set-Content "$env:LOCALAPPDATAhermesconfig.yaml" -Encoding UTF8 -NoNewline

然后以详细日志模式重启 Gateway：

$env:PYTHONUTF8 = "1"
hermes gateway run -vv

日志无报错即代表配置生效。

五、配置飞书事件订阅

最后一步：前往飞书开放平台，在应用的事件订阅页面开启长连接模式。

完成后在飞书群里 @ 机器人，即可正常对话。

总结

至此，我们成功在 Windows 上完成了 Hermes Agent 的安装，并接入了飞书。整个过程踩了不少 Windows 兼容性的坑。如果大家有遇到其他问题，也欢迎在评论区留言交流！