HermesAgent接入飞书教程：配置AppID与事件订阅

本文详细讲解了如何将HermesAgent成功接入飞书平台，重点解决“飞书端无法接收或响应消息”这一高频问题——根源往往在于App ID配置错误或事件订阅未生效。文章手把手引导用户完成五大关键步骤：从飞书开放平台创建自建应用并获取凭证、开通机器人能力与权限、配置Hermes网关参数、设置并验证事件订阅回调、最终发布应用并完成管理员审批与终端配对，确保Hermes Agent能稳定实现企业级群聊@响应、私聊互通与实时消息处理，是开发者快速落地AI助手与飞书深度集成的实用指南。

如果您已完成 Hermes Agent 的本地部署，但飞书端无法接收或响应消息，则可能是由于 App ID 配置错误或事件订阅未生效。以下是实现企业级对话所需的完整配置流程：

一、创建飞书企业自建应用并获取凭证

该步骤用于在飞书开放平台注册合法身份，生成唯一识别标识，确保 Hermes Agent 能以受信应用形式与飞书服务通信。需准确记录关键凭证供后续配置使用。

1、访问 https://open.feishu.cn，使用企业管理员账号登录。

2、点击“创建应用”，选择“企业自建应用”类型。

3、填写应用名称（如Hermes AI 助手）与描述，上传图标（可选），完成创建。

4、进入应用详情页，在“凭证与基础信息”中复制并保存以下两项：App ID 与 App Secret。

二、开通机器人能力并配置权限

此步骤赋予应用发送、接收消息及读取用户身份的必要操作权限，是实现群聊@响应与私聊互通的前提条件。

1、在应用详情页点击“添加应用能力”，勾选“机器人”并确认启用。

2、进入“权限管理” → “申请权限”，添加以下四项权限：

　　im:message:send_as_bot

　　im:message:read

　　im:message.group_at_msg

　　contact:user:readonly

3、点击“发布权限变更”使配置立即生效。

三、配置 Hermes Agent 的飞书网关参数

该步骤将飞书凭证注入 Hermes 运行时环境，建立双向通信通道，支持 WebSocket 或 HTTP 回调两种连接模式。

1、在服务器终端执行命令：hermes gateway setup。

2、在交互式向导中依次选择：feishu → 输入已复制的 App ID 与 App Secret。

3、User IDs 字段留空（允许全企业成员使用）或填入指定测试用户 ID。

4、Domain 保持默认 feishu，Connection mode 推荐选择 websocket。

四、设置事件订阅并验证回调地址

此步骤使飞书平台能主动推送用户消息至 Hermes Agent，需确保回调 URL 可被公网访问且服务端已监听对应路径。

1、返回飞书开放平台，进入应用详情页的“事件订阅”或“事件与回调”模块。

2、订阅方式选择 长连接（WebSocket） 或 HTTP 回调（若选后者，URL 填写 https://你的服务器IP:3000/webhook/feishu）。

3、添加事件类型：im.message.receive_v1。

4、点击“验证”按钮，系统将发起 GET 请求；请确保 Hermes Agent 已运行且监听该路径，否则验证失败。

五、发布应用并完成首次配对

该步骤使应用从开发态转为生产态，仅经管理员审批后，机器人方可被企业内用户搜索、添加并实际使用。

1、进入“版本管理与发布”，点击“创建版本”，填写版本说明后提交审核。

2、企业管理员登录飞书管理后台，在“应用管理”中找到该应用，点击“审批通过”。

3、在飞书中搜索机器人名称，点击进入并发送任意消息（如“你好”）。

4、此时 Hermes Agent 终端将提示配对请求，执行命令：hermes gateway pair，终端显示 Approved! 配对成功! 即完成激活。

到这里，我们也就讲完了《HermesAgent接入飞书教程：配置AppID与事件订阅》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于Hermes Agent,HermesAgent的知识点！