OpenClaw Feishu 配置可能在官方插件加载前就被核心 Schema 拒掉

最新一条 OpenClaw 问题显示：有些 本来符合官方 Feishu 插件文档的配置，会在 Gateway 启动阶段就被判定为非法。

核心矛盾不在于官方插件“不支持”，而在于：OpenClaw Core 会先用自己内置的 Feishu Schema 校验配置，而这个 Schema 据报 缺少官方 @larksuite/openclaw-lark 插件已经支持的若干字段。

结果就是：团队明明照着官方文档配，Gateway 却在插件真正加载之前就先挂掉。

来源：

• Issue： openclaw/openclaw#57173

这个故障通常长什么样

根据报告，问题环境大致是：

• OpenClaw Core：2026.3.28
• 官方 Feishu 插件：@larksuite/openclaw-lark 2026.3.26
• 系统：macOS / Linux

一个典型复现流程是：

1. 安装官方插件
2. 按官方文档加入 Feishu 高级配置
3. 启动 Gateway
4. 直接遇到类似下面的校验错误：

channels.feishu: invalid config: must NOT have additional properties

这说明失败点发生在 Gateway 启动时的 Schema 校验阶段，不是后面的发消息阶段。

哪些字段据报会被拒绝

该 issue 明确点名：以下字段官方插件支持，但内置 Schema 没跟上：

• footer
• replyMode
• threadSession
• dedup
• useStreamingCards
• configWrites
• capabilities
• uat

如果你的 channels.feishu 里一加这些字段，Gateway 就立刻起不来，很可能就是命中这类不兼容。

为什么这不是“小问题”

这不是简单的“文档和实现有点偏差”。

对于把 Feishu 当作主操作面的团队来说，被挡住的恰恰是那些更接近生产可用性的字段：

• replyMode 影响回复是如何流式展示、落卡片还是普通消息
• threadSession 影响会话是否能在线程里隔离干净
• footer 影响状态、耗时等调试信息是否可见
• dedup 一类配置会影响重复投递、噪音控制等体验

也就是说，它不是“高级功能先不能用”这么简单，而是 你真正需要的 Feishu 生产配置，可能直接把 Gateway 启动卡死。

关键判断点：这是 Schema 不一致，不是插件没装好

这条报告最重要的一点是：

即使你关闭内置插件入口，或者通过 plugins.load.paths 加载官方插件，也不一定能绕过这个问题。

原因在于：内置 Schema 校验发生在官方插件接管之前。

所以如果你原本的判断是：

• “我都装了官方插件了，应该按官方插件 Schema 来”
• “我把内置入口关掉了，Core 就不该再管它”

那在这个版本里，这两个判断都未必成立。

怎么确认自己命中的就是这一类问题

如果下面三条同时成立，基本就很像：

1. 你是按 官方 Feishu 插件文档 来配置的
2. 你加了 footer、replyMode、threadSession 这一类字段
3. Gateway 在 启动瞬间 就报 “additional properties” 之类的校验错误

这比“Feishu 不可用”要具体得多，也更能排除其他运行时问题。

谁最容易被这个 Feishu Schema 不兼容问题影响

这类问题尤其会卡住三类人：

• 正在从内置 Feishu 路径迁移到官方插件的团队，因为他们最容易照着官方文档配置，却在启动前就被 Core 拦下。
• 依赖 Feishu 高级投递行为做生产运维的人，因为 replyMode、threadSession、footer 这类字段通常不是“锦上添花”，而是实际可用性的组成部分。
• 把配置改动直接推到共享 Gateway 上的操作者，因为启动时 Schema 拒绝会让整个通道在运行前就被卡死，几乎没有优雅降级空间。

现在能怎么止血

方案 1：先删掉高级字段，只保留内置 Schema 能接受的最小子集

该 issue 给出的临时可用配置类似：

{
  "channels": {
    "feishu": {
      "streaming": true,
      "chunkMode": "newline",
      "typingIndicator": true,
      "replyInThread": "enabled"
    }
  }
}

这不是完整功能集，但能优先帮你把 Gateway 重新拉起来。

方案 2：把“官方文档支持”与“当前 Core 版本可接受”分成两层核验

今后往生产环境推 Feishu 配置前，至少确认两件事：

• 官方插件文档明确写了这个字段
• 你当前的 OpenClaw Core 版本在启动时真的接受这个字段

只满足其中一边，都不够。

方案 3：不要一次性把整块高级配置全贴进去

如果你正在排查启动失败，不要整段高级配置一次性上线。应该逐项增量加入，这样更容易快速定位到底是哪一个字段先触发了校验拒绝。

维护者真正需要修什么

该 issue 给了三个方向：

• 同步内置 Schema，让它跟上官方插件
• 弱化甚至移除内置 Feishu 插件路径，完全依赖官方插件
• 在检测到官方插件时动态加载其 Schema

从一线运维视角看，第一优先级其实很简单：启动时使用的 Schema，不能拒绝官方插件已经正式支持的字段。

常见上线判断问题

什么时候该停止怀疑插件没装好，优先怀疑 Core Schema

如果官方插件已经安装正确，Gateway 又是在启动瞬间报 must NOT have additional properties 这类错误，那更快的判断通常是 Schema 不一致，而不是插件本身没装对。

想先恢复 Feishu 服务，同时保留后续排障证据，最低风险做法是什么

先回退到当前 Core 明确接受的最小 Feishu 配置，把 Gateway 拉起来，再把被拒绝的高级配置块和启动报错完整保存下来，后续再追这个不兼容点。这样既能止损，也不会丢掉关键证据。

哪些团队应该把这次事故固化成发布前检查项

凡是把 Feishu 当成生产控制面的团队，都值得把这类问题从一次性故障升级为固定 preflight 检查。只要你们会频繁改 channels.feishu、切换插件版本，或者同时维护测试与生产 Gateway，就应该在发布前用“目标 core 版本 + 目标插件版本 + 实际配置块”做一次启动前核验。

如果只有一个环境出问题，第一批该对比什么

先看最朴素但最有判别力的几项：OpenClaw core 版本、官方插件版本、部署镜像 tag，以及环境里是否还在加载缓存的旧插件包。遇到这种问题时，“版本漂移”通常比消息层调试更快解释为什么测试环境正常、生产环境却直接起不来。

回退后想重新加回 Feishu 高级字段，应该先测什么

不要把“Gateway 又能启动了”误判成底层兼容问题已经消失。回退后如果要重新加字段，最好按固定顺序逐项恢复并每次重启验证：

1. 先加 footer 这类偏展示字段
2. 再加 replyMode 这类回复行为字段
3. 再加 threadSession 这类会话形态字段
4. 每次重启都保存完整启动报错

这样做的好处是，后续无论你是内部复盘还是继续提 issue，证据都会比“一次性整块贴回去”更清楚。

哪种操作习惯最容易把这次事故伪装成普通发布失败

最常见的坑，是把 Feishu 配置改动、Core 升级、插件升级和部署镜像刷新捆在同一次发布里。四件事一起动时，启动期 schema 拒绝很容易被误看成“这次部署又抽风了”，而不是一次明确的兼容性断裂。能拆就尽量拆。

内部升级/提单时建议顺手记录的信息

如果你准备内部汇报或补充 issue，建议把这几项一起带上：

• OpenClaw Core 版本
• 官方插件版本
• 完整的 channels.feishu 配置块
• 启动时报出的完整校验错误
• 删除高级字段后 Gateway 是否恢复启动

这些信息能帮助团队把“Schema 不兼容”与其他 Feishu 运行时故障快速区分开。

结论

如果你刚按官方文档加完 Feishu 高级配置，Gateway 就直接起不来，先别急着怀疑自己写错。

在 OpenClaw 2026.3.28 上，更快的解释很可能是：Core 内置 Schema 落后于官方插件，导致本来合法的字段在运行前就被拦截了。

哪些场景最容易遇到这种 schema 不兼容

这类问题最常见于 OpenClaw core 已升级，但社区版或官方 Feishu 插件还停留在旧版本的时候，或者测试环境与生产环境实际上跑着不同的插件修订版本。如果错误只出现在其中一个环境，第一优先级就应该怀疑版本漂移，而不是先把整个 Feishu 集成判死刑。

在把锅甩给整个 Feishu 集成之前，先查什么

在你下结论说“Feishu 通道整体坏了”之前，先优先核对下面几件事：

• OpenClaw core 和 Feishu 插件是不是一起升级的
• 当前环境是不是还在加载缓存里的旧插件包，或者旧部署镜像
• 这次升级说明里有没有提到 payload shape 或 schema 变化
• 同一个动作在另一个版本对齐的环境里是否还能正常工作

这些检查通常能更快帮你判断，眼前的问题到底是兼容性不匹配、部署残留，还是更大范围的集成故障。

上生产前，先跑一遍最小 Feishu 预检清单

如果这篇页面本身就在接搜索流量，很多读者其实正处在准备把 Feishu 配置推上生产的前一刻。这时最有价值的不是再看一遍抽象原理，而是一张能直接执行的最小预检清单：

1. 先确认目标 Gateway 上准确的 OpenClaw core 版本
2. 再确认目标环境里准确安装的 @larksuite/openclaw-lark 版本
3. 把这次准备上线的 channels.feishu 配置块，和最后一份确认可启动的配置逐项对比
4. 每次只加回一个高级字段，并在每次修改后单独重启验证
5. 在继续下一步前，先保存完整启动校验报错

这张清单的价值在于，它能把 Feishu 升级后突然坏了，收缩成一次边界清晰的兼容性验证，而不是把生产事故越查越散。

面向搜索入口的结论前置：搜 feishu additional properties 的人最该先怎么判断

如果用户是从 feishu additional properties startup 这类搜索词进来的，页面最好先帮他把判断路径压缩成三步：

• Gateway 还没启动完就失败：优先怀疑启动期 schema 不兼容
• Gateway 能启动，但后面才发不出消息：优先怀疑鉴权、权限或运行时投递问题
• 只有一个环境失败：优先怀疑版本漂移或旧镜像、旧插件缓存残留

这样写的好处是，页面不只是解释一次 issue，而是直接承担搜索入口页该做的分流职责。

恢复服务后，重新加回被拒字段时先怎么测

Gateway 先恢复启动后，不要一次性把整块高级 Feishu 配置重新贴回去。更稳的做法是按顺序逐项加回，这样你才能定位到底是哪一个字段再次触发启动期校验失败。

一个更低风险的顺序是：

1. 先加一个偏可见性字段，比如 footer
2. 重启 Gateway，确认仍能正常启动
3. 再加一个会影响会话行为的字段，比如 replyMode 或 threadSession
4. 再次重启，并记录错误是否回归
5. 最后再补 dedup、capabilities 一类配置

这样做的好处是，你最终得到的是“这个 core 版本到底接受哪些字段”的兼容清单，而不是一句模糊的“Feishu 配置又坏了”。

维护多套 Gateway 的团队，最好顺手固化一个上线前检查单

如果你们同时维护测试、灰度和生产 Gateway，这个问题很值得直接升级成一个最小发布检查单：

• 记录准确的 OpenClaw core 版本
• 记录准确的 @larksuite/openclaw-lark 版本
• 对比各环境的 channels.feishu 配置块差异
• 先在非关键 Gateway 上重启验证一次
• 提前保留上一版最小可启动配置，方便立刻回退

这套动作听起来很基础，但真正碰到 schema 级不兼容时，往往就是这些最朴素的检查最能缩短中断时间。

故障处理中可以顺手补的一张兼容矩阵

如果你想减少下一次重复踩坑，不要只停留在“某个字段把启动搞挂了”。更实用的做法，是顺手给当前生产版本补一张最小兼容矩阵：

字段	主要用途	当前版本启动是否接受	备注
footer	展示执行状态与调试信息	是 / 否	一般最适合先做回测
replyMode	控制回复呈现方式	是 / 否	往往最接近生产必需能力
threadSession	控制线程/会话隔离	是 / 否	Feishu 当主控制面时尤其关键
dedup	控制重复投递与噪音	是 / 否	建议在基础回复稳定后再测
capabilities	暴露插件能力开关	是 / 否	适合在基本消息链路恢复后核验

这张表往往比一次性的报错截图更有用，因为它能直接告诉下一位值班同事：当前 Core 版本到底能安全接受哪些字段。

面向生产 Feishu 发布的常见判断问题

为什么这类故障很容易被误判成“插件没装好”？

因为它坏得太早了，很多人第一反应会以为是插件根本没装对。但在这类问题里，插件本身可能没错，真正先坏掉的是 Core 在启动阶段就把配置形状拒掉了，官方插件还没来得及接管。

也正因为如此，同一个字段在官方文档里明明是合法的，到了某个 Core 版本上却依然能把 Gateway 启动直接打断。

为了尽快恢复服务，删字段前最该保留哪组证据？

如果你准备先删掉高级字段把 Gateway 拉起来，至少先把下面这组证据留住：

• 失败时那份完整的 channels.feishu 配置块
• 启动时报出的完整校验错误
• OpenClaw Core 版本与官方插件版本
• 另一个环境是否接受同一份配置

这组信息通常已经足够你后面继续追兼容性问题，而不用为了“重新证明一次”再把生产环境弄挂。

什么时候该停止把它当成消息投递问题，改查更前面的启动校验？

如果 Gateway 连启动都没完成，就别再把时间花在消息投递行为上了。此时 replyMode、线程回复表现、卡片样式都不是第一问题，第一问题是启动期 schema 校验到底接不接受这份配置。

对值班同事来说，这个切换很关键，因为它决定你后面的动作应该是继续聊消息层细节，还是立刻回到配置形状隔离与版本比对。

面向搜索入口的常见判断问题

为什么官方插件文档明明写了字段可用，Feishu 配置还是启动失败

因为在这类回归里，失败点发生在官方插件真正接管之前。OpenClaw core 会先拿内置 schema 校验 channels.feishu，所以插件文档里合法的字段，仍可能在启动期被先一步拒掉。

服务恢复后，应该先重新测试哪个 Feishu 字段

优先从 footer 这种偏展示字段开始。如果它能过，再测 replyMode，最后再测 threadSession。这样比一次性把所有高级字段全贴回去更容易定位第一处断点。

这更像是 Feishu token 问题，还是 schema 不兼容

如果 Gateway 在启动期就报 must NOT have additional properties，那更像 schema 不兼容，而不是 token 或鉴权问题。token 出错通常发生在启动后连接或发消息阶段，不会这么早就把进程拦住。

怎么一边保住 Feishu 可用性，一边留下足够证据给维护者修

先运行最小可启动配置，把服务恢复起来；然后每次只加回一个高级字段并重启，保存每次完整校验错误。这样既能止损，也能留下清晰复现链路。

面向搜索入口的对比判断：Schema 不兼容和其他 Feishu 故障怎么区分

Feishu 在 OpenClaw 升级窗口里出问题时，最浪费时间的往往不是修，而是先查错层。可以先用这张对比表快速分流：

现象	更可能的原因	第一优先检查
Gateway 还没启动完就失败	启动期 schema 不兼容	先移除 footer、replyMode、threadSession 后重启
Gateway 能启动，但后面发消息失败	token、权限或运行时投递问题	先查 channel 鉴权、机器人 scope、发送日志
/stop 或 /new 被收到了，但当前任务没停	命令中断 / 会话控制链路问题	先确认 Feishu 命令路径是否真的中断当前 run
ACP 已跑完，但历史看起来空白	transcript 投影延迟	先确认磁盘上的 .jsonl transcript 是否存在

这个区分很关键，因为本文说的是 启动期校验失败，不是所有 Feishu 问题都该往一个方向排。

值班同事最需要你补留下来的是什么

如果这个事故已经在生产环境打过一次，不要只在群里留一句“Feishu 升级后有坑”。更有价值的是补一张简短值班备注，至少写清：

• 触发问题的准确 OpenClaw core 版本
• 当时安装的准确 Feishu 插件版本
• 最后一个确认可启动的最小 channels.feishu 配置块
• 哪个字段一加回去就再次触发启动失败
• 失败重启时的完整校验报错

这种简短交接记录，通常比一句模糊的“升级后不稳定”更能减少下一次重复中断。

改 schema 前，先准备最小复现包

在你放宽校验或删除生产 Feishu 字段之前，先打一个能让下一位值班同事复现边界的最小包：

1. 被拒字段清单：复制完整 additional properties key，以及拒绝它们的 plugin 版本。
2. Gateway 启动日志：保留第一次启动失败日志，不要只留删字段后的成功启动结果。
3. 干净配置样本：脱敏 secret，但保留出问题的 Feishu 配置块结构。
4. 官方插件预期：标明字段来自飞书官方文档、旧版 OpenClaw 示例，还是本地 override。
5. 回滚决策：写清楚临时删字段、锁版本，还是先停 Feishu channel 等待 schema 修复。

这样能把模糊的“Feishu plugin 起不来”变成可路由的 schema compatibility 问题，让维护者和运维都更快判断下一步。

如果你是从 troubleshooting 进来，先分清 schema 拒绝和飞书插件失败

GA4 现在把这篇和 setup、agent 排障入口放在同一组里。读者可能还没判断清楚，是飞书本身失败，还是 OpenClaw 在更早阶段就拒掉了配置。

不要先改 token 或重装插件，先拆成三类检查：

1. 进程在插件加载前就失败：按 core schema 兼容性问题处理，保留被拒绝的配置路径、schema 报错和 OpenClaw 版本。
2. 插件已加载但飞书认证失败：把 app id、redirect/callback 设置、权限 scope 证据和 schema 报告分开。
3. 只有某个环境失败：对比完整 config 文件、插件包版本和 runtime channel，让修复指向验证漂移，而不是误判成飞书 API 行为。

这样能避免从 setup 心智进来的高意图读者反复轮换飞书凭证，而真正卡住的是本地 schema validation。

15 分钟热修动作：先恢复 Gateway，再保留 schema 证据

如果这是生产 Feishu channel，不要在启动失败时同时改 token、scope、bot 权限和 schema。先把恢复动作压成 15 分钟闭环：

1. 复制失败配置块：先保存脱敏后的 channels.feishu，尤其是 footer、replyMode、threadSession 这些被拒字段。
2. 最小删字段启动：只删 schema 拒绝的字段，先让 Gateway 启动，不要顺手重配飞书应用。
3. 确认 channel 仍可收发：用一条最小消息验证 Feishu 入站和出站还活着，把它和 schema 热修分开。
4. 锁住变更窗口：在事故记录里写清这是临时 schema 兼容热修，不是最终插件配置结论。
5. 排队上游修复：把 core 版本、plugin 版本和被拒字段一起交给维护者，避免下一次升级又把字段加回来。

这段热修路线能服务那些已经搜到 additional properties 报错、但眼前目标是先恢复 Feishu 入口的读者。先恢复，再把证据留完整，才不会把一次 schema 兼容问题拖成多小时的飞书凭证排障。

升级窗口前，先加这道 Feishu schema 放行门

如果团队准备在维护窗口里升级 OpenClaw 或官方 Feishu 插件，不要等 Gateway 起不来后再查。升级前先加一道小的放行门：

1. 列出当前生产字段：把 channels.feishu 里实际存在的字段列成清单，标出 footer、replyMode、threadSession 这类高风险项。
2. 用目标版本做 dry-run 启动：在不接生产流量的环境里加载同一份脱敏配置，确认 schema 是否先拒绝。
3. 准备最小可启动配置：提前保存一份只保留必需字段的 Feishu 配置块，作为维护窗口里的快速回退点。
4. 把 token/scope 排障延后：只有 Gateway 已经通过 schema 校验后，才继续查飞书凭证、权限和消息投递。
5. 写清上线判定：只有 dry-run 通过、最小回退配置可用、收发消息验证通过，才允许扩大到生产 channel。

这道放行门能把“升级后 Feishu 整体不可用”的风险前移到维护窗口前，也让搜索进来的运维读者知道如何避免下次同类中断。

恢复后，把事故沉淀成可复用的 Feishu 兼容性记录

Gateway 能重新启动后，不要让这次事故只留在一段私聊或临时群消息里。把恢复过程整理成一条后来者能从搜索里找到的兼容性记录：

1. 记录完整被拒字段：把 footer、replyMode、threadSession 或本地私有字段，连同 Core 和 plugin 版本一起列出来。
2. 写清可启动 fallback：保存一份已经验证能启动的最小 Feishu 配置，作为下一位维护者的安全基线。
3. 单独标注凭证状态：说明飞书 token、应用权限和 callback 配置是否没有变，避免后来的人重复轮换凭证。
4. 链接上游 issue 或 release note：等 schema 修复后，这条记录要能告诉操作者是重新加字段、锁版本，还是继续保留 fallback。

这类事故后记录能把一次生产中断沉淀成下一位搜索 feishu additional properties 的操作者可直接复用的入口。

加载飞书插件前先做 schema preflight

如果你是从“飞书插件加载不了”或“OpenClaw schema 拒绝 Feishu 配置”搜到这里，不要先重装插件。先证明失败发生在核心配置校验，还是官方飞书集成内部：

1. 校验根配置形状：先确认 plugins.entries 符合当前 OpenClaw core 版本要求，再看任何飞书专属字段。
2. 隔离单个飞书 entry：用一个最小可工作的飞书 entry 和失败 entry 对比，避免多余字段遮住第一条 schema error。
3. 记录拒绝层级：保留完整错误文本，并标明它发生在 plugin 初始化前、credential 加载时，还是第一次 Feishu API 调用时。
4. 最后再轮换凭证：如果 core schema 在插件加载前就拒绝配置，替换 app id、app secret 或 tenant 凭证不会改变结果。

这个 preflight 能把泛泛的飞书安装流量更快分流成：先查 schema mismatch，再查凭证，再查插件 runtime bug。

Feishu 插件消息过不去时，先对齐 schema 版本

官方 Feishu 插件和 OpenClaw Core schema 不兼容时，表象可能是消息没进 agent、工具参数丢字段，或者 channel 回调看起来成功但正文没有被运行时接受。不要先重装插件，先确认双方使用的是同一套消息 schema。

建议按三层收敛：

1. 对照插件发送的原始 payload，确认必填字段、嵌套结构和枚举值是否还符合当前 Core schema；
2. 检查 OpenClaw Core、Feishu plugin、部署镜像或 lockfile 的版本边界，找出哪次升级后 schema 开始漂移；
3. 用一条最小文本消息和一条带附件/富文本的消息分别验证，避免只覆盖最简单路径。

这段覆盖 “OpenClaw Feishu plugin schema incompatible”“Feishu 消息发不过去”“OpenClaw Core schema mismatch” 这类搜索意图，把读者从反复重连机器人引到协议版本归因。

相关阅读

• OpenClaw Feishu 排障：/stop 与 /new 可能无法中断正在执行的会话
• OpenClaw ACP 一次性运行明明有 transcript，sessions_history 却短暂为空：该怎么看、怎么止损
• OpenClaw Agents 排障指南：任务卡住、工具不回、结果异常时先查什么
• OpenClaw 完整安装指南：从环境准备到首次跑通
• OpenClaw Mac 快速安装指南
• 2026 年最值得优先落地的 5 个 OpenClaw Skills

如果你同时在排查多条控制面故障

很多团队是在同一次 Feishu 上线或升级窗口里，一起撞到这类 schema 问题、命令中断问题和 ACP 会话可见性问题的。为了缩短恢复时间，建议把故障先拆成三层看：

• 启动期 schema 拒绝：刚加上 replyMode、threadSession 一类字段，Gateway 直接起不来
• 命令中断失效：Feishu 看起来收到了 /stop 或 /new，但当前任务还在继续跑
• 会话历史投影延迟：ACP 一次性运行其实已经完成，但 sessions_history 短时间内还是空的

这三类问题会让人直觉上觉得“整个控制面都不可靠”，但它们发生在不同层。越早把它们拆开，越容易缩小排查范围，也越容易更快恢复服务。

常见判断问题 FAQ

如果 Gateway 在启动期就报 must NOT have additional properties，第一反应应该是什么？

第一反应不该是先查 token、权限或消息投递，而应该先把它当成 启动期 schema 不兼容 来看。

因为这类错误发生得太早了，通常还没进入真正的 Feishu 连接或发消息阶段。

什么时候更该优先怀疑 Core 和官方插件版本漂移，而不是配置手误？

如果你明明是按官方插件文档配置的，而且同一套字段在另一个环境能启动，只有当前环境在启动时被拒，那就更该先查：

1. Core 版本是否不同
2. 官方插件版本是否不同
3. 是否还在加载缓存的旧插件包或旧镜像

这类版本漂移，往往比“刚好把字段写错了”更能解释为什么只有一个环境炸。

搜 feishu additional properties startup 的人，页面最该先帮他分哪三个支路？

最该先分这三个：

1. 是启动前就报 schema 错，还是启动后才发消息失败
2. 是所有环境都炸，还是只有某一个环境炸
3. 删掉 footer、replyMode、threadSession 后 Gateway 能不能恢复启动

这三步最能帮助用户从“Feishu 全链路坏了”收缩到“当前 Core 对官方插件字段的启动期兼容性断裂”。

搜索入口分流：schema 不兼容时先判断什么

如果你是从 “Feishu plugin schema incompatible”、“官方飞书插件不能加载” 或 “OpenClaw core schema mismatch” 搜到这里，先不要急着改插件代码。更稳的判断顺序是：

1. 确认 core 版本：先看当前 OpenClaw core 是否已经升级到插件要求的 schema 版本。
2. 确认插件来源：区分官方插件、旧 fork、内部改造版，避免把 fork 的兼容问题误判成官方回归。
3. 确认报错层级：如果是在插件注册阶段失败，优先看 schema；如果是运行阶段工具调用失败，再看权限、token 和 Feishu API。
4. 确认是否可降级止血：生产环境里，先 pin 到已知可用组合，比在值班窗口里临时改 schema 更安全。

这类问题最容易浪费时间的地方，是把“加载时 schema 不兼容”误判成“飞书授权失败”。前者通常发生在插件进入运行态之前，后者则会在真实 API 调用时暴露。

相关阅读

• OpenClaw Agents 排障指南：任务卡住、工具不回、结果异常时先查什么
• OpenClaw 更新指南（2026-02-02）：升级前后该重点检查什么
• OpenClaw 安装完整指南：从本地到可维护部署
• Feishu Plugin Token 一直取不到时，先查什么

下一步优先覆盖的精确飞书 schema 搜索词

当操作者不是在排查飞书权限，而是官方飞书插件原本能用、升级后因为 OpenClaw core schema 与插件契约不一致而失败，优先用这一段承接搜索意图。

• OpenClaw Feishu plugin schema incompatible：先对比 gateway 实际加载的 core schema 版本和官方飞书插件版本，不要先改文档权限。
• OpenClaw core 更新后官方飞书插件失败：先 pin 回最后可用的 core/plugin 组合，再用只读文档操作验证，不要直接恢复写入动作。
• Feishu plugin validation error after upgrade：保留完整 schema validation 报错、插件包版本和 gateway 启动日志，方便维护者区分 schema 漂移和授权失败。

改飞书插件代码前，先做兼容性分层排查

如果你是因为 OpenClaw core 升级后飞书插件无法加载才搜到这篇文章，不要第一步就改插件代码。先按这个顺序证明不兼容发生在哪一层：

1. 记录 OpenClaw core 版本，以及飞书插件的准确 package 版本或 commit；
2. 用运行时报错里的字段去对照 plugin manifest/schema，不要只看 TypeScript 类型；
3. 在干净 workspace 里复测同一个插件，避免旧生成文件掩盖真实不兼容；
4. 在迁移 schema 前，先 pin 住 core 或 plugin 其中一边的版本；
5. 把失败 payload 和成功 payload 并排保留，方便提交上游 issue。

这段清单承接“OpenClaw 飞书插件 schema 不兼容”“OpenClaw 升级后飞书插件加载失败”这类搜索意图，帮助排查者区分真正的 SDK 契约变化、本地缓存、旧构建产物和混合版本部署。

来源

• openclaw/openclaw#57173