Lark 飞书适配器
约 987 字大约 3 分钟
2026-03-28
飞书 (Lark) 平台适配器完整指南 — 企业应用创建、WebSocket 长连接、群聊/私聊消息收发。
Quick Reference
| 属性 | 值 |
|---|---|
| 适配器名称 | lark |
| 平台标识 | lark |
| 协议 | lark-oapi SDK (WebSocket 长连接) |
| 类 | LarkAdapter |
| 导入 | from ncatbot.adapter.lark import LarkAdapter |
| 额外依赖 | lark-oapi >= 1.5.3(自动安装) |
# 最小配置
adapters:
- type: lark
platform: lark
enabled: true
config:
app_id: "cli_xxxxxxxxxxxx"
app_secret: "xxxxxxxxxxxxxxxxxxxxxxxx"创建飞书企业应用
飞书适配器通过企业自建应用接入。
1. 创建应用
- 访问 飞书开放平台 并登录
- 点击 创建企业自建应用
- 填写应用名称和描述,创建完成后进入应用详情
2. 获取凭据
在 凭证与基础信息 页获取:
| 凭据 | 说明 |
|---|---|
App ID | 应用唯一标识,填入 app_id |
App Secret | 应用密钥,填入 app_secret |
3. 配置事件订阅
在 事件与回调 → 事件配置 中:
- 选择 使用长连接接收事件(WebSocket 模式,无需公网 IP)
- 添加以下事件:
im.message.receive_v1— 接收消息im.message.message_read_v1— 消息已读im.message.recalled_v1— 消息撤回
4. 配置权限
在 权限管理 中申请并开通:
| 权限 | 用途 |
|---|---|
im:message | 获取与发送消息 |
im:message:send_as_bot | 以机器人身份发消息 |
im:resource | 上传/下载文件资源 |
5. 发布应用
在 版本管理与发布 中创建版本并审核发布。发布后 Bot 才能在群聊中使用。
提示
长连接模式(WebSocket)不需要公网 IP 和域名,适合本地开发和内网部署。
配置项详解
adapters:
- type: lark
platform: lark
enabled: true
config:
# 必填 — 从飞书开放平台获取
app_id: "cli_xxxxxxxxxxxx"
app_secret: "xxxxxxxxxxxxxxxxxxxxxxxx"
# 可选 — 必须默认空字符串
verification_token: ""
encrypt_key: ""配置项说明
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
app_id | string | "" | 必填 — 飞书应用 App ID |
app_secret | string | "" | 必填 — 飞书应用 App Secret |
verification_token | string | "" | 事件验证 Token(Webhook 模式使用) |
encrypt_key | string | "" | 事件加密 Key(Webhook 模式使用) |
连接方式
飞书适配器使用 lark-oapi SDK 的 WebSocket 长连接 接收事件。
工作流程
飞书服务器 ──WebSocket──→ lark-oapi SDK (后台线程)
│
事件回调
│
run_coroutine_threadsafe
│
NcatBot 主事件循环 → Dispatcher → 插件 HandlerSDK 的 ws.Client.start() 是阻塞调用,在独立线程中运行。事件回调通过 run_coroutine_threadsafe 安全调度到主事件循环。
支持的事件类型
| SDK 事件 | NcatBot 事件 | 说明 |
|---|---|---|
P2ImMessageReceiveV1 | LarkGroupMessageEvent / LarkPrivateMessageEvent | 群消息 / 私聊消息 |
P2ImMessageMessageReadV1 | LarkMessageReadEvent | 消息已读通知 |
P2ImMessageRecalledV1 | LarkMessageRecalledEvent | 消息撤回通知 |
消息收发
接收消息
使用 registrar.lark 子注册器:
from ncatbot.core import registrar
from ncatbot.event.lark import LarkGroupMessageEvent, LarkPrivateMessageEvent
@registrar.lark.on_group_message()
async def on_group(self, event: LarkGroupMessageEvent):
await event.reply(f"收到群消息: {event.content}")
@registrar.lark.on_private_message()
async def on_private(self, event: LarkPrivateMessageEvent):
await event.reply(f"收到私聊: {event.content}")发送消息
# 文本消息
await self.api.lark.send_text("chat_id_xxx", "Hello!")
# 引用回复
await self.api.lark.reply_text("msg_id_xxx", "收到!")
# MessageArray 自动转换
from ncatbot.types import MessageArray
msg = MessageArray().add_text("消息内容\n").add_at("ou_xxx")
await self.api.lark.send_msg_array("chat_id_xxx", msg, title="标题")
# LarkPostBuilder 富文本
from ncatbot.adapter.lark import LarkPostBuilder
content = (
LarkPostBuilder("公告标题")
.text("重要通知: ", styles=["bold"])
.link("详情链接", "https://example.com")
.newline()
.code_block("print('hello')", language="Python")
.build()
)
await self.api.lark.send_post("chat_id_xxx", content)常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
app_id 和 app_secret 为空 | 配置缺失 | 确认 config.yaml 中已填入正确凭据 |
| 连接后无事件 | 未订阅事件或应用未发布 | 检查事件订阅配置,确认应用已发布上线 |
| Bot 无法在群中回复 | 权限未开通 | 申请 im:message:send_as_bot 权限 |
| 依赖安装失败 | lark-oapi 版本问题 | 手动 pip install lark-oapi>=1.5.3 |
| 消息内容为空 | 消息类型不支持 | 当前仅解析文本消息,图片等类型暂不支持 |
示例
examples/lark/01_hello_world/— 最简飞书 Bot
延伸阅读
- 飞书 Bot API → api/lark/
- 飞书事件类型 → events/lark/
- 飞书数据类型 → types/lark/
- 多平台开发 → multi_platform/
- 适配器接口参考 → reference/adapter/
版权所有
版权归属:GEYUANwuqi
