# 一、一键安装

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

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

脚本会自动检测并安装 Python、Node.js、Git、ripgrep 等所有依赖，耐心等待即可。

![1.png](https://developer.qcloudimg.com/http-save/yehe-9985785/15312ce40b3bac4d30e742c9fbf413c2.png)


# 二、初始配置

安装完成后会自动进入配置向导，直接选第一项 **Quick setup**（推荐新手使用）。

![2.png](https://developer.qcloudimg.com/http-save/yehe-9985785/7329ef7a712a24d079f0dd09f51e7d0b.png)

## 2.1 配置模型供应商

根据自己的情况选择模型供应商，本文以 **Kimi** 为例。

![3.png](https://developer.qcloudimg.com/http-save/yehe-9985785/cc06124b43d47f2cbb6f7d68c722ae99.png)

![5.png](https://developer.qcloudimg.com/http-save/yehe-9985785/dfaa75e0ed571bd118fbef9251db4d7b.png)

## 2.2 跳过消息平台配置

向导中的消息平台列表暂时没有飞书选项，**直接跳过**，后续通过 Gateway 单独配置。

![6.png](https://developer.qcloudimg.com/http-save/yehe-9985785/d8e0feff9cfced4a938e4dba7fbe3bca.png)

接下来的自动化配置步骤，输入 `Y` 确认即可。

![7.png](https://developer.qcloudimg.com/http-save/yehe-9985785/6f83ef1e917c26c446ace0446cd4caa0.png)

看到欢迎界面，说明安装成功。

![8.png](https://developer.qcloudimg.com/http-save/yehe-9985785/cd78012bab148b31e69646825a354689.png)

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

安装完成后可能会发现模型没有被正确识别，如下图所示：

![9.png](https://developer.qcloudimg.com/http-save/yehe-9985785/ae9b95cd382e37d116b188ebec107b47.png)

这个问题不确定是否与 Windows 环境有关，解决方式很简单——使用内置命令 `/model` 手动指定模型，看到模型名称正确显示即代表设置成功。

![10.png](https://developer.qcloudimg.com/http-save/yehe-9985785/0810e1761d9870fa49e0371555ca02c5.png)



# 三、接入飞书

## 3.1 创建飞书机器人应用

前往[飞书开放平台](https://open.feishu.cn/)新建一个机器人应用，配置流程和我写的那篇小龙虾的安装教程完全一致，不熟悉的同学可以先去参考那篇，这里不再重复。

## 3.2 配置 Gateway

新开一个 PowerShell 终端，执行以下命令进入 Gateway 配置流程：

```powershell
hermes gateway setup
```

在渠道列表中选择 **飞书**。

![11.png](https://developer.qcloudimg.com/http-save/yehe-9985785/62ec10c2e5025064065d4fa65e3c83c3.png)

依次填入飞书应用的 **App ID** 和 **App Secret**。

![12.png](https://developer.qcloudimg.com/http-save/yehe-9985785/2f38029ba2619e74ce83f5077b941f53.png)

其余选项说明如下：

- **来源**：国内版填 `feishu`，海外版填 `lark`
- **连接方式**：默认 `websocket`，直接回车即可
- **允许的 User ID**：留空；在下一步鉴权中输入 `1`（不限制对话人），这样群里所有人都可以与机器人交互。如果有更严格的权限需求，可以按需填写。

![13.png](https://developer.qcloudimg.com/http-save/yehe-9985785/41db6eed532b198383fb2ca8d238beda.png)

配置完成后确认界面内容，选择 **Done** 保存。

![14.png](https://developer.qcloudimg.com/http-save/yehe-9985785/06ec96759dbd6c41eab1da3443eee005.png)

## 3.3 ⚠️ 坑二：缺少 `lark-oapi` 依赖

运行 `hermes gateway` 启动网关时，Windows 下大概率会报错，原因是 Hermes 的 venv 里缺少飞书 SDK `lark-oapi`。

由于 `hermes gateway` 使用的是其内置 venv 中的 Python，需要将依赖装进对应的 venv，而不是系统环境：

```powershell
# 第一步：找到 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"
```

![16.png](https://developer.qcloudimg.com/http-save/yehe-9985785/b76d31d8e14e1abca46e9dfefe779325.png)

> ⚠️ 注意：请将上方路径中的 `<用户名>` 替换为你自己的 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 命令：

```powershell
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 是否生效：

```powershell
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_id` / `user_id` / `name` 已正确加载。

**修复步骤：**

首先，将 Policy 改为 `open`（允许所有人）：

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

同时修正 `config.yaml` 中错误的配置键：

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

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

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

![18.png](https://developer.qcloudimg.com/http-save/yehe-9985785/012ddd01c961bb86329cc04faad9068f.png)



# 五、配置飞书事件订阅

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

![19.png](https://developer.qcloudimg.com/http-save/yehe-9985785/81f61374888ee3d0e83e23b4724799e9.png)

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

![20.png](https://developer.qcloudimg.com/http-save/yehe-9985785/2d7d656986915b48252ced7d6fecfc82.png)



# 总结

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


脚本会自动检测并安装 Python、Node.js、Git、ripgrep 等所有依赖，耐心等待即可。

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

先锋会员

开发工具

操作系统

客户端

Windows系统安装Hermes Agent教程，详细讲解一键安装脚本、飞书机器人配置及常见问题解决方案。包含Python依赖安装、飞书SDK修复、Windows兼容性补丁等关键步骤，帮助用户快速完成AI助手部署并接入飞书群聊。

Windows

Python

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Windows 也能跑 Hermes Agent！完整安装教程 + 飞书接入，全程避坑-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐