@xingyuou/feishu-enhanced

v0.2.25

Published

a month ago

Enhanced Clawdbot Feishu/Lark plugin with image receiving support

0High
0Medium
0Low

xiaoxiaoou

clawdbot moltbot feishu lark 飞书 chatbot ai claude image-support

@xingyuou/feishu-enhanced

飞书/Lark 增强版 Moltbot 频道插件，支持图片接收功能。

注意: Moltbot 是 Clawdbot 的官方改名版本。旧的 clawdbot 命令仍可用作兼容性支持。

功能特性

核心功能

WebSocket & Webhook - 两种连接模式，适配不同部署场景
私聊消息 - 支持审批流程的私聊对话
群聊消息 - 基于 @提及的群组交互
消息上下文 - 完整支持引用/回复消息上下文

增强功能（相比上游版本）

图片接收 - 下载并处理用户发送的图片
文件附件 - 接收和处理文件上传
安全加固 - DoS 防护、路径遍历防护、内存泄漏修复
类型安全 - 完整 TypeScript 支持，零 as any 类型断言

附加功能

输入指示器 - 通过表情反应提供视觉反馈
配对流程 - 安全的私聊审批工作流
用户目录 - 查询用户和群组信息
流式响应 - 实时响应流式输出，支持合并优化

前置要求

系统要求

| 要求 | 版本 | |------|------| | Node.js | ≥ 22.x | | 操作系统 | macOS / Linux / Windows (WSL2 推荐) | | 包管理器 | npm / pnpm / bun |

飞书要求

飞书企业版账号（或 Lark 国际版）
具有创建应用权限的管理员账号

安装 Moltbot

Moltbot（原 Clawdbot）是你的个人 AI 助手，支持多平台部署。

注意: 官方 npm 包名仍为 clawdbot，CLI 命令 clawdbot 和 moltbot 均可使用。

方式一：安装脚本（推荐）

macOS / Linux:

curl -fsSL https://molt.bot/install.sh | bash

Windows (PowerShell):

iwr -useb https://molt.bot/install.ps1 | iex

方式二：通过 npm/pnpm

# 使用 npm（官方包名为 clawdbot）
npm install -g clawdbot@latest

# 或使用 pnpm
pnpm add -g clawdbot@latest

运行交互式配置向导

安装完成后，运行配置向导：

clawdbot onboard --install-daemon

向导会引导你完成：

AI 模型配置（Anthropic Claude / OpenAI 等）
工作空间设置
频道配置
Gateway 守护进程安装

提示: clawdbot 是官方 CLI 命令，moltbot 作为别名也可使用。

安装本插件

通过 CLI（推荐）

# 官方文档口径（推荐）
clawdbot plugins install @xingyuou/feishu-enhanced

# 或使用 moltbot 别名
moltbot plugins install @xingyuou/feishu-enhanced

通过 npm

npm install @xingyuou/feishu-enhanced

验证安装

clawdbot plugins list
# 或
moltbot plugins list

应该能看到 feishu-enhanced 插件已安装。

飞书开放平台配置

1. 创建自建应用

访问飞书开放平台（国际版用 Lark Developer）
登录后点击 创建应用 → 选择 企业自建应用
填写应用名称（如 "Moltbot"）和描述
创建完成后进入应用管理页面

2. 获取凭证

进入 凭证与基础信息 页面，复制：

| 凭证 | 说明 | |------|------| | App ID | 格式: cli_xxxxxxxxxxxxxx | | App Secret | 应用密钥，注意保密 |

3. 配置权限

进入 权限管理 → API 权限，开通以下权限：

必需权限（缺一不可）

| 权限标识 | 权限名称 | 用途 | |----------|----------|------| | contact:user.base:readonly | 获取用户基本信息 | 识别发送者 | | im:message | 获取与发送消息 | 收发消息 | | im:message.p2p_msg:readonly | 读取私聊消息 | 接收私聊 | | im:message.group_at_msg:readonly | 读取群聊 @消息 | 群聊 @提及 | | im:message:send_as_bot | 以机器人身份发送消息 | 发送回复 | | im:resource | 获取与上传资源 | 图片/文件 |

可选权限（增强功能）

| 权限标识 | 权限名称 | 用途 | |----------|----------|------| | im:message.group_msg | 读取群聊消息 | 无需 @也能响应 | | im:message:readonly | 获取消息历史 | 引用消息内容 | | im:message:update | 更新消息 | 编辑已发消息 | | im:message.reactions:read | 获取消息表情回复 | 反应功能 |

4. 启用机器人能力

进入 添加应用能力 页面
开启 机器人 能力
配置机器人名称和头像

5. 配置事件订阅

进入 事件与回调 → 事件配置：

选择接收方式: 点击 使用长连接接收事件（推荐）
⚠️ 提示"应用未建立长连接"是正常的，长连接由 Moltbot Gateway 主动发起建立
添加订阅事件，点击 添加事件，搜索并添加：
| 事件类型 | 事件标识 | 说明 | |----------|----------|------| | 接收消息 | im.message.receive_v1 | 必需 | | 机器人进群 | im.chat.member.bot.added_v1 | 可选 | | 机器人出群 | im.chat.member.bot.deleted_v1 | 可选 | | 消息已读 | im.message.message_read_v1 | 可选 |

6. 发布应用

进入 版本管理与发布
创建新版本，填写版本号和更新说明
提交审核（企业内部应用通常自动通过）
审核通过后发布应用

⚠️ 重要: 应用必须发布后才能正常接收消息！

Moltbot 配置

配置文件位置

Moltbot 的配置文件位于：

| 操作系统 | 配置目录 | |----------|----------| | macOS / Linux | ~/.clawdbot/ | | Windows | %USERPROFILE%\.clawdbot\ |

主配置文件：~/.clawdbot/clawdbot.json（支持 JSON5 格式，允许注释和尾逗号）

通过 CLI 配置（推荐）

# 设置 App ID
clawdbot config set channels.feishu-enhanced.appId "cli_你的AppID"

# 设置 App Secret
clawdbot config set channels.feishu-enhanced.appSecret "你的AppSecret"

# 启用飞书频道
clawdbot config set channels.feishu-enhanced.enabled true

# 设置域名（中国版飞书）
clawdbot config set channels.feishu-enhanced.domain "feishu"

# 国际版 Lark
# clawdbot config set channels.feishu-enhanced.domain "lark"

# 设置连接模式（WebSocket 推荐）
clawdbot config set channels.feishu-enhanced.connectionMode "websocket"

通过环境变量配置（可选）

export FEISHU_APP_ID="cli_你的AppID"
export FEISHU_APP_SECRET="你的AppSecret"

直接编辑配置文件

编辑 ~/.clawdbot/clawdbot.json：

{
  "agent": {
    "model": "anthropic/claude-sonnet-4"
  },
  "channels": {
    "feishu-enhanced": {
      "enabled": true,
      "appId": "cli_xxxxxxxxxxxxxxxx",
      "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "domain": "feishu",
      "connectionMode": "websocket",
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["oc_your_group_id"],
      "requireMention": true,
      "historyLimit": 10
    }
  }
}

启动 Gateway

前台启动（查看日志）

clawdbot gateway --port 18789 --verbose

简化启动

clawdbot gateway

⚠️ 注意: 命令是 clawdbot gateway，不是 clawdbot start！

期望的启动日志

成功启动后，应该看到类似以下日志：

[gateway] starting on port 18789
[gateway] loading channels...
[feishu] starting WebSocket connection...
[feishu] bot open_id resolved: ou_xxxxxxxxxxxxxxxx
[feishu] WebSocket client started
[gateway] all channels ready

作为守护进程运行

# 安装为系统服务（launchd/systemd）
clawdbot onboard --install-daemon

# 查看守护进程状态
clawdbot daemon status

# 重启 Gateway
clawdbot gateway restart

# 查看日志
clawdbot logs

测试连接

检查连接状态

clawdbot status

在飞书中测试

打开飞书客户端
搜索你创建的机器人名称
发起私聊，发送 "你好"
应该收到 AI 回复

检查飞书开放平台

刷新飞书开放平台的 事件与回调 页面：

"应用未建立长连接" 提示应该消失
显示长连接已建立

运行健康检查

clawdbot health
clawdbot doctor

配置参考

完整配置示例

channels:
  feishu-enhanced:
    # === 必填项 ===
    enabled: true
    appId: "cli_xxxxxx"
    appSecret: "your_secret"

    # === 域名 ===
    # "feishu" 中国版, "lark" 国际版
    domain: "feishu"

    # === 连接模式 ===
    # "websocket"（推荐）或 "webhook"
    connectionMode: "websocket"
    
    # Webhook 专用配置（仅当 connectionMode: "webhook" 时需要）
    webhookPath: "/feishu/events"
    webhookPort: 3000
    encryptKey: "your_encrypt_key"        # 消息解密密钥
    verificationToken: "your_token"        # 请求验证令牌

    # === 私聊策略 ===
    # "pairing" - 需要审批流程（默认）
    # "open" - 任何人都可以私聊（需配置 allowFrom: ["*"]）
    # "allowlist" - 仅允许指定用户
    dmPolicy: "pairing"
    allowFrom:
      - "user_id_1"
      - "ou_xxxxx"

    # === 群聊策略 ===
    # "allowlist" - 仅允许的群组（默认）
    # "open" - 所有群组
    # "disabled" - 禁用群聊
    groupPolicy: "allowlist"
    groupAllowFrom:
      - "oc_xxxxx"  # 群组/会话 ID
    requireMention: true  # 群内需要 @机器人

    # === 群组专属配置 ===
    groups:
      "oc_specific_group":
        requireMention: false
        systemPrompt: "你是这个团队的专属助手。"
        tools:
          allow: ["read_file", "search"]
          deny: ["execute_command"]

    # === 私聊专属配置 ===
    dms:
      "ou_specific_user":
        enabled: true
        systemPrompt: "为此用户定制的提示词。"

    # === 消息设置 ===
    historyLimit: 20          # 包含的最大历史消息数
    dmHistoryLimit: 50        # 私聊专用历史消息限制
    textChunkLimit: 4000      # 每条消息最大字符数
    chunkMode: "length"       # "length" 或 "newline"

    # === 媒体设置 ===
    mediaMaxMb: 20            # 最大媒体文件大小（MB）

    # === Markdown 渲染 ===
    markdown:
      mode: "native"          # "native"、"escape" 或 "strip"
      tableMode: "ascii"      # "native"、"ascii" 或 "simple"

    # === 流式输出 ===
    blockStreamingCoalesce:
      enabled: true
      minDelayMs: 100
      maxDelayMs: 500

    # === 心跳 ===
    heartbeat:
      visibility: "hidden"    # "visible" 或 "hidden"
      intervalMs: 30000

配置选项速查表

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | enabled | boolean | false | 启用飞书频道 | | appId | string | - | 飞书应用 ID | | appSecret | string | - | 飞书应用密钥 | | domain | "feishu" | "lark" | "feishu" | API 域名 | | connectionMode | "websocket" | "webhook" | "websocket" | 连接模式 | | dmPolicy | "open" | "pairing" | "allowlist" | "pairing" | 私聊访问策略 | | groupPolicy | "open" | "allowlist" | "disabled" | "allowlist" | 群聊访问策略 | | requireMention | boolean | true | 群内是否需要 @机器人 | | mediaMaxMb | number | 20 | 最大媒体大小（MB） |

私聊策略详解

`pairing`（默认）

用户需完成审批流程后才能对话：

用户发送第一条消息
机器人回复配对请求
用户确认配对码
开始对话

批准配对请求：

clawdbot pairing approve feishu-enhanced <配对码>

`open`

任何人都可以直接私聊机器人。需要配置：

clawdbot config set channels.feishu-enhanced.dmPolicy "open"
clawdbot config set channels.feishu-enhanced.allowFrom '["*"]'

`allowlist`

仅允许指定用户私聊：

clawdbot config set channels.feishu-enhanced.dmPolicy "allowlist"
clawdbot config set channels.feishu-enhanced.allowFrom '["ou_user1", "ou_user2"]'

图片接收功能

本增强版插件支持接收用户发送的图片。当用户发送图片时：

图片自动从飞书服务器下载
转换为临时文件
传递给 AI 代理进行处理
响应后自动清理

安全特性

| 特性 | 说明 | |------|------| | 大小限制 | 图片最大 20MB，文件最大 50MB | | 超时保护 | 图片 30 秒，文件 60 秒 | | 路径验证 | 防止目录遍历攻击 | | 内存安全 | 正确的流清理，防止内存泄漏 |

常见问题排查

"应用未建立长连接" 提示不消失

原因: Gateway 没有正确启动或配置有误

解决:

确认凭证正确：clawdbot config get channels.feishu-enhanced
确认 Gateway 正在运行：clawdbot gateway --verbose
检查日志是否有错误

日志显示 "credentials not configured"

解决:

clawdbot config set channels.feishu-enhanced.appId "cli_你的AppID"
clawdbot config set channels.feishu-enhanced.appSecret "你的AppSecret"

连接后立即断开

可能原因:

应用未发布：去飞书开放平台发布应用
权限未通过：检查权限是否都已开通并发布

收不到消息

检查清单:

应用是否已发布？
是否订阅了 im.message.receive_v1 事件？
权限是否都开通了？
私聊策略是否允许？检查 dmPolicy 配置

群聊消息无响应

检查:

是否需要 @机器人？默认 requireMention: true
群组策略：groupPolicy 是否为 disabled？
群聊白名单：如果是 allowlist，群 ID 是否在白名单中？

# 设置群聊策略为开放（需要 @提及）
clawdbot config set channels.feishu-enhanced.groupPolicy "open"
clawdbot config set channels.feishu-enhanced.requireMention true

图片下载失败

确认已授予 im:resource 权限
检查 mediaMaxMb 限制
确保图片 URL 未过期（有效期 24 小时）

与上游版本对比

| 功能 | @m1heng-clawd/feishu | @xingyuou/feishu-enhanced | |------|---------------------|---------------------------| | 文本消息 | ✅ | ✅ | | 发送图片 | ✅ | ✅ | | 接收图片 | ❌ | ✅ | | 接收文件 | ❌ | ✅ | | WebSocket | ✅ | ✅ | | Webhook | ✅ | ✅ | | 安全加固 | - | ✅ | | 类型安全（无 as any） | - | ✅ |

CLI 命令速查

| 命令 | 说明 | |------|------| | clawdbot onboard | 交互式配置向导 | | clawdbot gateway | 启动 Gateway | | clawdbot gateway --verbose | 详细日志启动 | | clawdbot gateway restart | 重启 Gateway | | clawdbot status | 查看状态 | | clawdbot health | 健康检查 | | clawdbot doctor | 运行诊断（自动迁移配置） | | clawdbot config get channels.feishu-enhanced | 查看飞书配置 | | clawdbot config set <key> <value> | 设置配置 | | clawdbot plugins list | 列出已安装插件 | | clawdbot plugins install <name> | 安装插件 | | clawdbot pairing approve feishu-enhanced <code> | 批准配对请求 | | clawdbot logs | 查看日志 |

提示: moltbot 命令作为别名也可使用

获取帮助

官方网站: https://molt.bot
官方文档: https://docs.clawd.bot
飞书频道文档: https://docs.clawd.bot/channels/feishu
Discord 社区: https://discord.gg/clawd
GitHub Issues: https://github.com/moltbot/moltbot/issues

贡献

欢迎提交 Issue 和 PR！请确保：

TypeScript 编译无错误
无 as any 类型断言
测试通过（如有）

许可证

MIT

作者

XINGYUOU - [email protected]

为 Moltbot 社区用心打造。🦞

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@xingyuou/feishu-enhanced

目录

功能特性

核心功能

增强功能（相比上游版本）

附加功能

前置要求

系统要求

飞书要求

安装 Moltbot

方式一：安装脚本（推荐）

方式二：通过 npm/pnpm

运行交互式配置向导

安装本插件

通过 CLI（推荐）

通过 npm

验证安装

飞书开放平台配置

1. 创建自建应用

2. 获取凭证

3. 配置权限

必需权限（缺一不可）

可选权限（增强功能）

4. 启用机器人能力

5. 配置事件订阅

6. 发布应用

Moltbot 配置

配置文件位置

通过 CLI 配置（推荐）

通过环境变量配置（可选）

直接编辑配置文件

启动 Gateway

前台启动（查看日志）

简化启动

期望的启动日志

作为守护进程运行

测试连接

检查连接状态

在飞书中测试

检查飞书开放平台

运行健康检查

配置参考

完整配置示例

配置选项速查表

私聊策略详解

pairing（默认）

open

allowlist

图片接收功能

安全特性

常见问题排查

"应用未建立长连接" 提示不消失

日志显示 "credentials not configured"

连接后立即断开

收不到消息

群聊消息无响应

图片下载失败

与上游版本对比

CLI 命令速查

获取帮助

贡献

许可证

作者

`pairing`（默认）

`open`

`allowlist`