一、一键部署
启动 powershell（推荐以管理员权限运行），粘贴并执行如下命令：
irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
该脚本将自动识别系统环境，并安装 Python、Node.js、Git、ripgrep 等全部必需依赖，静候完成即可。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
二、首次配置
安装完毕后，程序将自动启动交互式配置向导。新手建议直接选择首项 Quick setup。
2.1 选择模型服务商
根据实际使用需求选定模型接入渠道，本文以 Kimi 为例进行演示。
2.2 跳过即时通讯平台设置
当前向导中暂未提供飞书选项，此处请 直接跳过；后续将通过 Gateway 模块单独完成飞书集成。
其余自动化配置步骤，键入 Y 并回车确认即可。
出现欢迎界面，即表示基础安装与初始化已成功完成。
2.3 ⚠️ 注意事项一：模型未被识别
安装后可能出现模型未正确加载的情况，界面显示异常（如图）：
该问题成因尚不明确，可能与 Windows 系统环境相关。解决方法极为简单——在聊天窗口中输入内置指令 /model 手动指定模型，待模型名称正常显示即说明配置生效。
三、对接飞书平台
3.1 创建飞书机器人应用
登录［飞书开放平台］(https://www.php.cn/link/d23a1bf07cdba281bc02aff051a91e78。
3.2 配置 Gateway 模块
另启一个 PowerShell 窗口，执行以下命令进入网关配置流程：
hermes gateway setup
在可用渠道列表中选择 飞书。
依次填入飞书应用的 App ID 和 App Secret。
其余参数说明如下：
-
来源类型：国内用户填写
feishu，国际用户填写lark -
连接协议：默认为
websocket，直接按回车采用默认值 -
允许访问的用户 ID 列表：留空；下一步鉴权环节输入
1（代表不限制对话对象），使群内所有成员均可与机器人交互。如需精细化权限控制，可按需填写具体 ID。
核对最终配置内容无误后，选择 Done 完成保存。
3.3 ⚠️ 注意事项二：缺失 lark-oapi 依赖包
在 Windows 下执行 hermes gateway 启动服务时，极有可能报错，根本原因在于 Hermes 内置虚拟环境中缺少飞书官方 SDK lark-oapi。
由于 hermes gateway 默认调用其专属 venv 中的 Python 解释器，因此必须将依赖安装至该虚拟环境，而非全局 Python 环境：
# 第一步：定位 hermes 可执行文件路径，从而获取 venv 实际位置 Get-Command hermes | Select-Object -ExpandProperty Source <h1>第二步：验证 venv 下 Scripts 目录结构是否完整</h1><p>ls "C:\Users\10371\AppData\Local\hermes\hermes-agent\venv\Scripts\"</p><h1>第三步：使用 uv 工具将 lark-oapi 安装进目标 venv</h1><p>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 兼容缺陷
问题根源：status.py 文件中使用 os.kill(pid, 0) 检测进程状态，但在 Windows 上该调用会触发 WinError 11 异常，而原始代码未对此类错误做捕获，导致 Gateway 进程意外崩溃。
修复方式：扩展异常捕获范围，将 OSError 加入 except 子句，使 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')"验证补丁是否成功写入：
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）：即便通过策略门控，还需进一步比对 @ 对象是否为当前 Bot，而这依赖 Bot 的 open_id / user_id / name 是否已正确载入。
修复步骤如下：
首先，将策略模式切换为 open（开放给所有人）：
Add-Content "$env:LOCALAPPDATA\hermes.env" "<pre class="brush:php;toolbar:false;">nFEISHU_GROUP_POLICY=open" -Encoding UTF8</code></pre><p>其次，修正 <code>config.yaml</code> 中格式错误的配置项：</p><pre><code class="powershell">(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
日志中不再出现异常报错，即代表配置已正确加载并生效。
五、启用飞书事件订阅
最终操作：返回飞书开放平台，在所建应用的 事件订阅 页面中，开启 长连接（WebSocket） 模式。
完成后，在飞书群内 @ 机器人，即可实现无障碍对话交互。
总结
至此，Hermes Agent 已在 Windows 系统上顺利完成部署，并成功接入飞书平台。整个过程涉及多个 Windows 特定兼容性问题，均已提供针对性解决方案。如你在实践过程中遇到其他异常情况，欢迎在评论区留言交流！
