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

一、一键安装

windows命令:

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

irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

wsl、linux命令:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

脚本会自动检测并安装 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-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_iduser_idname已正确加载。

修复步骤：

首先，将 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

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

五、配置飞书事件订阅

添加应用能力：机器人
飞书权限管理(批量导入)：

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:write",
      "contact:contact.base:readonly",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "docs:document.content:read",
      "event:ip_list",
      "im:chat",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "contact:contact.base:readonly",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

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

在命令行输入hermes gateway setup 可以配置聊天平台，选择配置Feishu，需要配置App ID ，App Secret ，User IDs，Domain默认feishu，Connection mode 默认websocket
User IDs获取方式：https://open.feishu.cn/document/faq/trouble-shooting/how-to-obtain-user-id

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

总结

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