Lark

最近更新 2026/10/07

前置条件

1. Lark开放平台配置

访问 Lark 开放平台
创建企业自建应用（或使用现有应用）
获取应用凭证：
- APP ID
- APP Secret

2. 配置机器人

在 Lark 开放平台 → 添加应用能力 → 按能力添加 → 添加机器人

3. 配置重定向URL

在 Lark 开放平台 → 安全设置 → 重定向URL → 添加

http://your-domain/agent/api/lark-oauth/callback

若是本地测试，重定向URL则为：http://localhost:3000/api/lark-oauth/callback

4. 事件与回调

订阅方式：在 Lark Developer Console 的「Events & Callbacks」中，事件和回调均选择使用长连接接收，无需填写公网 Callback URL。事件配置添加 im.message.receive_v1；回调配置添加 card.action.trigger，用于 AskUserQuestion 表单的提交、忽略和继续。应用权限必须包含 im:resource（下载用户图片/文件并上传生成文件）和 cardkit:card:write（创建、流式更新和替换交互卡片）。缺少 im:resource 时，文本消息可能正常，但图片读取和生成文件发送会失败。修改权限、事件或回调后，必须创建并发布新版本，并确认应用对目标用户可用。

5. 应用权限配置

Lark 开放平台 → 权限管理 → 点击【开通权限】 → 在【应用身份权限】中开启：

im:message	获取与发送单聊、群组消息
im:message.group_at_msg.include_bot:readonly	获取群组中其他机器人和用户@当前机器人的消息
im:message.group_at_msg:readonly	获取群组中用户@机器人消息
im:message.group_msg	获取群组中所有消息
im:message.p2p_msg:readonly	读取用户发给机器人的单聊消息
im:message:readonly	获取单聊、群组消息
im:message:send_as_bot	以应用的身份发消息
im:resource	获取与上传图片或文件资源
cardkit:card:write	创建与更新卡片

群聊消息分发建议新增权限：tenant:tenant:readonly（Read tenant information）。有此权限时，系统管理在验证渠道后即可识别 tenant 并显示群聊空间；没有此权限不会影响凭证验证和消息收发，但群聊空间需要等目标群第一次 @Bot 消息到达后才会被发现。添加权限后请重新发布应用版本，并在渠道管理中点击「重新验证」。

在【用户身份权限】中开启：
- contact:user.base:readonly（获取用户基本信息）
点击【确认开通权限】

6. 发布应用

Lark 开放平台 → 版本管理与发布 → 设置应用可见范围并发布应用

Agent配置

在系统管理配置：

登录系统，进入「系统管理」→「Agent 管理」→「渠道管理」
点击【新建渠道】，选择【Lark】类型
填写配置信息：
- 渠道名称：自定义名称（如：Lark机器人）
- APP ID、APP Secret
点击【保存】
启用渠道（确保【启用】开关打开）

注意：

配置信息会加密存储在数据库中，安全性更高
应用启动时会自动连接所有已启用的Lark渠道（通过 WebSocket 长连接）
修改配置后无需重启服务，立即生效

使用流程

用户绑定流程

用户登录系统
点击左下角用户头像，打开菜单
选择【渠道绑定】，在【Lark】下找到要绑定的渠道实例，点击【绑定】按钮
跳转到 Lark 授权页面
用户确认授权
自动跳转回系统，显示“绑定成功”页面
关闭授权窗口，刷新原页面，菜单中显示“已绑定”状态

用户解绑流程

点击左下角用户头像，打开菜单
选择【渠道绑定】，在【Lark】下找到已绑定的渠道实例，点击【解绑】按钮
确认解绑操作
解绑成功，菜单中显示“未绑定”状态

使用手册

自定义命令

Lark机器人支持以下命令（所有命令以 / 开头）：

命令	说明	示例
/new	开启新会话，清除当前会话历史	发送 /new
/agent <名称> <消息>	给指定名称的 Agent 发消息	/agent rhea 你好
/agent <消息>	给系统默认 Agent 发消息	/agent 你好

说明：

不以 / 开头的消息直接发送给系统默认 Agent
Agent 名称必须是用户有权限访问的 Agent
命令参数大小写敏感

群聊消息分发

群聊消息分发可以让同一个 Lark Bot 按规则把不同问题交给不同的 Agent 或 Team。一个「群聊空间」对应当前 Lark tenant，配置对该 tenant 内使用此 Bot 的群聊生效。只有已绑定 Agentic Engine 账号、并在群里明确 @Bot 的成员才能发起任务。

管理员配置

确认渠道已启用，应用已发布，并已订阅 im.message.receive_v1 和 card.action.trigger。建议增加 tenant:tenant:readonly，这样系统在验证渠道时即可识别 tenant；未增加时，需要先在目标群中 @Bot 发送一条消息，系统才会发现该群聊空间。
进入「系统管理 → Agent 管理 → 渠道管理」，在对应 Lark 渠道上打开「消息分发」。如果存在多个群聊空间，先选择要配置的空间。
选择默认使用的 Agent/Team。启用群聊分发前必须配置默认项；普通消息没有命中其他规则时会交给它处理。
按需添加最多 19 条规则。每条规则选择一个 Agent/Team，填写必填的「调用指令」，还可以填写最多 10 个关键词，然后打开该规则的启用开关。
保存后在群里发送 @Bot /help 做验收，确认清单中只出现当前用户可使用、且当前可运行的 Agent/Team。

配置项	规则
默认 Agent/Team	必须配置后才能启用；未指定调用指令、且未命中关键词时使用。
调用指令	必填，1～32 个字符；可使用字母、数字、`-` 和 `_`，不能使用系统保留命令。大小写以及全角、半角差异不视为不同指令。
关键词	可不填；每条规则最多 10 个，每个 2～32 个字符。多个关键词同时命中时优先使用更长的关键词；同长度规则无法唯一判断时回到默认 Agent/Team。
可选范围	可选择已启用且可运行的系统/企业 Agent，以及当前企业的 Team；个人 Agent 不会出现在群聊分发候选中。

群聊中的使用方式

用途	示例	说明
查看可用能力	`@Bot /help` `@Bot 能力清单`	列出默认项、调用指令和关键词；无权限或当前不可运行的能力不会展示。
指定 Agent/Team	`@Bot /analysis 分析本周数据`	`analysis` 为管理员配置的调用指令。也可以发送 `@Bot @analysis 分析本周数据`。
按关键词分发	`@Bot 帮我检查埋点方案`	正文命中某条规则的关键词时，交给对应 Agent/Team；未命中时使用默认项。
取消任务	`@Bot /cancel`	必须整条消息精确发送。任务已输出的正文会保留，并另外收到一条取消确认。
兼容旧写法	`@Bot /agent analysis 分析本周数据`	仍可使用，但新文档推荐直接使用 `/analysis`。

命令边界：群聊分发不支持 /new；私聊仍支持 /new、/agent 和 /cancel。群聊中的普通新任务必须先 @Bot；只有已有任务正在等待回答时，才可以按 Bot 提示在原 thread 或交互卡片中继续回复。

公开上下文与个人数据：系统只使用近期明确 @Bot 并实际进入处理的公开群聊轮次作为参考；未 @Bot 的普通群消息、其他群、私聊和个人记忆不会混入。历史内容只作为不可信参考，当前这条消息才是本轮指令。

故障排查

1. 回调 URL 错误

错误提示：重定向 URL 有误，请联系应用管理员。

解决方案：

检查 Lark 开放平台配置的回调 URL 是否正确
确保协议、域名、端口、路径完全匹配
本地开发注意端口号（如 3000 vs 8686）
如果使用了 NEXT_PUBLIC_BASE_PATH，回调 URL 需要包含该路径

2. 飞书渠道未配置

错误提示：Lark 渠道未配置或未启用

解决方案：

进入「系统管理」→「Agent 管理」→「渠道管理」检查 Lark 渠道是否存在
确认渠道的【启用】开关已打开
检查 App ID 和 App Secret 是否正确填写
确认应用类型为企业自建应用

3. App Access Token 无效

错误提示: The app access token passed is invalid

解决方案:

检查渠道管理中的 App ID 和 App Secret 是否正确
确认应用类型（企业自建应用）
检查应用是否已启用

4. 权限不足

错误提示: 权限不足或权限校验失败

解决方案:

在 Lark 开放平台申请必要的权限
等待管理员审批权限
确认权限已生效

5. 绑定失败

错误提示：该 Lark 账号已被其他用户绑定

解决方案：

一个 Lark 账号只能绑定一个系统用户
如需更换绑定，先在原账号解绑

前置条件​

1. Lark开放平台配置​

2. 配置机器人​

3. 配置重定向URL​

4. 事件与回调​

5. 应用权限配置​

6. 发布应用​

Agent配置​

使用流程​

用户绑定流程​

用户解绑流程​

使用手册​

自定义命令​

群聊消息分发​

管理员配置​

群聊中的使用方式​

故障排查​

1. 回调 URL 错误​

解决方案：​

2. 飞书渠道未配置​

解决方案：​

3. App Access Token 无效​

解决方案:​

4. 权限不足​

解决方案:​

5. 绑定失败​

解决方案：​

前置条件

1. Lark开放平台配置

2. 配置机器人

3. 配置重定向URL

4. 事件与回调

5. 应用权限配置

6. 发布应用

Agent配置

使用流程

用户绑定流程

用户解绑流程

使用手册

自定义命令

群聊消息分发

管理员配置

群聊中的使用方式

故障排查

1. 回调 URL 错误

解决方案：

2. 飞书渠道未配置

解决方案：

3. App Access Token 无效

解决方案:

4. 权限不足

解决方案:

5. 绑定失败

解决方案：