Skip to main content
飞书渠道通过 WebSocket 长连接接入，无需公网回调地址，本地或内网部署也能直接使用。目前飞书渠道的实现支持：
  • 交互式卡片确认：智能体调用需要审批的工具时，在飞书里以卡片形式请求确认，点击按钮即可批准或拒绝；
  • 流式回复：智能体的回答在同一条消息内逐步更新，边生成边呈现；
  • 多模态输入：接收用户发来的图片、文件、语音等消息，交给智能体处理；
  • Markdown 富文本：回复支持 Markdown 渲染，超长内容自动分段。
接入分三步：在飞书开放平台创建应用并拿到凭据，启动一个智能体服务承载渠道，最后在管理界面添加飞书渠道。

​
前置条件

飞书渠道依赖 lark-oapi，随 channel 可选依赖安装：
安装依赖

​
创建应用

在飞书开放平台完成机器人的创建与配置，全程约几分钟。
1

创建企业自建应用

进入开发者后台，创建一个”企业自建应用”，填写名称与图标。
2

记录 App ID 与 App Secret

在”凭证与基础信息”页，复制 App ID 与 App Secret，稍后填入渠道配置。App Secret 是机密，请妥善保管。
3

启用机器人能力

在”添加应用能力”中启用”机器人”，机器人才能收发消息。
4

配置事件订阅（长连接）

在”事件与回调”页，订阅方式选择 长连接，无需填写回调地址。订阅”接收消息” im.message.receive_v1 事件；卡片确认还需订阅卡片回传交互 card.action.trigger。
5

申请权限

在”权限管理”中申请消息相关权限：接收消息、以应用身份发送消息（单聊与群聊）。若需要在配置路由时列出机器人所在的群，再申请获取群列表的权限。具体权限项以飞书官方文档为准。
6

发布版本

创建并发布应用版本，使其在企业内可用。之后即可把机器人加入群聊，或直接与它私聊。

​
启动智能体服务

渠道运行在智能体服务之上。用 create_app 启动服务，并用 channels 参数声明允许接入的渠道类型。渠道依赖消息总线（message_bus），单机开发用 InMemoryMessageBus 即可，多进程或多节点部署再换成 RedisMessageBus。
启动承载渠道的智能体服务

​
添加渠道

在智能体服务的管理界面（参见示例前端 examples/web_ui）中，通过可视化表单添加渠道，无需手写配置。
1

新建渠道并选择飞书

在渠道管理页新建一个渠道，平台类型选择”飞书”。
2

填入凭据

把上一步拿到的 App ID 与 App Secret 填入凭据表单。
3

配置路由规则

选择消息交给哪个智能体、会话如何划分。路由规则的含义见会话路由。
4

保存并启用

保存后启用渠道，服务立即建立与飞书的长连接，机器人上线。把它加入群聊或发起私聊即可开始对话。
管理界面的操作对应一组 /channels 接口，需要以编程方式批量创建渠道时可直接调用，字段见本章 API 部分。

​
平台配置

飞书渠道有一个平台专属开关：
群聊里如果希望机器人像成员一样随时参与讨论，把 only_at_reply 关掉；默认开启可以避免机器人在群里过于活跃。

​
验证与排查

  • 在管理界面查看渠道状态，或调用 GET /channels/{id}/status 确认长连接已建立。
  • 若机器人在群里不响应，先确认 only_at_reply 与 @ 行为是否符合预期，再检查消息接收权限是否已申请并随版本发布。
  • 若机器人完全不上线，检查 App ID / App Secret 是否正确、事件订阅是否设为长连接方式。

​
延伸阅读

会话路由

把不同的群路由到不同的智能体。

Discord

用同一套流程接入 Discord。