飞书 / Lark

本页按照真实接入顺序，带你把飞书（中国大陆）或 Lark（国际版）机器人接入 Baize：先在平台创建应用并取得凭据，再安装渠道，最后在 Web Console 完成配置。

预计配置时间：10–15 分钟。

前提条件

• 拥有飞书或 Lark 开发者平台权限的账号。
• 已安装并运行的 Baize 实例。
• 如果使用 Webhook，需要一个平台可以访问的 HTTPS 域名。

第一步：打开对应的开发者平台

• 飞书（中国大陆）：open.feishu.cn
• Lark（国际版）：open.larksuite.com

第二步：创建企业自建应用

1. 登录开发者平台，进入应用列表。
2. 点击“创建企业自建应用”。
3. 填写应用名称和描述，例如 Baize。
4. 完成创建，进入应用详情。

第三步：添加机器人能力

在应用详情中找到“应用能力”或“添加应用能力”，添加 机器人 / Bot 能力。只有启用 Bot 后，应用才能接收和发送消息。

第四步：取得 App ID 和 App Secret

打开“凭证与基本信息”，复制并妥善保存：

• App ID：应用标识。
• App Secret：应用密钥，只在受信任的配置环境中使用。

不要把 App Secret 提交到代码仓库或公开截图中。

第五步：配置消息权限

进入“权限管理”，为机器人添加消息和基础用户信息权限。至少包括：

• im:message：发送消息
• im:message:send_as_bot：以机器人身份发送消息
• im:message.p2p_msg:readonly：读取私信
• im:message.group_at_msg:readonly：读取群组 @ 消息
• im:chat.members:bot_access：访问机器人所在群组
• im:resource：上传和下载文件、图片
• contact:user.base:readonly：读取基本用户信息

如果开发者平台支持 JSON 批量导入，可以使用平台提供的权限导入功能，再逐项确认权限范围。

第六步：取得 Verification Token 和 Encrypt Key

如果使用 Webhook 模式：

1. 打开“事件与回调”。
2. 进入“加密策略”。
3. 复制 Verification Token。
4. 建议同时复制 Encrypt Key，用于回调消息加密。

使用 WebSocket 长连接时，通常不需要公网回调地址；但仍建议保留这些值，后续切换 Webhook 时可以直接使用。

第七步：安装 Baize 渠道

确认平台侧应用和凭据准备完成后，再安装渠道组件：

baize add feishu

国际版 Lark 使用：

baize add lark

安装完成后，渠道会出现在 Baize 的渠道目录中，但此时还没有完成运行配置。

第八步：在 Web Console 配置渠道

现在打开 Web Console → 渠道与集成，找到已安装的飞书 / Lark 渠道，填写：

• App ID
• App Secret
• 连接模式：WebSocket 长连接或 Webhook
• Verification Token（Webhook 模式）
• Encrypt Key（可选，Webhook 模式）

推荐首次接入使用 WebSocket 长连接，不需要暴露公网回调地址。保存后先确认状态为“已配置”，再点击“启动”；状态进入“运行中”后再进行平台侧验证。

第九步：配置 Webhook 事件（仅 Webhook 模式）

如果选择 Webhook，回到飞书 / Lark 开发者平台：

1. 打开“事件与回调”。
2. 选择“将事件发送到开发者服务器”。
3. 将 Web Console 显示的回调 URL 粘贴到平台。
4. 填写并校验 Verification Token 与 Encrypt Key。
5. 订阅 im.message.receive_v1 等消息事件并保存。

第十步：发布应用并开始聊天

1. 进入“版本管理与发布”。
2. 创建版本，填写版本号和发布说明。
3. 保存并发布，按组织要求完成管理员审批。
4. 在飞书 / Lark 客户端搜索机器人并发送私信。
5. 群聊中先添加机器人，再 @ 提及它。

收到回复后，说明平台应用、渠道、通信总线和 Agent 运行时已经连通。

飞书与 Lark 的区别

同一套 Baize 渠道同时支持两个平台，主要区别是开发者平台地址和平台 API 域名；组件会自动处理对应的 API 端点，权限名称保持一致。

常见问题

• 凭据验证失败： 检查 App ID、App Secret 和当前选择的平台。
• Webhook 验证失败： 检查 HTTPS、回调 URL、Verification Token 和 Encrypt Key。
• 群聊没有回复： 确认机器人已加入群聊，并且消息中 @ 提及机器人。
• 应用没有收到消息： 确认权限已发布、事件已订阅、应用版本已发布并通过审批。
• 安装后没有运行： 在 Web Console 确认渠道状态，并检查运行日志。