> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # Compatibilità dei Plugin OpenClaw mantiene i contratti dei plugin meno recenti collegati tramite adattatori di compatibilità nominati prima di rimuoverli. Questo protegge i plugin bundled ed esterni esistenti mentre i contratti di SDK, manifest, setup, configurazione e runtime dell’agente evolvono. ## Registro di compatibilità I contratti di compatibilità dei plugin sono tracciati nel registro core in `src/plugins/compat/registry.ts`. Ogni record contiene: * un codice di compatibilità stabile * stato: `active`, `deprecated`, `removal-pending` o `removed` * proprietario: SDK, configurazione, setup, canale, provider, esecuzione del plugin, runtime dell’agente o core * date di introduzione e deprecazione quando applicabili * indicazioni per la sostituzione * documentazione, diagnostica e test che coprono il comportamento vecchio e nuovo Il registro è la fonte per la pianificazione dei maintainer e per i futuri controlli dell’ispettore dei plugin. Se un comportamento rivolto ai plugin cambia, aggiungi o aggiorna il record di compatibilità nella stessa modifica che aggiunge l’adattatore. La compatibilità per riparazioni e migrazioni di doctor è tracciata separatamente in `src/commands/doctor/shared/deprecation-compat.ts`. Quei record coprono vecchie forme di configurazione, layout del registro installazioni e shim di riparazione che potrebbero dover restare disponibili dopo la rimozione del percorso di compatibilità runtime. Le revisioni di release dovrebbero controllare entrambi i registri. Non eliminare una migrazione di doctor solo perché il record di compatibilità runtime o di configurazione corrispondente è scaduto; prima verifica che non esista un percorso di aggiornamento supportato che abbia ancora bisogno della riparazione. Rivalida inoltre ogni annotazione di sostituzione durante la pianificazione della release, perché la proprietà dei plugin e l’impronta della configurazione possono cambiare quando provider e canali escono dal core. ## Pacchetto ispettore dei plugin L’ispettore dei plugin dovrebbe vivere fuori dal repository core di OpenClaw come pacchetto/repository separato, basato sui contratti di compatibilità e manifest versionati. La CLI del primo giorno dovrebbe essere: ```sh theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw-plugin-inspector ./my-plugin ``` Dovrebbe emettere: * validazione manifest/schema * la versione di compatibilità del contratto controllata * controlli dei metadati di installazione/sorgente * controlli di importazione cold-path * avvisi di deprecazione e compatibilità Usa `--json` per un output stabile leggibile da macchina nelle annotazioni CI. Il core OpenClaw dovrebbe esporre contratti e fixture che l’ispettore può consumare, ma non dovrebbe pubblicare il binario dell’ispettore dal pacchetto principale `openclaw`. ### Corsia di accettazione per maintainer Usa Blacksmith Testbox con backend Crabbox per la corsia di accettazione del pacchetto installabile quando validi l’ispettore esterno rispetto ai pacchetti plugin di OpenClaw. Eseguila da un checkout OpenClaw pulito dopo la build del pacchetto: ```sh theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 -- --json" ``` Mantieni questa corsia opt-in per i maintainer, perché installa un pacchetto npm esterno e può ispezionare pacchetti plugin clonati fuori dal repository. Le guardie del repository locale coprono la mappa di export dell’SDK, i metadati del registro di compatibilità, lo smaltimento degli import SDK deprecati e i confini di importazione delle estensioni bundled; la prova dell’ispettore Testbox copre il pacchetto come lo consumano gli autori di plugin esterni. ## Criterio di deprecazione OpenClaw non dovrebbe rimuovere un contratto plugin documentato nella stessa release che introduce la sua sostituzione. La sequenza di migrazione è: 1. Aggiungi il nuovo contratto. 2. Mantieni il vecchio comportamento collegato tramite un adattatore di compatibilità nominato. 3. Emetti diagnostica o avvisi quando gli autori di plugin possono intervenire. 4. Documenta sostituzione e tempistiche. 5. Testa sia i vecchi sia i nuovi percorsi. 6. Attendi per tutta la finestra di migrazione annunciata. 7. Rimuovi solo con approvazione esplicita per release breaking. I record deprecati devono includere una data di inizio degli avvisi, una sostituzione, un link alla documentazione e una data di rimozione finale non oltre tre mesi dall’inizio degli avvisi. Non aggiungere un percorso di compatibilità deprecato con una finestra di rimozione aperta, a meno che i maintainer decidano esplicitamente che sia compatibilità permanente e lo contrassegnino invece come `active`. ## Aree di compatibilità attuali I record di compatibilità attuali includono: * vecchi import SDK ampi come `openclaw/plugin-sdk/compat` * vecchie forme di plugin solo hook e `before_agent_start` * vecchi nomi di hook di pulizia `api.on("deactivate", ...)` mentre i plugin migrano a `gateway_stop` * vecchi entrypoint plugin `activate(api)` mentre i plugin migrano a `register(api)` * vecchi alias SDK come `openclaw/extension-api`, `openclaw/plugin-sdk/channel-runtime`, builder di stato `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/test-utils` (sostituito da sottopercorsi di test `openclaw/plugin-sdk/*` mirati) e gli alias di tipo `ClawdbotConfig` / `OpenClawSchemaType` * comportamento di allowlist e abilitazione dei plugin bundled * vecchi metadati manifest per env-var di provider/canale * vecchi hook dei plugin provider e alias di tipo mentre i provider passano a hook espliciti di catalogo, autenticazione, thinking, replay e trasporto * vecchi alias runtime come `api.runtime.taskFlow`, `api.runtime.subagent.getSession`, `api.runtime.stt` e i deprecati `api.runtime.config.loadConfig()` / `api.runtime.config.writeConfigFile(...)` * campi callback piatti `WebInboundMessage` di WhatsApp come `body`, `chatId`, `reply(...)` e `mediaPath` mentre i consumatori di callback migrano ai contesti annidati `WebInboundCallbackMessage` `event`, `payload`, `quote`, `group` e `platform` * campi di ammissione top-level `WebInboundMessage` di WhatsApp come `from`, `conversationId`, `accountId`, `accessControlPassed` e `chatType` mentre i consumatori di callback migrano all’envelope `admission` * vecchia registrazione separata dei plugin di memoria mentre i plugin di memoria passano a `registerMemoryCapability` * vecchia registrazione di provider di embedding specifica per memoria mentre i provider di embedding passano a `api.registerEmbeddingProvider(...)` e `contracts.embeddingProviders` * vecchi helper SDK di canale per schemi di messaggi nativi, gating delle menzioni, formattazione degli envelope in ingresso e annidamento delle capability di approvazione * vecchi alias della chiave di route di canale e degli helper comparable-target mentre i plugin passano a `openclaw/plugin-sdk/channel-route` * suggerimenti di attivazione che vengono sostituiti dalla proprietà dei contributi nel manifest * fallback runtime `setup-api` mentre i descrittori di setup passano ai metadati cold `setup.requiresRuntime: false` * hook `discovery` dei provider mentre gli hook di catalogo dei provider passano a `catalog.run(...)` * metadati di canale `showConfigured` / `showInSetup` mentre i pacchetti canale passano a `openclaw.channel.exposure` * vecchie chiavi di configurazione runtime-policy mentre doctor migra gli operatori a `agentRuntime` * fallback dei metadati di configurazione dei canali bundled generati mentre arrivano i metadati `channelConfigs` registry-first * flag env persistiti di disabilitazione del registro plugin e migrazione installazioni mentre i flussi di riparazione migrano gli operatori a `openclaw plugins registry --refresh` e `openclaw doctor --fix` * vecchi percorsi di configurazione di web search, web fetch e x\_search di proprietà dei plugin mentre doctor li migra a `plugins.entries..config` * vecchia configurazione autoriale `plugins.installs` e alias dei percorsi di caricamento dei plugin bundled mentre i metadati di installazione passano al registro plugin gestito dallo stato Il nuovo codice plugin dovrebbe preferire la sostituzione elencata nel registro e nella guida di migrazione specifica. I plugin esistenti possono continuare a usare un percorso di compatibilità finché documentazione, diagnostica e note di release annunciano una finestra di rimozione. ### Alias piatti dei callback inbound di WhatsApp I callback runtime di WhatsApp consegnano `WebInboundMessage`: i contesti canonici annidati `event`, `payload`, `quote`, `group` e `platform` più alias piatti deprecati per i campi callback rilasciati. Il nuovo codice callback dovrebbe leggere i contesti annidati. Il codice che costruisce messaggi callback annidati puliti può usare `WebInboundCallbackMessage`; i listener di compatibilità che iniettano ancora vecchi messaggi di test o plugin piatti dovrebbero usare `LegacyFlatWebInboundMessage` o `WebInboundMessageInput`. Gli alias piatti restano disponibili fino al **2026-08-30**. Quella finestra di rimozione si applica solo all’accesso agli alias piatti; la forma callback annidata è il contratto runtime canonico. Le annotazioni TypeScript `@deprecated` su ogni alias piatto indicano la sua sostituzione annidata esatta. Esempi comuni: * `id`, `timestamp` e `isBatched` si spostano sotto `event`. * `body`, `mediaPath`, `mediaType`, `mediaFileName`, `mediaUrl`, `location` e `untrustedStructuredContext` si spostano sotto `payload`. * `to`, `chatId`, campi mittente/self, `sendComposing`, `reply(...)` e `sendMedia(...)` si spostano sotto `platform`. * I campi `replyTo*` si spostano sotto `quote`, e i campi di oggetto gruppo/partecipante/menzione si spostano sotto `group`. `payload.untrustedStructuredContext` viene estratto dai payload dei provider in ingresso. I plugin dovrebbero ispezionare `label`, `source` e `type` prima di trattare il suo `payload` come autorevole. ### Campi di ammissione inbound di WhatsApp I messaggi callback WhatsApp accettati ora trasportano `admission`, un envelope sicuro per il pubblico per la decisione di controllo degli accessi che ha ammesso il messaggio. Il nuovo codice callback dovrebbe leggere i fatti di ammissione da `msg.admission` invece che dai vecchi campi di ammissione top-level. I campi top-level restano disponibili fino al **2026-08-30**. Le annotazioni TypeScript `@deprecated` indicano ogni sostituzione: * `from` e `conversationId` si spostano in `admission.conversation.id`. * `accountId` si sposta in `admission.accountId`. * `accessControlPassed` è una vista di compatibilità derivata da `admission.ingress.decision === "allow"`; sui messaggi che trasportano già `admission`, scrivere il booleano legacy non riscrive il grafo ingress. * `chatType` si sposta in `admission.conversation.kind`. ## Note di release Le note di release dovrebbero includere le prossime deprecazioni dei plugin con date obiettivo e link alla documentazione di migrazione. Quell’avviso deve avvenire prima che un percorso di compatibilità passi a `removal-pending` o `removed`.