Interni del Plugin

Questo è il riferimento approfondito dell'architettura per il sistema di plugin di OpenClaw. Per guide pratiche, inizia da una delle pagine mirate qui sotto.

# Modello pubblico delle capability

Le capability sono il modello pubblico di plugin nativo dentro OpenClaw. Ogni plugin nativo di OpenClaw si registra per uno o più tipi di capability:

Capability	Metodo di registrazione	Plugin di esempio
Inferenza testuale	api.registerProvider(...)	openai, anthropic
Backend di inferenza CLI	api.registerCliBackend(...)	openai, anthropic
Voce	api.registerSpeechProvider(...)	elevenlabs, microsoft
Trascrizione in tempo reale	api.registerRealtimeTranscriptionProvider(...)	openai
Voce in tempo reale	api.registerRealtimeVoiceProvider(...)	openai
Comprensione dei media	api.registerMediaUnderstandingProvider(...)	openai, google
Generazione di immagini	api.registerImageGenerationProvider(...)	openai, google, fal, minimax
Generazione musicale	api.registerMusicGenerationProvider(...)	google, minimax
Generazione video	api.registerVideoGenerationProvider(...)	qwen
Recupero Web	api.registerWebFetchProvider(...)	firecrawl
Ricerca Web	api.registerWebSearchProvider(...)	google
Canale / messaggistica	api.registerChannel(...)	msteams, matrix
Rilevamento Gateway	api.registerGatewayDiscoveryService(...)	bonjour

# Posizione sulla compatibilità esterna

Il modello delle capability è integrato nel core ed è usato oggi dai plugin in bundle/nativi, ma la compatibilità dei plugin esterni richiede ancora una soglia più rigorosa di "è esportato, quindi è congelato".

Situazione del plugin	Indicazioni
Plugin esterni esistenti	Mantieni funzionanti le integrazioni basate su hook; questa è la base di compatibilità.
Nuovi plugin in bundle/nativi	Preferisci la registrazione esplicita delle capability rispetto ad accessi specifici del fornitore o nuovi design solo hook.
Plugin esterni che adottano la registrazione delle capability	Consentito, ma considera le superfici helper specifiche delle capability come in evoluzione, a meno che la documentazione non le marchi come stabili.

La registrazione delle capability è la direzione prevista. Gli hook legacy restano il percorso più sicuro senza rotture per i plugin esterni durante la transizione. I sottopercorsi helper esportati non sono tutti equivalenti: preferisci contratti stretti e documentati rispetto a esportazioni helper incidentali.

# Forme dei plugin

OpenClaw classifica ogni plugin caricato in una forma basata sul suo effettivo comportamento di registrazione (non solo sui metadati statici):

Usa openclaw plugins inspect <id> per vedere la forma di un plugin e la ripartizione delle sue capability. Vedi il riferimento CLI per i dettagli.

# Hook legacy

L'hook before_agent_start resta supportato come percorso di compatibilità per i plugin solo hook. I plugin legacy reali dipendono ancora da esso.

Direzione:

• mantenerlo funzionante
• documentarlo come legacy
• preferire before_model_resolve per il lavoro di override di modello/provider
• preferire before_prompt_build per il lavoro di mutazione del prompt
• rimuoverlo solo dopo il calo dell'uso reale e dopo che la copertura delle fixture dimostra la sicurezza della migrazione

# Segnali di compatibilità

Quando esegui openclaw doctor o openclaw plugins inspect <id>, potresti vedere una di queste etichette:

Segnale	Significato
config valid	La configurazione viene analizzata correttamente e i plugin si risolvono
compatibility advisory	Il plugin usa un modello supportato ma più vecchio (ad es. hook-only)
legacy warning	Il plugin usa before_agent_start, che è deprecato
hard error	La configurazione non è valida o il caricamento del plugin non è riuscito

Né hook-only né before_agent_start interromperanno oggi il tuo plugin: hook-only è un avviso, e before_agent_start attiva solo un warning. Questi segnali compaiono anche in openclaw status --all e openclaw plugins doctor.

# Panoramica dell'architettura

Il sistema di plugin di OpenClaw ha quattro livelli:

Per la CLI dei plugin in particolare, il rilevamento dei comandi root è diviso in due fasi:

• i metadati in fase di parsing provengono da registerCli(..., { descriptors: [...] })
• il vero modulo CLI del plugin può restare lazy e registrarsi alla prima invocazione

Questo mantiene il codice CLI di proprietà del plugin dentro il plugin, pur consentendo a OpenClaw di riservare i nomi dei comandi root prima del parsing.

Il confine di design importante:

• la validazione di manifesto/configurazione dovrebbe funzionare da metadati di manifesto/schema senza eseguire codice del plugin
• il rilevamento delle capability native può caricare codice di ingresso di plugin attendibili per costruire uno snapshot del registro non attivante
• il comportamento runtime nativo proviene dal percorso register(api) del modulo del plugin con api.registrationMode === "full"

Questa separazione consente a OpenClaw di validare la configurazione, spiegare plugin mancanti/disabilitati e creare suggerimenti UI/schema prima che il runtime completo sia attivo.

# Snapshot dei metadati dei plugin e tabella di lookup

L'avvio del Gateway crea un PluginMetadataSnapshot per lo snapshot di configurazione corrente. Lo snapshot contiene solo metadati: archivia l'indice dei plugin installati, il registro dei manifesti, la diagnostica dei manifesti, le mappe dei proprietari, un normalizzatore degli ID dei plugin e i record dei manifesti. Non conserva moduli plugin caricati, SDK provider, contenuti dei pacchetti o export runtime.

La validazione della configurazione consapevole dei plugin, l'abilitazione automatica all'avvio e il bootstrap dei plugin del Gateway consumano quello snapshot invece di ricostruire indipendentemente metadati di manifesto/indice. PluginLookUpTable deriva dallo stesso snapshot e aggiunge il piano dei plugin di avvio per la configurazione runtime corrente.

Dopo l'avvio, il Gateway mantiene lo snapshot dei metadati corrente come prodotto runtime sostituibile. Il rilevamento ripetuto dei provider runtime può prendere in prestito quello snapshot invece di ricostruire l'indice installato e il registro dei manifesti per ogni passaggio del catalogo provider. Lo snapshot viene cancellato o sostituito allo spegnimento del Gateway, quando cambiano configurazione/inventario dei plugin e quando vengono scritti gli indici installati; i chiamanti ricadono sul percorso freddo manifesto/indice quando non esiste uno snapshot corrente compatibile. I controlli di compatibilità devono includere radici di rilevamento plugin come plugins.load.paths e il workspace predefinito dell'agente, perché i plugin del workspace fanno parte dell'ambito dei metadati.

Lo snapshot e la tabella di lookup mantengono le decisioni di avvio ripetute sul percorso veloce:

• proprietà dei canali
• avvio differito dei canali
• ID dei plugin di avvio
• proprietà dei provider e dei backend CLI
• proprietà di provider di configurazione, alias di comando, provider del catalogo modelli e contratto del manifesto
• validazione 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 dello snapshot, non la mutazione. Ricostruisci lo snapshot quando cambiano configurazione, inventario dei plugin, record di installazione o policy dell'indice persistito. Non trattarlo come un ampio registro globale mutabile e non conservare snapshot storici illimitati. Il caricamento runtime dei plugin resta separato dagli snapshot dei metadati, così lo stato runtime obsoleto non può essere nascosto dietro una cache di metadati.

La regola della cache è documentata in Interni dell'architettura dei plugin: i metadati di manifesto e rilevamento sono freschi a meno che un chiamante non detenga uno snapshot, una tabella di lookup o un registro dei manifesti espliciti per il flusso corrente. Cache nascoste dei metadati e TTL basati sull'orologio non fanno parte del caricamento dei plugin. Solo le cache del loader runtime, dei moduli e degli artefatti delle dipendenze possono persistere dopo che codice o artefatti installati sono stati effettivamente caricati.

Alcuni chiamanti del percorso freddo ricostruiscono ancora registri dei manifesti direttamente dall'indice persistito dei plugin installati invece di ricevere una PluginLookUpTable del Gateway. Quel percorso ora ricostruisce il registro su richiesta; preferisci passare la tabella di lookup corrente o un registro dei manifesti esplicito attraverso i flussi runtime quando un chiamante ne ha già uno.

# Pianificazione dell'attivazione

La pianificazione dell'attivazione fa parte del piano di controllo. I chiamanti possono chiedere quali plugin sono rilevanti per un comando, provider, canale, route, harness dell'agente o capability concreti prima di caricare registri runtime più ampi.

Il planner mantiene compatibile il comportamento corrente dei manifesti:

• i campi activation.* sono suggerimenti espliciti per il planner
• providers, channels, commandAliases, setup.providers, contracts.tools e gli hook restano il fallback di proprietà del manifesto
• l'API del planner solo ID resta disponibile per i chiamanti esistenti
• l'API del piano segnala etichette di motivo, così la diagnostica può distinguere i suggerimenti espliciti dal fallback di proprietà

# Plugin di canale e lo strumento di messaggio 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, e i plugin di canale possiedono la discovery e l'esecuzione specifiche del canale dietro di esso.

Il confine attuale è:

• il core possiede l'host dello strumento message condiviso, il collegamento al prompt, la gestione di sessione/thread e il dispatch dell'esecuzione
• i plugin di canale possiedono la discovery delle azioni con scope, la discovery delle capability e qualsiasi frammento di schema specifico del canale
• i plugin di canale possiedono la grammatica delle conversazioni di sessione specifica del provider, ad esempio come gli id conversazione codificano gli id thread o ereditano dalle conversazioni padre
• i plugin di canale eseguono l'azione finale tramite il proprio adapter di azione

Per i plugin di canale, la superficie SDK è ChannelMessageActionAdapter.describeMessageTool(...). Questa chiamata di discovery unificata consente a un plugin di restituire insieme le proprie azioni visibili, capability e contributi allo schema, così questi elementi non divergono.

Quando un parametro dello strumento messaggi specifico del canale trasporta una sorgente multimediale, ad esempio un percorso locale o un URL multimediale remoto, il plugin dovrebbe anche restituire mediaSourceParams da describeMessageTool(...). Il core usa quell'elenco esplicito per applicare la normalizzazione dei percorsi sandbox e i suggerimenti di accesso ai media in uscita senza codificare rigidamente i nomi dei parametri posseduti dal plugin. Preferisci mappe con scope per azione, non un unico elenco piatto a livello di canale, così un parametro multimediale valido solo per il profilo non viene normalizzato su azioni non correlate come send.

Il core passa lo scope runtime in quel passaggio di discovery. I campi importanti includono:

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

Questo è importante per i plugin sensibili al contesto. Un canale può nascondere o esporre azioni di messaggio in base all'account attivo, alla stanza/thread/messaggio corrente o all'identità attendibile del richiedente, senza codificare rigidamente rami specifici del canale nello strumento message del core.

Questo è il motivo per cui le modifiche di routing dell'embedded runner restano lavoro del plugin: il runner è responsabile dell'inoltro dell'identità della chat/sessione corrente nel confine di discovery del plugin, così lo strumento message condiviso espone la superficie giusta, posseduta dal canale, per il turno corrente.

Per gli helper di esecuzione posseduti dal canale, i plugin inclusi dovrebbero mantenere il runtime di esecuzione dentro i propri moduli di estensione. Il core non possiede più i runtime delle azioni messaggio di Discord, Slack, Telegram o WhatsApp sotto src/agents/tools. Non pubblichiamo sottopercorsi separati plugin-sdk/*-action-runtime, e i plugin inclusi dovrebbero importare il proprio codice runtime locale direttamente dai moduli posseduti dalla loro estensione.

Lo stesso confine si applica in generale alle seam SDK con nomi di provider: il core non dovrebbe importare barrel di convenienza specifici del canale per Slack, Discord, Signal, WhatsApp o estensioni simili. Se il core ha bisogno di un comportamento, deve consumare il barrel api.ts / runtime-api.ts del plugin incluso oppure promuovere l'esigenza a una capability generica e ristretta nell'SDK condiviso.

I plugin inclusi seguono la stessa regola. Il runtime-api.ts di un plugin incluso non dovrebbe riesportare la propria facciata brandizzata openclaw/plugin-sdk/<plugin-id>. Queste facciate brandizzate restano shim di compatibilità per plugin esterni e consumer più vecchi, ma i plugin inclusi dovrebbero usare export locali più sottopercorsi SDK generici e ristretti come openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/runtime-store o openclaw/plugin-sdk/webhook-ingress. Il nuovo codice non dovrebbe aggiungere facciate SDK specifiche dell'id plugin, a meno che il confine di compatibilità per un ecosistema esterno esistente lo richieda.

Per i sondaggi in particolare, ci sono due percorsi di esecuzione:

• outbound.sendPoll è la baseline condivisa per i canali che rientrano nel modello comune di sondaggio
• actions.handleAction("poll") è il percorso preferito per semantiche di sondaggio specifiche del canale o parametri di sondaggio aggiuntivi

Ora il core rimanda il parsing condiviso dei sondaggi finché il dispatch del sondaggio del plugin non rifiuta l'azione, così gli handler di sondaggi posseduti dal plugin possono accettare campi di sondaggio specifici del canale senza essere prima bloccati dal parser generico dei sondaggi.

Consulta Interni dell'architettura dei Plugin per la sequenza completa di avvio.

# Modello di proprietà delle capability

OpenClaw tratta un plugin nativo come il confine di proprietà per una azienda o una funzionalità, non come un insieme casuale di integrazioni non correlate.

Questo significa:

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

Lo stato finale previsto è:

• OpenAI vive in un unico plugin anche se copre modelli testuali, parlato, immagini e video futuri
• un altro vendor può fare lo stesso per la propria superficie
• ai canali non importa quale plugin di vendor possieda il provider; consumano il contratto di capability condiviso esposto dal core

Questa è la distinzione chiave:

• plugin = confine di proprietà
• capability = contratto del core che più plugin possono implementare o consumare

Quindi, se OpenClaw aggiunge un nuovo dominio come il video, la prima domanda non è "quale provider dovrebbe codificare rigidamente la gestione video?" La prima domanda è "qual è il contratto di capability video del core?" Una volta che quel contratto esiste, i plugin di vendor possono registrarsi rispetto a esso e i plugin di canale/funzionalità possono consumarlo.

Se la capability non esiste ancora, la mossa giusta di solito è:

Questo mantiene esplicita la proprietà evitando al tempo stesso comportamenti del core che dipendono da un singolo vendor o da un percorso di codice specifico di un plugin una tantum.

# Stratificazione delle capability

Usa questo modello mentale quando decidi a chi appartiene il codice:

Ad esempio, il TTS segue questa forma:

• il core possiede policy TTS al momento della risposta, ordine di fallback, preferenze e consegna al canale
• openai, elevenlabs e microsoft possiedono le implementazioni di sintesi
• voice-call consuma l'helper runtime TTS per telefonia

Lo stesso pattern dovrebbe essere preferito per capability future.

# Esempio di plugin aziendale multi-capability

Un plugin aziendale dovrebbe risultare coeso dall'esterno. Se OpenClaw ha contratti condivisi per modelli, parlato, trascrizione realtime, voce realtime, comprensione dei media, generazione di immagini, generazione video, fetch web e ricerca web, un vendor può possedere 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({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
      async transcribeAudio(req) {
        return transcribeOpenAiCompatibleAudio({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
    });

    api.registerWebSearchProvider(
      createPluginBackedWebSearchProvider({
        id: "exampleai-search",
        // credential + fetch logic
      }),
    );
  },
};

export default plugin;

Ciò che conta non sono i nomi esattii degli helper. Conta la forma:

• un plugin possiede la superficie del vendor
• il core possiede comunque i contratti di capability
• i canali e i plugin di funzionalità consumano helper api.runtime.*, non codice del vendor
• i test di contratto possono verificare che il plugin abbia registrato le capability che dichiara di possedere

# Esempio di capability: comprensione video

OpenClaw tratta già la comprensione di immagini/audio/video come un'unica capability condivisa. Lo stesso modello di proprietà si applica lì:

Questo evita di incorporare nel core le assunzioni video di un singolo provider. Il plugin possiede la superficie del vendor; il core possiede il contratto di capability e il comportamento di fallback.

La generazione video usa già la stessa sequenza: il core possiede il contratto di capability tipizzato e l'helper runtime, e i plugin di vendor registrano implementazioni api.registerVideoGenerationProvider(...) rispetto a esso.

Hai bisogno di una checklist concreta per il rollout? Consulta Cookbook delle capability.

# Contratti e applicazione

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

Perché è importante:

• gli autori di plugin ottengono un unico standard interno stabile
• il core può rifiutare proprietà duplicate, ad esempio due plugin che registrano lo stesso id provider
• l'avvio può mostrare diagnostica azionabile per registrazioni malformate
• i test di contratto possono applicare la proprietà dei plugin inclusi e prevenire derive silenziose

Ci sono due livelli di applicazione:

L'effetto pratico è che OpenClaw sa in anticipo quale plugin possiede quale superficie. Questo consente a core e canali di comporsi senza soluzione di continuità, perché la proprietà è dichiarata, tipizzata e testabile invece che implicita.

# Cosa appartiene a un contratto

In caso di dubbio, alza il livello di astrazione: definisci prima la capacità, poi lascia che i plugin si colleghino a essa.

# Modello di esecuzione

I plugin nativi di OpenClaw vengono eseguiti in-process con il Gateway. Non sono sandboxati. Un plugin nativo caricato ha lo stesso confine di fiducia a livello di processo del codice core.

I bundle compatibili sono più sicuri per impostazione predefinita perché OpenClaw attualmente li tratta come pacchetti di metadati/contenuti. Nelle versioni attuali, questo significa soprattutto Skills inclusi.

Usa allowlist e percorsi espliciti di installazione/caricamento per i plugin non inclusi. Tratta i plugin dello workspace come codice per il tempo di sviluppo, non come impostazioni predefinite di produzione.

Per i nomi dei pacchetti workspace 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ù ristretto.

# Confine di esportazione

OpenClaw esporta capacità, non comodità di implementazione.

Mantieni pubblica la registrazione delle capacità. Riduci le esportazioni di helper non contrattuali:

• sottopercorsi helper specifici dei plugin inclusi
• sottopercorsi di plumbing runtime non destinati a essere API pubblica
• helper di comodità specifici del vendor
• helper di configurazione/onboarding che sono dettagli di implementazione

I sottopercorsi helper riservati dei plugin inclusi sono stati ritirati dalla mappa di esportazione generata dell'SDK. Mantieni gli helper specifici del proprietario all'interno del pacchetto del plugin proprietario; promuovi solo il comportamento host riutilizzabile a contratti SDK generici come plugin-sdk/gateway-runtime, plugin-sdk/security-runtime e plugin-sdk/plugin-config-runtime.

# Interni e riferimento

Per la pipeline di caricamento, il modello del registro, gli hook runtime dei provider, le route HTTP del Gateway, gli schemi degli strumenti di messaggio, la risoluzione dei target dei canali, i cataloghi dei provider, i plugin del motore di contesto e la guida all'aggiunta di una nuova capacità, consulta Interni dell'architettura dei plugin.

# Correlati

• Creare plugin
• Manifest del plugin
• Configurazione dell'SDK dei plugin