OpenClaw Lark/Feishu Plugin (9.7 Compat)

OpenClaw Lark/Feishu channel plugin

Install

openclaw plugins install clawhub:@hotwvpyym/openclaw-lark

OpenClaw Lark/Feishu Plugin — Community Compatibility Build（社区兼容版）

⚠️ 非官方版本声明 / NOT the official release

本仓库是社区维护的兼容适配版（Community Compatibility Build），基于飞书官方 openclaw-lark 插件源码（MIT 许可）二次开发，并非飞书（Lark/Feishu）官方出品，也不享受任何官方支持。

官方插件已于 2026.7.16 停止更新，无法在 OpenClaw 2026.9.x 及以上版本正常工作。本版本解决该问题，供社区自用与分享。

English: This is a community-maintained fork of the official Lark/Feishu plugin for OpenClaw (MIT licensed). It is NOT an official release and receives NO official support. The official plugin stopped at 2026.7.16 and is incompatible with OpenClaw 2026.9.x+; this build restores full functionality.

一、这个插件解决什么问题（What this build fixes）

背景

事实	说明
官方插件停更	`larksuite/openclaw-lark` 最后一个官方版本为 2026.7.16，之后官方不再维护
与新版 OpenClaw 不兼容	官方 2026.7.16 版无法安装/正常运行在 OpenClaw 2026.9.x（插件 SDK API 已变化）
官方新线门槛更高	官方替代插件 `@openclaw/feishu` 要求 OpenClaw ≥2026.9.8，无法用于 9.7 及以下版本，且该插件不提供卡片用量页脚（footer metrics）

本版本修复的核心问题（OpenClaw 2026.9.7 生产实测验证）

卡片页脚指标缺失：官方版升级到 9.7 后，卡片页脚只剩「状态 + 耗时」，tokens / cache / context / model 四项全部丢失。
- 根因：OpenClaw 2026.9.7 起会话存储从 sessions.json 改为 per-agent SQLite（<stateDir>/agents/<agentId>/agent/openclaw-agent.sqlite），footer 渲染时的 agent 归属解析抛出 AgentSelectionRequiredError，被外层 catch 静默吞掉，导致页脚渲染中止。
- 修复：在 streaming-card-controller.ts 与 tool-use-config.ts 两处增加 try/catch 兜底回退，指标完整恢复。
日历等分页接口 400 报错：calendar.list、calendar.event.search、event.attendee.list 等接口的 page_size schema 缺少 minimum 约束，传入小于下限的值（如 10）直接 400 field validation failed。
- 修复：全量核对飞书开放平台文档，为 13 个文件 20 处 page_size 补齐 minimum/maximum（如 calendar.list [50,1000]、event.search [1,100]、event.attendee [10,100]、task-v2 全系 [1,100]），并对 calendar 系列增加运行时钳制（双保险）。
性能与稳定性优化：
- 会话快照探测削峰（每轮 720 次 → ≤60 次，SDK 探测一次缓存）；
- 高频日志降噪（info → debug）；
- AbortController 生命周期管理（流式卡片请求可被中断、随网关关闭清理）。

保留的官方全部功能

本版本完整保留官方插件全部功能（40+ 飞书工具族），未删减任何能力：

类别	能力
💬 消息	读取消息（群聊/私聊历史、线程回复）、发送消息、回复消息、搜索消息、下载图片/文件
📄 文档	创建、更新、读取文档
📊 多维表格 Base	管理 Base/数据表/字段/记录（增删改查、批量、高级筛选）、视图
📈 电子表格	创建、编辑、查看表格
📅 日历	管理日历与日程（增删改查、搜索）、参与人管理、忙闲查询
✅ 任务	任务（增删改查、完成）、任务清单、子任务、评论
📁 云盘/维基	云盘文件、知识库空间与节点
🔍 搜索	文档/消息搜索
🎴 交互卡片	实时状态更新（思考/生成/完成）+ 敏感操作确认按钮
🌊 流式输出	卡片内实时流式文本（私聊为流式、群聊为静态，设计如此）
📊 卡片页脚六项	状态、耗时、Token 使用量、缓存命中、上下文占用、模型（全部可独立开关）
🔒 权限策略	私聊/群聊灵活访问控制
⚙️ 群组高级配置	白名单、Skill 绑定、自定义系统提示词

二、兼容版本（Compatibility）

声明：兼容 OpenClaw 2026.8.1 及以上所有版本。

以下版本已实测验证（替换 node_modules/openclaw 软链逐一跑 typecheck，全部 0 错误；9.7 为生产环境实测）：

OpenClaw 版本	类型	验证结果
2026.8.1	官方 tarball	typecheck 0 错误 ✅
2026.8.35	官方 tarball（extended-stable）	typecheck 0 错误 ✅
2026.9.6	官方 tarball	typecheck 0 错误 ✅
2026.9.7	官方 tarball + 生产服务器	typecheck 0 错误 + 生产实测（footer 六项/消息收发/插件加载全过）✅
2026.9.8	官方 tarball	typecheck 0 错误 ✅

架构适配说明：OpenClaw 8.x / 9.6 使用 sessions.json 会话存储，9.7+ 使用 per-agent SQLite —— 插件对两种架构均做了兼容（SQLite 直读不可用时自动回退 SDK 读取），因此 2026.8.1 至最新版均可用。

三、安装与使用（Installation & Usage）

前置要求

Node.js：v22 或更高
OpenClaw：2026.8.1 或更高（openclaw -v 查看）

安装方式

方式 A：本地 tgz 安装（推荐，最可控）

bash

openclaw plugins install npm-pack:/path/to/hotwvpyym-openclaw-lark-2026.9.7.tgz --force --accept-capabilities

方式 B：从 GitHub Release 下载

在 Releases 页面下载 hotwvpyym-openclaw-lark-2026.9.7.tgz，然后按方式 A 安装。

方式 C：ClawHub（发布后可用）

bash

openclaw plugins install @hotwvpyym/openclaw-lark

安装完成后确认：

bash

openclaw plugins list        # 应看到 openclaw-lark，版本 2026.9.7
openclaw gateway restart     # 若安装过程提示 drain 超时，用此命令兜底

启用与配置

bash

# 启用飞书渠道（WebSocket 长连接 + 流式输出）
openclaw config set channels.feishu.enabled true
openclaw config set channels.feishu.websocket true
openclaw config set channels.feishu.streaming true

# 卡片页脚六项指标（默认即可全部打开）
openclaw config set channels.feishu.footer.status true    # 状态
openclaw config set channels.feishu.footer.elapsed true   # 耗时
openclaw config set channels.feishu.footer.tokens true    # Token 使用量
openclaw config set channels.feishu.footer.cache true     # 缓存命中
openclaw config set channels.feishu.footer.context true   # 上下文占用
openclaw config set channels.feishu.footer.model true     # 模型

行为说明

私聊：流式输出（文字在卡片内实时滚动）；
群聊：静态卡片（设计如此，避免刷屏）；
页脚指标：tokens/cache/context/model 在每次回复完成后随卡片展示；
敏感操作（如删除、批量操作）：卡片弹出确认按钮，需人工确认后执行。

四、风险与免责声明（Risk & Disclaimer）

请在使用前完整阅读本节。

非官方声明：本插件是社区适配版，与飞书（Lark/Feishu）官方无关，官方不提供任何支持、不承担任何责任；请勿将本插件相关问题提交给官方渠道。
按现状提供（AS-IS）：本插件按「现状」提供，不提供任何明示或默示担保，包括但不限于适销性、特定用途适用性、不侵权的默示担保。使用产生的任何后果由使用者自行承担。
AI 自动化固有风险：插件对接 OpenClaw AI 自动化能力，存在模型幻觉、不可预测执行、提示词注入等固有风险。授权飞书权限后，OpenClaw 将在授权范围内以你的用户身份执行操作，可能造成敏感数据泄露或未授权操作等高风险后果。
使用建议：强烈建议仅将机器人作为私聊助手使用，不要加入公开群聊或允许陌生人交互，避免权限滥用与数据泄露；生产环境使用前请充分评估。
第三方条款：插件运行时调用飞书开放平台 API，使用即视为同意遵守：
兼容性边界：虽已对 2026.8.1+ 全线做兼容验证，但 OpenClaw 与飞书 API 持续演进，未来版本可能出现新的不兼容；升级 OpenClaw 前请先验证本插件。
授权与许可：本插件基于官方 MIT 源码改造，保留官方版权声明，MIT 许可允许修改与再分发（详见 LICENSE）；请勿以本插件名义冒充官方版本。

五、反馈与更新（Feedback & Updates）

欢迎任何问题反馈！

🐛 Bug 报告：请提交 Issue，附上：OpenClaw 版本（openclaw -v）、插件版本（openclaw plugins list）、复现步骤、相关日志。
💡 功能建议：同样通过 Issue 提出。
🔄 持续更新：本仓库将跟随 OpenClaw 版本演进持续维护；新版本发布后，使用 openclaw plugins install npm-pack:/path/to/<新版.tgz> --force --accept-capabilities 升级即可（同名升级直接覆盖，无需卸载）。

已知限制：暂无已知功能性问题；如发现问题会在本 README 与 CHANGELOG 中同步更新。

六、版本历史（Changelog）

版本	内容
2026.9.7（当前，正式发布版）	发布就绪版本：包名改为 `@hotwvpyym/openclaw-lark`（匹配 ClawHub 发布者 scope），补 `openclaw.build.openclawVersion`/`license` 字段；内容与 9.6.11 一致（日历 page_size 全量修复 + footer 指标 + 性能优化）
2026.9.6.11	日历等 13 文件 20 处 `page_size` 上下限全量补齐（按飞书文档），calendar 系列运行时钳制双保险；修复上一版注入产生的语法问题
2026.9.6.10	AbortController 生命周期管理；`not available` 日志降级 debug
2026.9.6.9	会话快照探测削峰（720→≤60 次/轮）；4 处高频日志降噪
2026.9.6.8	核心修复：卡片页脚 tokens/cache/context/model 恢复（agent 归属解析兜底）
2026.9.6.x 前序	加载/收发/流式适配（对齐官方 9.6 基线）

七、许可证（License）

本适配版在原作基础上修改，见 LICENSE 全文。

致谢（Acknowledgements）

飞书官方 openclaw-lark 插件（MIT）—— 本仓库的源码基底
OpenClaw 社区 —— 测试与反馈