如果你需要在飞书内部署一个能够自动响应消息的机器人，并且希望过程足够轻便、无需复杂的服务器架构，那么 Hermes 是一个值得考虑的工具。结合飞书开放平台，它可以在本地环境（如 WSL）中快速搭建起一个可用的机器人连接，以处理诸如消息提醒、自动问答等场景。
 

不用担心，本文将指导你完成将 Hermes 接入飞书的全过程，涵盖飞书自建应用创建 → 事件与权限配置 → 通过 WSL 部署 Hermes → 机器人联调测试 → 开机自启设置等关键步骤。同时，会附上配置中常见问题的排查要点，帮助你顺利跑通。快点来试试吧！
 

一、准备事项

在开始前，请确保满足以下基础条件：

1. 账号权限：拥有企业飞书的管理员权限（用于在飞书开放平台创建企业自建应用）；
2. 运行环境：Windows 系统并已安装 WSL（Ubuntu） 环境（Hermes 的命令行操作依赖 Linux 环境）；
3. 网络环境：本地网络可正常访问飞书开放平台，无企业防火墙拦截长连接；
4. 工具认知：对飞书应用、机器人、事件回调等概念有基本了解即可（文中会做必要说明）。

二、第一步：在飞书开放平台创建企业自建应用

机器人需要依托一个飞书企业自建应用作为载体，该应用仅在当前企业内部生效。

2.1 创建应用

1. 使用企业飞书管理员账号登录飞书开发者平台：开发者后台 - 飞书开放平台；

1. 在首页选择企业自建应用（自建应用仅供内部使用，这是我们搭建机器人的合适选择）；

1. 点击「创建企业自建应用」，按提示填写基本信息（带*为必填）：
   • 应用名称：自定义，例如「Hermes 机器人」；
   • 应用描述：简要说明用途，如“基于 Hermes 搭建的飞书消息响应机器人”；
   • 应用图标：支持常见图片格式，尺寸建议大于 240*240 px，文件大小 2MB 以内，可后续补充；
2. 填写完成后点击创建，应用即生成，进入应用后台详情页。

2.2 开启机器人能力

新创建的应用默认不具备交互能力，需要手动开启「机器人」：

1. 在应用详情页，找到【添加应用能力】模块；
2. 在能力列表中选中机器人，点击右侧「+添加」完成开通；
3. 其他能力（如网页应用）本次无需开启。

2.3 配置事件与回调（确保机器人能接收消息）

许多配置完成后机器人无响应的问题，都源于事件与回调、权限未正确配置。

2.3.1 选择事件订阅方式

飞书提供两种事件推送模式，对于本地部署场景，推荐使用长连接模式：

1. 在左侧导航栏进入【事件与回调】，切换到「事件配置」标签页；
2. 订阅方式选择：
   • ✅ 使用长连接接收事件（推荐）：无需公网域名、无需配置加密，适合本地开发测试，与 WSL 环境兼容；
   • ❌ 将事件发送至开发者服务器：适用于已部署在公网服务器的应用，本地测试不推荐；
3. 选中「使用长连接接收事件」，点击验证检测连接状态，验证通过后保存。

简单来说，长连接是在本地服务与飞书服务器之间建立一条持续的“专线”，消息可以实时推送。

2.3.2 添加「接收消息」事件

仅开启长连接还不够，需要订阅具体的事件，机器人才能识别消息：

在「已添加事件」区域，点击「添加事件」；

1. 在事件列表中找到 im.message.receive_v1（接收消息v2.0），勾选并添加；
2. 可按需添加其他附属事件，如消息已读、表情回复等，基础聊天机器人可暂不添加；

1. 注意：每添加一个事件，都需要单独开通对应的权限。点击权限名称，在弹窗中确认开通，列表显示「已开通」即为生效。

2.3.3 开通必要的权限

确保机器人正常收发消息，需要开通以下权限（缺一不可）：

权限作用	对应权限标识	使用场景
读取单聊、群组普通消息	im.message.receive_v1	机器人接收用户消息（核心必开）
读取群内@机器人消息	im:message.group_at_msg:readonly	群聊中@机器人触发响应
读取用户私聊消息	im:message.p2p_msg:readonly	一对一私聊交互
机器人主动发送消息	im:message.send_as_bot	机器人自动回复、推送通知

2.4 记录应用凭证

1. 在左侧导航栏进入【凭证与基础信息】；
2. 复制并妥善保存以下两个关键信息（请勿泄露）：
   • App ID：飞书应用的唯一标识；
   • App Secret：应用的密钥，相当于密码；
3. 所有配置完成后，点击页面右上角发布并创建版本，提交配置并等待企业管理员审核（通常很快，要么就去敲管理员的头，当然自己是管理员就免审核了）。

三、第二步：在 WSL 环境中部署 Hermes 网关

完成飞书侧配置后，切换到 WSL（Ubuntu）环境，安装并配置 Hermes 网关，建立与飞书的连接。

3.1 WSL 终端优化（可选）好细节好感动😢！
 

为方便后续操作，可以先优化 WSL 终端的复制粘贴体验：

1. 打开 WSL Ubuntu 终端，右键点击终端边框，选择「属性」；

1. 在选项面板中勾选：插入模式、将 Ctrl+Shift+C/V 用作复制/粘贴快捷键；

1. 确认后即可使用快捷键进行复制粘贴。

3.2 初始化 Hermes 配置

1. 在 WSL 终端中，执行 Hermes 配置初始化命令：

hermes gateway setup

1. 命令执行后将进入交互式配置界面，使用 上下方向键 切换选项，回车/空格 确认，ESC 取消。

3.3 分步配置 Hermes

3.3.1 选择飞书版本

界面出现版本选项：

• feishu (China)：飞书中国版（国内企业通用，默认选中，直接回车确认）；
• lark (International)：Lark 国际版（海外团队使用，国内无需切换）。

3.3.2 录入飞书应用凭证

1. 根据提示，依次粘贴之前保存的 App ID 和 App Secret；
    
2. 注意：粘贴 App Secret 时终端不会显示明文（安全机制），粘贴完成直接回车即可。

   

   

3.3.3 选择连接模式

连接模式需要与飞书事件订阅方式对应，本地部署请选择 WebSocket：

1. WebSocket (recommended — no public URL needed)（推荐）：长连接模式，无需公网地址，匹配飞书的长连接配置；
2. Webhook (requires a reachable HTTP endpoint)：回调模式，需要公网可访问接口，适用于线上服务器。

3.3.4 设置私聊授权策略

设置陌生人发起私聊时的处理规则，按需选择：

1. Use DM pairing approval (recommended)（推荐）：配对码审批模式。陌生人发起私聊需管理员审批，安全性较高；
2. Allow all direct messages：允许所有人私聊。仅建议用于临时测试；
3. Only allow listed user IDs：白名单模式。仅指定飞书用户可私聊。

企业办公场景通常使用默认推荐选项即可。

3.3.5 设置群聊响应规则

定义机器人在群聊中的触发逻辑：

1. Respond only when @mentioned in groups (recommended)（推荐）：仅当群内被@时才响应。不会干扰正常群聊；
2. Disable group chats：禁用所有群聊功能。仅在无需群聊场景下选择。

3.3.6 可选：配置 Home chat ID（通知群）

配置最后一步会提示填写 Home chat ID，用于绑定默认通知群，机器人运行日志、异常通知等会推送到该群。

• 若暂时不需要消息推送，直接回车跳过，不影响基础聊天功能；
• 若需要配置，可后续补充，下文会说明获取方式。

3.3.7 配置成功确认

当终端出现绿色成功提示文字，表示 App ID 和 App Secret 校验通过，Hermes 网关已与飞书应用成功绑定。

四、第三步：补充配置与功能测试

4.1 获取群聊 Home chat ID（按需）

如需接收机器人运行通知，可按以下步骤获取群 ID 并补全配置：

1. 在飞书内新建或打开目标群聊，点击群右上角「···」更多菜单；

1. 在菜单中找到「群聊机器人」，将我们刚创建的 Hermes 机器人拉入群内；

1. 在群设置界面，查找并复制该群的唯一标识（群 ID）；

1. 重新执行 hermes gateway setup，在 Home chat ID 步骤粘贴 ID 并保存。

4.2 功能测试

配置完成后，进行以下测试以验证机器人是否工作正常：

1. 私聊测试

在飞书搜索找到自建机器人应用，发起一对一私聊并发送任意消息。若机器人正常响应，说明私聊链路配置正确。

1. 群聊测试

将机器人拉入企业内部群，在群内 @机器人名称 + 消息，观察机器人是否回复。若正常响应，代表群聊触发规则生效。

若机器人无响应，可优先检查：①飞书权限是否全部开通；②是否订阅了「接收消息」事件；③Hermes 连接模式与飞书订阅模式是否统一。

五、第四步：服务启动与开机自启设置

WSL 关闭后 Hermes 网关服务会停止，机器人将下线。以下是日常运维命令及开机自启方案，以实现服务持续在线。

5.1 基础运维命令（在 WSL 终端执行）

1. 启动网关服务（首次运行或重启后使用）

hermes gateway start

1. 重启网关服务（配置修改或服务异常时使用）

hermes gateway restart

1. 查看服务运行状态

hermes gateway status

• 显示 Active: active (running) = 服务正常运行；
• 若无此提示，则服务可能启动失败，需要检查配置。

5.2 设置 Windows 开机自动启动

为避免每次开机手动启动服务，可以创建开机自启脚本：

1. 在电脑桌面新建文本文档，重命名为 启动机器人.bat（后缀从 .txt 改为 .bat）；
2. 右键编辑文件，写入一行脚本：

wsl -u root hermes gateway start

1. 保存文件，将该 bat 文件移动到 Windows 开机启动目录：

C:\Users\你的电脑用户名\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup

1. 之后 Windows 开机时，系统会自动在后台启动 WSL 并运行 Hermes 网关服务。

5.3 下线通知说明

若手动关闭 WSL 终端，Hermes 服务会停止，绑定的通知群（如已设置）会自动收到机器人下线提醒。重新启动服务即可恢复。

六、常见问题排查

汇总配置过程中常见的问题及解决方法：

1. 机器人收不到消息、无响应

通常为飞书侧配置问题：未开启「机器人」能力、未订阅 im.message.receive_v1 事件、或相关权限未开通，请逐一核对。

1. Hermes 校验 App Secret 失败

检查密钥是否复制错误，确认区分 App ID 和 App Secret，并确保飞书应用状态正常。

1. 长连接验证失败

可能是本地防火墙或企业网络拦截了飞书的长连接，可尝试临时关闭防火墙，或切换网络环境（如手机热点）重试。

1. 群聊@机器人无反应

确认群聊响应规则选择了「仅被@时响应」，并确保机器人已成功加入该群聊。

七、拓展与总结

拓展玩法

基于 Hermes 接入的飞书机器人，除基础聊天外，还可进行功能拓展，例如：

• 企业内部：考勤提醒、工单状态推送、文档检索；
• 个人效率：消息备忘、日程提醒；
• 进阶开发：对接大模型 API，实现智能问答。

全文总结

整个接入流程主要分为 飞书应用配置 → Hermes 网关部署 → 功能测试 → 运维设置 几个部分。核心难点往往集中在飞书侧的事件与权限配置上，确保这一步无误，后续步骤通常能顺利执行。

Hermes 的轻量化特性使得在本地 WSL 环境中搭建飞书机器人成为可能，降低了技术门槛。按照本文步骤操作，你可以实现将 Hermes 接入飞书，构建一个满足内部自动化需求的机器人。

如果在操作中遇到新问题，欢迎在评论区留言交流。