Configurazione e impostazioni del Plugin

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.

Metadati del pacchetto

Il tuo package.json deve contenere un campo openclaw che indichi al sistema dei Plugin ciò che il tuo Plugin fornisce:

{  "name": "@myorg/openclaw-my-channel",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "channel": {      "id": "my-channel",      "label": "My Channel",      "blurb": "Short description of the channel."    }  }}

{  "name": "@myorg/openclaw-my-plugin",  "version": "1.0.0",  "type": "module",  "dependencies": {    "typebox": "1.1.39"  },  "peerDependencies": {    "openclaw": ">=2026.3.24-beta.2"  },  "openclaw": {    "extensions": ["./index.ts"],    "compat": {      "pluginApi": ">=2026.3.24-beta.2",      "minGatewayVersion": "2026.3.24-beta.2"    },    "build": {      "openclawVersion": "2026.3.24-beta.2",      "pluginSdkVersion": "2026.3.24-beta.2"    }  }}

Campi di openclaw

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:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "My Channel",      "selectionLabel": "My Channel (self-hosted)",      "detailLabel": "My Channel Bot",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Webhook-based self-hosted chat integration.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Guide:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

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

openclaw.install

openclaw.install è un metadato del pacchetto, non del manifest.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

Caricamento completo differito

I Plugin di canale possono abilitare il caricamento differito con:

{  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "startup": {      "deferConfiguredChannelFullLoadUntilAfterListen": true    }  }}

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.

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.

{  "id": "my-plugin",  "name": "My Plugin",  "description": "Adds My Plugin capabilities to OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Webhook verification secret"      }    }  }}

Per i plugin di canale, aggiungere channels (mentre i plugin provider aggiungono providers):

{  "id": "my-channel",  "channels": ["my-channel"],  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

Anche i plugin senza configurazione devono includere uno schema. Uno schema vuoto è valido:

{  "id": "my-plugin",  "configSchema": {    "type": "object",    "additionalProperties": false  }}

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 package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

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):

// setup-entry.ts  export default defineSetupPluginEntry(myChannelPlugin);

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.

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

Schema di configurazione

La configurazione del plugin viene convalidata rispetto allo schema JSON nel manifest. Gli utenti configurano i plugin tramite:

{  plugins: {    entries: {      "my-plugin": {        config: {          webhookSecret: "abc123",        },      },    },  },}

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:

{  channels: {    "my-channel": {      token: "bot-token",      allowFrom: ["user1", "user2"],    },  },}

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:

  const accountSchema = z.object({  token: z.string().optional(),  allowFrom: z.array(z.string()).optional(),  accounts: z.object({}).catchall(z.any()).optional(),  defaultAccount: z.string().optional(),}); const configSchema = buildChannelConfigSchema(accountSchema);

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:

  const configSchema = buildJsonChannelConfigSchema(  Type.Object({    token: Type.Optional(Type.String()),    allowFrom: Type.Optional(Type.Array(Type.String())),  }),);

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:

 const setupWizard: ChannelSetupWizard = {  channel: "my-channel",  status: {    configuredLabel: "Connected",    unconfiguredLabel: "Not configured",    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),  },  credentials: [    {      inputKey: "token",      providerHint: "my-channel",      credentialLabel: "Bot token",      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",      keepPrompt: "Keep current token?",      inputPrompt: "Enter your bot token:",      inspect: ({ cfg, accountId }) => {        const token = (cfg.channels as any)?.["my-channel"]?.token;        return {          accountConfigured: Boolean(token),          hasConfiguredValue: Boolean(token),        };      },    },  ],};

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.

import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; const setupSurface = createOptionalChannelSetupSurface({  channel: "my-channel",  label: "My Channel",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// Returns { setupAdapter, setupWizard }

Pubblicazione e installazione

Plugin esterni: pubblica su ClawHub, quindi installa:

openclaw plugins install @myorg/openclaw-my-plugin

openclaw plugins install clawhub:@myorg/openclaw-my-plugin

openclaw plugins install npm:@myorg/openclaw-my-plugin

Plugin nel repository: inseriscili nell'albero dell'area di lavoro dei Plugin inclusi; vengono rilevati automaticamente durante la compilazione.

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

• Creazione di Plugin — guida introduttiva dettagliata
• Manifest del Plugin — riferimento completo allo schema del manifest
• Punti di ingresso dell'SDK — definePluginEntry e defineChannelPluginEntry