Fix ClawHub Plugin Validation Findings Before Publishing

Plugin validation fixes

Before a plugin package is published, ClawHub runs validations and can also surface results from automated package scans. This document describes findings that plugin authors can act on, meaning issues they can resolve in their package metadata, manifest, SDK imports, or published artifact.

Internal Plugin Inspector coverage findings are excluded from this page. When a full report includes scanner maintenance codes that offer no author remediation steps, those codes are intended for OpenClaw maintainers, not plugin authors.

Once you have applied a fix, execute the following command again:

clawhub package validate <path-to-plugin>

Author-facing findings

Package metadata

package-json-missing

The package root is missing package.json, which means ClawHub cannot detect the npm package name, version, entrypoints, or any OpenClaw metadata.

• Append package.json with name, version, and type.
• Insert an openclaw block if the delivered package includes an OpenClaw plugin.
• Refer to Building plugins for a minimal package example and Plugin manifest for the distinction between package and manifest.
• Execute clawhub package validate <path-to-plugin> again.

package-openclaw-metadata-missing

Although the package includes package.json, OpenClaw package metadata is missing.

• Supply package.json#openclaw.
• Provide entrypoint metadata like openclaw.extensions or openclaw.runtimeExtensions.
• When the package is destined for ClawHub publishing or installation, add compatibility and install metadata.
• Consult package.json fields that affect discovery.
• Run clawhub package validate <path-to-plugin> once more.

package-openclaw-entry-missing

Package metadata is present, but no OpenClaw runtime entrypoint is declared.

• For native plugin entrypoints, add openclaw.extensions.
• When the published package should load compiled JavaScript, add openclaw.runtimeExtensions.
• Ensure every entrypoint path resides within the package directory.
• See Plugin entry points and package.json fields that affect discovery.
• Rerun clawhub package validate <path-to-plugin>.

package-entrypoint-missing

An OpenClaw entrypoint is declared, but the file it points to is absent from the package under validation.

• Verify each path in openclaw.extensions, openclaw.runtimeExtensions, openclaw.setupEntry, and openclaw.runtimeSetupEntry.
• If the entrypoint is produced into dist, build the package first.
• If the entrypoint location changed, refresh the metadata.
• Refer to Plugin entry points.
• Execute clawhub package validate <path-to-plugin> again.

package-install-metadata-incomplete

ClawHub cannot determine how to install or update the package.

• Populate openclaw.install with the supported install source, for example clawhubSpec, npmSpec, or localPath.
• When multiple install sources are offered, set openclaw.install.defaultChoice.
• Use openclaw.install.minHostVersion to specify the minimum OpenClaw host version.
• See package.json fields that affect discovery.
• Run clawhub package validate <path-to-plugin> once more.

package-plugin-api-compat-missing

The package does not specify the OpenClaw plugin API range it supports.

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

package-min-host-version-drift

The package minimum host version conflicts with the OpenClaw version metadata used during the build.

• Inspect openclaw.install.minHostVersion.
• Examine any OpenClaw build metadata in the package, such as the OpenClaw version employed during release.
• Ensure the minimum host version matches the host version range the package actually supports.
• See package.json fields that affect discovery.
• Execute clawhub package validate <path-to-plugin> again.

package-manifest-version-drift

The package version and the plugin manifest version do not match.

• Use package.json#version as the preferred package release version.
• If openclaw.plugin.json also contains version, update it to match or remove stale manifest version metadata when the package metadata is authoritative.
• After modifying published metadata, publish a new package version.
• Refer to Plugin manifest.
• Run clawhub package validate <path-to-plugin> once more.

package-openclaw-unsupported-metadata

The package.json#openclaw block holds fields that are not recognized as valid OpenClaw package metadata.

• Drop unsupported entries like openclaw.bundle.
• Preserve native plugin metadata inside openclaw.plugin.json.
• Retain package entrypoints, compatibility, install, setup, and catalog metadata in the package.json#openclaw fields that are supported.
• Refer to package.json fields that affect discovery.
• Execute clawhub package validate <path-to-plugin> again.

Published artifact

package-npm-pack-unavailable

The artifact that ClawHub would inspect or publish cannot be built from the package.

• From the package root, run npm pack --dry-run.
• Correct any invalid package metadata, broken lifecycle scripts, or files entries that prevent packing.
• If the package is meant for public release, delete private: true.
• Run clawhub package validate <path-to-plugin> once more.

package-npm-pack-entrypoint-missing

Although the package can be packed, the resulting artifact is missing the entrypoint files listed in package.json#openclaw.

• Use npm pack --dry-run to see which files would be included.
• Generate any entrypoints that require building before packing.
• Adjust files, .npmignore, or the build output so that the declared entrypoints are present.
• Check Plugin entry points.
• Rerun clawhub package validate <path-to-plugin>.

package-npm-pack-metadata-missing

OpenClaw metadata that exists in your source package is absent from the packed artifact.

• Inspect the metadata files included by running npm pack --dry-run.
• Confirm that package.json contains the openclaw block in the packed artifact.
• For a native OpenClaw plugin, verify that openclaw.plugin.json is included.
• Modify files or .npmignore so that package metadata is not omitted.
• See Building plugins.
• Run clawhub package validate <path-to-plugin> again.

Manifest metadata

manifest-name-missing

A display name is missing from the native plugin manifest.

• Insert a non-empty name field into openclaw.plugin.json.
• Make name readable by humans while keeping id as the stable machine identifier.
• Read Plugin manifest.
• Rerun clawhub package validate <path-to-plugin>.

manifest-unknown-fields

The plugin manifest contains top-level fields that OpenClaw does not recognise.

• Go through each top-level field against the manifest field reference.
• Strip custom fields from openclaw.plugin.json.
• Move package or install metadata into the package.json#openclaw fields that are supported, not into the manifest.
• Run clawhub package validate <path-to-plugin> again.

manifest-unknown-contracts

Under contracts, the manifest declares keys that are not supported.

• Check every key within contracts against the contracts reference.
• Delete unsupported contract keys.
• Place runtime behaviour in plugin registration code, and restrict contracts to static metadata about capability ownership.
• Execute clawhub package validate <path-to-plugin> once more.

SDK and compatibility migration

legacy-root-sdk-import

The plugin uses a deprecated root SDK barrel import: openclaw/plugin-sdk.

• Swap root-barrel imports for focused public subpath imports.
• For definePluginEntry, import from openclaw/plugin-sdk/plugin-entry.
• For channel entry helpers, import from openclaw/plugin-sdk/channel-core.
• Locate the correct narrow import using Import conventions and Plugin SDK subpaths.
• Rerun clawhub package validate <path-to-plugin>.

reserved-sdk-import

The plugin imports an SDK path that is reserved for bundled plugins or internal compatibility.

• Replace reserved OpenClaw internal SDK imports with documented public openclaw/plugin-sdk/* subpaths.
• If no public SDK provides the behaviour, keep the helper within your own package or request a public OpenClaw API.
• Choose a supported import by consulting Plugin SDK subpaths and SDK migration.
• Run clawhub package validate <path-to-plugin> again.

sdk-load-session-store

The plugin continues to rely on the outdated whole-session-store helper loadSessionStore.

• When retrieving session state, use getSessionEntry(...) or listSessionEntries(...).
• When saving session state, use patchSessionEntry(...) or upsertSessionEntry(...).
• Do not load, modify, or persist the entire session store object.
• Retain loadSessionStore(...) only if your declared compatibility range still supports older OpenClaw versions that depend on it.
• Refer to Runtime API and Plugin SDK subpaths.
• Run clawhub package validate <path-to-plugin> again.

sdk-session-store-write

A deprecated whole-session-store write helper, like saveSessionStore or updateSessionStore, is still being used by the plugin.

• To update fields on an existing session entry, use patchSessionEntry(...).
• To replace or create a session entry, use upsertSessionEntry(...).
• 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, for instance resolveSessionFilePath or resolveAndPersistSessionFile.

• To read session metadata by agent and session identity, use getSessionEntry(...).
• To persist session metadata, use patchSessionEntry(...) or upsertSessionEntry(...).
• When preparing a transcript operation, use transcript identity or target helpers.
• Do not persist or depend on legacy transcript file paths.
• Check Runtime API and Plugin SDK subpaths.
• Rerun clawhub package validate <path-to-plugin>.

sdk-session-transcript-file-target

The deprecated transcript file target helper resolveSessionTranscriptLegacyFileTarget is still in use by the plugin.

• Use resolveSessionTranscriptIdentity(...) when the code only requires public session identity.
• Use resolveSessionTranscriptTarget(...) when the code needs a structured transcript operation target.
• Avoid directly reading or constructing legacy transcript file targets.
• 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

Deprecated low-level transcript helpers, such as appendSessionTranscriptMessage or emitSessionTranscriptUpdate, are still used by the plugin.

• For transcript appends, use appendSessionTranscriptMessageByIdentity(...).
• For transcript update notifications, use publishSessionTranscriptUpdateByIdentity(...).
• 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.
• Refer to 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.
• Retain 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.
• Check 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 that ClawHub expects.

• Keep channel environment variable metadata declarative so OpenClaw can check setup status without loading the channel runtime.
• Reflect environment driven channel setup into the current setup, channel configuration, or package channel metadata that your plugin shape uses.
• Retain channelEnvVars solely as compatibility metadata while older supported OpenClaw versions still demand it.
• Refer to Plugin manifest and Channel plugins.
• Execute clawhub package validate <path-to-plugin> again.

Security manifest

security-manifest-schema-unavailable

The package includes openclaw.security.json with a schema reference that ClawHub does not consider available.

• Delete the schema URL if it is only advisory.
• Use a documented versioned schema only after OpenClaw releases one.
• Run clawhub package validate <path-to-plugin> once more.

unrecognized-security-manifest

The package includes 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 documentation or README until the manifest contract exists.
• Rerun clawhub package validate <path-to-plugin>.

Related

• ClawHub CLI
• ClawHub publishing
• Building plugins
• Plugin manifest
• Plugin entry points
• Plugin compatibility