如果你需要在飞书内部署一个能够自动响应消息的机器人并且希望过程足够轻便、无需复杂的服务器架构那么 Hermes 是一个值得考虑的工具。结合飞书开放平台它可以在本地环境如 WSL中快速搭建起一个可用的机器人连接以处理诸如消息提醒、自动问答等场景。不用担心本文将指导你完成将 Hermes 接入飞书的全过程涵盖飞书自建应用创建 → 事件与权限配置 → 通过 WSL 部署 Hermes → 机器人联调测试 → 开机自启设置等关键步骤。同时会附上配置中常见问题的排查要点帮助你顺利跑通。快点来试试吧一、准备事项在开始前请确保满足以下基础条件账号权限拥有企业飞书的管理员权限用于在飞书开放平台创建企业自建应用运行环境Windows 系统并已安装WSLUbuntu环境Hermes 的命令行操作依赖 Linux 环境网络环境本地网络可正常访问飞书开放平台无企业防火墙拦截长连接工具认知对飞书应用、机器人、事件回调等概念有基本了解即可文中会做必要说明。二、第一步在飞书开放平台创建企业自建应用机器人需要依托一个飞书企业自建应用作为载体该应用仅在当前企业内部生效。2.1 创建应用使用企业飞书管理员账号登录飞书开发者平台开发者后台 - 飞书开放平台在首页选择企业自建应用自建应用仅供内部使用这是我们搭建机器人的合适选择点击「创建企业自建应用」按提示填写基本信息带*为必填应用名称自定义例如「Hermes 机器人」应用描述简要说明用途如“基于 Hermes 搭建的飞书消息响应机器人”应用图标支持常见图片格式尺寸建议大于 240*240 px文件大小 2MB 以内可后续补充填写完成后点击创建应用即生成进入应用后台详情页。2.2 开启机器人能力新创建的应用默认不具备交互能力需要手动开启「机器人」在应用详情页找到【添加应用能力】模块在能力列表中选中机器人点击右侧「添加」完成开通其他能力如网页应用本次无需开启。2.3 配置事件与回调确保机器人能接收消息许多配置完成后机器人无响应的问题都源于事件与回调、权限未正确配置。2.3.1 选择事件订阅方式飞书提供两种事件推送模式对于本地部署场景推荐使用长连接模式在左侧导航栏进入【事件与回调】切换到「事件配置」标签页订阅方式选择✅使用长连接接收事件推荐无需公网域名、无需配置加密适合本地开发测试与 WSL 环境兼容❌将事件发送至开发者服务器适用于已部署在公网服务器的应用本地测试不推荐选中「使用长连接接收事件」点击验证检测连接状态验证通过后保存。简单来说长连接是在本地服务与飞书服务器之间建立一条持续的“专线”消息可以实时推送。2.3.2 添加「接收消息」事件仅开启长连接还不够需要订阅具体的事件机器人才能识别消息在「已添加事件」区域点击「添加事件」在事件列表中找到im.message.receive_v1接收消息v2.0勾选并添加可按需添加其他附属事件如消息已读、表情回复等基础聊天机器人可暂不添加注意每添加一个事件都需要单独开通对应的权限。点击权限名称在弹窗中确认开通列表显示「已开通」即为生效。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 记录应用凭证在左侧导航栏进入【凭证与基础信息】复制并妥善保存以下两个关键信息请勿泄露App ID飞书应用的唯一标识App Secret应用的密钥相当于密码所有配置完成后点击页面右上角发布并创建版本提交配置并等待企业管理员审核通常很快要么就去敲管理员的头当然自己是管理员就免审核了。三、第二步在 WSL 环境中部署 Hermes 网关完成飞书侧配置后切换到 WSLUbuntu环境安装并配置 Hermes 网关建立与飞书的连接。3.1 WSL 终端优化可选好细节好感动为方便后续操作可以先优化 WSL 终端的复制粘贴体验打开 WSL Ubuntu 终端右键点击终端边框选择「属性」在选项面板中勾选插入模式、将 CtrlShiftC/V 用作复制/粘贴快捷键确认后即可使用快捷键进行复制粘贴。3.2 初始化 Hermes 配置在 WSL 终端中执行 Hermes 配置初始化命令hermes gateway setup命令执行后将进入交互式配置界面使用上下方向键切换选项回车/空格确认ESC取消。3.3 分步配置 Hermes3.3.1 选择飞书版本界面出现版本选项feishu (China)飞书中国版国内企业通用默认选中直接回车确认lark (International)Lark 国际版海外团队使用国内无需切换。3.3.2 录入飞书应用凭证根据提示依次粘贴之前保存的App ID和App Secret注意粘贴 App Secret 时终端不会显示明文安全机制粘贴完成直接回车即可。3.3.3 选择连接模式连接模式需要与飞书事件订阅方式对应本地部署请选择 WebSocketWebSocket (recommended — no public URL needed)推荐长连接模式无需公网地址匹配飞书的长连接配置Webhook (requires a reachable HTTP endpoint)回调模式需要公网可访问接口适用于线上服务器。3.3.4 设置私聊授权策略设置陌生人发起私聊时的处理规则按需选择Use DM pairing approval (recommended)推荐配对码审批模式。陌生人发起私聊需管理员审批安全性较高Allow all direct messages允许所有人私聊。仅建议用于临时测试Only allow listed user IDs白名单模式。仅指定飞书用户可私聊。企业办公场景通常使用默认推荐选项即可。3.3.5 设置群聊响应规则定义机器人在群聊中的触发逻辑Respond only when mentioned in groups (recommended)推荐仅当群内被时才响应。不会干扰正常群聊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 并补全配置在飞书内新建或打开目标群聊点击群右上角「···」更多菜单在菜单中找到「群聊机器人」将我们刚创建的 Hermes 机器人拉入群内在群设置界面查找并复制该群的唯一标识群 ID重新执行hermes gateway setup在 Home chat ID 步骤粘贴 ID 并保存。4.2 功能测试配置完成后进行以下测试以验证机器人是否工作正常私聊测试在飞书搜索找到自建机器人应用发起一对一私聊并发送任意消息。若机器人正常响应说明私聊链路配置正确。群聊测试将机器人拉入企业内部群在群内机器人名称 消息观察机器人是否回复。若正常响应代表群聊触发规则生效。若机器人无响应可优先检查①飞书权限是否全部开通②是否订阅了「接收消息」事件③Hermes 连接模式与飞书订阅模式是否统一。五、第四步服务启动与开机自启设置WSL 关闭后 Hermes 网关服务会停止机器人将下线。以下是日常运维命令及开机自启方案以实现服务持续在线。5.1 基础运维命令在 WSL 终端执行启动网关服务首次运行或重启后使用hermes gateway start重启网关服务配置修改或服务异常时使用hermes gateway restart查看服务运行状态hermes gateway status显示Active: active (running) 服务正常运行若无此提示则服务可能启动失败需要检查配置。5.2 设置 Windows 开机自动启动为避免每次开机手动启动服务可以创建开机自启脚本在电脑桌面新建文本文档重命名为启动机器人.bat后缀从.txt改为.bat右键编辑文件写入一行脚本wsl -u root hermes gateway start保存文件将该 bat 文件移动到 Windows 开机启动目录C:\Users\你的电脑用户名\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup之后 Windows 开机时系统会自动在后台启动 WSL 并运行 Hermes 网关服务。5.3 下线通知说明若手动关闭 WSL 终端Hermes 服务会停止绑定的通知群如已设置会自动收到机器人下线提醒。重新启动服务即可恢复。六、常见问题排查汇总配置过程中常见的问题及解决方法机器人收不到消息、无响应通常为飞书侧配置问题未开启「机器人」能力、未订阅im.message.receive_v1事件、或相关权限未开通请逐一核对。Hermes 校验 App Secret 失败检查密钥是否复制错误确认区分 App ID 和 App Secret并确保飞书应用状态正常。长连接验证失败可能是本地防火墙或企业网络拦截了飞书的长连接可尝试临时关闭防火墙或切换网络环境如手机热点重试。群聊机器人无反应确认群聊响应规则选择了「仅被时响应」并确保机器人已成功加入该群聊。七、拓展与总结拓展玩法基于 Hermes 接入的飞书机器人除基础聊天外还可进行功能拓展例如企业内部考勤提醒、工单状态推送、文档检索个人效率消息备忘、日程提醒进阶开发对接大模型 API实现智能问答。全文总结整个接入流程主要分为飞书应用配置 → Hermes 网关部署 → 功能测试 → 运维设置几个部分。核心难点往往集中在飞书侧的事件与权限配置上确保这一步无误后续步骤通常能顺利执行。Hermes 的轻量化特性使得在本地 WSL 环境中搭建飞书机器人成为可能降低了技术门槛。按照本文步骤操作你可以实现将 Hermes 接入飞书构建一个满足内部自动化需求的机器人。如果在操作中遇到新问题欢迎在评论区留言交流。