AI Hub Icon
AIBit 发现开源项目
首页 / 实用开源项目

飞书频道插件 for Clawdbot – 快速且功能丰富

January 29, 2026
类别: 实用开源项目
标签:
Open Source clawdbot Feishu Chatbot Plugin

飞书频道插件 for Clawdbot – 快速且功能丰富

Clawdbot 是一个轻量但强大的聊天机器人框架，它的插件生态系统可以让您将其连接到多种平台。最新的插件之一就是 飞书（Lark）频道插件（@m1heng-clawd/feishu）。它能将 Clawdbot 转换为完整功能的飞书机器人，支持以下功能：

  • 发送和接收私聊及群聊消息
  • 上传和下载图片、PDF、Excel 表格以及其他文件
  • 将回复渲染为纯文本、Markdown 卡片或原始消息
  • 支持媒体丰富的上下文（图片 + 嵌入文本）
  • 通过飞书开放平台管理权限、事件订阅及 DM 配对流程

以下是一份逐步指南，帮助您快速部署此插件，并配有配置选项与常见问题快速参考。

1. Prerequisites

Item Details
Node.js v20+ (npm 或 pnpm)
Clawdbot v0.1.x 及以上
飞书 App 在飞书开放平台自建应用且具备必要权限

请确保您拥有飞书开放平台的管理员权限，能够创建新应用并授予所需权限范围。

2. Install the Plugin

您可以直接通过 Clawdbot 的插件管理器安装此插件，或使用 npm。

A. Clawdbot Plugin Manager

clawdbot plugins install @m1heng-clawd/feishu

该命令将从 npm 拉取最新版本，安装并注册插件。

B. Manual NPM Install

如果上述命令因环境问题失败，下载 tarball 并本地安装：

curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.1.tgz
clawdbot plugins install ./feishu-0.1.1.tgz

3. Create & Configure a Feishu App

  1. 前往飞书开放平台 并创建一个新的 自建应用。
  2. 在 凭证 页面，记录 App ID 与 App Secret。
  3. 启用权限 如下所示：

必填 | Permission | Scope | Description | |------------|-------|-------------| | contact:user.base:readonly | 用户信息 | 获取基础用户信息 | | im:message | 消息 | 发送和接收消息 | | im:message.p2p_msg:readonly | 私聊 | 读取私聊信息 | | im:message.group_at_msg:readonly | @提及 | 接收 @提及 | | im:message:send_as_bot | 发送 | 以机器人身份发送消息 | | im:resource | 媒体 | 上传/下载图片/文件 |

可选（如需扩展访问） | Permission | Scope | Description | |------------|-------|-------------| | im:message.group_msg | 群聊 | 读取所有群聊消息 | | im:message:readonly | 读取 | 获取消息历史 | | im:message:update | 编辑 | 编辑已发送消息 | | im:message:recall | 撤回 | 撤回已发送消息 | | im:message.reactions:read | 表情 | 查看表情 |

  1. 配置事件订阅：
  2. 选择 长连接（推荐）。
  3. 订阅以下事件：
    • im.message.receive_v1 – 必须用于接收消息。
    • im.message.message_read_v1 – 已读回执（可选）。
    • im.chat.member.bot.added_v1 – 机器人被添加到群聊。
    • im.chat.member.bot.deleted_v1 – 机器人被移除群聊。

  4. 确认所有事件权限已获飞书审核批准。

  5. 发布应用 – 至少发布到 测试 领域，以便您将机器人添加到聊天。

4. Configure the Plugin in Clawdbot

打开您的 Clawdbot 配置文件（通常是 clawdbot.yml 或等效文件），并添加：

channels:
  feishu:
    enabled: true
    appId: "cli_xxxxx"
    appSecret: "your_app_secret"
    domain: "feishu"          # use "lark" for the international domain
    connectionMode: "websocket"  # "websocket" or "webhook"
    dmPolicy: "pairing"         # "pairing", "open", or "allowlist"
    groupPolicy: "allowlist"    # "open", "allowlist", or "disabled"
    requireMention: true
    mediaMaxMb: 30
    renderMode: "auto"          # "auto", "raw", or "card"

提示 – dmPolicy pairing 流程需要用户批准直接消息。若想即时 DM 访问，使用 open。

5. Key Features & How They Work

Feature What it Does Configuration
WebSocket 与 Webhook WebSocket 提供低延迟、实时事件；Webhook 推送式但更易设置 connectionMode
DM 与群聊策略 控制谁能与机器人聊天 dmPolicy & groupPolicy
媒体支持 机器人可以查看图片、PDF、Excel 等文件，并可上传/下载 mediaMaxMb
输入指示 使用表情回复提示机器人正在处理 内置 – 无需额外配置
卡片渲染 可选丰富格式响应（语法高亮、表格、链接） renderMode
事件订阅 接收消息事件、已读回执以及机器人生命周期事件 飞书开放平台 → 事件与回调

6. Common Issues & Troubleshooting

Symptom Likely Cause Fix
机器人无法接收消息 事件订阅未设置或连接模式错误。 确认已选择 长连接 并订阅了 im.message.receive_v1。
发送消息 403 缺少 im:message:send_as_bot 权限批准。 在飞书控制台请求批准。
输出未流式 飞书 API 速率限制阻止流式。 使用默认的 完整-再发 方式（默认）。
安装错误：ENOENT npm 生成路径问题（Windows）。 使用 2B 手动安装方式。
机器人未在飞书出现 应用未发布或可见范围问题。 在“测试”发布并将账号加入可见范围。

7. Quick Reference Commands

# 检查插件状态
clawdbot plugins list

# 卸载插件
clawdbot plugins uninstall @m1heng-clawd/feishu

# 重启 Clawdbot 以应用配置更改
clawdbot restart

# 重置聊天历史
/new

8. Extending the Plugin

该插件通过 clawdbot.plugin 暴露了简易的 TypeScript API。要进行高级使用，可 fork 仓库，添加自定义消息处理器，或集成其他 Feishu SDK 功能。欢迎通过拉取请求贡献！

9. Summary

Clawdbot 的飞书频道插件将强大的 AI 能力与飞书协作生态融合在一起。拥有简洁的安装流程、完善的配置选项以及丰富的媒体处理，您可快速部署一款贴合飞书的聊天机器人。无论是构建团队助手、学习助手，还是实验项目，插件均为搭建智能对话提供坚实基础。

祝编码愉快——愿您的机器人永不因消息接收而崩溃！

原创文章: 查看原文

分享本文