02-配置 · 03 飞书深度配置

预计阅读：12 分钟适用版本：公开稳定包 OpenClaw 2026.5.2；作者端已验证 openclaw-lark 2026.5.7 · 最后审核：2026-05-09 本章回答：openclaw-lark 还是官方 feishu？凭什么选？怎么切？配置细节坑在哪？

两个插件的来历

OpenClaw 生态里有两个飞书通道插件共存，初看会让人迷糊：

插件	来源	维护方	默认安装
`feishu`	官方 bundled	OpenClaw 官方	是（装 OpenClaw 即带）
`openclaw-lark`	社区 / 第三方	独立开发	否，需要手动装

为什么有两个？

早期 OpenClaw 的 feishu 插件功能有限（主要支持 im 消息 + 基础卡片）。社区用户需要更多能力（多维表格、任务、日历、云文档、全套 bot 管理工具），于是有人开了 openclaw-lark 这个更全的实现。

后续官方也在扩展 feishu，但进度上 openclaw-lark 长期领先。

功能对比（作者 2026-04 视角）

⚠️ OpenClaw 和 openclaw-lark 都在快速迭代，下表是 2026-04-27 的观察，当前公开稳定包仍以 openclaw-lark 2026.4.8 为交付基线；作者端已验证 openclaw-lark 2026.5.7。具体以两者当前版本的 README 为准。

能力	`feishu`（官方）	`openclaw-lark`（社区）
im 消息收发	✅	✅
卡片（基础）	✅	✅
CardKit 2.0 完整支持	⚠️ 部分	✅
多维表格 CRUD	⚠️ 基础	✅ 字段 / 视图 / 记录全套
日历（读 + 写 + 参会人）	❌	✅
飞书任务	❌	✅
云文档（创建 / 读 / 写 / 评论）	⚠️ 读 only	✅ CRUD 全套
Wiki 搜索	❌	✅
OAuth 批量授权	❌	✅
Footer metrics（model/cache/context）	⚠️ 多 agent 场景缺失	✅ 有 hotfix 补丁

tl;dr：重度用飞书 → openclaw-lark 明显更顺；只发私聊消息 → feishu 也够。

作者的选择与推荐

作者目前用：openclaw-lark.enabled = true，feishu.enabled = false。

两插件软开关的正确配置

即使只用一个，把两个都在 allow 白名单里留着，方便切换。只通过 enabled 做开关：

{
  "plugins": {
    "allow": [
      "memory-lancedb-pro",
      "lossless-claw",
      "openclaw-lark",
      "feishu"
    ],
    "entries": {
      "openclaw-lark": { "enabled": true },
      "feishu": { "enabled": false }
    }
  }
}

好处：

切换时只改两个 enabled 布尔值，不动 allow 白名单
openclaw 升级时，如果一个插件临时挂了，可以快速切到另一个
hotfix 脚本里的 bundled Feishu disable guard 就是靠这个配合工作

从 feishu 切到 openclaw-lark

场景：你用 feishu 跑了一段时间，现在要换 openclaw-lark。

步骤

1. 装 openclaw-lark

# 本地源码（推荐，开发时）
openclaw plugins install ~/.openclaw/extensions/openclaw-lark --link
# 或 npm / clawhub / 市场
openclaw plugins install openclaw-lark

⚠️ 子命令是 plugins（复数），不是 plugin。--link 走 symlink，改代码立即生效；不加则拷贝到内部缓存。

2. 改 plugins 配置

改 ~/.openclaw/openclaw.json：

"entries": {
  "feishu": { "enabled": true },
  "feishu": { "enabled": false },
  "openclaw-lark": { "enabled": true }
}

3. 在每个 agent 的 `tools.alsoAllow` 里补齐 feishu_* 工具

⚠️ tools.alsoAllow 是每个 agent 独立配的，位置在 agents.list[].tools.alsoAllow，不是根级 tools。

openclaw-lark 提供的工具都用 feishu_* 前缀命名，和 feishu 用的前缀一致，工具名不用改。

但如果原来只允许基础几个（比如 feishu_im_user_message），换到 openclaw-lark 后按需补齐：

{
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "alsoAllow": [
            "feishu_im_user_message",
            "feishu_bitable_app_table_record",
            "feishu_calendar_event",
            "feishu_task_task",
            "feishu_search_doc_wiki",
            "feishu_fetch_doc",
            "feishu_create_doc",
            "feishu_update_doc"
          ]
        }
      }
    ]
  }
}

作者 main agent 实际配了 35 个 feishu_* 工具（im / bitable / calendar / chat / docs / drive / oauth / search / sheet / task / wiki 全类），按需挑选，不要一次全开。

4. 跑 CLI hotfix + openclaw-lark patch（⚠️）

node ~/.openclaw/scripts/apply-openclaw-cli-hotfixes.mjs

# 如果你使用 openclaw-lark，并且安装包里带了 patch 链：
bash ~/.openclaw/scripts/apply-openclaw-lark-patches.sh
bash ~/.openclaw/scripts/verify-openclaw-lark-patches.sh

apply-openclaw-cli-hotfixes.mjs 负责 OpenClaw CLI 侧的本地兼容修复；apply-openclaw-lark-patches.sh / verify-openclaw-lark-patches.sh 负责 openclaw-lark 插件侧 patch。两条链不要混在一起理解。

当前公开稳定包基线仍是 openclaw-lark 2026.4.8；作者端已验证 2026.5.7。升级插件后必须重新执行 apply/verify，且不要手工跳过版本校验。

5. 重启 + 等 OK + 冒烟

openclaw gateway restart
until bash ~/.openclaw/scripts/check-feishu-gateway-health.sh --summary 2>/dev/null | grep -q "^OK:"; do
  sleep 2
done

# 发一条飞书消息试

切换时会丢什么？

不会丢：

所有记忆（L0~L4 都独立于插件）
飞书应用本身（App ID / Secret / event 订阅都不动）
session 历史（storage 是 OpenClaw 管的，不是插件管的）

可能需要重配：

如果 openclaw-lark 有自己的配置节（entries.openclaw-lark.config），要按它的 README 填
footer metrics 要靠 openclaw-lark patch 链，见下节

这是 openclaw-lark 相比官方 feishu 的关键优势。

问题（官方 feishu 早期版本）：多 agent 场景下，main 的飞书卡片 footer 正常显示 model/cache/context 三项，但子 agent（planner / minsu 等）的 footer 只有”耗时”一行。

根因：streaming-card-controller.js 查 sessions.json 时用了固定 session 路径，没按当前 sessionKey 的 agent id 切换读取路径。

修复（当前公开稳定包基线 openclaw-lark 2026.4.8；作者端已验证 2026.5.7）：

bash ~/.openclaw/scripts/apply-openclaw-lark-patches.sh
bash ~/.openclaw/scripts/verify-openclaw-lark-patches.sh

这条 patch 链会修复多 agent footer metrics，并验证 streaming-card-controller.js 等关键文件是否仍完整。作者侧升级脚本和买家侧安装/更新脚本都会在检测到这些脚本存在时自动重跑 apply/verify。

飞书应用端的深度配置

除了 OpenClaw 侧，飞书开放平台这边也有些关键但容易漏的配置。

1. 事件订阅完整清单

只订 im.message.receive_v1 够入门，但以下也建议订：

事件	用途
`im.message.receive_v1`	接收消息（必选）
`im.message.reaction.created_v1`	消息表情反应（用户点”👍“等）
`im.chat.member.bot.added_v1`	bot 被拉进群聊
`im.chat.member.user.deleted_v1`	用户退群（视场景）
`application.bot.menu_v6`	bot 菜单点击（如果你配了菜单）
`card.action.trigger`	卡片按钮交互（CardKit 2.0 重要）

2. 权限范围（scopes）

最小集：

im:message / im:message:send_as_bot
im:message.group_at_msg

扩展（如果用 openclaw-lark 的全套能力）：

im:chat / im:chat:readonly
bitable:*
calendar:*
contact:user.base:readonly
docs:doc
wiki:wiki
task:task

一开始不要全开。先开最小集跑通，后续按需一个个加。开多了审批会被打回。

3. 回调 URL 的签名模式选择

飞书后台「事件订阅」允许三种回调模式：

模式	说明	推荐
明文	没有 encrypt key	本地测试用
加密（encryptKey）	AES-GCM 加密 payload	生产必选
HTTPS + verificationToken	简单校验	简化模式

作者用加密 + verificationToken 双保险，secrets 独立放 ~/.openclaw/credentials/lark.secrets.json。

4. 消息卡片 v2 vs CardKit 2.0

现在主流是 CardKit 2.0（飞书文档里叫”互动卡片”）。openclaw-lark 默认用它。

注意：

旧版 card schema（v2）在新版飞书客户端渲染可能错位
不同客户端（PC / 移动 / web）对某些组件支持度不一样 —— 重要场景每种都测
column_set 超过 3 列在移动端会挤

详见作者的记忆：“飞书卡片 UX 偏好”（八条硬规则：移动端优先 / 反术语 / 对齐 / 分步 / 状态驱动 / 三档 column_set / 无”未知”分支 / 英文错误必译）。

常见飞书配置踩坑

坑 1：appSecret 改了没重启 gateway

改了 ~/.openclaw/credentials/lark.secrets.json 的 appSecret，但没 restart gateway → 所有飞书调用 401。

修：改 secrets 必 restart + 等 OK。

坑 2：事件订阅 URL 的校验失败

飞书要求第一次配 URL 时校验 challenge。如果 gateway 还没启动或者公网不通，校验会一直失败。

修：

先 curl https://<公网>/health 确认通
再填 URL
如果还是校验失败，看 gateway.err.log 有没有 “challenge” 相关报错

坑 3：多 bot 场景下 open_id 不一致

同一个用户在 main bot 和 planner bot 下 open_id 不同。

修：每个子 agent 的 USER.md（或 allowFrom）填的是该 bot 下的 open_id，不是 main 的。详见 05-排障/00 第 3 节。

坑 4：bot 发消息给群，但 @ 自己没触发

群里 @bot 后 bot 没反应，但私聊正常。

原因：

没订阅 im.message.group_at_msg 事件
groupChat.mentionPatterns 没匹配到
bot 在群里没有发消息权限

修：三项都查一遍。

坑 5：openclaw-lark 和 feishu 同时 enabled

两个插件工具名都是 feishu_* 前缀，同时启用会工具名冲突，调用时走哪个随机。

修：一次只启用一个，hotfix 脚本里的 bundled Feishu disable guard 会帮你守住。

验证清单

配完飞书后验证：

检查项	期望
私聊消息	main 5-10s 内回
群 @bot	bot 在群里回复
卡片按钮	点按钮有反馈（toast + 卡片更新）
多维表格查询	让 agent 读一条表格记录
云文档创建	让 agent 新建一个 doc
日历创建	让 agent 创建一个会议（如果启用）
footer metrics	子 agent 的卡片 footer 也显示 model/cache/context

下一步

04-运维/00-健康检查 —— 飞书健康监控怎么纳入日常
03-多Agent/00-协作拓扑 —— 哪些 agent 要独立 bot
05-排障/00-常见问题 —— 飞书不回复 12 种诊断路径

本章准确性保证 功能对比基于作者 ~/.openclaw/extensions/openclaw-lark 真实安装 + openclaw.json plugins 配置（2026-04-27）。当前公开稳定包基线为 openclaw-lark 2026.4.8，作者端已验证 openclaw-lark 2026.5.7。feishu_* 工具清单来自真实 tools.alsoAllow 列表。footer metrics 修复路径来自 apply-openclaw-lark-patches.sh / verify-openclaw-lark-patches.sh patch 链。

导航：← Skills选择 · 📖 目录 · → 协作拓扑