---
title: 将 LobeHub 连接到飞书
description: 了解如何创建飞书自定义应用并将其连接到您的 LobeHub 代理作为消息渠道，使您的 AI 助手能够在飞书聊天中与团队成员互动。
tags:
  - 飞书
  - 消息渠道
  - 机器人设置
  - 集成
---

# 将 LobeHub 连接到飞书

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

> 如果您使用的是国际版（Lark），请参阅 [Lark 设置指南](/docs/usage/channels/lark)。

## 前置条件

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

## 第一步：创建飞书应用

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

  访问 [open.feishu.cn/app](https://open.feishu.cn/app) 并使用您的账户登录。

  ### 创建企业应用

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

  ![](/blog/assets086849ced67ad95fc3f0d1f509add1bf.webp)

  ### 复制应用凭证

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

  - **应用 ID**（格式：`cli_xxx`）
  - **应用密钥**

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

  ![](/blog/assetsf811b07c10e4a887248fc3f53d085241.webp)
</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"
      ]
    }
  }
  ```

  ![](/blog/assets03aba6c4b7a39ed9b1be75ecd8f335dc.webp)

  ### 启用机器人功能

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

  ![](/blog/assetsb74a9fc9aecbaa74529cf0fb0da37bca.webp)
</Steps>

## 第三步：在 LobeHub 中配置飞书

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

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

  ### 填写应用凭证

  输入以下字段：

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

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

  ### 保存并复制 Webhook URL

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

  ![](/blog/assetsbc6a72dc53430bbbbeafcc7d921396f4.webp)
</Steps>

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

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

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

  ### 配置请求 URL

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

  ### 添加消息事件

  添加以下事件：

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

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

  ![](/blog/assetsb6f4b163825de58e2b6fe4dba8ef1b26.webp)

  ### （推荐）填写 Verification Token 和 Encrypt Key

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

  ![](/blog/assets05b5684db0f7035e8f0609f6b1b8d85c.webp)

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

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

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

  ![](/blog/assets3fcf2ee44ffb6be5c3148667f0c1696e.webp)
</Steps>

## 第五步：发布应用

<Steps>
  ### 创建版本

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

  ![](/blog/assetsbd0ac93d1d3bba86d5da86b9569a6fb1.webp)

  ### 提交审核

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

## 第六步：测试连接

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

## 第七步：填写你的平台身份（推荐）

**高级设置**里有一个可选字段影响日常使用体验，建议一开始就填好。

### 你的平台用户 ID

也就是你自己的飞书 `open_id`（按应用、按用户隔离的标识符 ——**不是**手机号或邮箱），用于：

- **配对审批** — 当 **私信策略** 为 **配对审批** 时为必填项，`/approve <code>` 是属主命令，runtime 会用这个 ID 校验发起人。
- **AI 工具主动推送** — 让 Agent 能主动联系你（提醒、通知），把内部用户引用映射到你的飞书账号。
- **防自锁** — 自动被 **允许的用户** 信任，给同事收紧 bot 时不会把自己挡在外面。

获取方式：先用任意消息私信 bot 一次，查看入站事件 payload 中发送方的 `open_id` 字段，那就是你的。飞书开发者后台也提供 **User ID 查询** 工具，用手机号 / 邮箱反查 `open_id`。粘贴到 LobeHub 高级设置的 **你的平台用户 ID** 字段。

> 飞书没有一个 AI 工具能默认指向的 "默认服务器" 概念（bot 通过凭证按租户运行），因此飞书渠道不展示 **默认服务器** 字段。

## 接入策略

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

### 允许的用户 ID（全局）

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

### 私信策略

- **开放 (Open)（默认）** — 租户内任何成员都可以私信机器人（若设置了全局白名单则受其约束）。
- **白名单 (Allowlist)** — 私信需要发送者在 **允许的用户 ID** 里。和 `Open` 的差别在白名单为空时：`Allowlist` 模式**全部拒绝**。
- **配对审批 (Pairing)** — 与 `Allowlist` 共享同一份名单，但非名单用户被拒后会收到一次性配对码，由你（属主）通过 `/approve <code>` 审批。审批通过的用户会被自动追加到 **允许的用户 ID**，后续 DM 直通。需先填 **你的平台用户 ID**（runtime 用它校验 `/approve` 发起人），并需要部署 Redis。
- **禁用 (Disabled)** — 机器人忽略所有私信，只在群聊里被 `@提及` 时回复。

### 群组策略

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

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

跨平台细节见 [渠道概览](/docs/usage/channels/overview#direct-message-policy)。

## 配置参考

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

## 故障排除

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