Plugin-compatibiliteit

OpenClaw houdt oudere Plugin-contracten bedraad via benoemde compatibiliteitsadapters voordat ze worden verwijderd. Dit beschermt bestaande gebundelde en externe plugins terwijl de SDK-, manifest-, setup-, configuratie- en agent-runtimecontracten evolueren.

Compatibiliteitsregister

Plugin-compatibiliteitscontracten worden bijgehouden in het kernregister op src/plugins/compat/registry.ts.

Elke record heeft:

• een stabiele compatibiliteitscode
• status: active, deprecated, removal-pending of removed
• eigenaar: SDK, configuratie, setup, kanaal, provider, Plugin-uitvoering, agent-runtime of core
• introductie- en afschrijvingsdatums waar van toepassing
• vervangingsrichtlijnen
• docs, diagnoses en tests die het oude en nieuwe gedrag dekken

Het register is de bron voor maintainerplanning en toekomstige plugin-inspectorcontroles. Als Plugin-gericht gedrag verandert, voeg dan de compatibiliteitsrecord toe of werk deze bij in dezelfde wijziging die de adapter toevoegt.

Compatibiliteit voor doctor-herstel en migratie wordt apart bijgehouden op src/commands/doctor/shared/deprecation-compat.ts. Die records dekken oude configuratievormen, install-ledgerindelingen en herstel-shims die mogelijk beschikbaar moeten blijven nadat het runtime-compatibiliteitspad is verwijderd.

Release-sweeps moeten beide registers controleren. Verwijder geen doctor-migratie alleen omdat de bijbehorende runtime- of configuratiecompatibiliteitsrecord is verlopen; verifieer eerst dat er geen ondersteund upgradepad is dat de reparatie nog nodig heeft. Valideer ook elke vervangingsannotatie opnieuw tijdens releaseplanning, omdat Plugin-eigenaarschap en configuratievoetafdruk kunnen veranderen wanneer providers en kanalen uit core worden verplaatst.

Plugin-inspectorpakket

De Plugin-inspector moet buiten de core OpenClaw-repo leven als een apart pakket/repository, ondersteund door de geversioneerde compatibiliteits- en manifestcontracten.

De CLI op dag één moet zijn:

openclaw-plugin-inspector ./my-plugin

Deze moet het volgende uitvoeren:

• manifest-/schemavalidatie
• de contractcompatibiliteitsversie die wordt gecontroleerd
• controles van installatie-/bronmetadata
• cold-path importcontroles
• waarschuwingen voor afschrijving en compatibiliteit

Gebruik --json voor stabiele, machineleesbare uitvoer in CI-annotaties. OpenClaw core moet contracten en fixtures blootstellen die de inspector kan gebruiken, maar mag de inspector-binary niet publiceren vanuit het hoofdpackage openclaw.

Acceptatielane voor maintainers

Gebruik Crabbox-ondersteunde Blacksmith Testbox voor de acceptatielane voor installeerbare pakketten bij het valideren van de externe inspector tegen OpenClaw Plugin-pakketten. Voer dit uit vanuit een schone OpenClaw-checkout nadat het pakket is gebouwd:

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"

Houd deze lane opt-in voor maintainers, omdat deze een extern npm-pakket installeert en Plugin-pakketten kan inspecteren die buiten de repo zijn gekloond. De lokale repo-guards dekken de SDK-exportmap, compatibiliteitsregistermetadata, afbouw van verouderde SDK-imports en importgrenzen van gebundelde extensies; Testbox-inspectorbewijs dekt het pakket zoals externe Plugin-auteurs het gebruiken.

Afschrijvingsbeleid

OpenClaw mag een gedocumenteerd Plugin-contract niet verwijderen in dezelfde release waarin de vervanging wordt geïntroduceerd.

De migratiereeks is:

1. Voeg het nieuwe contract toe.
2. Houd het oude gedrag bedraad via een benoemde compatibiliteitsadapter.
3. Geef diagnoses of waarschuwingen wanneer Plugin-auteurs kunnen handelen.
4. Documenteer de vervanging en tijdlijn.
5. Test zowel oude als nieuwe paden.
6. Wacht gedurende het aangekondigde migratievenster.
7. Verwijder alleen met expliciete goedkeuring voor een breaking release.

Verouderde records moeten een startdatum voor waarschuwingen, vervanging, docs-link en definitieve verwijderingsdatum bevatten, niet meer dan drie maanden nadat de waarschuwing start. Voeg geen verouderd compatibiliteitspad toe met een open verwijderingsvenster, tenzij maintainers expliciet besluiten dat het permanente compatibiliteit is en het in plaats daarvan als active markeren.

Huidige compatibiliteitsgebieden

Huidige compatibiliteitsrecords omvatten:

• legacy brede SDK-imports zoals openclaw/plugin-sdk/compat
• legacy hook-only Plugin-vormen en before_agent_start
• legacy activate(api) Plugin-entrypoints terwijl plugins migreren naar register(api)
• legacy SDK-aliassen zoals openclaw/extension-api, openclaw/plugin-sdk/channel-runtime, openclaw/plugin-sdk/command-auth status builders, openclaw/plugin-sdk/test-utils (vervangen door gerichte openclaw/plugin-sdk/* test-subpaden), en de type-aliassen ClawdbotConfig / OpenClawSchemaType
• allowlist- en enablementgedrag voor gebundelde plugins
• legacy provider-/kanaal-env-var-manifestmetadata
• legacy provider-Plugin-hooks en type-aliassen terwijl providers overgaan naar expliciete catalogus-, auth-, thinking-, replay- en transporthooks
• legacy runtime-aliassen zoals api.runtime.taskFlow, api.runtime.subagent.getSession, api.runtime.stt, en verouderde api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...)
• legacy gesplitste registratie voor memory-plugins terwijl memory-plugins migreren naar registerMemoryCapability
• legacy kanaal-SDK-helpers voor native berichtschema’s, mention gating, inbound envelope-formattering en nesting van approval capabilities
• legacy kanaalroute-key en comparable-target helper-aliassen terwijl plugins migreren naar openclaw/plugin-sdk/channel-route
• activation hints die worden vervangen door eigenaarschap van manifest contributions
• setup-api runtime-fallback terwijl setup-descriptors worden verplaatst naar koude setup.requiresRuntime: false metadata
• provider-discovery hooks terwijl providercatalogushooks migreren naar catalog.run(...)
• kanaalmetadata showConfigured / showInSetup terwijl kanaalpakketten migreren naar openclaw.channel.exposure
• legacy runtime-policy configuratiesleutels terwijl doctor operators migreert naar agentRuntime
• gegenereerde metadatafallback voor gebundelde kanaalconfiguratie terwijl registry-first channelConfigs metadata landt
• persistente env-flags voor uitschakeling van het Plugin-register en installatiemigratie terwijl reparatiestromen operators migreren naar openclaw plugins registry --refresh en openclaw doctor --fix
• legacy Plugin-beheerde configuratiepaden voor web search, web fetch en x_search terwijl doctor ze migreert naar plugins.entries.<plugin>.config
• legacy plugins.installs authored config en aliasen voor laadpaden van gebundelde plugins terwijl installatiemetadata naar de door state beheerde Plugin-ledger wordt verplaatst

Nieuwe Plugin-code moet de vervanging gebruiken die in het register en in de specifieke migratiegids staat. Bestaande plugins kunnen een compatibiliteitspad blijven gebruiken totdat de docs, diagnoses en release notes een verwijderingsvenster aankondigen.

Release notes

Release notes moeten aankomende Plugin-afschrijvingen bevatten met doeldatums en links naar migratiedocs. Die waarschuwing moet plaatsvinden voordat een compatibiliteitspad naar removal-pending of removed gaat.