飞书机器人接入配置指南 Hermes Agent提升团队协作效率

想要为团队部署智能助手，实现飞书机器人自动回复消息、处理任务？将 Hermes Agent 集成到飞书，是达成这一目标的高效方案。整个接入流程清晰明了，核心在于完成飞书开放平台的应用创建、权限配置、凭证获取，并对 Hermes 服务端进行相应设置。接下来，我们将详细解析这六个关键步骤。

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

一切始于一个合法的身份认证。你需要在飞书开放平台创建一个“企业自建应用”，这相当于为你的智能助手办理一张官方“工作证”。只有通过此方式创建的应用，才能被 Hermes Agent 正确识别并建立连接。

操作非常简便：访问 https://open.feishu.cn，使用管理员账号登录。随后，点击右上角的「创建应用」，选择「企业自建应用」。填写应用名称（例如“Hermes AI 助手”）、应用描述，上传应用图标，最后点击「创建」即可完成。

二、启用机器人能力并配置权限

创建应用仅是第一步，接下来需要激活它的核心功能。启用机器人能力，是赋予应用接收和发送消息的基础。而精确配置权限，则决定了 Hermes Agent 的操作范围——例如能否读取消息内容、发送回复、获取用户信息等。

进入应用详情页，找到「应用功能」模块下的「机器人」，点击「启用机器人」。此处有一个关键细节：务必勾选「开启交互式卡片」选项，否则后续的按钮点击、表单提交等高级交互功能将无法正常使用。

接着，转到「权限管理」→「申请权限」，添加以下核心权限：
• im:message:send_as_bot（以机器人身份发送消息）
• im:message:read（读取接收到的消息）
• contact:user:readonly（读取用户基本信息）
• im:message.group_at_msg:readonly（接收群聊中@机器人的消息）

权限添加完成后，记得点击「保存」并执行「发布」操作，使权限配置生效。

三、获取并记录应用凭证

现在，你需要获取应用的核心“密钥”——App ID 和 App Secret。这两组字符串是 Hermes Agent 与飞书平台建立安全通信、进行身份验证的凭证，后续的每一步配置都依赖于它们。

在应用详情页左侧菜单栏，点击「凭证与基础信息」。将页面显示的 App ID（格式通常为 cli_xxxxxxxxxx）和 App Secret（一串随机生成的字符）复制下来，并妥善保管。请特别注意，App Secret 属于敏感信息，切勿泄露到公开的代码仓库或聊天记录中。

四、配置 Hermes Gateway 接入飞书通道

拿到密钥后，下一步就是建立连接通道。此步骤的目标，是将你的 Hermes Agent 服务实例与刚才创建的飞书应用进行逻辑绑定。通常有两种主流配置方式：使用交互式向导或手动编辑配置文件。

方式一：使用交互式向导（推荐新手用户）
在运行 Hermes Agent 的服务端终端中，执行命令：hermes gateway setup。随后跟随命令行提示操作：选择 feishu → 输入之前保存的 App ID 和 App Secret → User IDs 字段可留空（表示允许全员访问）或填入特定的测试用户ID → Domain 保持默认 feishu → Connection mode 选择 websocket。

方式二：手动编辑配置文件（适合熟悉YAML格式的用户）
打开 Hermes 的主配置文件：~/.hermes/config.yaml。在 gateways 配置部分下，添加如下内容（请注意YAML的缩进格式）：

feishu:
  enabled: true
  app_id: "cli_xxxxxxxxxx"
  app_secret: "xxxxxxxxxxxxxxx"
  verification_token: "your_verification_token"
  encrypt_key: "your_encrypt_key"

五、配置事件订阅与回调地址

绑定完成后，如何让飞书将用户消息实时“推送”给 Hermes Agent 呢？这就需要配置事件订阅。飞书通过此机制，在特定事件（如收到消息）被触发时，主动向你的服务端发送通知。

回到飞书开放平台的应用详情页，进入「事件与回调」→「事件订阅」。订阅方式推荐选择「长连接」，其连接稳定性更佳。如果选择「HTTP 回调」方式，则需要填写一个公网可访问的 HTTPS URL 地址，例如：https://你的服务器域名或IP:端口号/webhook/feishu。

在「需要订阅的事件」列表中，至少确保勾选了：im.message.receive_v1（接收消息事件）。保存配置后，飞书服务器会向你的回调地址发送一个验证请求，请确保此时 Hermes Agent 服务正在运行并正确监听着对应的路径。

六、发布应用并完成测试

至此，后台的配置工作已基本完成。但处于开发状态的应用仅限开发者本人调试使用，若要让团队其他成员也能调用机器人，必须将其发布上线。

在飞书开放平台找到「版本管理与发布」入口，点击「创建版本」，填写版本说明后提交审核。等待团队管理员在飞书客户端内完成审批。

应用发布成功后，团队成员就可以在飞书客户端中搜索到你的应用名称，并点击「添加」。现在，可以尝试在私聊或群聊会话中@机器人或直接发送消息进行测试。观察 Hermes Agent 是否返回了预期的智能回复。如果机器人没有响应，不必担心，请检查 Hermes 服务端的运行日志，查看是否有 feishu webhook received 之类的接收记录，或是 connection refused 等连接错误信息，根据日志线索逐步排查即可。

完成以上六个步骤，一个能够理解对话上下文、实现自动响应的智能飞书机器人便正式部署成功。它不仅能够解答常见问题，更能通过深度集成，协助处理工作流程、查询业务数据，真正成为提升团队协作效率的智能助手。