Skip to main content
Riferimento per il pacchettamento dei Plugin (metadati di package.json), i manifest (openclaw.plugin.json), gli entry point di configurazione e gli schemi di configurazione.
Cerchi una guida dettagliata? Le guide pratiche illustrano il pacchettamento nel relativo contesto: Plugin di canale e Plugin provider.

Metadati del pacchetto

Il tuo package.json deve contenere un campo openclaw che indichi al sistema dei Plugin ciò che il tuo Plugin fornisce:
La pubblicazione esterna su ClawHub richiede compat e build. I frammenti canonici per la pubblicazione si trovano in docs/snippets/plugin-publish/.

Campi di openclaw

string[]
File degli entry point (relativi alla radice del pacchetto). Entry point sorgente validi per lo sviluppo nell’area di lavoro e nei checkout git.
string[]
Controparti JavaScript compilate di extensions, preferite quando OpenClaw carica un pacchetto npm installato. Consulta Entry point dell’SDK per l’ordine di risoluzione tra sorgente e versione compilata.
string
Entry point leggero riservato alla configurazione (facoltativo).
string
Controparte JavaScript compilata di setupEntry. Richiede che sia impostato anche setupEntry.
object
Identità di riserva del Plugin { id, label }, utilizzata quando un Plugin non dispone di metadati di canale/provider da cui ricavare un id o un’etichetta.
object
Metadati del catalogo dei canali per le interfacce di configurazione, selezione, avvio rapido e stato.
object
Indicazioni per l’installazione: npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery, requiredPlatformPackages.
object
Flag del comportamento di avvio.
object
Intervallo di versioni di pluginApi supportato da questo Plugin. Obbligatorio per le pubblicazioni esterne su ClawHub.
Gli id dei provider (providers: string[]) sono metadati del manifest, non del pacchetto. Dichiarali in openclaw.plugin.json, non qui; consulta Manifest del Plugin.

openclaw.channel

openclaw.channel contiene metadati leggeri del pacchetto per il rilevamento dei canali e le interfacce di configurazione prima del caricamento del runtime. Esempio:
exposure supporta:
  • configured: include il canale nelle interfacce di elenco dei canali configurati e di stato
  • setup: include il canale nei selettori interattivi di configurazione
  • docs: contrassegna il canale come pubblico nelle interfacce di documentazione e navigazione
showConfigured e showInSetup rimangono supportati come alias legacy. Preferisci exposure.

openclaw.install

openclaw.install è un metadato del pacchetto, non del manifest.
L’onboarding interattivo usa openclaw.install per le interfacce di installazione su richiesta: se il tuo Plugin espone opzioni di autenticazione del provider o metadati di configurazione/catalogo dei canali prima del caricamento del runtime, l’onboarding può richiedere un’installazione da ClawHub, npm o locale, installare o abilitare il Plugin e quindi proseguire con il flusso selezionato. Le opzioni ClawHub usano clawhubSpec e sono preferite quando presenti; le opzioni npm richiedono metadati di catalogo attendibili con un npmSpec del registro (le versioni esatte e expectedIntegrity sono vincoli facoltativi, applicati durante l’installazione o l’aggiornamento quando impostati). Mantieni «cosa mostrare» in openclaw.plugin.json e «come installarlo» in package.json.
Se minHostVersion è impostato, viene applicato sia durante l’installazione sia durante il caricamento dal registro dei manifest non inclusi. Gli host meno recenti ignorano i Plugin esterni; le stringhe di versione non valide vengono rifiutate. Si presume che i Plugin sorgente inclusi abbiano la stessa versione del checkout dell’host.
Per le installazioni npm vincolate, mantieni la versione esatta in npmSpec e aggiungi l’integrità prevista dell’artefatto:
allowInvalidConfigRecovery non è un meccanismo generale per aggirare configurazioni non valide. È limitato esclusivamente al recupero dei Plugin inclusi e consente alla reinstallazione/configurazione di correggere residui noti degli aggiornamenti, come un percorso mancante di un Plugin incluso o una voce channels.<id> obsoleta relativa allo stesso Plugin. Se la configurazione non è valida per motivi non correlati, l’installazione continua a bloccarsi in modo sicuro e indica all’operatore di eseguire openclaw doctor --fix.

Caricamento completo differito

I Plugin di canale possono abilitare il caricamento differito con:
Quando questa opzione è abilitata, OpenClaw carica soltanto setupEntry durante la fase di avvio precedente all’ascolto, anche per i canali già configurati. L’entry point completo viene caricato dopo che il Gateway inizia l’ascolto.
Abilita il caricamento differito solo quando setupEntry registra tutto ciò di cui il Gateway ha bisogno prima di iniziare l’ascolto (registrazione del canale, route HTTP, metodi del Gateway). Se l’entry point completo gestisce funzionalità necessarie all’avvio, mantieni il comportamento predefinito.
Se gli entry point di configurazione/completi registrano metodi RPC del Gateway, mantienili sotto un prefisso specifico del Plugin. Gli spazi dei nomi amministrativi riservati del nucleo (config.*, exec.approvals.*, wizard.*, update.*) restano di proprietà del nucleo e vengono sempre normalizzati in operator.admin.

Manifest del Plugin

Ogni plugin nativo deve includere un file openclaw.plugin.json nella radice del pacchetto. OpenClaw lo utilizza per convalidare la configurazione senza eseguire il codice del plugin.
Per i plugin di canale, aggiungere channels (mentre i plugin provider aggiungono providers):
Anche i plugin senza configurazione devono includere uno schema. Uno schema vuoto è valido:
Consultare Manifest del plugin per il riferimento completo dello schema.

Pubblicazione su ClawHub

I pacchetti di Skills e plugin utilizzano comandi di pubblicazione ClawHub distinti. Per i pacchetti di plugin, utilizzare il comando specifico per i pacchetti:
clawhub skill publish <path> è un comando diverso, destinato alla pubblicazione di una cartella di Skills, non di un pacchetto di plugin. Consultare Pubblicazione su ClawHub.

Punto di ingresso per la configurazione

setup-entry.ts è un’alternativa leggera a index.ts che OpenClaw carica quando necessita soltanto delle superfici di configurazione (procedura di introduzione, riparazione della configurazione, ispezione dei canali disabilitati):
In questo modo si evita di caricare codice di runtime pesante (librerie crittografiche, registrazioni CLI, servizi in background) durante i flussi di configurazione. I canali inclusi nell’area di lavoro che mantengono esportazioni sicure per la configurazione in moduli collaterali possono utilizzare defineBundledChannelSetupEntry(...) da openclaw/plugin-sdk/channel-entry-contract anziché defineSetupPluginEntry(...). Questo contratto per i componenti inclusi supporta anche un’esportazione facoltativa runtime, così il collegamento del runtime durante la configurazione può rimanere leggero ed esplicito.
  • Il canale è disabilitato, ma necessita delle superfici di configurazione o della procedura di introduzione.
  • Il canale è abilitato, ma non configurato.
  • Il caricamento differito è abilitato (deferConfiguredChannelFullLoadUntilAfterListen).
  • L’oggetto del plugin di canale (tramite defineSetupPluginEntry).
  • Tutte le route HTTP necessarie prima che il Gateway inizi l’ascolto.
  • Tutti i metodi del Gateway necessari durante l’avvio.
Tali metodi del Gateway utilizzati all’avvio devono comunque evitare gli spazi dei nomi amministrativi riservati al core, come config.* o update.*.
  • Registrazioni CLI.
  • Servizi in background.
  • Importazioni di runtime pesanti (crittografia, SDK).
  • Metodi del Gateway necessari soltanto dopo l’avvio.

Importazioni mirate degli helper di configurazione

Per i percorsi critici dedicati esclusivamente alla configurazione, quando è necessaria soltanto una parte della superficie di configurazione è preferibile utilizzare le interfacce mirate degli helper di configurazione anziché l’interfaccia generale plugin-sdk/setup: Utilizzare l’interfaccia generale plugin-sdk/setup quando è necessario il set completo di strumenti condivisi per la configurazione, inclusi gli helper per le modifiche alla configurazione, come moveSingleAccountChannelSectionToDefaultAccount(...). Utilizzare createSetupTranslator(...) per i testi fissi della procedura guidata di configurazione. Segue la lingua della procedura guidata CLI (OPENCLAW_LOCALE, quindi le variabili di lingua del sistema) e ricorre all’inglese come lingua di riserva. Mantenere il testo di configurazione specifico del plugin nel codice di proprietà del plugin e utilizzare le chiavi del catalogo condiviso soltanto per etichette comuni di configurazione, testo di stato e testi di configurazione dei plugin ufficiali inclusi. Gli adattatori per le modifiche di configurazione rimangono sicuri da importare nei percorsi critici. La ricerca della superficie del contratto per la promozione inclusa di un singolo account è differita; pertanto, l’importazione di plugin-sdk/setup-runtime non carica anticipatamente il rilevamento delle superfici dei contratti inclusi prima dell’effettivo utilizzo dell’adattatore.

Promozione di un singolo account gestita dal canale

Quando un canale passa da una configurazione di primo livello per un singolo account a channels.<id>.accounts.*, il comportamento condiviso predefinito sposta i valori promossi specifici dell’account in accounts.default. I canali inclusi possono restringere o sostituire tale promozione tramite la propria superficie del contratto di configurazione:
  • singleAccountKeysToMove: chiavi aggiuntive di primo livello da spostare nell’account promosso
  • namedAccountPromotionKeys: quando esistono già account denominati, soltanto queste chiavi vengono spostate nell’account promosso; le chiavi condivise relative a criteri e consegna rimangono nella radice del canale
  • resolveSingleAccountPromotionTarget(...): sceglie quale account esistente riceve i valori promossi
Matrix è l’esempio incluso attuale. Se esiste già esattamente un account Matrix denominato oppure se defaultAccount fa riferimento a una chiave esistente non canonica, come Ops, la promozione conserva tale account anziché creare una nuova voce accounts.default.

Schema di configurazione

La configurazione del plugin viene convalidata rispetto allo schema JSON nel manifest. Gli utenti configurano i plugin tramite:
Durante la registrazione, il plugin riceve questa configurazione come api.pluginConfig. Per la configurazione specifica del canale, utilizzare invece la sezione di configurazione del canale:

Creazione degli schemi di configurazione dei canali

Utilizzare buildChannelConfigSchema per convertire uno schema Zod nel wrapper ChannelConfigSchema usato dagli artefatti di configurazione di proprietà del plugin:
Se il contratto è già definito come schema JSON o TypeBox, utilizzare l’helper diretto affinché OpenClaw possa evitare la conversione da Zod a schema JSON nei percorsi dei metadati:
Per i plugin di terze parti, il contratto per i percorsi non critici rimane il manifest del plugin: replicare lo schema JSON generato in openclaw.plugin.json#channelConfigs, in modo che lo schema di configurazione, la configurazione e le superfici dell’interfaccia utente possano esaminare channels.<id> senza caricare il codice di runtime.

Procedure guidate di configurazione

I plugin di canale possono fornire procedure guidate interattive per openclaw onboard. La procedura guidata è un oggetto ChannelSetupWizard nel ChannelPlugin:
ChannelSetupWizard supporta inoltre textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize e altro ancora. Consultare src/setup-core.ts del plugin Discord per un esempio completo incluso.
Per le richieste relative all’elenco consentito dei messaggi diretti che richiedono soltanto il flusso standard nota -> richiesta -> analisi -> unione -> modifica, è preferibile utilizzare gli helper di configurazione condivisi da openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) e createNestedChannelParsedAllowFromPrompt(...).
Per i blocchi di stato della configurazione del canale che variano soltanto per etichette, punteggi e righe aggiuntive facoltative, è preferibile utilizzare createStandardChannelSetupStatus(...) da openclaw/plugin-sdk/setup anziché ricreare manualmente lo stesso oggetto status in ogni plugin.
Per le superfici di configurazione facoltative che devono apparire soltanto in determinati contesti, utilizzare createOptionalChannelSetupSurface da openclaw/plugin-sdk/channel-setup:
plugin-sdk/channel-setup espone inoltre i costruttori di livello inferiore createOptionalChannelSetupAdapter(...) e createOptionalChannelSetupWizard(...) quando è necessaria soltanto una delle due parti di tale superficie di installazione facoltativa.L’adattatore/la procedura guidata facoltativi generati adottano un comportamento fail-closed durante le scritture effettive della configurazione. Riutilizzano un unico messaggio che richiede l’installazione in validateInput, applyAccountConfig e finalize e aggiungono un collegamento alla documentazione quando è impostato docsPath.
Per le interfacce di configurazione basate su binari, preferisci gli helper condivisi con delega anziché copiare in ogni canale la stessa logica di integrazione per binari e stato:
  • createDetectedBinaryStatus(...) per i blocchi di stato che variano solo per etichette, suggerimenti, punteggi e rilevamento dei binari
  • createCliPathTextInput(...) per gli input di testo basati su percorsi
  • createDelegatedSetupWizardStatusResolvers(...), createDelegatedPrepare(...), createDelegatedFinalize(...) e createDelegatedResolveConfigured(...) quando setupEntry deve inoltrare in modo lazy a una procedura guidata completa più articolata
  • createDelegatedTextInputShouldPrompt(...) quando setupEntry deve solo delegare una decisione textInputs[*].shouldPrompt

Pubblicazione e installazione

Plugin esterni: pubblica su ClawHub, quindi installa:
Le specifiche di pacchetto semplici vengono installate da npm durante il passaggio all’avvio, a meno che il nome non corrisponda all’ID di un Plugin incluso o ufficiale; in tal caso, OpenClaw usa invece la relativa copia locale/ufficiale. Usa clawhub:, npm:, git: o npm-pack: per selezionare la sorgente in modo deterministico — consulta Gestire i Plugin.
Plugin nel repository: inseriscili nell’albero dell’area di lavoro dei Plugin inclusi; vengono rilevati automaticamente durante la compilazione.
Per le installazioni provenienti da npm, openclaw plugins install installa il pacchetto in un progetto dedicato al Plugin sotto ~/.openclaw/npm/projects, con gli script del ciclo di vita disabilitati (--ignore-scripts). Mantieni gli alberi delle dipendenze dei Plugin esclusivamente in JS/TS ed evita i pacchetti che richiedono compilazioni postinstall.
L’avvio del Gateway non installa le dipendenze dei Plugin. I flussi di installazione npm/git/ClawHub gestiscono la convergenza delle dipendenze; le dipendenze dei Plugin locali devono essere già installate.
I metadati dei pacchetti inclusi sono espliciti e non vengono dedotti dal codice JavaScript compilato all’avvio del Gateway. Le dipendenze di runtime appartengono al pacchetto del Plugin che ne è proprietario; l’avvio della distribuzione di OpenClaw non ripara né duplica mai le dipendenze dei Plugin.

Contenuti correlati