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

Hermes Agent 这东西，Linux/Mac 上跑得很丝滑，但换到 Windows 上就各种水土不服。我花了一整天把坑踩完，这里把完整流程和四个典型兼容性问题一次性说清楚，照着走就行。

一、一键安装

打开 PowerShell，建议用管理员权限跑，省得后面权限问题纠缠不清：

1

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

脚本会自动检测 Python、Node.js、Git、ripgrep 这些依赖并装好。网速正常的话，几分钟搞定。

二、初始配置

装完自动进配置向导，选第一项 Quick setup 就行，别折腾手动配置。

2.1 配置模型供应商

按自己情况选。本文以 Kimi 为例，选完填 API Key 即可。

2.2 跳过消息平台配置

向导里的消息平台列表暂时没有飞书选项，直接跳过。飞书后面通过 Gateway 单独接，比向导里配更可控。

接下来的自动化步骤输入 Y 确认。看到欢迎界面，安装就算完成了。

2.3 ⚠️ 坑一：模型未被识别

装完发现模型没正确识别？别慌。这个问题不确定是不是 Windows 特有，但解决方式很简单，用内置命令 /model 手动指定一下，模型名正确显示就行了。

三、接入飞书

3.1 创建飞书机器人应用

去飞书开放平台新建一个机器人应用。配置流程跟小龙虾那篇教程一样，不重复了。没看过的先去补课。

3.2 配置 Gateway

新开一个 PowerShell 终端，跑：

1

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：

1
2
3
4
5
6
7
8

# 第一步：定位 Hermes 可执行文件，找 venv 路径
Get-Command hermes | Select-Object -ExpandProperty Source

# 第二步：确认 venv 的 Scripts 目录
ls "C:\Users\<用户名>\AppData\Local\hermes\hermes-agent\venv\Scripts"

# 第三步：用 uv 装进 venv
uv pip install lark-oapi --python "C:\Users\<用户名>\AppData\Local\hermes\hermes-agent\venv\Scripts\python.exe"

把 <用户名> 换成你自己的 Windows 用户名，下文同理。

四、消息不响应？逐步排查

重新跑 hermes gateway 后去群里 @ 机器人，如果没反应，按这个顺序查：

第一步：检查飞书机器人权限配置是否完整，对照小龙虾那篇教程的权限清单逐一核对。

第二步：权限没问题的话，大概率是下面两个 Windows 兼容性 bug，按顺序修。

4.1 ⚠️ 坑三：status.py 的 Windows 兼容性 Bug

问题根源：status.py 用 os.kill(pid, 0) 检查进程存活状态，但 Windows 上这调用会抛 WinError 11。原始代码没捕获这个异常，Gateway 进程直接挂了。

修复方案：把 OSError 加进异常捕获，让 WinError 11 被当成"进程不存在"处理：

1
2
3
4
5
6
7
8
9
10
11
12

python -c "
path = r'C:\Users\<用户名>\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')
"

验证一下：

1
2
3
4
5
6
7

python -c "
path = r'C:\Users\<用户名>\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 生效了。

顺手修个日志编码问题（可选）：Windows 下 Gateway 日志的 Unicode 符号可能乱码，启动时加环境变量就行：

1
2

$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：

1

Add-Content "$env:LOCALAPPDATA\hermes\.env" "`nFEISHU_GROUP_POLICY=open" -Encoding UTF8

再修正 config.yaml 里错误的配置键：

1
2
3

(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：

1
2

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

日志无报错，配置就生效了。

五、配置飞书事件订阅

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

完成后在飞书群里 @ 机器人，应该就能正常对话了。

总结

Windows 上跑 Hermes Agent 确实比 Linux 多踩不少坑：模型识别、lark-oapi 缺失、status.py 的 WinError 11、config.yaml 配置段缺失。但只要按顺序一个个修，最终跑起来还是稳的。有问题评论区见。

本文由 BOSH 的博客助手 HerMes 整理 🦔

原文链接：https://developer.aliyun.com/article/1725007