Componenti interni dei Plugin

Questo è il riferimento approfondito sull'architettura del sistema di Plugin di OpenClaw. Per le guide pratiche, inizia da una delle pagine specifiche riportate di seguito.

Modello pubblico delle funzionalità

Le funzionalità costituiscono il modello pubblico dei Plugin nativi all'interno di OpenClaw. Ogni Plugin nativo di OpenClaw si registra per uno o più tipi di funzionalità:

Posizione sulla compatibilità esterna

Il modello delle funzionalità è integrato nel core e attualmente utilizzato dai Plugin inclusi e nativi, ma per la compatibilità dei Plugin esterni serve ancora un criterio più rigoroso di «è esportato, quindi è immutabile».

La registrazione delle funzionalità è la direzione prevista. Durante la transizione, gli hook legacy restano il percorso più sicuro per evitare incompatibilità nei Plugin esterni. I sottopercorsi ausiliari esportati non sono tutti equivalenti: preferisci contratti circoscritti e documentati alle esportazioni ausiliarie accidentali.

Forme dei Plugin

OpenClaw classifica ogni Plugin caricato in una forma in base al suo effettivo comportamento di registrazione, non solo ai metadati statici:

Usa openclaw plugins inspect <id> per visualizzare la forma di un Plugin e la suddivisione delle sue funzionalità. Per i dettagli, consulta il riferimento della CLI.

Hook legacy

L'hook before_agent_start resta supportato come percorso di compatibilità per i Plugin basati esclusivamente su hook. I Plugin legacy utilizzati in scenari reali dipendono ancora da questo hook.

Direzione:

• mantenerlo funzionante
• documentarlo come legacy
• preferire before_model_resolve per la sostituzione del modello o del provider
• preferire before_prompt_build per la modifica dei prompt
• rimuoverlo solo dopo che il suo utilizzo effettivo sarà diminuito e la copertura delle fixture avrà dimostrato la sicurezza della migrazione

Segnali di compatibilità

openclaw doctor, openclaw plugins inspect <id>, openclaw status --all e openclaw plugins doctor mostrano questi avvisi di compatibilità:

Attualmente, nessuno dei segnali informativi o di avviso interrompe il funzionamento del Plugin. Questi segnali compaiono anche in openclaw status --all e openclaw plugins doctor.

Panoramica dell'architettura

Il sistema di Plugin di OpenClaw è composto da quattro livelli:

Per la CLI dei Plugin in particolare, il rilevamento dei comandi radice è suddiviso in due fasi:

• i metadati disponibili durante l'analisi provengono da registerCli(..., { descriptors: [...] })
• il modulo CLI effettivo del Plugin può rimanere a caricamento differito e registrarsi alla prima invocazione

In questo modo, il codice CLI gestito dal Plugin resta all'interno del Plugin, consentendo comunque a OpenClaw di riservare i nomi dei comandi radice prima dell'analisi.

Il confine progettuale importante:

• la convalida del manifest e della configurazione deve funzionare usando i metadati del manifest e dello schema, senza eseguire il codice del Plugin
• il rilevamento delle funzionalità native può caricare il codice di ingresso di un Plugin attendibile per creare un'istantanea non attivante del registro
• il comportamento nativo in fase di esecuzione deriva dal percorso register(api) del modulo del Plugin con api.registrationMode === "full"

Questa separazione consente a OpenClaw di convalidare la configurazione, spiegare i Plugin mancanti o disabilitati e creare suggerimenti per l'interfaccia utente e lo schema prima che il runtime completo sia attivo.

Istantanea dei metadati dei Plugin e tabella di ricerca

All'avvio, il Gateway crea un unico PluginMetadataSnapshot per l'istantanea della configurazione corrente. L'istantanea contiene solo metadati: memorizza l'indice dei Plugin installati, il registro dei manifest, la diagnostica dei manifest, le mappe dei proprietari, un normalizzatore degli ID dei Plugin e i record dei manifest. Non contiene moduli Plugin caricati, SDK dei provider, contenuti dei pacchetti o esportazioni di runtime.

La convalida della configurazione sensibile ai Plugin, l'abilitazione automatica all'avvio e l'avvio dei Plugin del Gateway utilizzano tale istantanea invece di ricostruire separatamente i metadati del manifest e dell'indice. PluginLookUpTable deriva dalla stessa istantanea e aggiunge il piano dei Plugin di avvio per la configurazione di runtime corrente.

Dopo l'avvio, il Gateway conserva l'istantanea dei metadati corrente come prodotto di runtime sostituibile. Le ripetute operazioni di rilevamento dei provider in fase di esecuzione possono riutilizzare tale istantanea invece di ricostruire l'indice degli elementi installati e il registro dei manifest a ogni passaggio sul catalogo dei provider. L'istantanea viene cancellata o sostituita allo spegnimento del Gateway, quando cambiano la configurazione o l'inventario dei Plugin e quando viene scritto l'indice degli elementi installati; in assenza di un'istantanea corrente compatibile, i chiamanti ripiegano sul percorso a freddo del manifest e dell'indice. I controlli di compatibilità devono includere le directory radice di rilevamento dei Plugin, come plugins.load.paths, e lo spazio di lavoro predefinito dell'agente, perché i Plugin dello spazio di lavoro fanno parte dell'ambito dei metadati.

L'istantanea e la tabella di ricerca mantengono nel percorso rapido le decisioni ripetute all'avvio:

• proprietà dei canali
• avvio differito dei canali
• ID dei Plugin di avvio
• proprietà dei provider e dei backend CLI
• proprietà del provider di configurazione, degli alias dei comandi, del provider del catalogo dei modelli e dei contratti dei manifest
• convalida dello schema di configurazione dei Plugin e dello schema di configurazione dei canali
• decisioni di abilitazione automatica all'avvio

Il confine di sicurezza è la sostituzione dell'istantanea, non la sua modifica. Ricrea l'istantanea quando cambiano la configurazione, l'inventario dei Plugin, i record di installazione o i criteri dell'indice persistente. Non considerarla un ampio registro globale modificabile e non conservare un numero illimitato di istantanee storiche. Il caricamento dei Plugin in fase di esecuzione resta separato dalle istantanee dei metadati, in modo che uno stato di runtime obsoleto non possa essere nascosto dietro una cache dei metadati.

La regola della cache è documentata in Dettagli interni dell'architettura dei Plugin: i metadati dei manifest e del rilevamento sono aggiornati, a meno che un chiamante non disponga di un'istantanea, una tabella di ricerca o un registro dei manifest espliciti per il flusso corrente. Le cache nascoste dei metadati e i TTL basati sull'orologio non fanno parte del caricamento dei Plugin. Solo le cache del caricatore di runtime, dei moduli e degli artefatti delle dipendenze possono persistere dopo l'effettivo caricamento del codice o degli artefatti installati.

Alcuni chiamanti del percorso a freddo ricostruiscono ancora i registri dei manifest direttamente dall'indice persistente dei Plugin installati, invece di ricevere una PluginLookUpTable del Gateway. Questo percorso ora ricostruisce il registro su richiesta; quando un chiamante ne dispone già, preferisci trasmettere la tabella di ricerca corrente o un registro dei manifest esplicito attraverso i flussi di runtime.

Pianificazione dell'attivazione

La pianificazione dell'attivazione fa parte del piano di controllo. I chiamanti possono chiedere quali plugin siano pertinenti a un comando, provider, canale, percorso, harness dell'agente o funzionalità concreti prima di caricare registri di runtime più ampi.

Il pianificatore mantiene compatibile il comportamento corrente del manifesto:

• i campi activation.* sono indicazioni esplicite per il pianificatore
• providers, channels, commandAliases, setup.providers, contracts.tools e gli hook rimangono il fallback basato sulla titolarità del manifesto
• l'API del pianificatore che restituisce solo gli ID rimane disponibile per i chiamanti esistenti
• l'API del piano segnala etichette di motivazione affinché la diagnostica possa distinguere le indicazioni esplicite dal fallback basato sulla titolarità

Plugin di canale e strumento di messaggistica condiviso

I plugin di canale non devono registrare uno strumento separato di invio/modifica/reazione per le normali azioni di chat. OpenClaw mantiene un unico strumento message condiviso nel core, mentre i plugin di canale gestiscono l'individuazione e l'esecuzione specifiche del canale dietro di esso.

Il confine attuale è il seguente:

• il core gestisce l'host dello strumento message condiviso, il collegamento dei prompt, la registrazione delle sessioni e dei thread e l'inoltro dell'esecuzione
• i plugin di canale gestiscono l'individuazione delle azioni con ambito definito, l'individuazione delle funzionalità e gli eventuali frammenti di schema specifici del canale
• i plugin di canale gestiscono la grammatica delle conversazioni di sessione specifica del provider, per esempio il modo in cui gli ID conversazione codificano gli ID dei thread o vengono ereditati dalle conversazioni principali
• i plugin di canale eseguono l'azione finale tramite il proprio adattatore di azioni

Per i plugin di canale, la superficie dell'SDK è ChannelMessageActionAdapter.describeMessageTool(...). Questa chiamata unificata di individuazione consente a un plugin di restituire insieme le azioni visibili, le funzionalità e i contributi allo schema, evitando che questi elementi divergano.

Quando un parametro specifico del canale dello strumento di messaggistica contiene una sorgente multimediale, come un percorso locale o un URL multimediale remoto, il plugin deve restituire anche mediaSourceParams da describeMessageTool(...). Il core usa questo elenco esplicito per applicare la normalizzazione dei percorsi della sandbox e le indicazioni per l'accesso ai contenuti multimediali in uscita, senza codificare direttamente i nomi dei parametri gestiti dal plugin. In questo caso, preferire mappe con ambito di azione anziché un unico elenco piatto per l'intero canale, in modo che un parametro multimediale riservato al profilo non venga normalizzato per azioni non correlate come send.

Il core passa l'ambito del runtime a questa fase di individuazione. I campi importanti includono:

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• il valore attendibile in ingresso requesterSenderId

Questo è importante per i plugin sensibili al contesto. Un canale può nascondere o mostrare azioni di messaggistica in base all'account attivo, alla stanza, al thread o al messaggio corrente oppure all'identità attendibile del richiedente, senza codificare nel core dello strumento message diramazioni specifiche del canale.

Per questo motivo, le modifiche all'instradamento dell'esecutore incorporato restano di competenza del plugin: l'esecutore è responsabile dell'inoltro dell'identità corrente della chat e della sessione al confine di individuazione del plugin, affinché lo strumento message condiviso esponga la superficie corretta gestita dal canale per il turno corrente.

Per gli helper di esecuzione gestiti dal canale, i plugin inclusi devono mantenere il runtime di esecuzione all'interno dei propri moduli. Il core non gestisce più i runtime delle azioni di messaggistica di Discord, Slack, Telegram o WhatsApp in src/agents/tools. Non pubblichiamo sottopercorsi separati plugin-sdk/*-action-runtime e i plugin inclusi devono importare direttamente il proprio codice di runtime locale dai moduli di loro competenza.

Lo stesso confine si applica in generale alle interfacce dell'SDK denominate in base al provider: il core non deve importare barrel di utilità specifici del canale per Discord, Signal, Slack, WhatsApp o plugin simili. Se il core necessita di un comportamento, deve usare il barrel api.ts / runtime-api.ts del plugin incluso oppure trasformare tale necessità in una funzionalità generica e circoscritta nell'SDK condiviso.

I plugin inclusi seguono la stessa regola. Il file runtime-api.ts di un plugin incluso non deve riesportare la propria facciata personalizzata openclaw/plugin-sdk/<plugin-id>. Queste facciate personalizzate rimangono shim di compatibilità per plugin esterni e utilizzatori meno recenti, ma i plugin inclusi devono usare esportazioni locali e sottopercorsi generici e circoscritti dell'SDK, come openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/runtime-store o openclaw/plugin-sdk/webhook-ingress. Il nuovo codice non deve aggiungere facciate dell'SDK specifiche dell'ID del plugin, a meno che ciò sia richiesto dal confine di compatibilità di un ecosistema esterno esistente.

Per i sondaggi, in particolare, esistono due percorsi di esecuzione:

• outbound.sendPoll è la base condivisa per i canali compatibili con il modello comune dei sondaggi
• actions.handleAction("poll") è il percorso preferito per la semantica dei sondaggi specifica del canale o per parametri aggiuntivi dei sondaggi

Il core ora rinvia l'analisi condivisa del sondaggio fino a quando l'inoltro del sondaggio al plugin non rifiuta l'azione, in modo che i gestori dei sondaggi di competenza del plugin possano accettare campi specifici del canale senza essere prima bloccati dall'analizzatore generico dei sondaggi.

Consultare Dettagli interni dell'architettura dei plugin per la sequenza completa di avvio.

Modello di titolarità delle funzionalità

OpenClaw considera un plugin nativo come il confine di titolarità di un'azienda o di una funzionalità, non come una raccolta eterogenea di integrazioni non correlate.

Ciò significa che:

• un plugin aziendale dovrebbe normalmente gestire tutte le superfici di quell'azienda rivolte a OpenClaw
• un plugin di funzionalità dovrebbe normalmente gestire l'intera superficie della funzionalità che introduce
• i canali dovrebbero utilizzare le funzionalità condivise del core invece di reimplementare ad hoc il comportamento del provider

Lo stato finale previsto è il seguente:

• la superficie di un fornitore rivolta a OpenClaw risiede in un unico plugin, anche se comprende modelli testuali, voce, immagini e video
• gli altri fornitori possono fare lo stesso per la propria area funzionale
• ai canali non interessa quale plugin di un fornitore gestisca il provider; utilizzano il contratto di funzionalità condiviso esposto dal core

Questa è la distinzione fondamentale:

• plugin = confine di titolarità
• funzionalità = contratto del core che più plugin possono implementare o utilizzare

Pertanto, se OpenClaw aggiunge un nuovo ambito come il video, la prima domanda non è «quale provider deve codificare direttamente la gestione dei video?». La prima domanda è «qual è il contratto della funzionalità video del core?». Una volta definito tale contratto, i plugin dei fornitori possono registrarsi per implementarlo, mentre i plugin di canale o funzionalità possono utilizzarlo.

Se la funzionalità non esiste ancora, in genere la procedura corretta è:

Questo approccio mantiene esplicita la titolarità evitando al contempo comportamenti del core che dipendano da un singolo fornitore o da un percorso di codice specifico di un plugin creato per un solo caso.

Stratificazione delle funzionalità

Usare questo modello concettuale per decidere a quale livello appartiene il codice:

Per esempio, la sintesi vocale TTS segue questa struttura:

• il core gestisce i criteri TTS al momento della risposta, l'ordine dei fallback, le preferenze e la consegna al canale
• elevenlabs, google, microsoft e openai gestiscono le implementazioni della sintesi
• voice-call utilizza l'helper di runtime TTS per la telefonia

Lo stesso modello dovrebbe essere preferito per le funzionalità future.

Esempio di plugin aziendale con più funzionalità

Un plugin aziendale dovrebbe apparire coeso dall'esterno. Se OpenClaw dispone di contratti condivisi per modelli, sintesi vocale, trascrizione in tempo reale, voce in tempo reale, comprensione multimediale, generazione di immagini, generazione di video, recupero web e ricerca web, un fornitore può gestire tutte le proprie superfici in un unico punto:

    describeImageWithModel,  transcribeOpenAiCompatibleAudio,} from "openclaw/plugin-sdk/media-understanding"; const plugin: OpenClawPluginDefinition = {  id: "exampleai",  name: "ExampleAI",  register(api) {    api.registerProvider({      id: "exampleai",      // auth/model catalog/runtime hooks    });     api.registerSpeechProvider({      id: "exampleai",      // vendor speech config — implement the SpeechProviderPlugin interface directly    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      async describeImage(req) {        return describeImageWithModel({          ...req,          provider: "exampleai",        });      },      async transcribeAudio(req) {        return transcribeOpenAiCompatibleAudio({          ...req,          provider: "exampleai",        });      },    });     api.registerWebSearchProvider(      createPluginBackedWebSearchProvider({        id: "exampleai-search",        // credential + fetch logic      }),    );  },}; export default plugin;

Ciò che conta non sono i nomi esatti degli helper, ma la struttura:

• un unico plugin gestisce la superficie del fornitore
• il core continua a gestire i contratti delle funzionalità
• i canali e i plugin di funzionalità utilizzano gli helper api.runtime.*, non il codice del fornitore
• i test dei contratti possono verificare che il plugin abbia registrato le funzionalità che dichiara di gestire

Esempio di funzionalità: comprensione dei video

OpenClaw considera già la comprensione di immagini/audio/video come un'unica funzionalità condivisa. Anche in questo caso si applica lo stesso modello di titolarità:

In questo modo si evita di incorporare nel core le ipotesi sui video di un singolo provider. Il plugin gestisce la superficie del fornitore; il core gestisce il contratto della funzionalità e il comportamento di fallback.

La generazione di video usa già la stessa sequenza: il core gestisce il contratto tipizzato della funzionalità e l'helper di runtime, mentre i plugin dei fornitori registrano le implementazioni api.registerVideoGenerationProvider(...) conformi a tale contratto.

Serve una lista di controllo concreta per l'implementazione? Consultare il Manuale operativo delle funzionalità.

Contratti e applicazione

La superficie dell'API dei plugin è intenzionalmente tipizzata e centralizzata in OpenClawPluginApi. Questo contratto definisce i punti di registrazione supportati e gli helper di runtime su cui un plugin può fare affidamento.

Perché è importante:

• gli autori di plugin dispongono di un unico standard interno stabile
• il core può rifiutare proprietà duplicate, ad esempio quando due plugin registrano lo stesso ID provider
• all'avvio possono essere visualizzate informazioni diagnostiche utili per registrazioni non valide
• i test dei contratti possono verificare la proprietà dei plugin inclusi e impedire divergenze silenziose

L'applicazione delle regole avviene su due livelli:

L'effetto pratico è che OpenClaw sa in anticipo quale plugin è responsabile di ciascuna superficie. Ciò consente al core e ai canali di integrarsi senza discontinuità, perché la proprietà è dichiarata, tipizzata e verificabile tramite test anziché implicita.

Cosa deve includere un contratto

In caso di dubbio, aumenta il livello di astrazione: definisci prima la funzionalità, quindi consenti ai plugin di integrarsi con essa.

Modello di esecuzione

I plugin nativi di OpenClaw vengono eseguiti all'interno del processo insieme al Gateway. Non sono isolati in una sandbox. Un plugin nativo caricato condivide lo stesso confine di attendibilità a livello di processo del codice del core.

I pacchetti compatibili sono più sicuri per impostazione predefinita, perché OpenClaw attualmente li considera pacchetti di metadati e contenuti. Nelle versioni attuali, ciò riguarda principalmente le Skills incluse.

Utilizza elenchi di elementi consentiti e percorsi espliciti di installazione e caricamento per i plugin non inclusi. Considera i plugin dell'area di lavoro come codice destinato alla fase di sviluppo, non come impostazioni predefinite per la produzione.

Per i nomi dei pacchetti dell'area di lavoro inclusi, mantieni l'ID del plugin ancorato al nome npm: @openclaw/<id> per impostazione predefinita oppure un suffisso tipizzato approvato, come -provider, -plugin, -speech, -sandbox o -media-understanding, quando il pacchetto espone intenzionalmente un ruolo di plugin più specifico.

Confine delle esportazioni

OpenClaw esporta funzionalità, non elementi pratici specifici dell'implementazione.

Mantieni pubblica la registrazione delle funzionalità. Riduci le esportazioni degli helper non incluse nel contratto:

• sottopercorsi di helper specifici dei plugin inclusi
• sottopercorsi dell'infrastruttura di runtime non destinati a essere API pubbliche
• helper pratici specifici dei fornitori
• helper di configurazione e onboarding che costituiscono dettagli di implementazione

I sottopercorsi riservati agli helper dei plugin inclusi sono stati rimossi dalla mappa delle esportazioni dell'SDK generata. Mantieni gli helper specifici del proprietario all'interno del pacchetto del plugin che ne è responsabile; promuovi a contratti SDK generici soltanto il comportamento dell'host riutilizzabile, come plugin-sdk/gateway-runtime, plugin-sdk/security-runtime e plugin-sdk/plugin-config-runtime.

Dettagli interni e riferimenti

Per la pipeline di caricamento, il modello del registro, gli hook di runtime dei provider, le route HTTP del Gateway, gli schemi degli strumenti di messaggistica, la risoluzione delle destinazioni dei canali, i cataloghi dei provider, i plugin del motore di contesto e la guida per aggiungere una nuova funzionalità, consulta Dettagli interni dell'architettura dei plugin.

Contenuti correlati

• Creazione di plugin
• Manifesto del plugin
• Configurazione dell'SDK per i plugin