Lark / 飞书
当你希望在 Lark / 飞书工作区的私聊、群聊或团队工作流中访问 Agent 时，可以连接 Lark / 飞书。
前提条件
- 已有 Cloud Agents Agent。
- 有权限在 Lark 或飞书开放平台中创建或管理自定义 app。
- App 已启用 bot 能力。
创建 app
- 打开飞书或 Lark 开放平台控制台。
- 创建自定义 app。
- 启用 bot 能力。
- 复制 App ID 和 App Secret。
- 修改权限或事件订阅后，发布 app 版本。
推荐权限：
| 权限范围 | 用途 |
|---|---|
| 读取发给 bot 的私聊消息 | 接收私聊消息。 |
| 读取群消息或群 mention | 接收群聊消息。 |
| 以 bot 身份发送消息 | 发送 Agent 回复和进度卡片。 |
| 读取 bot 或 chat 元数据 | 让健康检查验证 bot 身份。 |
具体 scope 名称会随飞书和 Lark 控制台略有差异，但通常都是 im:* 相关的 bot 消息权限。
事件订阅
订阅消息事件：
| Event | 用途 |
|---|---|
im.message.receive_v1 | 接收用户消息。 |
Cloud Agents 可根据你的工作区支持情况使用 webhook 投递或长连接投递。多数用户使用 webhook 模式。
为了 webhook 安全，请在开放平台控制台和 Cloud Agents 中都配置 Verification Token 或 Encrypt Key。
连接到 Cloud Agents
- 打开 Settings -> Channels。
- 创建新渠道并选择 Lark / Feishu。
- 选择要接收消息的 Agent。
- 输入标签、App ID、App Secret 和 webhook 安全配置。
- 创建渠道。
- 从渠道详情页复制 inbound URL。
- 把它粘贴到开放平台事件订阅的 Request URL。
- 修改权限或订阅后发布 app 版本。
- 运行渠道测试。
推荐设置
| 设置 | 建议 |
|---|---|
| Mention only | 群聊中建议开启，让 Agent 只在被 mention 时回复。 |
| Bot name | 设置 bot 显示名称，提升群 mention 识别可靠性。 |
| Shared session | 默认关闭，除非群里的所有人都应该共享同一段对话。 |
| Progress mode | 使用 preview，让 Agent 工作时更新进度卡片。 |
验证
打开渠道详情页并运行 Test。健康的渠道会确认 app 凭证有效，并显示最近投递状态。
排查问题
- Webhook 验证失败：确认 Verification Token 或 Encrypt Key，并粘贴 Cloud Agents 当前显示的 inbound URL。
- 消息不到达：确认已订阅
im.message.receive_v1，并且 app 版本已发布。 - 群消息被忽略：设置 bot 显示名称、mention bot，或关闭 mention-only 模式。
- Bot 身份检查失败：确认 App ID、App Secret、区域和已批准的消息权限。