将 LobeHub 连接到飞书
通过将飞书渠道连接到您的 LobeHub 代理,团队成员可以直接在飞书的私聊和群组对话中与 AI 助手互动。
如果您使用的是国际版(Lark),请参阅 Lark 设置指南。
前置条件
- 一个拥有有效订阅的 LobeHub 账户
- 一个拥有创建企业应用权限的飞书账户
连接模式
LobeHub 支持两种飞书机器人连接模式:
- WebSocket(推荐) — 使用飞书官方的长连接客户端建立持久连接。事件实时推送,无需配置公网可访问的 Webhook 地址,即使没有公网服务器也能开箱即用。这是新机器人的默认模式。
- Webhook — 基于事件订阅 URL 的 HTTP 回调。如果您倾向于无状态的回调方式,或应用已在飞书开放平台配置了事件订阅 URL,可使用此模式。
注意: 两种模式都需要消息接收事件订阅。快捷创建入口会预置权限和事件配置;手动创建时需要自行添加。只有 Webhook 模式需要配置 事件订阅 URL;WebSocket 模式使用长连接订阅。
快捷创建飞书智能体应用(推荐)
新建机器人时,优先使用飞书开放平台的 创建飞书智能体应用 入口。它会预置智能体所需的权限和事件配置,再将应用凭证填入 LobeHub 即可接入你的助理。这里创建的是飞书应用,你仍需在 LobeHub 中选择要连接的助理。
打开快捷创建入口
登录 飞书开放平台,在应用列表顶部找到 创建飞书智能体应用,点击 立即创建。
选择头像和名称
选择头像,填写应用名称(例如「LobeHub 助手」),然后点击 立即创建,等待自动配置完成。
复制应用凭证
在 创建成功 页面,分别复制 App ID 和 App Secret。请妥善保管 App Secret,不要发送到群聊或公开截图。
接入 LobeHub
打开 LobeHub 中要连接的助理,进入 设置 → 渠道 → 飞书,填入刚才复制的 应用 ID 和 应用密钥。在 高级设置 中保持默认的 WebSocket 连接模式,点击 保存配置。
WebSocket 模式无需填写事件订阅 URL、Verification Token 或 Encrypt Key。已有的预置权限和事件配置无需重复添加;如果后续使用某项工具提示缺少权限,再按提示补充对应权限。
打开应用并测试
按飞书页面提示确认应用已发布并可用;如果企业要求管理员审批,请先完成审批。点击 打开应用,给机器人发送一条消息,确认收到 LobeHub 助理的回复。
若没有回复,检查飞书应用是否已启用机器人、订阅方式是否为 使用长连接接收事件、是否包含 im.message.receive_v1,以及 LobeHub 渠道配置是否已保存。具体排障项见本文末尾。
截图以「Lobehub 周报小助手」为例,你可以使用自己的应用名称。
快捷方式连接成功后,无需重复下面的手动创建步骤,可继续阅读 第七步:填写你的平台身份 和 接入策略。如果没有快捷入口、需要配置已有应用,或选择 Webhook 模式,请使用下面的手动配置流程。
手动配置(备用方式)
以下步骤适用于从零创建企业应用。已有应用可从需要补充或调整的步骤开始;快捷创建的应用仅需核对缺失的配置,无需重新创建。
第一步:创建飞书应用
打开开发者门户
访问 open.feishu.cn/app 并使用您的账户登录。
创建企业应用
点击 创建企业应用。填写应用名称(例如 "LobeHub 助手")、描述和图标,然后提交表单。

复制应用凭证
进入 凭证与基本信息,复制以下内容:
- 应用 ID(格式:
cli_xxx) - 应用密钥
重要提示: 请妥善保管您的应用密钥。切勿公开分享。

第二步:配置应用权限和机器人功能
导入所需权限
在您的应用设置中,进入 权限与范围,点击 批量导入,然后粘贴以下 JSON 以授予机器人所需的所有权限。

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

第三步:在 LobeHub 中配置飞书
打开渠道设置
在 LobeHub 中,导航到您的代理设置,然后选择 渠道 标签。点击平台列表中的 飞书。
填写应用凭证
输入以下字段:
- 应用 ID — 来自飞书应用的应用 ID
- 应用密钥 — 来自飞书应用的应用密钥
选择连接模式
在 高级设置 中,选择 连接模式:
- WebSocket(默认)— 推荐新机器人使用。保存后继续第四步,在飞书开放平台启用长连接订阅。
- Webhook — 适用于已配置公网回调地址的应用。保存后复制事件订阅 URL,并在第四步配置回调。
Verification Token 和 Encrypt Key 仅用于 Webhook 模式。此时可以先留空,在第四步配置回调后再填写。
保存配置
点击 保存配置。WebSocket 模式会立即尝试建立长连接;Webhook 模式会显示一个 事件订阅 URL,请复制此 URL 供下一步使用。

第四步:在飞书中设置事件订阅
无论选择哪种连接模式,都必须完成此步骤,否则机器人无法收到消息。
打开事件订阅设置
返回飞书开发者门户中的应用。导航到 事件订阅。
选择订阅方式
根据您在 LobeHub 中选择的连接模式完成配置:
- WebSocket(推荐) — 选择 使用长连接接收事件 并保存。请确保 LobeHub 中的渠道配置已保存且机器人保持连接;此模式不需要公网请求 URL。
- Webhook — 选择 将事件发送至开发者服务器,将从 LobeHub 复制的 事件订阅 URL 粘贴到 请求 URL 字段。平台会自动验证端点。
添加消息事件
添加以下事件:
im.message.receive_v1— 当收到消息时触发
这将使您的应用能够接收消息并将其转发到 LobeHub。

配置 Webhook 安全参数(仅 Webhook 模式)
如果使用 Webhook 模式,您可以在事件订阅页面顶部的 加密策略 中找到 Verification Token 和 Encrypt Key。WebSocket 模式无需配置这两个字段。

返回 LobeHub 的渠道设置,填写:
- Verification Token — 用于验证 webhook 事件是否来自飞书
- Encrypt Key(可选)— 用于解密加密事件负载
再次点击 保存配置 以应用。

第五步:发布应用
第六步:测试连接
回到 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) — 忽略所有群聊流量,机器人只接受私信。
跨平台细节见 渠道概览。
配置参考
| 字段 | 是否必需 | 描述 |
|---|---|---|
| 应用 ID | 是 | 您的飞书应用的应用 ID(cli_xxx) |
| 应用密钥 | 是 | 您的飞书应用的应用密钥 |
| 连接模式 | 否 | websocket(默认)或 webhook,根据应用是否能接收公网 Webhook 请求来选择 |
| Verification Token | 否 | 验证 Webhook 事件来源(仅 Webhook 模式,推荐) |
| Encrypt Key | 否 | 解密加密事件负载(仅 Webhook 模式使用) |
| 事件订阅 URL | — | Webhook 模式下保存后自动生成;粘贴到飞书开发者门户 |
| 允许的用户 ID | 否 | 逗号或空格分隔的飞书 open_id。全局闸门 — 私信和群聊 @ 都受其约束 |
| 私信策略 | 否 | open(默认)、allowlist、pairing 或 disabled — 控制谁可以私信机器人 |
| 群组策略 | 否 | open(默认)、allowlist 或 disabled — 控制机器人在哪些群中响应 |
| 允许的频道 ID | 否 | 逗号或空格分隔的飞书 chat_id。仅在群组策略为白名单时使用 |
故障排除
- 机器人无法连接(WebSocket 模式): 验证应用 ID 和应用密钥是否正确,并确认 LobeHub 服务可以访问飞书开放平台。
- 连接成功但收不到消息(WebSocket 模式): 确认飞书开放平台的订阅方式为 使用长连接接收事件,已添加
im.message.receive_v1,并已发布包含这些变更的应用版本。 - 事件订阅 URL 验证失败(Webhook 模式): 确保您已在 LobeHub 中保存配置,并正确复制了 URL。
- 机器人未响应: 验证应用已发布并获得批准,机器人功能已启用,并订阅了
im.message.receive_v1事件。 - 机器人不回私信: 在 LobeHub 的 高级设置 检查 私信策略。如果是
Disabled,改成Open或Allowlist;如果是Allowlist,确认发起方的open_id已加入 允许的用户 ID。 - 权限错误: 确保所有所需权限已在开发者门户中添加并获得批准。
- 测试连接失败: 仔细检查应用 ID 和应用密钥。
