插件验证修复

ClawHub 在发布之前验证插件包，还可以显示自动包扫描的结果。此页面涵盖面向作者的发现，这意味着插件作者可以在其包元数据、清单、SDK 导入或已发布的工件中修复发现。

它不涵盖内部插件检查器覆盖率调查结果。如果完整报告包含扫描仪维护代码而没有作者修复指南，则这些代码适用于 OpenClaw 维护者而不是插件作者。

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

clawhub package validate <path-to-plugin>

面向作者的调查结果

当已弃用的 OpenClaw API 有计划的停用日期时，插件页面会显示信息性 API 更新通知。打开 API 详细信息 查看每个 API 及其替代品。该日期为最终兼容日；这些通知不会阻止安装。发布者还会在其仪表板中看到 API update 项。单独的兼容性错误继续显示现有的不兼容警报。

更新到替换 API 后，验证并发布新版本以刷新插件最新版本的结果。

包元数据

package-json-缺失

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

• 添加package.json与name、version和type。
• 当软件包附带 OpenClaw 插件时添加 openclaw 块。
• 使用 构建插件 作为最小包示例，使用 插件清单 用于包与清单拆分。
• 重新运行clawhub package validate <path-to-plugin>。

package-openclaw-元数据缺失

该包具有 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>。

软件包安装元数据不完整

ClawHub 无法判断应如何安装或更新该软件包。

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

package-plugin-api-compat-missing

该包没有声明它支持的 OpenClaw 插件 API 范围。

• 将openclaw.compat.pluginApi添加到package.json。
• 使用您构建和测试的 OpenClaw 插件 API 版本或 semver 底层。
• 将其与软件包版本分开。软件包版本描述了插件版本； 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-不支持的元数据

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

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

发布神器

package-npm-pack-不可用

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

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

package-npm-pack-入口点缺失

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

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

package-npm-pack-元数据缺失

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

• 运行 npm pack --dry-run 并检查包含的元数据文件。
• 确保 package.json 在打包工件中包含 openclaw 块。
• 确保当包是本机 OpenClaw 插件时包含 openclaw.plugin.json。
• 更新files或.npmignore，因此不排除包元数据。
• 请参见 构建插件。
• 重新运行clawhub package validate <path-to-plugin>。

Manifest 元数据

清单名称缺失

本机插件清单不包含显示名称。

• 向openclaw.plugin.json添加一个非空的name字段。
• 保持 name 可读，并保持 id 作为稳定的机器 ID。
• 请参阅 插件清单。
• 重新运行clawhub package validate <path-to-plugin>。

清单未知字段

插件清单具有 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-导入

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

• 用集中的公共子路径导入替换根桶导入。
• 使用openclaw/plugin-sdk/plugin-entry作为definePluginEntry。
• 使用 openclaw/plugin-sdk/channel-core 作为频道输入助手。
• 使用导入约定和插件SDK子路径来查找窄导入。
• 重新运行clawhub package validate <path-to-plugin>。

保留-sdk-导入

该插件导入为捆绑插件或内部兼容性保留的 SDK 路径。

• 将保留的 OpenClaw 内部 SDK 导入替换为记录的公共 openclaw/plugin-sdk/* 子路径。
• 如果该行为没有公共SDK，请将帮助程序保留在您的包中或请求公共OpenClaw API。
• 使用插件SDK子路径和SDK迁移来选择支持的导入。
• 重新运行clawhub package validate <path-to-plugin>。

sdk-加载会话存储

该插件仍然使用已弃用的整个会话存储帮助程序 loadSessionStore。

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

sdk-会话存储-写入

该插件仍然使用已弃用的整个会话存储写入帮助程序，例如 saveSessionStore 或 updateSessionStore。

• 更新现有会话条目上的字段时使用 patchSessionEntry(...)。
• 替换或创建会话条目时使用 upsertSessionEntry(...)。
• 避免加载、改变和保存整个会话存储对象。
• 仅在您声明的兼容性范围仍支持需要它们的较旧 OpenClaw 版本时保留全商店写入帮助程序。
• 请参见 运行时 API 和 插件 SDK 子路径。
• 重新运行clawhub package validate <path-to-plugin>。

sdk-会话-文件-帮助程序

该插件仍然使用已弃用的会话文件路径帮助程序，例如 resolveSessionFilePath 或 resolveAndPersistSessionFile。

• 使用 getSessionEntry(...) 按代理和会话身份读取会话元数据。
• 使用 patchSessionEntry(...) 或 upsertSessionEntry(...) 保存会话元数据。
• 在代码准备转录操作时使用转录标识或目标助手。
• 不要保留或依赖旧的转录文件路径。
• 请参见 运行时 API 和 插件 SDK 子路径。
• 重新运行clawhub package validate <path-to-plugin>。

sdk-会话-转录-文件-目标

该插件仍然使用已弃用的转录文件目标帮助器 resolveSessionTranscriptLegacyFileTarget。

• 当代码只需要公共会话标识时使用 resolveSessionTranscriptIdentity(...)。
• 当代码需要结构化转录操作目标时使用 resolveSessionTranscriptTarget(...)。
• 避免直接读取或构建遗留转录文件目标。
• 仅当您声明的兼容性范围仍支持需要它的较旧 OpenClaw 版本时才保留旧版助手。
• 请参见 运行时 API 和 插件 SDK 子路径。
• 重新运行clawhub package validate <path-to-plugin>。

sdk-会话-转录本-低级别

该插件仍然使用已弃用的低级转录助手，例如 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。
• 仅当您声明的兼容性范围仍支持需要它的较旧 OpenClaw 版本时才保留 before_agent_start。
• 请参阅 Hooks 和 插件兼容性。
• 重新运行clawhub package validate <path-to-plugin>。

provider-auth-env-vars

该清单仍使用旧版 providerAuthEnvVars 提供程序身份验证元数据。

• 将提供程序环境变量元数据镜像到 setup.providers[].envVars 中。
• 仅将 providerAuthEnvVars 保留为兼容性元数据，而您支持的 OpenClaw 系列仍需要它。
• 请参见设置参考和SDK迁移。
• 重新运行clawhub package validate <path-to-plugin>。

通道环境变量

清单使用旧版或较旧的通道环境变量元数据，而没有 ClawHub 期望的当前设置或配置元数据。

• 保持通道环境变量元数据声明性，以便 OpenClaw 可以在不加载通道运行时的情况下检查设置状态。
• 将环境驱动的通道设置镜像到插件形状使用的当前设置、通道配置或包通道元数据中。
• 仅保留 channelEnvVars 作为兼容性元数据，而较旧的受支持 OpenClaw 版本仍然需要它。
• 参见插件清单和频道插件。
• 重新运行clawhub package validate <path-to-plugin>。

安全清单

安全清单架构不可用

该软件包附带 openclaw.security.json 和 ClawHub 无法识别为可用的架构引用。

• 如果架构 URL 仅供咨询，则删除该架构。
• 仅在 OpenClaw 发布版本化模式后才使用记录的版本化模式。
• 重新运行clawhub package validate <path-to-plugin>。

unrecognized-安全清单

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

• 删除 openclaw.security.json，直到 OpenClaw 记录版本化安全清单架构和 ClawHub 行为。
• 将安全敏感行为记录在公共包文档或 README 中，直到清单合同存在。
• 重新运行clawhub package validate <path-to-plugin>。

相关内容

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