Hermes Agent HelperHermes Agent Helper

飞书配置完全指南：Hermes Agent 接入飞书机器人教程

Hermes Agent Helperon a month ago

概述

飞书（Lark）是一款企业级协作平台，Hermes Agent 支持通过飞书机器人与用户进行对话交互。本教程将指导你完成从创建飞书应用到配置 Hermes Gateway 的完整流程。

🚀 推荐：使用飞书配置小助手（3 分钟完成）

强烈推荐使用 Hermes Agent 飞书配置小助手 来完成飞书机器人的配置！

使用飞书配置小助手，你只需要：

  1. 手动创建飞书应用（参考下方「第一步」）
  2. 获取 App ID 和 App Secret（参考下方「第一步」）
  3. 运行飞书配置小助手，它会自动完成所有飞书侧的配置（权限、事件订阅等）
  4. 将 App ID 和 App Secret 配置到 Hermes 服务管理工具中

飞书配置小助手能帮你节省 60+ 分钟的手动配置时间，自动处理繁琐的权限设置和事件订阅配置。

如果你选择手动配置，请继续阅读下方的完整教程。

手动配置预计时间：15-20 分钟

所需信息：

  • App ID（应用唯一标识）
  • App Secret（应用密钥）
  • 飞书用户 ID（用于授权访问）

第一步：创建飞书企业自建应用

1.1 进入开发者后台

  1. 打开 飞书开放平台
  2. 点击右上角「开发者后台」
  3. 如未登录，使用飞书账号登录

1.2 创建应用

  1. 在「我的应用」页面，点击「创建企业自建应用」
  2. 填写应用信息：
    • 应用名称：填写一个易于识别的名称，如「Hermes AI 助手」
    • 应用描述：简要描述应用用途
    • 应用图标：上传一个应用图标（可选）
  3. 点击「创建」

1.3 获取凭证

创建完成后，进入应用详情页：

  1. 在「凭证与基础信息」中找到：
    • App ID：类似 cli_xxxxxxxxxxxxxxxx 格式
    • App Secret：点击「显示」后复制

请妥善保存这两个值，后续配置需要使用。

第二步：配置应用权限和功能

2.1 添加机器人能力

  1. 进入「应用功能」→「机器人」
  2. 开启「启用机器人」开关
  3. 填写机器人信息：
    • 机器人名称：用户看到的机器人名称
    • 机器人描述：简要说明机器人功能

2.2 配置事件订阅

  1. 进入「开发配置」→「事件与回调」
  2. 在「事件订阅」中，点击「添加事件」
  3. 添加以下事件：
    • im.message.receive_v1（接收消息）

2.3 配置请求网址（Webhook）

在「事件订阅」页面：

  1. 找到「请求网址」配置项
  2. 填写你的 Hermes Gateway 回调地址： 
    https://你的服务器IP或域名:端口/webhook/feishu
  3. 点击「保存」

注意：保存时飞书会向该地址发送验证请求，请确保 Gateway 已启动。

2.4 申请权限

  1. 进入「开发配置」→「权限管理」
  2. 申请以下权限：
    • im:message（获取与发送单聊、群组消息）
    • im:message:send_as_bot（以应用的身份发送消息）
    • contact:user.id:readonly（获取用户 user ID）

第三步：获取飞书用户 ID

飞书用户 ID（Open ID 或 User ID）用于授权哪些用户可以与机器人对话。

方法一：通过飞书小助手获取（推荐）

我们提供了便捷的飞书小助手工具：

  1. 前往 飞书配置小助手页面
  2. 下载并安装飞书小助手
  3. 按照页面指引获取你的飞书 User ID

方法二：通过 API 获取

  1. 在飞书开放平台的「API 调试台」中
  2. 调用「获取用户信息」接口
  3. 从返回结果中获取 open_id 或 user_id

方法三：查看消息日志

  1. 先完成后续配置并启动 Gateway
  2. 给机器人发送一条测试消息
  3. 查看 Gateway 日志，其中会包含发送者的用户 ID

第四步：配置 Hermes Gateway

方式一：通过 Hermes 服务管理工具（推荐）

如果你使用的是我们的托管服务：

  1. 前往 Hermes 服务管理工具 页面
  2. 登录你的服务器管理界面
  3. 在「Config」标签页中填写：
    • gateway.feishu.app_id：你的 App ID
    • gateway.feishu.app_secret：你的 App Secret
    • gateway.feishu.allowed_users：授权的用户 ID（多个用逗号分隔）
  4. 点击「Save Changes」保存并重启

或者使用「Feishu Setup」快捷配置标签页，一键完成配置。

方式二：通过交互式向导

在服务器终端中运行：

hermes gateway setup

按提示操作：

  1. 选择「Feishu / Lark」
  2. 输入 App ID
  3. 输入 App Secret
  4. 输入允许的用户 ID（多个用逗号分隔）

方式三：手动编辑配置文件

编辑 ~/.hermes/.env 文件，添加：

FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=your_app_secret
FEISHU_ALLOWED_USERS=ou_xxxxx,ou_yyyyy

第五步：发布应用

5.1 创建应用版本

  1. 在应用详情页，点击「创建版本」
  2. 填写版本号和更新说明
  3. 保存版本

5.2 申请发布

  1. 点击「申请发布」
  2. 选择发布范围（建议先选择「仅对管理员可见」进行测试）
  3. 提交审核

5.3 审核通过后

审核通过后，授权用户即可在飞书中搜索并添加你的机器人。

第六步：测试验证

6.1 启动 Gateway

hermes gateway run

或作为系统服务启动：

hermes gateway install
hermes gateway start

6.2 发送测试消息

  1. 在飞书中找到你的机器人
  2. 发送一条测试消息，如「你好」
  3. 如果配置正确，机器人会回复 AI 生成的响应

常见问题

Q: 收到消息但机器人没有回复

可能原因：

  1. 用户 ID 未在 FEISHU_ALLOWED_USERS 中
  2. App Secret 配置错误
  3. Gateway 未正确启动

解决方法：

  1. 检查 Gateway 日志中的用户 ID
  2. 确认 App Secret 正确
  3. 运行 hermes gateway status 检查服务状态

Q: 事件订阅验证失败

可能原因：

  1. Gateway 未启动
  2. 回调地址不可访问
  3. 防火墙阻止了请求

解决方法：

  1. 确保 Gateway 正在运行
  2. 检查服务器端口是否开放
  3. 确认 HTTPS 证书有效（如使用 HTTPS）

Q: 权限申请被拒绝

可能原因：企业管理员限制了应用权限

解决方法：联系企业飞书管理员审批权限申请

相关资源

如有问题，请 联系我们 获取技术支持。