在使用 OpenClaw CLI（例如 openclaw status、openclaw gateway restart）时，若 ~/.openclaw/openclaw.json 中配置了第三方插件白名单，配置校验失败会导致整条配置被视为无效，CLI 无法启动、网关拒绝启动。本文记录一次与 openclaw-lark（@larksuite/openclaw-lark）相关的真实排查：症状 → 误判 → 根因 → 可行修复 → 与飞书通道配置的关系。

---

现象

终端大致会出现：

• Config invalid，指向 ~/.openclaw/openclaw.json
• 明确错误：plugins.allow: plugin not found: openclaw-lark
• openclaw doctor 可能同时提示：plugins.entries.openclaw-lark 为 stale（陈旧条目，校验时忽略）

即：配置里“允许”了一个插件 ID，但运行时插件注册表里找不到同名已解析插件。

---

常见第一反应（以及为何不够）

1. 执行 openclaw doctor --fix

有助于发现其它问题，但若根因是「插件根本没被登记」，不一定能单靠 doctor 修好；doctor 仍可能在最后提示 plugins.allow 无效。

2. 升级 @larksuite/openclaw-lark

用 npm view @larksuite/openclaw-lark version 可查 registry 上 latest（例如 2026.3.25）。
仅升级 npm 包版本，往往解决不了本次 plugin not found。
原因是：校验失败通常不是「包太旧」，而是 OpenClaw 没有把你的安装路径识别为合法扩展，从而 ID openclaw-lark 从未进入 allow 名单所对照的插件表。

3. openclaw plugins install @larksuite/openclaw-lark@latest

若 CLI 走 ClawHub 等上游且遇到 HTTP 429（Rate limit），安装会失败，需要换 直连 npm 或 本地路径安装 等替代路径（视你环境而定）。

---

根因（核心）

OpenClaw 会从 ~/.openclaw/extensions 等根目录发现插件。
若 extensions/openclaw-lark 只是一个 指向 node_modules/@larksuite/openclaw-lark 的符号链接：

• 磁盘上「包是存在的」，甚至 package.json 里 openclaw.channel.id / openclaw.plugin.json 的 id 仍是 openclaw-lark；
• 但 CLI 的路径/来源校验可能把「解析后的真实路径」判为不在允许的扩展布局内，结果：插件列表里看不到 openclaw-lark，plugins.allow 却写了它 → 配置非法。

对照现象：openclaw plugins list 里只有 global:openclaw-qqbot 这类「真实目录」插件，没有 openclaw-lark；一旦把安装改成与 QQ 插件类似的 extensions 下的真实目录，列表里就会出现 global:openclaw-lark/index.js。

结论： 这是 安装形态（符号链接 + 路径语义）与 OpenClaw 发现/校验规则不匹配 的问题，不是单纯「版本号旧」。

---

最终解决方案（可复现步骤）

目标：让 openclaw-lark 被正常发现，并与 plugins.allow / plugins.entries /（建议）plugins.installs 一致。

步骤 1：用「真实目录」承载插件（不要用指向 node_modules 的 symlink）

在 ~/.openclaw/extensions 下：

• 删除 openclaw-lark 符号链接（若存在）；
• 将 node_modules/@larksuite/openclaw-lark 整包复制为 extensions/openclaw-lark（与 openclaw-qqbot 同级、同为实体目录更稳妥）。

步骤 2：在插件目录内安装生产依赖

进入 extensions/openclaw-lark，执行：

npm install --omit=dev

避免运行时缺依赖。

步骤 3：用官方 CLI 写回启用状态

openclaw plugins enable openclaw-lark

一般会更新：

• plugins.allow 包含 openclaw-lark；
• plugins.entries.openclaw-lark.enabled 为 true。

步骤 4：（推荐）补全 plugins.installs 元数据

启用后若日志仍提示 缺少 install / load-path 来源（provenance），可在 plugins.installs 中为 openclaw-lark 增加与 npm 一致的记录（固定版本、installPath 指向实体目录、integrity 等可用 npm view @larksuite/openclaw-lark@<version> dist --json 查询）。

步骤 5：验证与重启网关

openclaw status
openclaw gateway restart   # 或你正在用的网关托管方式

期望：不再出现 plugin not found: openclaw-lark，plugins list 中可见该插件。

后续升级思路（ClawHub 仍不稳定时）

在 extensions 里用 npm 拉到新版本后，再 重新复制到 openclaw-lark 目录并 npm install --omit=dev，并同步更新 plugins.installs 中的版本与完整性字段。

---

延伸：飞书「通道配置」和「插件」不要混为一谈

很多人担心：修插件会不会把飞书弄断？可以记住这张表：

配置	含义	能否删
channels.feishu	应用凭证、连接方式、黑白名单、群策略等 收消息所依赖的业务配置	不能删（删了等于断链/无法鉴权）
plugins.entries.feishu	OpenClaw 内置/库存飞书扩展的开关	可与官方 Lark 插件二选一，避免 双开抢同一通道
openclaw-lark	@larksuite/openclaw-lark，同样对接 feishu 通道	启用时通常 channels.feishu 仍要保留

推荐稳定组合（与多数「已能收消息」的现状一致）：

• channels.feishu：保留且 enabled: true
• openclaw-lark：启用
• 库存 plugins.entries.feishu：enabled: false（避免与 openclaw-lark 重复挂同一 channel）

---

小结

项目	说明
直接诱因	plugins.allow 含 openclaw-lark，但插件未被 OpenClaw 登记
根因	extensions/openclaw-lark 用 symlink → node_modules 时，路径/发现规则导致插件未进入注册表
升级 alone	通常不够；要先解决 安装布局
最终修复	实体目录 + 本地 npm install + plugins enable +（建议）plugins.installs
飞书	保留 channels.feishu；插件选 官方 Lark 时，关掉库存 feishu 插件以免冲突

---

安全备忘（写博文时建议给读者一句）

配置文件中的 appSecret、clientSecret、网关 token 等属于高敏信息；博文、截图、备份仓库中应脱敏；若曾泄露，应在各平台轮换密钥。