Plugin validation fixes

기준일: 2026-07-26
공식 기준: Plugin validation fixes

Plugin validation fixes 문서는 OpenClaw 공식 문서(clawhub/plugin-validation-fixes)를 한국어로 정리한 가이드입니다. Fix ClawHub plugin package validation findings before publishing 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Fix ClawHub plugin package validation findings before publishing

한국어 가이드 범위: clawhub/plugin-validation-fixes 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Plugin validation fixes
• Author-facing findings
• Package metadata
• package-json-missing
• package-openclaw-metadata-missing
• package-openclaw-entry-missing
• package-entrypoint-missing
• package-install-metadata-incomplete
• package-plugin-api-compat-missing
• package-min-host-version-drift
• package-manifest-version-drift
• package-openclaw-unsupported-metadata
• Published artifact
• package-npm-pack-unavailable
• package-npm-pack-entrypoint-missing
• package-npm-pack-metadata-missing
• Manifest metadata
• manifest-name-missing
• manifest-unknown-fields
• manifest-unknown-contracts
• SDK and compatibility migration
• legacy-root-sdk-import
• reserved-sdk-import
• sdk-load-session-store
• sdk-session-store-write
• sdk-session-file-helper
• sdk-session-transcript-file-target
• sdk-session-transcript-low-level
• legacy-before-agent-start
• provider-auth-env-vars

상세 내용

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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

clawhub package validate <path-to-plugin>

Author-facing findings

Code	Start here
package-json-missing	Add package metadata
package-openclaw-metadata-missing	Add the package openclaw block
package-openclaw-entry-missing	Declare OpenClaw package entrypoints
package-entrypoint-missing	Publish the declared entrypoint
package-install-metadata-incomplete	Complete install metadata
package-plugin-api-compat-missing	Declare plugin API compatibility
package-min-host-version-drift	Align minimum host version
package-manifest-version-drift	Align package and manifest versions
package-openclaw-unsupported-metadata	Remove unsupported OpenClaw package metadata
package-npm-pack-unavailable	Make the npm artifact packable
package-npm-pack-entrypoint-missing	Include entrypoints in npm pack output
package-npm-pack-metadata-missing	Include metadata in npm pack output
manifest-name-missing	Add a manifest display name
manifest-unknown-fields	Remove unsupported manifest fields
manifest-unknown-contracts	Remove unsupported contract keys
legacy-root-sdk-import	Replace root SDK imports
reserved-sdk-import	Remove reserved SDK imports
sdk-load-session-store	Replace whole-session-store access
sdk-session-store-write	Replace whole-session-store writes
sdk-session-file-helper	Replace session file-path helpers
sdk-session-transcript-file-target	Replace legacy transcript file targets
sdk-session-transcript-low-level	Replace low-level transcript helpers
legacy-before-agent-start	Replace before_agent_start
provider-auth-env-vars	Move provider env vars to setup metadata
channel-env-vars	Mirror channel env vars in current metadata
security-manifest-schema-unavailable	Remove unavailable security manifest schema references
unrecognized-security-manifest	Remove unsupported security manifest files

Package metadata

이 섹션의 세부 항목은 공식 문서 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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• 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
• Rerun clawhub package validate <path-to-plugin>.

package-openclaw-metadata-missing

The package has package.json, but it does not declare OpenClaw package metadata.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Add package.json#openclaw.
• Include entrypoint metadata such as openclaw.extensions or
• Add compatibility and install metadata when the package will be published or
• 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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Add openclaw.extensions for native plugin entrypoints.
• Add openclaw.runtimeExtensions when the published package should load built
• Keep all entrypoint paths inside the package directory.
• See Plugin entry points and
• 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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Check each path in openclaw.extensions, openclaw.runtimeExtensions,
• 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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Fill openclaw.install with the supported install source, such as
• Set openclaw.install.defaultChoice when more than one install source is
• 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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Add openclaw.compat.pluginApi to package.json.
• Use the OpenClaw plugin API version or semver floor that you built and tested
• Keep this separate from the package version. The package version describes the
• 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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Check openclaw.install.minHostVersion.
• Check any OpenClaw build metadata in the package, such as the OpenClaw version
• Align the minimum host version with the host version range the package
• 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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Prefer package.json#version as the package release version.
• If openclaw.plugin.json also has version, update it to match or remove
• 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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

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

Published artifact

이 섹션의 세부 항목은 공식 문서 Published artifact를 참고하세요.

package-npm-pack-unavailable

The package cannot be packed into the artifact ClawHub would inspect or publish.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Run npm pack --dry-run from the package root.
• Fix invalid package metadata, broken lifecycle scripts, or files entries that
• 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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• 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
• 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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• 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
• Update files or .npmignore so package metadata is not excluded.
• See Building plugins.
• Rerun clawhub package validate <path-to-plugin>.

Manifest metadata

이 섹션의 세부 항목은 공식 문서 Manifest metadata를 참고하세요.

manifest-name-missing

The native plugin manifest does not include a display name.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• 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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Compare each top-level field with the
• Remove custom fields from openclaw.plugin.json.
• Move package or install metadata into supported package.json#openclaw fields
• Rerun clawhub package validate <path-to-plugin>.

manifest-unknown-contracts

The manifest declares unsupported keys inside contracts.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Compare each key under contracts with the
• Remove unsupported contract keys.
• Move runtime behavior into plugin registration code, and keep contracts
• Rerun clawhub package validate <path-to-plugin>.

SDK and compatibility migration

이 섹션의 세부 항목은 공식 문서 SDK and compatibility migration를 참고하세요.

legacy-root-sdk-import

The plugin imports from the deprecated root SDK barrel: openclaw/plugin-sdk.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• 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
• Rerun clawhub package validate <path-to-plugin>.

reserved-sdk-import

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

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Replace reserved OpenClaw internal SDK imports with documented public
• If the behavior has no public SDK, keep the helper inside your package or
• Use Plugin SDK subpaths and
• Rerun clawhub package validate <path-to-plugin>.

sdk-load-session-store

The plugin still uses the deprecated whole-session-store helper loadSessionStore.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Use getSessionEntry(...) or listSessionEntries(...) when reading session
• Use patchSessionEntry(...) or upsertSessionEntry(...) when writing session
• Avoid loading, mutating, and saving the whole session store object.
• Keep loadSessionStore(...) only while your declared compatibility range
• See Runtime API and
• 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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Use patchSessionEntry(...) when updating fields on an existing session
• 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
• See Runtime API and
• 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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Use getSessionEntry(...) to read session metadata by agent and session
• Use patchSessionEntry(...) or upsertSessionEntry(...) to persist session
• Use transcript identity or target helpers when the code is preparing a
• Do not persist or depend on legacy transcript file paths.
• See Runtime API and
• Rerun clawhub package validate <path-to-plugin>.

sdk-session-transcript-file-target

The plugin still uses the deprecated transcript file target helper resolveSessionTranscriptLegacyFileTarget.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Use resolveSessionTranscriptIdentity(...) when the code only needs public
• Use resolveSessionTranscriptTarget(...) when the code needs a structured
• Avoid reading or constructing legacy transcript file targets directly.
• Keep the legacy helper only while your declared compatibility range still
• See Runtime API and
• 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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Use appendSessionTranscriptMessageByIdentity(...) for transcript appends.
• Use publishSessionTranscriptUpdateByIdentity(...) for transcript update
• Prefer the structured transcript runtime surface so OpenClaw can apply the
• Keep low-level transcript helpers only while your declared compatibility range
• See Runtime API and
• Rerun clawhub package validate <path-to-plugin>.

legacy-before-agent-start

The plugin still uses the legacy before_agent_start hook.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• 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
• See Hooks and
• Rerun clawhub package validate <path-to-plugin>.

provider-auth-env-vars

The manifest still uses legacy providerAuthEnvVars provider auth metadata.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Mirror provider env-var metadata into setup.providers[].envVars.
• Keep providerAuthEnvVars only as compatibility metadata while your supported
• See setup reference and
• 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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Keep channel env-var metadata declarative so OpenClaw can inspect setup status
• Mirror env-driven channel setup into the current setup, channel config, or
• Keep channelEnvVars only as compatibility metadata while older supported
• See Plugin manifest and
• Rerun clawhub package validate <path-to-plugin>.

Security manifest

이 섹션의 세부 항목은 공식 문서 Security manifest를 참고하세요.

security-manifest-schema-unavailable

The package ships openclaw.security.json with a schema reference that ClawHub does not recognize as available.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• 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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Remove openclaw.security.json until OpenClaw documents a versioned security
• Keep security-sensitive behavior documented in your public package docs or
• Rerun clawhub package validate <path-to-plugin>.

관련 문서

주요 항목:

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

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/clawhub/plugin-validation-fixes
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

clawhub package validate <path-to-plugin>

관련 링크

• 공식 원문: clawhub/plugin-validation-fixes
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.