Skip to main content

​
Plugin validation fixes

ClawHub validates plugin packages before publish and can also show findings from automated package scans. This page covers author-facing findings, which means findings the plugin author can fix in their package metadata, manifest, SDK imports, or published artifact. It does not cover internal Plugin Inspector coverage findings. If a full report contains scanner maintenance codes without author remediation guidance, those are for OpenClaw maintainers rather than plugin authors. After applying any fix, rerun:

​
Author-facing findings

​
Package metadata

​
package-json-missing

The package root does not include package.json, so ClawHub cannot identify the npm package, version, entrypoints, or OpenClaw metadata.
  • Add package.json with name, version, and type.
  • Add an openclaw block when the package ships an OpenClaw plugin.
  • Use Building plugins for a minimal package example and Plugin manifest for the package versus manifest split.
  • Rerun clawhub package validate <path-to-plugin>.

​
package-openclaw-metadata-missing

The package has package.json, but it does not declare OpenClaw package metadata.
  • Add package.json#openclaw.
  • Include entrypoint metadata such as openclaw.extensions or openclaw.runtimeExtensions.
  • Add compatibility and install metadata when the package will be published or installed through ClawHub.
  • See package.json fields that affect discovery.
  • Rerun clawhub package validate <path-to-plugin>.

​
package-openclaw-entry-missing

The package metadata exists, but it does not declare an OpenClaw runtime entrypoint.
  • Add openclaw.extensions for native plugin entrypoints.
  • Add openclaw.runtimeExtensions when the published package should load built JavaScript.
  • Keep all entrypoint paths inside the package directory.
  • See Plugin entry points and package.json fields that affect discovery.
  • Rerun clawhub package validate <path-to-plugin>.

​
package-entrypoint-missing

The package declares an OpenClaw entrypoint, but the referenced file is missing from the package being validated.
  • Check each path in openclaw.extensions, openclaw.runtimeExtensions, openclaw.setupEntry, and openclaw.runtimeSetupEntry.
  • Build the package if the entrypoint is generated into dist.
  • Update the metadata if the entrypoint moved.
  • See Plugin entry points.
  • Rerun clawhub package validate <path-to-plugin>.

​
package-install-metadata-incomplete

ClawHub cannot tell how the package should be installed or updated.
  • Fill openclaw.install with the supported install source, such as clawhubSpec, npmSpec, or localPath.
  • Set openclaw.install.defaultChoice when more than one install source is available.
  • Use openclaw.install.minHostVersion for the minimum OpenClaw host version.
  • See package.json fields that affect discovery.
  • Rerun clawhub package validate <path-to-plugin>.

​
package-plugin-api-compat-missing

The package does not declare the OpenClaw plugin API range it supports.
  • Add openclaw.compat.pluginApi to package.json.
  • Use the OpenClaw plugin API version or semver floor that you built and tested against.
  • Keep this separate from the package version. The package version describes the plugin release; openclaw.compat.pluginApi describes the host API contract.
  • See package.json fields that affect discovery.
  • Rerun clawhub package validate <path-to-plugin>.

​
package-min-host-version-drift

The package minimum host version does not match the OpenClaw version metadata the package was built against.
  • Check openclaw.install.minHostVersion.
  • Check any OpenClaw build metadata in the package, such as the OpenClaw version used during release.
  • Align the minimum host version with the host version range the package actually supports.
  • See package.json fields that affect discovery.
  • Rerun clawhub package validate <path-to-plugin>.

​
package-manifest-version-drift

The package version and plugin manifest version disagree.
  • Prefer package.json#version as the package release version.
  • If openclaw.plugin.json also has version, update it to match or remove stale manifest version metadata when package metadata is authoritative.
  • Publish a new package version after changing published metadata.
  • See Plugin manifest.
  • Rerun clawhub package validate <path-to-plugin>.

​
package-openclaw-unsupported-metadata

The package.json#openclaw block contains fields that are not supported OpenClaw package metadata.
  • Remove unsupported fields such as openclaw.bundle.
  • Keep native plugin metadata in openclaw.plugin.json.
  • Keep package entrypoints, compatibility, install, setup, and catalog metadata in supported package.json#openclaw fields.
  • See package.json fields that affect discovery.
  • Rerun clawhub package validate <path-to-plugin>.

​
Published artifact

​
package-npm-pack-unavailable

The package cannot be packed into the artifact ClawHub would inspect or publish.
  • Run npm pack --dry-run from the package root.
  • Fix invalid package metadata, broken lifecycle scripts, or files entries that make packing fail.
  • Remove private: true if this package is intended for public publishing.
  • Rerun clawhub package validate <path-to-plugin>.

​
package-npm-pack-entrypoint-missing

The package can be packed, but the packed artifact does not include the entrypoint files declared in package.json#openclaw.
  • Run npm pack --dry-run and inspect the files that would be included.
  • Build generated entrypoints before packing.
  • Update files, .npmignore, or build output so declared entrypoints are included.
  • See Plugin entry points.
  • Rerun clawhub package validate <path-to-plugin>.

​
package-npm-pack-metadata-missing

The packed artifact is missing OpenClaw metadata that exists in your source package.
  • Run npm pack --dry-run and inspect the included metadata files.
  • Ensure package.json includes the openclaw block in the packed artifact.
  • Ensure openclaw.plugin.json is included when the package is a native OpenClaw plugin.
  • Update files or .npmignore so package metadata is not excluded.
  • See Building plugins.
  • Rerun clawhub package validate <path-to-plugin>.

​
Manifest metadata

​
manifest-name-missing

The native plugin manifest does not include a display name.
  • Add a non-empty name field to openclaw.plugin.json.
  • Keep name human-readable and keep id as the stable machine id.
  • See Plugin manifest.
  • Rerun clawhub package validate <path-to-plugin>.

​
manifest-unknown-fields

The plugin manifest has top-level fields that OpenClaw does not support.
  • Compare each top-level field with the manifest field reference.
  • Remove custom fields from openclaw.plugin.json.
  • Move package or install metadata into supported package.json#openclaw fields instead of the manifest.
  • Rerun clawhub package validate <path-to-plugin>.

​
manifest-unknown-contracts

The manifest declares unsupported keys inside contracts.
  • Compare each key under contracts with the contracts reference.
  • Remove unsupported contract keys.
  • Move runtime behavior into plugin registration code, and keep contracts limited to static capability ownership metadata.
  • Rerun clawhub package validate <path-to-plugin>.

​
SDK and compatibility migration

​
legacy-root-sdk-import

The plugin imports from the deprecated root SDK barrel: openclaw/plugin-sdk.
  • Replace root-barrel imports with focused public subpath imports.
  • Use openclaw/plugin-sdk/plugin-entry for definePluginEntry.
  • Use openclaw/plugin-sdk/channel-core for channel entry helpers.
  • Use Import conventions and Plugin SDK subpaths to find the narrow import.
  • Rerun clawhub package validate <path-to-plugin>.

​
reserved-sdk-import

The plugin imports an SDK path reserved for bundled plugins or internal compatibility.
  • Replace reserved OpenClaw internal SDK imports with documented public openclaw/plugin-sdk/* subpaths.
  • If the behavior has no public SDK, keep the helper inside your package or request a public OpenClaw API.
  • Use Plugin SDK subpaths and SDK migration to choose a supported import.
  • Rerun clawhub package validate <path-to-plugin>.

​
sdk-load-session-store

The plugin still uses the deprecated whole-session-store helper loadSessionStore.
  • Use getSessionEntry(...) or listSessionEntries(...) when reading session state.
  • Use patchSessionEntry(...) or upsertSessionEntry(...) when writing session state.
  • Avoid loading, mutating, and saving the whole session store object.
  • Keep loadSessionStore(...) only while your declared compatibility range still supports older OpenClaw versions that require it.
  • See Runtime API and Plugin SDK subpaths.
  • Rerun clawhub package validate <path-to-plugin>.

​
sdk-session-store-write

The plugin still uses a deprecated whole-session-store write helper such as saveSessionStore or updateSessionStore.
  • Use patchSessionEntry(...) when updating fields on an existing session entry.
  • Use upsertSessionEntry(...) when replacing or creating a session entry.
  • Avoid loading, mutating, and saving the whole session store object.
  • Keep whole-store write helpers only while your declared compatibility range still supports older OpenClaw versions that require them.
  • See Runtime API and Plugin SDK subpaths.
  • Rerun clawhub package validate <path-to-plugin>.

​
sdk-session-file-helper

The plugin still uses deprecated session file-path helpers such as resolveSessionFilePath or resolveAndPersistSessionFile.
  • Use getSessionEntry(...) to read session metadata by agent and session identity.
  • Use patchSessionEntry(...) or upsertSessionEntry(...) to persist session metadata.
  • Use transcript identity or target helpers when the code is preparing a transcript operation.
  • Do not persist or depend on legacy transcript file paths.
  • See Runtime API and Plugin SDK subpaths.
  • Rerun clawhub package validate <path-to-plugin>.

​
sdk-session-transcript-file-target

The plugin still uses the deprecated transcript file target helper resolveSessionTranscriptLegacyFileTarget.
  • Use resolveSessionTranscriptIdentity(...) when the code only needs public session identity.
  • Use resolveSessionTranscriptTarget(...) when the code needs a structured transcript operation target.
  • Avoid reading or constructing legacy transcript file targets directly.
  • Keep the legacy helper only while your declared compatibility range still supports older OpenClaw versions that require it.
  • See Runtime API and Plugin SDK subpaths.
  • Rerun clawhub package validate <path-to-plugin>.

​
sdk-session-transcript-low-level

The plugin still uses deprecated low-level transcript helpers such as appendSessionTranscriptMessage or emitSessionTranscriptUpdate.
  • Use appendSessionTranscriptMessageByIdentity(...) for transcript appends.
  • Use publishSessionTranscriptUpdateByIdentity(...) for transcript update notifications.
  • Prefer the structured transcript runtime surface so OpenClaw can apply the correct transaction boundaries and identity handling.
  • Keep low-level transcript helpers only while your declared compatibility range still supports older OpenClaw versions that require them.
  • See Runtime API and Plugin SDK subpaths.
  • Rerun clawhub package validate <path-to-plugin>.

​
legacy-before-agent-start

The plugin still uses the legacy before_agent_start hook.
  • Move model or provider override work to before_model_resolve.
  • Move prompt or context mutation work to before_prompt_build.
  • Keep before_agent_start only while your declared compatibility range still supports older OpenClaw versions that require it.
  • See Hooks and Plugin compatibility.
  • Rerun clawhub package validate <path-to-plugin>.

​
provider-auth-env-vars

The manifest still uses legacy providerAuthEnvVars provider auth metadata.
  • Mirror provider env-var metadata into setup.providers[].envVars.
  • Keep providerAuthEnvVars only as compatibility metadata while your supported OpenClaw range still needs it.
  • See setup reference and SDK migration.
  • Rerun clawhub package validate <path-to-plugin>.

​
channel-env-vars

The manifest uses legacy or older channel env-var metadata without the current setup or config metadata ClawHub expects.
  • Keep channel env-var metadata declarative so OpenClaw can inspect setup status without loading channel runtime.
  • Mirror env-driven channel setup into the current setup, channel config, or package channel metadata used by your plugin shape.
  • Keep channelEnvVars only as compatibility metadata while older supported OpenClaw versions still require it.
  • See Plugin manifest and Channel plugins.
  • Rerun clawhub package validate <path-to-plugin>.

​
Security manifest

​
security-manifest-schema-unavailable

The package ships openclaw.security.json with a schema reference that ClawHub does not recognize as available.
  • Remove the schema URL if it is advisory-only.
  • Use a documented versioned schema only after OpenClaw publishes one.
  • Rerun clawhub package validate <path-to-plugin>.

​
unrecognized-security-manifest

The package ships an unsupported security manifest file.
  • Remove openclaw.security.json until OpenClaw documents a versioned security manifest schema and ClawHub behavior.
  • Keep security-sensitive behavior documented in your public package docs or README until the manifest contract exists.
  • Rerun clawhub package validate <path-to-plugin>.