插件验证修复

ClawHub 在发布前会验证插件包，也可以显示自动化包扫描的发现结果。本页介绍面向作者的发现结果，即插件作者可以通过修复包元数据、清单、SDK 导入或已发布工件来解决的发现结果。

本页不涵盖 Plugin Inspector 的内部覆盖率发现结果。如果完整报告包含没有作者修复指南的扫描器维护代码，则这些代码面向 OpenClaw 维护者，而非插件作者。

应用任何修复后，请重新运行：

clawhub package validate <path-to-plugin>

面向作者的发现结果

包元数据

package-json-missing

包根目录中不包含 package.json，因此 ClawHub 无法识别 npm 包、版本、入口点或 OpenClaw 元数据。

• 添加包含 name、version 和 type 的 package.json。
• 当包提供 OpenClaw 插件时，添加 openclaw 块。
• 有关最小包示例，请参阅构建插件；有关包与清单的划分，请参阅插件清单。
• 重新运行 clawhub package validate <path-to-plugin>。

package-openclaw-metadata-missing

包中包含 package.json，但未声明 OpenClaw 包元数据。

• 添加 package.json#openclaw。
• 包含入口点元数据，例如 openclaw.extensions 或 openclaw.runtimeExtensions。
• 当包将通过 ClawHub 发布或安装时，添加兼容性和安装元数据。
• 请参阅影响设备发现的 package.json 字段。
• 重新运行 clawhub package validate <path-to-plugin>。

package-openclaw-entry-missing

包元数据已存在，但未声明 OpenClaw 运行时入口点。

• 为原生插件入口点添加 openclaw.extensions。
• 当已发布的包应加载构建后的 JavaScript 时，添加 openclaw.runtimeExtensions。
• 确保所有入口点路径均位于包目录内。
• 请参阅插件入口点和影响设备发现的 package.json 字段。
• 重新运行 clawhub package validate <path-to-plugin>。

package-entrypoint-missing

包声明了 OpenClaw 入口点，但正在验证的包中缺少引用的文件。

• 检查 openclaw.extensions、openclaw.runtimeExtensions、openclaw.setupEntry 和 openclaw.runtimeSetupEntry 中的每个路径。
• 如果入口点生成到 dist 中，请构建包。
• 如果入口点已移动，请更新元数据。
• 请参阅插件入口点。
• 重新运行 clawhub package validate <path-to-plugin>。

package-install-metadata-incomplete

ClawHub 无法确定应如何安装或更新该包。

• 在 openclaw.install 中填写受支持的安装源，例如 clawhubSpec、npmSpec 或 localPath。
• 当有多个安装源可用时，设置 openclaw.install.defaultChoice。
• 使用 openclaw.install.minHostVersion 指定 OpenClaw 的最低宿主版本。
• 请参阅影响设备发现的 package.json 字段。
• 重新运行 clawhub package validate <path-to-plugin>。

package-plugin-api-compat-missing

包未声明其支持的 OpenClaw 插件 API 范围。

• 将 openclaw.compat.pluginApi 添加到 package.json。
• 使用你构建并测试时所针对的 OpenClaw 插件 API 版本或语义化版本下限。
• 将其与包版本分开。包版本描述插件发布版本；openclaw.compat.pluginApi 描述宿主 API 契约。
• 请参阅影响设备发现的 package.json 字段。
• 重新运行 clawhub package validate <path-to-plugin>。

package-min-host-version-drift

包的最低宿主版本与构建该包时所针对的 OpenClaw 版本元数据不匹配。

• 检查 openclaw.install.minHostVersion。
• 检查包中的所有 OpenClaw 构建元数据，例如发布时使用的 OpenClaw 版本。
• 将最低宿主版本与包实际支持的宿主版本范围对齐。
• 请参阅影响设备发现的 package.json 字段。
• 重新运行 clawhub package validate <path-to-plugin>。

package-manifest-version-drift

包版本与插件清单版本不一致。

• 优先使用 package.json#version 作为包发布版本。
• 如果 openclaw.plugin.json 也包含 version，请更新它以保持一致；如果包元数据是权威来源，则移除过时的清单版本元数据。
• 更改已发布的元数据后，请发布新的包版本。
• 请参阅插件清单。
• 重新运行 clawhub package validate <path-to-plugin>。

package-openclaw-unsupported-metadata

package.json#openclaw 块包含不受 OpenClaw 包元数据支持的字段。

• 移除不受支持的字段，例如 openclaw.bundle。
• 将原生插件元数据保留在 openclaw.plugin.json 中。
• 将包入口点、兼容性、安装、设置和目录元数据保留在受支持的 package.json#openclaw 字段中。
• 请参阅影响设备发现的 package.json 字段。
• 重新运行 clawhub package validate <path-to-plugin>。

已发布工件

package-npm-pack-unavailable

无法将该包打包为 ClawHub 将检查或发布的工件。

• 从包根目录运行 npm pack --dry-run。
• 修复导致打包失败的无效包元数据、损坏的生命周期脚本或 files 条目。
• 如果此包用于公开发布，请移除 private: true。
• 重新运行 clawhub package validate <path-to-plugin>。

package-npm-pack-entrypoint-missing

该包可以打包，但打包后的工件不包含 package.json#openclaw 中声明的入口点文件。

• 运行 npm pack --dry-run 并检查将包含的文件。
• 在打包前构建生成的入口点。
• 更新 files、.npmignore 或构建输出，以包含已声明的入口点。
• 请参阅插件入口点。
• 重新运行 clawhub package validate <path-to-plugin>。

package-npm-pack-metadata-missing

打包后的工件缺少源包中存在的 OpenClaw 元数据。

• 运行 npm pack --dry-run 并检查其中包含的元数据文件。
• 确保打包工件中的 package.json 包含 openclaw 块。
• 当软件包是原生 OpenClaw 插件时，确保包含 openclaw.plugin.json。
• 更新 files 或 .npmignore，以免软件包元数据被排除。
• 请参阅构建插件。
• 重新运行 clawhub package validate <path-to-plugin>。

清单元数据

manifest-name-missing

原生插件清单未包含显示名称。

• 向 openclaw.plugin.json 添加非空的 name 字段。
• 确保 name 便于人类阅读，并将 id 保留为稳定的机器 ID。
• 请参阅插件清单。
• 重新运行 clawhub package validate <path-to-plugin>。

manifest-unknown-fields

插件清单包含 OpenClaw 不支持的顶层字段。

• 将每个顶层字段与清单字段参考进行比较。
• 从 openclaw.plugin.json 中移除自定义字段。
• 将软件包或安装元数据移入受支持的 package.json#openclaw 字段，而不是放在清单中。
• 重新运行 clawhub package validate <path-to-plugin>。

manifest-unknown-contracts

清单在 contracts 中声明了不受支持的键。

• 将 contracts 下的每个键与契约参考进行比较。
• 移除不受支持的契约键。
• 将运行时行为移入插件注册代码，并将 contracts 限定为静态能力所有权元数据。
• 重新运行 clawhub package validate <path-to-plugin>。

SDK 和兼容性迁移

legacy-root-sdk-import

插件仍从已弃用的根 SDK 桶文件导入： openclaw/plugin-sdk。

• 将根桶文件导入替换为聚焦的公共子路径导入。
• 对 definePluginEntry 使用 openclaw/plugin-sdk/plugin-entry。
• 对渠道入口辅助函数使用 openclaw/plugin-sdk/channel-core。
• 使用导入约定和插件 SDK 子路径查找范围最窄的导入。
• 重新运行 clawhub package validate <path-to-plugin>。

reserved-sdk-import

插件导入了仅供内置插件或内部兼容性使用的 SDK 路径。

• 将保留的 OpenClaw 内部 SDK 导入替换为文档中列出的公共 openclaw/plugin-sdk/* 子路径。
• 如果该行为没有公共 SDK，请将辅助函数保留在你的软件包内，或请求添加公共 OpenClaw API。
• 使用插件 SDK 子路径和 SDK 迁移选择受支持的导入。
• 重新运行 clawhub package validate <path-to-plugin>。

sdk-load-session-store

插件仍在使用已弃用的完整会话存储辅助函数 loadSessionStore。

• 读取会话状态时，使用 getSessionEntry(...) 或 listSessionEntries(...)。
• 写入会话状态时，使用 patchSessionEntry(...) 或 upsertSessionEntry(...)。
• 避免加载、修改并保存整个会话存储对象。
• 仅当你声明的兼容范围仍支持需要 loadSessionStore(...) 的旧版 OpenClaw 时，才保留它。
• 请参阅运行时 API和插件 SDK 子路径。
• 重新运行 clawhub package validate <path-to-plugin>。

sdk-session-store-write

插件仍在使用已弃用的完整会话存储写入辅助函数，例如 saveSessionStore 或 updateSessionStore。

• 更新现有会话条目的字段时，使用 patchSessionEntry(...)。
• 替换或创建会话条目时，使用 upsertSessionEntry(...)。
• 避免加载、修改并保存整个会话存储对象。
• 仅当你声明的兼容范围仍支持需要完整存储写入辅助函数的旧版 OpenClaw 时，才保留这些辅助函数。
• 请参阅运行时 API和插件 SDK 子路径。
• 重新运行 clawhub package validate <path-to-plugin>。

sdk-session-file-helper

插件仍在使用已弃用的会话文件路径辅助函数，例如 resolveSessionFilePath 或 resolveAndPersistSessionFile。

• 使用 getSessionEntry(...) 按 Agent 和会话身份读取会话元数据。
• 使用 patchSessionEntry(...) 或 upsertSessionEntry(...) 持久化会话元数据。
• 当代码准备执行转录操作时，使用转录身份或目标辅助函数。
• 不要持久化或依赖旧版转录文件路径。
• 请参阅运行时 API和插件 SDK 子路径。
• 重新运行 clawhub package validate <path-to-plugin>。

sdk-session-transcript-file-target

插件仍在使用已弃用的转录文件目标辅助函数 resolveSessionTranscriptLegacyFileTarget。

• 当代码只需要公共会话身份时，使用 resolveSessionTranscriptIdentity(...)。
• 当代码需要结构化转录操作目标时，使用 resolveSessionTranscriptTarget(...)。
• 避免直接读取或构造旧版转录文件目标。
• 仅当你声明的兼容范围仍支持需要旧版辅助函数的旧版 OpenClaw 时，才保留该辅助函数。
• 请参阅运行时 API和插件 SDK 子路径。
• 重新运行 clawhub package validate <path-to-plugin>。

sdk-session-transcript-low-level

插件仍在使用已弃用的底层转录辅助函数，例如 appendSessionTranscriptMessage 或 emitSessionTranscriptUpdate。

• 使用 appendSessionTranscriptMessageByIdentity(...) 追加转录内容。
• 使用 publishSessionTranscriptUpdateByIdentity(...) 发送转录更新通知。
• 优先使用结构化转录运行时接口，以便 OpenClaw 应用正确的事务边界和身份处理。
• 仅当你声明的兼容范围仍支持需要底层转录辅助函数的旧版 OpenClaw 时，才保留这些辅助函数。
• 请参阅运行时 API和插件 SDK 子路径。
• 重新运行 clawhub package validate <path-to-plugin>。

legacy-before-agent-start

插件仍在使用旧版 before_agent_start 钩子。

• 将模型或提供商覆盖工作移至 before_model_resolve。
• 将提示词或上下文修改工作移至 before_prompt_build。
• 仅当你声明的兼容范围仍支持需要 before_agent_start 的旧版 OpenClaw 时，才保留它。
• 请参阅Hooks和插件兼容性。
• 重新运行 clawhub package validate <path-to-plugin>。

provider-auth-env-vars

清单仍在使用旧版 providerAuthEnvVars 提供商身份验证元数据。

• 将提供商环境变量元数据同步到 setup.providers[].envVars。
• 仅当你支持的 OpenClaw 版本范围仍需要 providerAuthEnvVars 时，才将其保留为兼容性元数据。
• 请参阅设置参考和 SDK 迁移。
• 重新运行 clawhub package validate <path-to-plugin>。

channel-env-vars

清单使用了旧版或较旧的渠道环境变量元数据，但未包含 ClawHub 所需的当前设置或配置元数据。

• 保持渠道环境变量元数据的声明式形式，以便 OpenClaw 无需加载渠道运行时即可检查设置状态。
• 将环境变量驱动的渠道设置同步到插件形态所使用的当前设置、渠道配置或软件包渠道元数据中。
• 仅当支持的旧版 OpenClaw 仍需要 channelEnvVars 时，才将其保留为兼容性元数据。
• 请参阅插件清单和渠道插件。
• 重新运行 clawhub package validate <path-to-plugin>。

安全清单

security-manifest-schema-unavailable

软件包附带 openclaw.security.json，其中引用的架构未被 ClawHub 识别为可用架构。

• 如果架构 URL 仅用于提供建议，请将其移除。
• 仅在 OpenClaw 发布文档化的版本化架构后才使用它。
• 重新运行 clawhub package validate <path-to-plugin>。

unrecognized-security-manifest

软件包附带了不受支持的安全清单文件。

• 在 OpenClaw 发布版本化安全清单架构和 ClawHub 行为文档之前，移除 openclaw.security.json。
• 在清单契约建立之前，请在公开的软件包文档或 README 中记录安全敏感行为。
• 重新运行 clawhub package validate <path-to-plugin>。

相关内容

• ClawHub CLI
• ClawHub 发布
• 构建插件
• 插件清单
• 插件入口点
• 插件兼容性