将 LobeHub 连接到飞书

通过将飞书渠道连接到您的 LobeHub 代理，团队成员可以直接在飞书的私聊和群组对话中与 AI 助手互动。

如果您使用的是国际版（Lark），请参阅 Lark 设置指南。

前置条件

一个拥有有效订阅的 LobeHub 账户
一个拥有创建企业应用权限的飞书账户

第一步：创建飞书应用

<Steps> ### 打开开发者门户

访问 open.feishu.cn/app 并使用您的账户登录。

创建企业应用

点击 创建企业应用。填写应用名称（例如 "LobeHub 助手"）、描述和图标，然后提交表单。

复制应用凭证

进入 凭证与基本信息，复制以下内容：

应用 ID（格式：cli_xxx）
应用密钥

重要提示： 请妥善保管您的应用密钥。切勿公开分享。

</Steps>

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

<Steps> ### 导入所需权限

在您的应用设置中，进入 权限与范围，点击 批量导入，然后粘贴以下 JSON 以授予机器人所需的所有权限。

json

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

启用机器人功能

进入 应用能力 → 机器人。开启机器人功能并设置您喜欢的机器人名称。

</Steps>

第三步：在 LobeHub 中配置飞书

<Steps> ### 打开渠道设置

在 LobeHub 中，导航到您的代理设置，然后选择渠道标签。点击平台列表中的飞书。

填写应用凭证

输入以下字段：

应用 ID — 来自飞书应用的应用 ID
应用密钥 — 来自飞书应用的应用密钥

此时您不需要填写 Verification Token 或 Encrypt Key —— 可以在完成第四步配置事件订阅后再设置。

保存并复制 Webhook URL

点击 保存配置。保存后，将显示一个 事件订阅 URL。复制此 URL—— 您将在下一步中需要它。

</Steps>

第四步：在飞书中设置事件订阅

<Steps> ### 打开事件订阅设置

返回飞书开发者门户中的应用。导航到 事件订阅。

配置请求 URL

将您从 LobeHub 复制的 事件订阅 URL 粘贴到 请求 URL 字段中。平台会自动验证端点。

添加消息事件

添加以下事件：

im.message.receive_v1 — 当收到消息时触发

这将使您的应用能够接收消息并将其转发到 LobeHub。

（推荐）填写 Verification Token 和 Encrypt Key

配置事件订阅后，您可以在事件订阅页面顶部的 加密策略 中找到 Verification Token 和 Encrypt Key。

返回 LobeHub 的渠道设置，填写：

Verification Token — 用于验证 webhook 事件是否来自飞书
Encrypt Key（可选）— 用于解密加密事件负载

再次点击 保存配置 以应用。

</Steps>

第五步：发布应用

<Steps> ### 创建版本

在您的应用设置中，进入 版本管理与发布。创建一个新版本并填写发布说明。

提交审核

提交版本进行审核并发布。对于企业自管理应用，通常会自动批准。 </Steps>

第六步：测试连接

回到 LobeHub 的渠道设置，点击 测试连接 以验证凭证。然后在飞书中搜索您的机器人名称并发送消息，确认其是否响应。

接入策略

两个独立的策略控制入站消息，默认都为开放。

允许的用户 ID（全局）

填入 允许的用户 ID 后，所有入站消息（私信和群聊 @提及）都必须来自列表里的飞书 open_id。留空则不做用户级过滤。open_id 可从事件 payload 读取，或在飞书开发者后台查看 User ID。

私信策略

开放 (Open)（默认） — 租户内任何成员都可以私信机器人（若设置了全局白名单则受其约束）。
白名单 (Allowlist) — 私信需要发送者在 允许的用户 ID 里。和 Open 的差别在白名单为空时：Allowlist 模式全部拒绝。
禁用 (Disabled) — 机器人忽略所有私信，只在群聊里被 @提及 时回复。

群组策略

控制机器人会在哪些飞书群里响应。

开放 (Open)（默认） — 在机器人加入的任何群里被 @ 都响应。
白名单 (Allowlist) — 只在 允许的频道 ID 列出的会话里响应（使用事件 payload 里的 chat_id）。
禁用 (Disabled) — 忽略所有群聊流量，机器人只接受私信。

跨平台细节见渠道概览。

配置参考

字段	是否必需	描述
应用 ID	是	您的飞书应用的应用 ID（`cli_xxx`）
应用密钥	是	您的飞书应用的应用密钥
Verification Token	否	验证 webhook 事件来源（推荐）
Encrypt Key	否	解密加密事件负载
事件订阅 URL	—	保存后自动生成；粘贴到飞书开发者门户
允许的用户 ID	否	逗号或空格分隔的飞书 `open_id`。全局闸门 — 私信和群聊 @ 都受其约束
私信策略	否	`open`（默认）、`allowlist` 或 `disabled` — 控制谁可以私信机器人
群组策略	否	`open`（默认）、`allowlist` 或 `disabled` — 控制机器人在哪些群中响应
允许的频道 ID	否	逗号或空格分隔的飞书 `chat_id`。仅在群组策略为白名单时使用

故障排除

事件订阅 URL 验证失败： 确保您已在 LobeHub 中保存配置，并正确复制了 URL。
机器人未响应： 验证应用已发布并获得批准，机器人功能已启用，并订阅了 im.message.receive_v1 事件。
机器人不回私信： 在 LobeHub 的 高级设置 检查 私信策略。如果是 Disabled，改成 Open 或 Allowlist；如果是 Allowlist，确认发起方的 open_id 已加入 允许的用户 ID。
权限错误： 确保所有所需权限已在开发者门户中添加并获得批准。
测试连接失败： 仔细检查应用 ID 和应用密钥。