检查和诊断插件

本页介绍只读诊断命令：openclaw plugins inspect、openclaw plugins doctor 和 openclaw plugins registry。

Inspect¶

openclaw plugins inspect <id>
openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
openclaw plugins inspect --all

inspect 命令显示身份、加载状态、来源、manifest 能力、策略标志、诊断信息、安装元数据、bundle 能力，以及任何检测到的 MCP 或 LSP 服务器支持；默认情况下不会导入插件运行时。JSON 输出包含插件 manifest 契约，例如 contracts.agentToolResultMiddleware 和 contracts.trustedToolPolicies，因此操作员可以在启用或重启插件之前审计受信任表面声明。添加 --runtime 可加载插件模块，并包含已注册的 hooks、工具、命令、服务、Gateway 方法和 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`	仅 hooks，无能力、工具、命令、服务或路由
`non-capability`	有工具/命令/服务，但无能力

参见 Plugin shapes 以了解更多关于能力模型的内容。

Note

--json 标志会输出适合脚本编写和审计的机器可读报告。inspect --all 渲染一张全舰队表格，包含形态、能力种类、兼容性提示、bundle 能力和 hook 摘要列。info 是 inspect 的别名。

全局发现诊断信息会输出到 stderr，包括使用 --json 时也是如此。当工作区发现没有选定的系统所有者时，即使未找到任何插件，这也能解释清单不完整的原因。插件特定的诊断信息保留在各自报告中。策略字段使用与运行时配置相同的不区分大小写的插件 ID 匹配；报告的插件 ID 保留其声明的拼写。

SDK 导入失败会出现在现有的插件错误输出和 Doctor 的插件诊断信息中。诊断信息会指明插件、导入的 openclaw/plugin-sdk/* seam、正在运行的核心版本，以及已知时的构建版本。对于官方插件，请运行 openclaw plugins update <id>。正在运行的 Gateway 会在命令完成前应用该更新；否则会在下次启动时加载更新。如果错误指向嵌套 SDK，说明插件捆绑了不兼容的 OpenClaw SDK；请更新插件或联系其作者。

JSON 诊断可能包含 code: "sdk-incompatible" 以及可选的 sdkCompatibility 对象，其中包含 seam、coreVersion、builtWithOpenClawVersion（已知时）和 nestedSdk。没有这些字段的现有诊断仍然有效。模型错误会指向运行时检查，而不会包含原始加载器错误。

Doctor¶

openclaw plugins doctor
openclaw plugins doctor --json

doctor 报告插件加载错误、manifest/发现诊断、兼容性提示，以及过时的插件配置引用（例如缺失的插件槽）。它会加载插件模块但不激活插件，也不会查询正在运行的 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 读取当前的运行时隔离（quarantine）和回退（fallback）状态。如果过时配置仍然存在但安装树在其他方面健康，摘要会说明这一点，而不会暗示插件完全健康。

使用 --json 时，相同的发现、兼容性和配置诊断信息会作为一个机器可读对象返回。

Doctor 在打印报告并设置诊断退出状态之前，会等待其检查注册资源被释放。清理失败会产生命令错误，而不是成功报告。正在运行的 Gateway 注册不会被此检查释放。

如果某个已配置的插件存在于磁盘上，但被加载器的路径安全检查阻止，配置验证会保留该插件条目，并将其报告为 present but blocked。请修复前面的阻塞插件诊断（例如路径所有权或全局可写权限），而不是删除 plugins.entries.<id> 或 plugins.allow 配置。

对于模块形态失败，例如缺少 register/activate 导出，请使用 OPENCLAW_PLUGIN_LOAD_DEBUG=1 重新运行，以便在诊断输出中包含简洁的导出形态摘要。

Registry¶

openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins registry --json

本地插件注册表是 OpenClaw 对已安装插件身份、启用状态、来源元数据和贡献所有权的持久化冷读模型。正常启动、提供方属主查找、渠道设置分类以及插件清单都可以读取它，而无需导入插件运行时模块。

使用 plugins registry 检查持久化注册表是否存在、是否最新或已过期。使用 --refresh 从持久化插件索引、配置策略以及清单/包元数据重建注册表。这是修复路径，而非运行时激活路径。

当持久化记录与派生插件记录不一致时，该命令会列出每个存在差异的插件及其两种来源。JSON 输出在 differences 中返回相同的行。策略过期时会在 refreshReasons 中报告 policy-changed，并让 differences 保持为空，因为策略验证在记录比较之前运行；策略刷新仍然可以更新启用字段。刷新会在报告成功之前重新读取并验证其持久化替换结果。如果插件包文件在验证期间持续变化，请停止这些更新并重新运行 openclaw plugins registry --refresh。

openclaw doctor --fix 还会修复注册表相邻的受管 npm 漂移。如果受管插件 npm 项目或旧式扁平受管 npm 根目录下的孤立或恢复的 @openclaw/* 包遮蔽了捆绑插件，doctor 会移除该过期包并重建注册表，使启动时依据捆绑清单进行验证。当权威安装记录选择了某一个受管代次，但旧式扁平目录或代次目录仍然存在时，doctor 会将这些过期目录树退役，待网关重启后进行修剪。doctor 还会将宿主的 openclaw 包重新链接到声明了 peerDependencies.openclaw 的受管 npm 插件中，从而使 openclaw/plugin-sdk/* 等包内运行时导入在更新或 npm 修复后能够正常解析。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw