Fehlerbehebung bei der Plugin-Validierung

ClawHub validiert Plugin-Pakete vor der Veröffentlichung und kann auch Befunde aus automatisierten Paket-Scans anzeigen. Diese Seite behandelt Befunde für Autoren, also Befunde, die Plugin-Autoren in ihren Paketmetadaten, im Manifest, in SDK- Importen oder im veröffentlichten Artefakt beheben können.

Interne Befunde zur Abdeckung durch den Plugin Inspector werden nicht behandelt. Wenn ein vollständiger Bericht Wartungscodes des Scanners ohne Hinweise zur Behebung durch Autoren enthält, sind diese für OpenClaw-Maintainer und nicht für Plugin-Autoren bestimmt.

Führen Sie nach jeder Korrektur erneut Folgendes aus:

clawhub package validate <path-to-plugin>

Befunde für Autoren

Paketmetadaten

package-json-missing

Das Stammverzeichnis des Pakets enthält kein package.json, sodass ClawHub das npm-Paket, seine Version, seine Einstiegspunkte oder seine OpenClaw-Metadaten nicht identifizieren kann.

• Fügen Sie package.json mit name, version und type hinzu.
• Fügen Sie einen openclaw-Block hinzu, wenn das Paket ein OpenClaw-Plugin ausliefert.
• Unter Plugins erstellen finden Sie ein minimales Paketbeispiel und unter Plugin-Manifest die Aufteilung zwischen Paket und Manifest.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

package-openclaw-metadata-missing

Das Paket enthält package.json, deklariert aber keine OpenClaw- Paketmetadaten.

• Fügen Sie package.json#openclaw hinzu.
• Nehmen Sie Einstiegspunktmetadaten wie openclaw.extensions oder openclaw.runtimeExtensions auf.
• Fügen Sie Kompatibilitäts- und Installationsmetadaten hinzu, wenn das Paket über ClawHub veröffentlicht oder installiert werden soll.
• Siehe package.json-Felder, die die Erkennung beeinflussen.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

package-openclaw-entry-missing

Die Paketmetadaten sind vorhanden, deklarieren aber keinen OpenClaw-Laufzeit- Einstiegspunkt.

• Fügen Sie openclaw.extensions für native Plugin-Einstiegspunkte hinzu.
• Fügen Sie openclaw.runtimeExtensions hinzu, wenn das veröffentlichte Paket kompiliertes JavaScript laden soll.
• Belassen Sie alle Einstiegspunktpfade innerhalb des Paketverzeichnisses.
• Siehe Plugin-Einstiegspunkte und package.json-Felder, die die Erkennung beeinflussen.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

package-entrypoint-missing

Das Paket deklariert einen OpenClaw-Einstiegspunkt, aber die referenzierte Datei fehlt im validierten Paket.

• Prüfen Sie jeden Pfad in openclaw.extensions, openclaw.runtimeExtensions, openclaw.setupEntry und openclaw.runtimeSetupEntry.
• Erstellen Sie das Paket, wenn der Einstiegspunkt in dist generiert wird.
• Aktualisieren Sie die Metadaten, wenn der Einstiegspunkt verschoben wurde.
• Siehe Plugin-Einstiegspunkte.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

package-install-metadata-incomplete

ClawHub kann nicht feststellen, wie das Paket installiert oder aktualisiert werden soll.

• Füllen Sie openclaw.install mit der unterstützten Installationsquelle aus, beispielsweise clawhubSpec, npmSpec oder localPath.
• Legen Sie openclaw.install.defaultChoice fest, wenn mehr als eine Installationsquelle verfügbar ist.
• Verwenden Sie openclaw.install.minHostVersion für die minimale OpenClaw-Hostversion.
• Siehe package.json-Felder, die die Erkennung beeinflussen.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

package-plugin-api-compat-missing

Das Paket deklariert nicht den unterstützten Versionsbereich der OpenClaw-Plugin-API.

• Fügen Sie openclaw.compat.pluginApi zu package.json hinzu.
• Verwenden Sie die Version der OpenClaw-Plugin-API oder die SemVer-Untergrenze, mit der Sie das Paket erstellt und getestet haben.
• Halten Sie dies von der Paketversion getrennt. Die Paketversion beschreibt das Plugin-Release; openclaw.compat.pluginApi beschreibt den Host-API-Vertrag.
• Siehe package.json-Felder, die die Erkennung beeinflussen.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

package-min-host-version-drift

Die minimale Hostversion des Pakets stimmt nicht mit den OpenClaw-Versionsmetadaten überein, mit denen das Paket erstellt wurde.

• Prüfen Sie openclaw.install.minHostVersion.
• Prüfen Sie alle OpenClaw-Build-Metadaten im Paket, beispielsweise die während des Releases verwendete OpenClaw-Version.
• Gleichen Sie die minimale Hostversion an den Hostversionsbereich an, den das Paket tatsächlich unterstützt.
• Siehe package.json-Felder, die die Erkennung beeinflussen.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

package-manifest-version-drift

Die Paketversion und die Version des Plugin-Manifests stimmen nicht überein.

• Verwenden Sie vorzugsweise package.json#version als Release-Version des Pakets.
• Wenn openclaw.plugin.json ebenfalls version enthält, aktualisieren Sie es entsprechend oder entfernen Sie veraltete Versionsmetadaten aus dem Manifest, wenn die Paketmetadaten maßgeblich sind.
• Veröffentlichen Sie nach einer Änderung veröffentlichter Metadaten eine neue Paketversion.
• Siehe Plugin-Manifest.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

package-openclaw-unsupported-metadata

Der package.json#openclaw-Block enthält Felder, die nicht als OpenClaw-Paketmetadaten unterstützt werden.

• Entfernen Sie nicht unterstützte Felder wie openclaw.bundle.
• Belassen Sie native Plugin-Metadaten in openclaw.plugin.json.
• Belassen Sie Paketeinstiegspunkte sowie Kompatibilitäts-, Installations-, Setup- und Katalogmetadaten in unterstützten package.json#openclaw-Feldern.
• Siehe package.json-Felder, die die Erkennung beeinflussen.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

Veröffentlichtes Artefakt

package-npm-pack-unavailable

Das Paket kann nicht in das Artefakt gepackt werden, das ClawHub prüfen oder veröffentlichen würde.

• Führen Sie npm pack --dry-run im Stammverzeichnis des Pakets aus.
• Beheben Sie ungültige Paketmetadaten, fehlerhafte Lebenszyklusskripte oder Dateieinträge, die das Packen verhindern.
• Entfernen Sie private: true, wenn dieses Paket für eine öffentliche Veröffentlichung vorgesehen ist.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

package-npm-pack-entrypoint-missing

Das Paket kann gepackt werden, aber das gepackte Artefakt enthält nicht die in package.json#openclaw deklarierten Einstiegspunktdateien.

• Führen Sie npm pack --dry-run aus und prüfen Sie die Dateien, die aufgenommen würden.
• Erstellen Sie generierte Einstiegspunkte vor dem Packen.
• Aktualisieren Sie files, .npmignore oder die Build-Ausgabe, damit deklarierte Einstiegspunkte aufgenommen werden.
• Siehe Plugin-Einstiegspunkte.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

package-npm-pack-metadata-missing

Im gepackten Artefakt fehlen OpenClaw-Metadaten, die in Ihrem Quellpaket vorhanden sind.

• Führen Sie npm pack --dry-run aus und prüfen Sie die enthaltenen Metadatendateien.
• Stellen Sie sicher, dass package.json den Block openclaw im gepackten Artefakt enthält.
• Stellen Sie sicher, dass openclaw.plugin.json enthalten ist, wenn das Paket ein natives OpenClaw-Plugin ist.
• Aktualisieren Sie files oder .npmignore, damit Paketmetadaten nicht ausgeschlossen werden.
• Siehe Plugins erstellen.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

Manifestmetadaten

manifest-name-missing

Das native Plugin-Manifest enthält keinen Anzeigenamen.

• Fügen Sie openclaw.plugin.json ein nicht leeres Feld name hinzu.
• Halten Sie name für Menschen lesbar und verwenden Sie id weiterhin als stabile Maschinen-ID.
• Siehe Plugin-Manifest.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

manifest-unknown-fields

Das Plugin-Manifest enthält Felder auf oberster Ebene, die OpenClaw nicht unterstützt.

• Vergleichen Sie jedes Feld auf oberster Ebene mit der Referenz der Manifestfelder.
• Entfernen Sie benutzerdefinierte Felder aus openclaw.plugin.json.
• Verschieben Sie Paket- oder Installationsmetadaten in unterstützte Felder von package.json#openclaw statt in das Manifest.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

manifest-unknown-contracts

Das Manifest deklariert nicht unterstützte Schlüssel innerhalb von contracts.

• Vergleichen Sie jeden Schlüssel unter contracts mit der Referenz der Verträge.
• Entfernen Sie nicht unterstützte Vertragsschlüssel.
• Verschieben Sie das Laufzeitverhalten in den Plugin-Registrierungscode und beschränken Sie contracts auf statische Metadaten zur Zuständigkeit für Funktionen.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

SDK- und Kompatibilitätsmigration

legacy-root-sdk-import

Das Plugin importiert aus dem veralteten SDK-Root-Barrel: openclaw/plugin-sdk.

• Ersetzen Sie Importe aus dem Root-Barrel durch gezielte Importe aus öffentlichen Unterpfaden.
• Verwenden Sie openclaw/plugin-sdk/plugin-entry für definePluginEntry.
• Verwenden Sie openclaw/plugin-sdk/channel-core für Hilfsfunktionen von Kanaleinstiegspunkten.
• Verwenden Sie Importkonventionen und Unterpfade des Plugin-SDKs, um den spezifischen Import zu finden.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

reserved-sdk-import

Das Plugin importiert einen SDK-Pfad, der gebündelten Plugins oder der internen Kompatibilität vorbehalten ist.

• Ersetzen Sie reservierte interne OpenClaw-SDK-Importe durch dokumentierte öffentliche Unterpfade von openclaw/plugin-sdk/*.
• Wenn für das Verhalten kein öffentliches SDK verfügbar ist, behalten Sie die Hilfsfunktion in Ihrem Paket oder fordern Sie eine öffentliche OpenClaw-API an.
• Verwenden Sie Unterpfade des Plugin-SDKs und SDK-Migration, um einen unterstützten Import auszuwählen.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

sdk-load-session-store

Das Plugin verwendet weiterhin die veraltete Hilfsfunktion für den gesamten Sitzungsspeicher loadSessionStore.

• Verwenden Sie getSessionEntry(...) oder listSessionEntries(...), wenn Sie den Sitzungszustand lesen.
• Verwenden Sie patchSessionEntry(...) oder upsertSessionEntry(...), wenn Sie den Sitzungszustand schreiben.
• Vermeiden Sie es, das gesamte Sitzungsspeicherobjekt zu laden, zu verändern und zu speichern.
• Behalten Sie loadSessionStore(...) nur bei, solange Ihr deklarierter Kompatibilitätsbereich noch ältere OpenClaw-Versionen unterstützt, die diese Hilfsfunktion benötigen.
• Siehe Laufzeit-API und Unterpfade des Plugin-SDKs.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

sdk-session-store-write

Das Plugin verwendet weiterhin eine veraltete Schreibhilfsfunktion für den gesamten Sitzungsspeicher, beispielsweise saveSessionStore oder updateSessionStore.

• Verwenden Sie patchSessionEntry(...), wenn Sie Felder eines vorhandenen Sitzungseintrags aktualisieren.
• Verwenden Sie upsertSessionEntry(...), wenn Sie einen Sitzungseintrag ersetzen oder erstellen.
• Vermeiden Sie es, das gesamte Sitzungsspeicherobjekt zu laden, zu verändern und zu speichern.
• Behalten Sie Schreibhilfsfunktionen für den gesamten Speicher nur bei, solange Ihr deklarierter Kompatibilitätsbereich noch ältere OpenClaw-Versionen unterstützt, die sie benötigen.
• Siehe Laufzeit-API und Unterpfade des Plugin-SDKs.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

sdk-session-file-helper

Das Plugin verwendet weiterhin veraltete Hilfsfunktionen für Sitzungspfade, beispielsweise resolveSessionFilePath oder resolveAndPersistSessionFile.

• Verwenden Sie getSessionEntry(...), um Sitzungsmetadaten anhand der Agenten- und Sitzungsidentität zu lesen.
• Verwenden Sie patchSessionEntry(...) oder upsertSessionEntry(...), um Sitzungsmetadaten dauerhaft zu speichern.
• Verwenden Sie Hilfsfunktionen für die Transkriptidentität oder das Transkriptziel, wenn der Code einen Transkriptvorgang vorbereitet.
• Speichern Sie keine veralteten Transkriptdateipfade dauerhaft und machen Sie sich nicht von ihnen abhängig.
• Siehe Laufzeit-API und Unterpfade des Plugin-SDKs.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

sdk-session-transcript-file-target

Das Plugin verwendet weiterhin die veraltete Hilfsfunktion für Transkriptdateiziele resolveSessionTranscriptLegacyFileTarget.

• Verwenden Sie resolveSessionTranscriptIdentity(...), wenn der Code nur die öffentliche Sitzungsidentität benötigt.
• Verwenden Sie resolveSessionTranscriptTarget(...), wenn der Code ein strukturiertes Ziel für einen Transkriptvorgang benötigt.
• Vermeiden Sie es, veraltete Transkriptdateiziele direkt zu lesen oder zu erstellen.
• Behalten Sie die veraltete Hilfsfunktion nur bei, solange Ihr deklarierter Kompatibilitätsbereich noch ältere OpenClaw-Versionen unterstützt, die sie benötigen.
• Siehe Laufzeit-API und Unterpfade des Plugin-SDKs.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

sdk-session-transcript-low-level

Das Plugin verwendet weiterhin veraltete systemnahe Transkripthilfsfunktionen, beispielsweise appendSessionTranscriptMessage oder emitSessionTranscriptUpdate.

• Verwenden Sie appendSessionTranscriptMessageByIdentity(...), um Transkripte zu ergänzen.
• Verwenden Sie publishSessionTranscriptUpdateByIdentity(...) für Benachrichtigungen über Transkriptaktualisierungen.
• Bevorzugen Sie die strukturierte Transkript-Laufzeitschnittstelle, damit OpenClaw die korrekten Transaktionsgrenzen und die Identitätsverarbeitung anwenden kann.
• Behalten Sie systemnahe Transkripthilfsfunktionen nur bei, solange Ihr deklarierter Kompatibilitätsbereich noch ältere OpenClaw-Versionen unterstützt, die sie benötigen.
• Siehe Laufzeit-API und Unterpfade des Plugin-SDKs.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

legacy-before-agent-start

Das Plugin verwendet weiterhin den veralteten Hook before_agent_start.

• Verschieben Sie Überschreibungen des Modells oder Providers nach before_model_resolve.
• Verschieben Sie Änderungen an Prompt oder Kontext nach before_prompt_build.
• Behalten Sie before_agent_start nur bei, solange Ihr deklarierter Kompatibilitätsbereich noch ältere OpenClaw-Versionen unterstützt, die diesen Hook benötigen.
• Siehe Hooks und Plugin-Kompatibilität.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

provider-auth-env-vars

Das Manifest verwendet weiterhin veraltete Metadaten für die Provider-Authentifizierung in providerAuthEnvVars.

• Spiegeln Sie die Metadaten der Provider-Umgebungsvariablen nach setup.providers[].envVars.
• Behalten Sie providerAuthEnvVars nur als Kompatibilitätsmetadaten bei, solange Ihr unterstützter OpenClaw-Versionsbereich sie noch benötigt.
• Siehe Setup-Referenz und SDK-Migration.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

channel-env-vars

Das Manifest verwendet veraltete oder ältere Metadaten für Kanalumgebungsvariablen ohne die aktuellen Setup- oder Konfigurationsmetadaten, die ClawHub erwartet.

• Halten Sie Metadaten für Kanalumgebungsvariablen deklarativ, damit OpenClaw den Setup-Status prüfen kann, ohne die Kanallaufzeit zu laden.
• Spiegeln Sie die umgebungsvariablengesteuerte Kanaleinrichtung in die aktuellen Setup-, Kanalkonfigurations- oder Paketkanalmetadaten, die von Ihrer Plugin-Struktur verwendet werden.
• Behalten Sie channelEnvVars nur als Kompatibilitätsmetadaten bei, solange ältere unterstützte OpenClaw-Versionen sie noch benötigen.
• Siehe Plugin-Manifest und Kanal-Plugins.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

Sicherheitsmanifest

security-manifest-schema-unavailable

Das Paket liefert openclaw.security.json mit einem Schemaverweis aus, den ClawHub nicht als verfügbar erkennt.

• Entfernen Sie die Schema-URL, wenn sie nur informativen Charakter hat.
• Verwenden Sie ein dokumentiertes versioniertes Schema erst, nachdem OpenClaw eines veröffentlicht hat.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

unrecognized-security-manifest

Das Paket liefert eine nicht unterstützte Sicherheitsmanifestdatei aus.

• Entfernen Sie openclaw.security.json, bis OpenClaw ein versioniertes Schema für Sicherheitsmanifeste und das Verhalten von ClawHub dokumentiert.
• Dokumentieren Sie sicherheitsrelevantes Verhalten weiterhin in Ihrer öffentlichen Paketdokumentation oder README, bis der Manifestvertrag verfügbar ist.
• Führen Sie clawhub package validate <path-to-plugin> erneut aus.

Verwandte Themen

• ClawHub-CLI
• Veröffentlichen auf ClawHub
• Plugins erstellen
• Plugin-Manifest
• Plugin-Einstiegspunkte
• Plugin-Kompatibilität