package.json), i manifest (openclaw.plugin.json), gli entry point di configurazione e gli schemi di configurazione.
Metadati del pacchetto
Il tuopackage.json deve contenere un campo openclaw che indichi al sistema dei Plugin ciò che il tuo Plugin fornisce:
- Plugin di canale
- Plugin provider / configurazione di base ClawHub
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 statosetup: include il canale nei selettori interattivi di configurazionedocs: 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.
Comportamento dell'onboarding
Comportamento dell'onboarding
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.Applicazione di minHostVersion
Applicazione di minHostVersion
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.Installazioni npm vincolate
Installazioni npm vincolate
Per le installazioni npm vincolate, mantieni la versione esatta in
npmSpec e aggiungi l’integrità prevista dell’artefatto:Ambito di allowInvalidConfigRecovery
Ambito di allowInvalidConfigRecovery
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: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.
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 fileopenclaw.plugin.json nella radice del pacchetto. OpenClaw lo utilizza per convalidare la configurazione senza eseguire il codice del plugin.
channels (mentre i plugin provider aggiungono providers):
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):
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.
Quando OpenClaw utilizza setupEntry anziché il punto di ingresso completo
Quando OpenClaw utilizza setupEntry anziché il punto di ingresso completo
- 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).
Cosa deve registrare setupEntry
Cosa deve registrare setupEntry
- 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.
config.* o update.*.Cosa NON deve includere setupEntry
Cosa NON deve includere setupEntry
- 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 generaleplugin-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 achannels.<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 promossonamedAccountPromotionKeys: 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 canaleresolveSingleAccountPromotionTarget(...): 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:api.pluginConfig.
Per la configurazione specifica del canale, utilizzare invece la sezione di configurazione del canale:
Creazione degli schemi di configurazione dei canali
UtilizzarebuildChannelConfigSchema per convertire uno schema Zod nel wrapper ChannelConfigSchema usato dagli artefatti di configurazione di proprietà del plugin:
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 peropenclaw 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.
Richieste allowFrom condivise
Richieste allowFrom condivise
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(...).Stato standard della configurazione del canale
Stato standard della configurazione del canale
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.Superficie facoltativa di configurazione del canale
Superficie facoltativa di configurazione del canale
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.Helper di configurazione basati su binari
Helper di configurazione basati su binari
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 binaricreateCliPathTextInput(...)per gli input di testo basati su percorsicreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...)ecreateDelegatedResolveConfigured(...)quandosetupEntrydeve inoltrare in modo lazy a una procedura guidata completa più articolatacreateDelegatedTextInputShouldPrompt(...)quandosetupEntrydeve solo delegare una decisionetextInputs[*].shouldPrompt
Pubblicazione e installazione
Plugin esterni: pubblica su ClawHub, quindi installa:- npm
- Solo ClawHub
- Specifica del pacchetto npm
clawhub:, npm:, git: o npm-pack: per selezionare la sorgente in modo deterministico — consulta Gestire i Plugin.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.
Contenuti correlati
- Creazione di Plugin — guida introduttiva dettagliata
- Manifest del Plugin — riferimento completo allo schema del manifest
- Punti di ingresso dell’SDK —
definePluginEntryedefineChannelPluginEntry