接入飞书机器人

Buda 原生支持通过 WebSocket 长连接接入飞书机器人，无需配置公网 Webhook URL 或内网穿透，只需提供 App ID 和 App Secret 即可建立实时 AI 对话。

步骤 1：创建飞书应用

1.1 进入飞书开发者平台

访问 飞书开放平台 并登录。

Lark（国际版）租户请访问 https://open.larksuite.com/app，并在配置中设置 domain: "lark"。

1.2 创建企业自建应用

1. 点击 创建企业自建应用
2. 填写应用名称、描述和图标
3. 点击 创建

1.3 记录凭证

在左侧菜单 凭证与基础信息 中记录：

App ID：      cli_xxxxxxxxxxxx
App Secret：  xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

App Secret 默认隐藏，点击"查看"显示。请妥善保管。

1.4 配置权限

在 权限管理 → 权限配置 中，点击 批量导入权限，粘贴以下内容：

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "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",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "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": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

1.5 首次发布应用

必须先发布，才能启用事件订阅。

1. 左侧菜单 → 版本管理与发布 → 创建版本
2. 版本号填 1.0.0，点击 保存 → 申请上线
3. 等待审批通过（企业自建应用通常自动通过）

步骤 2：在 Buda 中配置通道

打开 Buda 的 Channel 界面，选择飞书，填入 App ID 和 App Secret 后保存。

Buda 会立即在后台通过 WebSocket 与飞书服务器建立长连接。

⚠️ 必须先完成此步骤，飞书才能检测到长连接，否则下一步的事件配置无法保存。

步骤 3：启用事件订阅

1. 左侧菜单 → 事件和回调 → 事件配置
2. 打开 使用长连接接收事件 开关
3. 点击 添加事件，添加 im.message.receive_v1
4. 点击 保存

⚠️ 如果无法启用长连接，说明应用尚未发布，请先完成步骤 1.5。

步骤 4：发布新版本

添加事件后，必须发布新版本才能生效：

1. 版本管理与发布 → 创建版本，版本号自增（如 1.0.1）
2. 点击 保存 → 申请上线

步骤 5：测试

1. 打开飞书客户端，搜索你的机器人名称
2. 发送一条消息，例如：你好
3. Buda回复后，即可正常对话 🎉

常见问题

机器人不响应

长连接无法启用

应用未发布。完成步骤 1.5 并等待 1-2 分钟后重试。

App Secret 泄露

1. 在飞书开放平台重置 App Secret
2. 更新 Buda 配置中的 App Secret

支持的消息类型

接收

• ✅ 文本、富文本
• ✅ 图片、文件、音频、视频
• ✅ 表情包

发送

• ✅ 文本、图片、文件、音频、视频
• ✅ 交互式卡片（流式输出）

配置参考