Plugin maintainer reference

Compatibilità dei Plugin

OpenClaw mantiene operativi i contratti Plugin meno recenti tramite adattatori di compatibilità denominati prima di rimuoverli. Ciò protegge i Plugin inclusi e quelli esterni esistenti mentre evolvono i contratti dell'SDK, del manifesto, della configurazione iniziale, della configurazione e del runtime degli agenti.

Registro di compatibilità

I contratti di compatibilità dei Plugin sono registrati nel registro principale in src/plugins/compat/registry.ts. Ogni voce include:

un codice di compatibilità stabile
stato: active, deprecated, removal-pending o removed
responsabile: sdk, config, setup, channel, provider, plugin-execution, agent-runtime o core
date di introduzione e deprecazione, quando applicabili
indicazioni per la sostituzione
documentazione, diagnostica e test che coprono il comportamento precedente e quello nuovo

Il registro è la fonte di riferimento per la pianificazione dei manutentori e per i futuri controlli dell'analizzatore dei Plugin. Se cambia un comportamento esposto ai Plugin, aggiungere o aggiornare la voce di compatibilità nella stessa modifica che introduce l'adattatore.

La compatibilità delle riparazioni e delle migrazioni di Doctor viene registrata separatamente in src/commands/doctor/shared/deprecation-compat.ts. Queste voci coprono le precedenti strutture di configurazione, le strutture del registro delle installazioni e gli shim di riparazione che potrebbe essere necessario mantenere disponibili dopo la rimozione del percorso di compatibilità del runtime.

Le verifiche di rilascio devono controllare entrambi i registri. Non eliminare una migrazione di Doctor solo perché la voce di compatibilità del runtime o della configurazione corrispondente è scaduta; verificare prima che non esista un percorso di aggiornamento supportato che richieda ancora la riparazione. Durante la pianificazione del rilascio, convalidare nuovamente anche ogni annotazione di sostituzione, poiché la responsabilità dei Plugin e l'ambito della configurazione possono cambiare quando i provider e i canali vengono spostati fuori dal core.

Criteri di deprecazione

OpenClaw non deve rimuovere un contratto Plugin documentato nella stessa versione che introduce il relativo sostituto. Sequenza di migrazione:

Aggiungere il nuovo contratto.
Mantenere operativo il comportamento precedente tramite un adattatore di compatibilità denominato.
Emettere messaggi diagnostici o avvisi quando gli autori dei Plugin possono intervenire.
Documentare la sostituzione e la tempistica.
Verificare con test sia il percorso precedente sia quello nuovo.
Attendere il termine della finestra di migrazione annunciata.
Rimuovere solo con l'approvazione esplicita di una versione con modifiche incompatibili.

Le voci deprecate devono includere una data di inizio degli avvisi, una sostituzione, un collegamento alla documentazione e una data di rimozione definitiva non successiva a tre mesi dall'inizio degli avvisi. Non aggiungere un percorso di compatibilità deprecato con una finestra di rimozione senza scadenza, a meno che i manutentori non decidano esplicitamente che si tratta di compatibilità permanente e lo contrassegnino invece come active.

Aree di compatibilità attuali

Il registro attualmente contiene circa 70 codici di compatibilità relativi alle aree seguenti. Il nuovo codice dei Plugin deve utilizzare la sostituzione prevista in ogni area e nella guida di migrazione specifica; i Plugin esistenti possono continuare a utilizzare un percorso di compatibilità finché la documentazione, la diagnostica e le note di rilascio non annunciano una finestra di rimozione.

precedenti importazioni generiche dell'SDK, come openclaw/plugin-sdk/compat
precedenti strutture dei Plugin basate esclusivamente sugli hook e before_agent_start
precedenti nomi degli hook di pulizia api.on("deactivate", ...) durante la migrazione dei Plugin a gateway_stop
precedenti punti di ingresso dei Plugin activate(api) durante la migrazione dei Plugin a register(api)
precedenti alias dell'SDK, come openclaw/extension-api, openclaw/plugin-sdk/channel-runtime, i costruttori di stato di openclaw/plugin-sdk/command-auth, openclaw/plugin-sdk/test-utils (sostituito dai sottopercorsi di test specifici openclaw/plugin-sdk/*) e gli alias di tipo ClawdbotConfig / OpenClawSchemaType
comportamento relativo all'elenco consentito e all'abilitazione dei Plugin inclusi
precedenti metadati del manifesto per le variabili di ambiente di provider e canali
precedenti hook e alias di tipo dei Plugin provider durante la migrazione dei provider a hook espliciti per catalogo, autenticazione, ragionamento, riproduzione e trasporto
precedenti alias del runtime, come api.runtime.taskFlow, api.runtime.subagent.getSession, api.runtime.stt e gli elementi deprecati api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...)
campi piatti dei callback WebInboundMessage di WhatsApp (vedere sotto)
campi di ammissione di primo livello di WebInboundMessage di WhatsApp (vedere sotto)
precedente registrazione separata dei Plugin di memoria durante la migrazione dei Plugin di memoria a registerMemoryCapability
precedente registrazione dei provider di incorporamento specifica per la memoria, durante la migrazione dei provider di incorporamento a api.registerEmbeddingProvider(...) e contracts.embeddingProviders
precedenti helper dell'SDK dei canali per gli schemi dei messaggi nativi, il controllo delle menzioni, la formattazione degli involucri in ingresso e l'annidamento delle funzionalità di approvazione
precedenti alias per la chiave di instradamento dei canali e per gli helper dei destinatari confrontabili, durante la migrazione dei Plugin a openclaw/plugin-sdk/channel-route
suggerimenti di attivazione sostituiti dalla responsabilità dei contributi del manifesto
fallback del runtime setup-api durante la migrazione dei descrittori di configurazione iniziale ai metadati a freddo setup.requiresRuntime: false
hook discovery dei provider durante la migrazione degli hook del catalogo dei provider a catalog.run(...)
metadati showConfigured / showInSetup dei canali durante la migrazione dei pacchetti dei canali a openclaw.channel.exposure
precedenti chiavi di configurazione dei criteri del runtime durante la migrazione degli operatori ad agentRuntime tramite Doctor
fallback dei metadati di configurazione generati per i canali inclusi durante l'introduzione dei metadati channelConfigs basati prioritariamente sul registro
variabili di ambiente persistenti per la disabilitazione del registro dei Plugin e per la migrazione delle installazioni, durante la migrazione degli operatori tramite i flussi di riparazione a openclaw plugins registry --refresh e openclaw doctor --fix
precedenti percorsi di configurazione di ricerca web, recupero web e x_search gestiti dai Plugin, durante la migrazione tramite Doctor a plugins.entries.<plugin>.config
precedente configurazione plugins.installs creata manualmente e alias dei percorsi di caricamento dei Plugin inclusi, durante lo spostamento dei metadati di installazione nel registro dei Plugin gestito dallo stato

Alias piatti dei callback in ingresso di WhatsApp

I callback del runtime di WhatsApp forniscono WebInboundMessage: i contesti canonici annidati event, payload, quote, group e platform, oltre agli alias piatti deprecati per i campi dei callback distribuiti. Il nuovo codice dei callback deve leggere i contesti annidati. Il codice che crea messaggi di callback annidati puliti può utilizzare WebInboundCallbackMessage; i listener di compatibilità che inseriscono ancora vecchi messaggi piatti di test o dei Plugin devono utilizzare LegacyFlatWebInboundMessage o WebInboundMessageInput.

Gli alias piatti rimangono disponibili fino al 2026-08-30; questa finestra si applica solo all'accesso tramite alias piatti, non alla struttura annidata, che è il contratto canonico del runtime. L'annotazione TypeScript @deprecated di ogni alias piatto indica la relativa sostituzione annidata esatta. Esempi comuni:

id, timestamp e isBatched vengono spostati sotto event.
body, mediaPath, mediaType, mediaFileName, mediaUrl, location e untrustedStructuredContext vengono spostati sotto payload.
to, chatId, i campi relativi al mittente e all'identità del sistema, sendComposing, reply(...) e sendMedia(...) vengono spostati sotto platform.
I campi replyTo* vengono spostati sotto quote; i campi relativi all'oggetto, ai partecipanti e alle menzioni del gruppo vengono spostati sotto group.

payload.untrustedStructuredContext viene estratto dai payload in ingresso dei provider. I Plugin devono esaminare label, source e type prima di considerare autorevole il relativo payload.

Campi di ammissione in ingresso di WhatsApp

I messaggi di callback WhatsApp accettati contengono admission, un involucro sicuro per l'esposizione pubblica della decisione di controllo degli accessi che ha ammesso il messaggio. Il nuovo codice dei callback deve leggere i dati sull'ammissione da msg.admission anziché dai precedenti campi di ammissione di primo livello.

I campi di primo livello rimangono disponibili fino al 2026-08-30. L'annotazione TypeScript @deprecated di ogni campo indica la relativa sostituzione:

from e conversationId vengono spostati in admission.conversation.id.
accountId viene spostato in admission.accountId.
accessControlPassed è una vista di compatibilità derivata da admission.ingress.decision === "allow"; nei messaggi che contengono già admission, la scrittura del valore booleano precedente non riscrive il grafo di ingresso.
chatType viene spostato in admission.conversation.kind.

Pacchetto dell'analizzatore dei Plugin

L'analizzatore dei Plugin deve risiedere al di fuori del repository principale di OpenClaw come pacchetto/repository separato, basato sui contratti di compatibilità e del manifesto con controllo delle versioni. La CLI iniziale deve essere:

openclaw-plugin-inspector ./my-plugin

Deve produrre la convalida del manifesto e dello schema, la versione di compatibilità del contratto sottoposta a controllo, i controlli dei metadati di installazione e origine, i controlli delle importazioni dei percorsi a freddo e gli avvisi di deprecazione e compatibilità. Utilizzare --json per ottenere un output stabile e leggibile dalle macchine nelle annotazioni CI. Il core di OpenClaw deve esporre i contratti e i dati di test utilizzabili dall'analizzatore, ma non deve pubblicare il binario dell'analizzatore dal pacchetto principale openclaw.

Percorso di accettazione per i manutentori

Utilizzare Blacksmith Testbox con supporto Crabbox per il percorso di accettazione dei pacchetti installabili quando si convalida l'analizzatore esterno rispetto ai pacchetti Plugin di OpenClaw. Eseguirlo da un checkout pulito di OpenClaw dopo la compilazione del pacchetto:

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

Mantenere questo percorso facoltativo per i manutentori, poiché installa un pacchetto npm esterno e può esaminare pacchetti Plugin clonati al di fuori del repository. Le protezioni del repository locale coprono la mappa delle esportazioni dell'SDK, i metadati del registro di compatibilità, la progressiva eliminazione delle importazioni deprecate dell'SDK e i confini delle importazioni delle estensioni incluse; la verifica dell'analizzatore in Testbox copre il pacchetto così come viene utilizzato dagli autori di Plugin esterni.

Note di rilascio

Le note di rilascio devono includere le imminenti deprecazioni dei Plugin, con le date previste e i collegamenti alla documentazione di migrazione, prima che un percorso di compatibilità passi a removal-pending o removed.

Was this useful?