Plugin-Kompatibilität

OpenClaw hält ältere Plugin-Verträge über benannte Kompatibilitätsadapter verdrahtet, bevor sie entfernt werden. Das schützt vorhandene gebündelte und externe Plugins, während sich die SDK-, Manifest-, Setup-, Konfigurations- und Agent-Runtime-Verträge weiterentwickeln.

Kompatibilitäts-Registry

Plugin-Kompatibilitätsverträge werden in der Core-Registry unter src/plugins/compat/registry.ts nachverfolgt.

Jeder Eintrag enthält:

• einen stabilen Kompatibilitätscode
• Status: active, deprecated, removal-pending oder removed
• Owner: SDK, Konfiguration, Setup, Kanal, Provider, Plugin-Ausführung, Agent-Runtime oder Core
• Einführungs- und Deprecation-Daten, sofern zutreffend
• Hinweise zum Ersatz
• Dokumentation, Diagnosen und Tests, die das alte und neue Verhalten abdecken

Die Registry ist die Quelle für die Maintainer-Planung und künftige Prüfungen durch den Plugin-Inspector. Wenn sich ein Plugin-seitiges Verhalten ändert, fügen Sie im selben Change, der den Adapter hinzufügt, den Kompatibilitätseintrag hinzu oder aktualisieren Sie ihn.

Kompatibilität für Doctor-Reparaturen und Migrationen wird separat unter src/commands/doctor/shared/deprecation-compat.ts nachverfolgt. Diese Einträge decken alte Konfigurationsformen, Install-Ledger-Layouts und Reparatur-Shims ab, die möglicherweise verfügbar bleiben müssen, nachdem der Runtime-Kompatibilitätspfad entfernt wurde.

Release-Sweeps sollten beide Registries prüfen. Löschen Sie eine Doctor-Migration nicht nur deshalb, weil der passende Runtime- oder Konfigurations-Kompatibilitätseintrag abgelaufen ist; prüfen Sie zuerst, dass es keinen unterstützten Upgrade-Pfad gibt, der die Reparatur noch benötigt. Validieren Sie außerdem jede Ersatz-Annotation während der Release-Planung erneut, weil sich Plugin-Ownership und Konfigurationsumfang ändern können, wenn Provider und Kanäle aus dem Core ausgelagert werden.

Plugin-Inspector-Paket

Der Plugin-Inspector sollte außerhalb des zentralen OpenClaw-Repos als separates Paket/Repository liegen, gestützt auf die versionierten Kompatibilitäts- und Manifest-Verträge.

Die Day-one-CLI sollte sein:

openclaw-plugin-inspector ./my-plugin

Sie sollte ausgeben:

• Manifest-/Schema-Validierung
• die geprüfte Vertragskompatibilitätsversion
• Prüfungen der Install-/Quellmetadaten
• Cold-Path-Importprüfungen
• Deprecation- und Kompatibilitätswarnungen

Verwenden Sie --json für stabile maschinenlesbare Ausgabe in CI-Annotationen. OpenClaw Core sollte Verträge und Fixtures bereitstellen, die der Inspector verwenden kann, sollte das Inspector-Binary aber nicht aus dem Hauptpaket openclaw veröffentlichen.

Maintainer-Akzeptanz-Lane

Verwenden Sie die Crabbox-gestützte Blacksmith Testbox für die Akzeptanz-Lane installierbarer Pakete, wenn Sie den externen Inspector gegen OpenClaw-Plugin-Pakete validieren. Führen Sie sie aus einem sauberen OpenClaw-Checkout aus, nachdem das Paket gebaut wurde:

pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "pnpm install && pnpm build && npm exec --yes @openclaw/[email protected] -- ./extensions/telegram --json"pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/[email protected] -- ./extensions/discord --json"pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/[email protected] -- <clawhub-plugin-dir> --json"

Halten Sie diese Lane für Maintainer opt-in, weil sie ein externes npm-Paket installiert und möglicherweise Plugin-Pakete prüft, die außerhalb des Repos geklont wurden. Die lokalen Repo-Guards decken die SDK-Export-Map, Kompatibilitäts-Registry-Metadaten, den Abbau veralteter SDK-Imports und die Import-Grenzen gebündelter Plugins ab; Testbox-Inspector-Proof deckt das Paket so ab, wie externe Plugin-Autoren es konsumieren.

Deprecation-Richtlinie

OpenClaw sollte einen dokumentierten Plugin-Vertrag nicht im selben Release entfernen, das seinen Ersatz einführt.

Die Migrationssequenz ist:

1. Fügen Sie den neuen Vertrag hinzu.
2. Halten Sie das alte Verhalten über einen benannten Kompatibilitätsadapter verdrahtet.
3. Geben Sie Diagnosen oder Warnungen aus, wenn Plugin-Autoren handeln können.
4. Dokumentieren Sie Ersatz und Zeitplan.
5. Testen Sie alte und neue Pfade.
6. Warten Sie das angekündigte Migrationsfenster ab.
7. Entfernen Sie nur mit ausdrücklicher Breaking-Release-Genehmigung.

Veraltete Einträge müssen ein Startdatum für Warnungen, einen Ersatz, einen Dokumentationslink und ein endgültiges Entfernungsdatum enthalten, das höchstens drei Monate nach Beginn der Warnungen liegt. Fügen Sie keinen veralteten Kompatibilitätspfad mit offenem Entfernungsfenster hinzu, es sei denn, Maintainer entscheiden ausdrücklich, dass es sich um permanente Kompatibilität handelt, und markieren ihn stattdessen als active.

Aktuelle Kompatibilitätsbereiche

Aktuelle Kompatibilitätseinträge umfassen:

• alte breite SDK-Imports wie openclaw/plugin-sdk/compat
• alte Hook-only-Plugin-Formen und before_agent_start
• alte activate(api)-Plugin-Einstiegspunkte, während Plugins zu register(api) migrieren
• alte SDK-Aliasse wie openclaw/extension-api, openclaw/plugin-sdk/channel-runtime, openclaw/plugin-sdk/command-auth Status-Builder, openclaw/plugin-sdk/test-utils (ersetzt durch fokussierte openclaw/plugin-sdk/*-Test-Subpfade) sowie die Typaliase ClawdbotConfig / OpenClawSchemaType
• Allowlist- und Enablement-Verhalten gebündelter Plugins
• alte Provider-/Kanal-Env-Var-Manifest-Metadaten
• alte Provider-Plugin-Hooks und Typaliase, während Provider zu expliziten Katalog-, Auth-, Thinking-, Replay- und Transport-Hooks wechseln
• alte Runtime-Aliasse wie api.runtime.taskFlow, api.runtime.subagent.getSession, api.runtime.stt und veraltete api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...)
• alte Split-Registrierung von Memory-Plugins, während Memory-Plugins zu registerMemoryCapability wechseln
• alte Kanal-SDK-Helfer für native Nachrichtenschemas, Mention-Gating, Inbound-Envelope-Formatierung und Verschachtelung von Approval-Capabilities
• alte Kanal-Routenschlüssel- und Comparable-Target-Helferaliase, während Plugins zu openclaw/plugin-sdk/channel-route wechseln
• Aktivierungshinweise, die durch Ownership für Manifest-Contributions ersetzt werden
• setup-api-Runtime-Fallback, während Setup-Deskriptoren zu kalten setup.requiresRuntime: false-Metadaten wechseln
• Provider-discovery-Hooks, während Provider-Katalog-Hooks zu catalog.run(...) wechseln
• Kanal-Metadaten showConfigured / showInSetup, während Kanalpakete zu openclaw.channel.exposure wechseln
• alte Runtime-Policy-Konfigurationsschlüssel, während Doctor Operators zu agentRuntime migriert
• Fallback für generierte gebündelte Kanal-Konfigurationsmetadaten, während registry-first-channelConfigs-Metadaten landen
• persistierte Plugin-Registry-Deaktivierungs- und Install-Migration-Env-Flags, während Reparaturflows Operators zu openclaw plugins registry --refresh und openclaw doctor --fix migrieren
• alte Plugin-eigene Konfigurationspfade für Websuche, Webabruf und x_search, während Doctor sie zu plugins.entries.<plugin>.config migriert
• alte verfasste plugins.installs-Konfiguration und gebündelte Plugin-Load-Path-Aliasse, während Installationsmetadaten in das zustandsverwaltete Plugin-Ledger wechseln

Neuer Plugin-Code sollte den in der Registry und im jeweiligen Migrationsleitfaden aufgeführten Ersatz bevorzugen. Vorhandene Plugins können einen Kompatibilitätspfad weiterverwenden, bis Dokumentation, Diagnosen und Release Notes ein Entfernungsfenster ankündigen.

Release Notes

Release Notes sollten kommende Plugin-Deprecations mit Zieldaten und Links zu Migrationsdokumentation enthalten. Diese Warnung muss erfolgen, bevor ein Kompatibilitätspfad zu removal-pending oder removed wechselt.