检查和诊断插件
本页介绍只读诊断命令:openclaw plugins inspect、openclaw plugins doctor 和 openclaw plugins registry。
检查¶
openclaw plugins inspect <id>
openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
openclaw plugins inspect --all
检查显示标识、加载状态、来源、清单能力、策略标志、诊断信息、安装元数据、捆绑能力,以及检测到的 MCP 或 LSP 服务器支持,默认不导入插件运行时。JSON 输出包含插件清单契约,例如 contracts.agentToolResultMiddleware 和 contracts.trustedToolPolicies,以便运维人员在启用或重启插件之前审计可信面声明。添加 --runtime 可加载插件模块,并包含已注册的钩子、工具、命令、服务、网关方法和 HTTP 路由。运行时检查会直接报告缺失的插件依赖;安装和修复仍由 openclaw plugins install、openclaw plugins update 和 openclaw doctor --fix 负责。
默认人工检查使用 enabled、disabled 或 error 状态标签,与 plugins list 一致。它描述元数据快照,并不表示插件模块已被导入。使用 --runtime 时,成功的运行时检查使用 loaded。JSON 保留底层注册表状态和单独的 imported 字段。
对于多入口包,检查任意子项都会显示共享的包安装元数据。inspect --all --json 会为每个子项包含相同记录。如果包归属缺失或存在歧义,检查会省略安装元数据,而不是关联无关的安装记录。
插件拥有的 CLI 命令通常安装为根 openclaw 命令组,但插件也可以在核心父命令(如 openclaw nodes)下注册嵌套命令。当 inspect --runtime 在 cliCommands 下显示某个命令后,请在列出的路径处运行它;例如,注册了 demo-git 的插件可以通过 openclaw demo-git ping 验证。
每个插件根据其运行时实际注册的内容进行分类:
| 形态 | 含义 |
|---|---|
plain-capability |
恰好一种能力类型(例如仅提供 provider 的插件) |
hybrid-capability |
多种能力类型(例如文本 + 语音 + 图像) |
hook-only |
仅钩子,没有能力、工具、命令、服务或路由 |
non-capability |
有工具/命令/服务,但没有能力 |
有关能力模型的更多信息,请参阅 插件形态。
Note
--json 标志输出适合脚本和审计的机器可读报告。inspect --all 渲染一个全量表格,包含形态、能力类型、兼容性通知、捆绑能力和钩子摘要列。info 是 inspect 的别名。
全局发现诊断信息会输出到 stderr,包括使用 --json 时。当工作区发现没有选定的系统所有者时,即使未找到插件,这也会解释部分清单。特定于插件的诊断信息保留在各自报告中。策略字段使用与运行时配置相同的插件 ID 不区分大小写匹配;报告的插件 ID 保留其声明的拼写。
SDK 导入失败会出现在现有的插件错误输出和 Doctor 的插件诊断中。诊断信息会指明插件、导入的 openclaw/plugin-sdk/* 接缝、运行核心版本,以及在已知时的构建版本。对于官方插件,运行 openclaw plugins update <id>。正在运行的 Gateway 会在命令完成前应用更新;否则它会在下次启动时加载更新。如果错误识别出嵌套 SDK,则插件捆绑了不兼容的 OpenClaw SDK;请更新插件或联系其作者。
JSON 诊断信息可能包含 code: "sdk-incompatible" 以及可选的 sdkCompatibility 对象,其中包含 seam、coreVersion、builtWithOpenClawVersion(如果已知)和 nestedSdk。不包含这些字段的现有诊断信息仍然有效。模型错误指向运行时检查,而不包含原始加载器错误。
诊断¶
doctor 报告插件加载错误、清单/发现诊断信息、兼容性通知以及过时的插件配置引用(例如缺失的插件槽位)。它会加载插件模块,但不会激活插件,也不会查询正在运行的 Gateway。当这些本地检查通过时,它会打印 Plugin discovery, module loading, compatibility, and configuration checks passed. Run "openclaw health" to check the running Gateway, including runtime quarantines and fallbacks.。health 命令 从 Gateway 读取当前运行时隔离和回退状态。如果仍存在过时配置,但安装树其他方面健康,摘要会说明这一点,而不是暗示插件完全健康。
使用 --json 时,相同的发现、兼容性和配置诊断信息会作为一个机器可读对象返回。
Doctor 会等待其检查注册资源释放,然后打印报告并设置诊断退出状态。清理失败会产生命令错误,而不是成功报告。正在运行的 Gateway 注册项不会被此检查释放。
如果已配置的插件存在于磁盘上,但被加载器的路径安全检查阻止,配置验证会保留该插件条目,并将其报告为 present but blocked。请修复前面的被阻止插件诊断问题,例如路径所有权或全局可写权限,而不是删除 plugins.entries.<id> 或 plugins.allow 配置。
对于模块形态失败(例如缺少 register/activate 导出),请使用 OPENCLAW_PLUGIN_LOAD_DEBUG=1 重新运行,以便在诊断输出中包含简明的导出形态摘要。
注册表¶
本地插件注册表是 OpenClaw 的持久化冷读模型,用于已安装插件身份、启用状态、源元数据和贡献所有权。正常启动、提供者所有者查找、通道设置分类和插件清单可以读取它,而无需导入插件运行时模块。
当该注册表缺失或过期时,Gateway 启动会验证当前插件元数据,并从该准备好的快照提供服务。就绪后,维护进程会在插件生命周期租约下,于共享状态工作线程中使用当前配置和包事实刷新持久化注册表。这为后续更新保留元数据,而不会因 SQLite 写入而阻塞请求处理。刷新失败会产生警告,但不会替换当前活动运行时快照。配置恢复和数据库兼容性检查仍然是启动关卡;更新会保留这些检查。
使用 plugins registry 检查持久化注册表是否存在、是否为最新或已过期。使用 --refresh 从持久化插件索引、配置策略以及清单/包元数据中重建它。这是一条修复路径,而不是运行时激活路径。
当持久化插件记录与派生插件记录不一致时,该命令会列出每个存在差异的插件及其两个来源。JSON 输出会在 differences 中返回相同的行。策略过期会在 refreshReasons 中报告 policy-changed,并保持 differences 为空,因为策略验证在记录比较之前运行;策略刷新仍可能更新启用字段。刷新在报告成功之前会重新读取并验证其持久化替换内容。如果插件包文件在验证期间持续变化,请停止这些更新并再次运行 openclaw plugins registry --refresh。
openclaw doctor --fix 还会修复与注册表相邻的受管 npm 漂移。如果受管插件 npm 项目或旧版扁平受管 npm 根目录下的孤立或已恢复的 @openclaw/* 包遮蔽了捆绑插件,doctor 会删除该过期包并重建注册表,以便启动时针对捆绑清单进行验证。当权威安装记录选择某个受管代际,但旧的扁平目录或代际目录仍然存在时,doctor 会将这些过期目录树标记为退役,以便在 gateway 重启后进行清理。doctor 还会将宿主 openclaw 包重新链接到声明了 peerDependencies.openclaw 的受管 npm 插件中,以便在更新或 npm 修复后,诸如 openclaw/plugin-sdk/* 之类的包内运行时导入能够解析。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw