NcatBot 文档

外观

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. 创建应用

  1. 访问 飞书开放平台 并登录
  2. 点击 创建企业自建应用
  3. 填写应用名称和描述，创建完成后进入应用详情

2. 获取凭据

在 凭证与基础信息 页获取：

凭据说明
App ID应用唯一标识，填入 app_id
App Secret应用密钥，填入 app_secret

3. 配置事件订阅

在 事件与回调 → 事件配置 中：

  1. 选择 使用长连接接收事件（WebSocket 模式，无需公网 IP）
  2. 添加以下事件：
    • 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_idstring""必填 — 飞书应用 App ID
app_secretstring""必填 — 飞书应用 App Secret
verification_tokenstring""事件验证 Token（Webhook 模式使用）
encrypt_keystring""事件加密 Key（Webhook 模式使用）

连接方式

飞书适配器使用 lark-oapi SDK 的 WebSocket 长连接 接收事件。

工作流程

飞书服务器 ──WebSocket──→ lark-oapi SDK (后台线程)
                              │
                          事件回调
                              │
                     run_coroutine_threadsafe
                              │
                     NcatBot 主事件循环 → Dispatcher → 插件 Handler

SDK 的 ws.Client.start() 是阻塞调用，在独立线程中运行。事件回调通过 run_coroutine_threadsafe 安全调度到主事件循环。

支持的事件类型

SDK 事件NcatBot 事件说明
P2ImMessageReceiveV1LarkGroupMessageEvent / LarkPrivateMessageEvent群消息 / 私聊消息
P2ImMessageMessageReadV1LarkMessageReadEvent消息已读通知
P2ImMessageRecalledV1LarkMessageRecalledEvent消息撤回通知

消息收发

接收消息

使用 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

延伸阅读

版权归属：GEYUANwuqi

许可证：署名 4.0 国际 (CC-BY-4.0)

© 2025-2026 NcatBot