docs/usage/channels/lark.zh-CN.mdx
通过将 Lark 渠道连接到您的 LobeHub 代理，团队成员可以直接在 Lark 的私聊和群组对话中与 AI 助手互动。
如果您使用的是中国版（飞书），请参阅飞书设置指南。
LobeHub 支持两种 Lark 机器人连接模式：
注意： 下文第四步中在 Lark 开放平台配置 Event Subscription URL 的步骤仅适用于 Webhook 模式。如果您使用默认的 WebSocket 模式，请跳过这些步骤。
访问 open.larksuite.com/app 并使用您的账户登录。
点击 Create Enterprise App。填写应用名称（例如 "LobeHub Assistant"）、描述和图标，然后提交表单。
进入 Credentials & Basic Info，复制以下内容：
cli_xxx）重要提示： 请妥善保管您的 App Secret。切勿公开分享。
</Steps>
在您的应用设置中，进入 Permissions & Scopes，点击 Batch Import，然后粘贴以下 JSON 以授予机器人所需的所有权限。
{
"scopes": {
"tenant": [
"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",
"event:ip_list",
"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": []
}
}
<Callout type={'info'}>
以上权限码已针对 Lark（国际版）进行调整。部分飞书特有的权限码（如 aily:*、corehr:*、im:chat.access_event.bot_p2p_chat:read）在 Lark 上不可用，已被排除。
</Callout>
进入 App Capability → Bot。开启机器人功能并设置您喜欢的机器人名称。 </Steps>
在 LobeHub 中，导航到您的代理设置，然后选择 渠道 标签。点击平台列表中的 Lark。
输入以下字段：
在 Advanced Settings 中，选择 Connection Mode：
此时您不需要填写 Verification Token 或 Encrypt Key —— 可以在完成第四步（仅 Webhook 模式需要）配置事件订阅后再设置。
点击 Save Configuration。在 Webhook 模式 下，保存后将显示一个 Event Subscription URL，复制此 URL —— 您将在下一步中需要它。在 WebSocket 模式 下，机器人会自动连接，不会生成该 URL。
</Steps>
<Steps> ### 打开事件订阅设置如果您使用的是 WebSocket 模式（默认），请跳过此步骤。
返回 Lark 开发者门户中的应用。导航到 Event Subscription。
将您从 LobeHub 复制的 Event Subscription URL 粘贴到 Request URL 字段中。平台会自动验证端点。
添加以下事件：
im.message.receive_v1 — 当收到消息时触发这将使您的应用能够接收消息并将其转发到 LobeHub。
配置事件订阅后，您可以在事件订阅页面顶部的 Encryption Strategy 中找到 Verification Token 和 Encrypt Key。
返回 LobeHub 的渠道设置，填写：
再次点击 Save Configuration 以应用。
</Steps>
在您的应用设置中，进入 Version Management & Release。创建一个新版本并填写发布说明。
提交版本进行审核并发布。对于企业自管理应用，通常会自动批准。
</Steps>
回到 LobeHub 的渠道设置，点击 Test Connection 以验证凭证。然后在 Lark 中搜索您的机器人名称并发送消息，确认其是否响应。
高级设置里有一个可选字段影响日常使用体验，建议一开始就填好。
也就是你自己的 Lark open_id（按应用、按用户隔离的标识符 ——不是手机号或邮箱），用于：
/approve <code> 是属主命令，runtime 会用这个 ID 校验发起人。获取方式：先用任意消息私信 bot 一次，查看入站事件 payload 中发送方的 open_id 字段，那就是你的。Lark 开发者后台也提供 User ID 查询 工具，用手机号 / 邮箱反查 open_id。粘贴到 LobeHub 高级设置的 你的平台用户 ID 字段。
Lark 没有一个 AI 工具能默认指向的 "默认服务器" 概念（bot 通过凭证按租户运行），因此 Lark 渠道不展示 默认服务器 字段。
两个独立的策略控制入站消息，默认都为 开放。
填入 允许的用户 ID 后，所有入站消息（私信和群聊 @提及）都必须来自列表里的 Lark open_id。留空则不做用户级过滤。open_id 可从事件 payload 读取，或在 Lark 开发者后台查看 User ID。
Open 的差别在白名单为空时：Allowlist 模式全部拒绝。Allowlist 共享同一份名单，但非名单用户被拒后会收到一次性配对码，由你（属主）通过 /approve <code> 审批。审批通过的用户会被自动追加到 允许的用户 ID，后续 DM 直通。需先填 你的平台用户 ID（runtime 用它校验 /approve 发起人），并需要部署 Redis。@提及 时回复。控制机器人会在哪些 Lark 群里响应。
@ 都响应。chat_id）。跨平台细节见 渠道概览。
| 字段 | 是否必需 | 描述 |
|---|---|---|
| App ID | 是 | 您的 Lark 应用的 App ID（cli_xxx） |
| App Secret | 是 | 您的 Lark 应用的 App Secret |
| Connection Mode | 否 | websocket（默认）或 webhook，根据应用是否能接收公网 Webhook 请求来选择 |
| Verification Token | 否 | 验证 webhook 事件来源（推荐） |
| Encrypt Key | 否 | 解密加密事件负载（仅 Webhook 模式使用） |
| Event Subscription URL | — | Webhook 模式下保存后自动生成；粘贴到 Lark 开发者门户 |
| 允许的用户 ID | 否 | 逗号或空格分隔的 Lark open_id。全局闸门 — 私信和群聊 @ 都受其约束 |
| 私信策略 | 否 | open（默认）、allowlist、pairing 或 disabled — 控制谁可以私信机器人 |
| 群组策略 | 否 | open（默认）、allowlist 或 disabled — 控制机器人在哪些群中响应 |
| 允许的频道 ID | 否 | 逗号或空格分隔的 Lark chat_id。仅在群组策略为白名单时使用 |
im.message.receive_v1 事件。im.message.receive_v1 事件。Disabled，改成 Open 或 Allowlist；如果是 Allowlist，确认发起方的 open_id 已加入 允许的用户 ID。