飞书通道配置

配置飞书企业自建应用，接入 OpenVort AI 助手，支持流式卡片输出。

飞书通道配置

飞书推荐使用 WebSocket 长连接模式，无需公网 IP，支持流式卡片输出。

模式说明公网 IP推荐WebSocket 长连接官方 SDK 长连接不需要推荐Event SubscriptionHTTP 事件回调需要备选

配置步骤

1. 创建企业自建应用

  1. 登录 飞书开放平台
  2. 点击「创建企业自建应用」
  3. 填写应用名称和描述

2. 添加机器人能力

  1. 在应用详情页，点击左侧「添加应用能力」
  2. 选择添加「机器人」能力
  3. 添加后左侧菜单会出现「机器人」入口

这一步容易遗漏。如果左侧菜单「应用能力」下没有「机器人」条目，说明还没有添加。

3. 获取应用凭证

在应用详情页 ->「凭证与基础信息」中获取：

  • App ID — 应用唯一标识（以 cli_ 开头）
  • App Secret — 应用密钥

4. 开通 API 权限

飞书应用需要手动开通 API 权限。在「权限管理」页面，使用批量导入功能一键开通所有所需权限：

  1. 点击「权限管理」->「批量导入/导出」
  2. 切换到「导入」标签页
  3. 粘贴以下 JSON 并确认：
{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message:send_as_bot",
      "im:message.p2p_msg:readonly",
      "im:message.group_at_msg:readonly",
      "im:resource",
      "cardkit:card:write",
      "contact:contact.base:readonly",
      "contact:user.base:readonly",
      "contact:user.employee_id:readonly",
      "contact:user.email:readonly",
      "contact:user.phone:readonly",
      "contact:department.base:readonly"
    ]
  }
}

权限说明：

权限用途im:message接收用户消息（事件订阅）im:message:send_as_bot以机器人身份发送消息im:resource下载消息中的图片、语音、文件cardkit:card:write流式卡片的创建和更新contact:contact:readonly_as_app以应用身份读取通讯录contact:user.base:readonly获取用户基本信息contact:user.employee_id:readonly获取用户员工 IDcontact:user.email:readonly获取用户邮箱contact:user.phone:readonly获取用户手机号contact:department.base:readonly获取部门信息

5. 订阅消息事件

这一步决定了用户能否在飞书中给机器人发消息。如果跳过或配置错误，机器人对话窗口将没有消息输入框，用户无法发送消息。

  1. 进入应用详情页，点击左侧「事件与回调」
  2. 在页面顶部选择连接方式：
    • 长连接方式（推荐）：切换为「使用长连接接收事件」，无需填写请求地址
    • HTTP 回调方式：填写请求地址 https://your-domain/api/channels/feishu/event，需要公网可访问
  3. 在「事件配置」中，点击「添加事件」
  4. 搜索并添加 im.message.receive_v1（接收消息 v2.0）

必须订阅 im.message.receive_v1 事件并选择连接方式，否则飞书不会在机器人对话窗口显示消息输入框。

6. 发布应用

飞书应用的所有配置变更（权限、能力、事件订阅）都需要发布新版本后才生效：

  1. 进入「版本管理与发布」
  2. 点击「创建版本」
  3. 填写版本号和更新说明
  4. 设置可用范围（选择哪些员工可以使用此应用）
  5. 提交发布（如需审批，等待管理员审批通过）

每次修改权限、能力或事件订阅后都需要重新发布，否则变更不会生效。

7. 在 OpenVort 中配置

登录 OpenVort Web 后台，进入「通道管理」，点击飞书的「配置」按钮：

字段值必填App ID凭证与基础信息中获取是App Secret凭证与基础信息中获取是Verification Token事件订阅验证 Token否（长连接模式不需要）Encrypt Key事件订阅加密 Key否（长连接模式不需要）API 地址飞书 API 地址否（默认无需修改）

环境变量方式：

OPENVORT_FEISHU_APP_ID=cli_a945d16debb65cd1
OPENVORT_FEISHU_APP_SECRET=your_app_secret

保存后点击「测试连接」，显示「连接成功，已获取 tenant_access_token」即配置完成。

8. 与机器人对话

配置完成并发布应用后，企业成员可以在飞书中找到机器人并发起对话：

  1. 在飞书搜索栏中搜索机器人名称（如「OpenVort」）
  2. 在搜索结果中找到对应的机器人，点击进入对话
  3. 对话窗口底部会显示消息输入框，输入文字即可与 AI 对话

也可以将机器人添加到群聊中使用：

  1. 在群聊设置中点击「机器人」->「添加机器人」
  2. 搜索并添加机器人
  3. 群聊中 @ 机器人即可触发 AI 回复

OpenVort 服务需要以正式模式启动（不带 --dev 参数），飞书 WebSocket 长连接才会建立，机器人才能接收和回复用户消息。

Event Subscription 模式（备选）

如果无法使用 WebSocket 长连接，可以使用 HTTP 事件回调模式。此模式需要公网可访问的地址。

配置步骤

  1. 在飞书开放平台「事件与回调」中配置请求地址：https://your-domain/api/channels/feishu/event
  2. 系统会发送验证请求（url_verification），确认 URL 可达
  3. 获取 Verification Token 和 Encrypt Key
  4. 在 OpenVort 中填入这两个值

特色功能

流式卡片输出

飞书支持流式卡片，AI 回复时用户可以实时看到内容逐字输出。此功能基于飞书 CardKit API，无需额外配置，开通 cardkit:card:write 权限后自动启用。

流式卡片使用飞书 2.0 JSON 结构，支持 Markdown 渲染，效果类似 ChatGPT 的打字机效果。

语音消息

支持接收飞书语音消息，通过 ASR 自动转写为文字后交给 AI 处理。群聊中的语音消息无需 @ 机器人即可触发处理。

通讯录同步

配置完成后，可在 OpenVort 的「通讯录」页面一键同步飞书组织架构和成员信息，包括：

  • 部门层级结构
  • 成员基本信息（姓名、头像、职位）
  • 邮箱和手机号
  • 员工 ID

富文本消息

支持接收和发送多种消息类型：

  • 文本消息
  • 图片消息
  • 富文本消息（Post）
  • Markdown 卡片
  • 语音消息

常见问题

Q: 机器人对话窗口没有消息输入框，无法发消息？

这是最常见的问题，通常是事件订阅未正确配置。按以下顺序排查：

  1. 检查事件订阅：进入飞书开放平台 -> 应用详情 ->「事件与回调」->「事件配置」，确认已添加 im.message.receive_v1 事件
  2. 检查连接方式：确认「事件与回调」页面顶部的连接方式为「使用长连接接收事件」（WebSocket 模式）
  3. 检查发布状态：添加事件订阅后必须重新发布应用版本，否则不会生效
  4. 检查可用范围：确认当前用户在应用的可用范围内（发布时设置的员工范围）

Q: 能收到机器人发的消息，但给机器人发消息没有回复？

  1. 确认 OpenVort 以正式模式启动（不带 --dev 参数），开发模式下不会启动 IM 通道
  2. 查看 OpenVort 后台日志，确认是否有「飞书 WebSocket 长连接已启动」的日志
  3. 如使用 Event Subscription 模式，确认回调地址公网可访问

Q: 测试连接报「获取 tenant_access_token 失败」？

  1. 确认 App ID 和 App Secret 填写正确，注意不要有多余空格
  2. 检查网络连通性（需能访问 open.feishu.cn）
  3. 确认应用未被禁用

Q: 发送消息报「Bot ability is not activated」？

应用没有添加机器人能力，或添加后未发布：

  1. 确认左侧菜单「应用能力」下有「机器人」条目
  2. 如果没有，点击「添加应用能力」添加「机器人」
  3. 添加后必须重新发布应用

Q: 通讯录同步报权限错误？

确认已开通以下权限并发布了新版本：

  • contact:contact:readonly_as_app
  • contact:user.base:readonly
  • contact:department.base:readonly

Q: 群聊中机器人不回复？

  1. 确认已将机器人添加到群聊中
  2. 群聊中需要 @ 机器人才能触发回复
  3. 语音消息是例外，群聊中无需 @ 即可触发

Q: 修改了权限/能力但没生效？

飞书的所有配置变更都需要发布新版本。进入「版本管理与发布」，创建并发布新版本。