Installazione e configurazione del Plugin

Riferimento per il packaging dei Plugin (metadati di package.json), manifest (openclaw.plugin.json), voci di configurazione e schemi di configurazione.

Metadati del pacchetto

Il tuo package.json richiede un campo openclaw che indichi al sistema di Plugin cosa fornisce il tuo Plugin:

{  "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",  "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 openclaw

openclaw.channel

openclaw.channel è costituito da metadati di pacchetto leggeri per la scoperta dei canali e le superfici 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 superfici di elenco in stile configurazione/stato
• setup: include il canale nei selettori interattivi di configurazione
• docs: contrassegna il canale come rivolto al pubblico nelle superfici di documentazione/navigazione

openclaw.install

openclaw.install contiene metadati del pacchetto, non metadati del manifest.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/[email protected]",      "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 abilitato, OpenClaw carica solo setupEntry durante la fase di avvio prima dell'ascolto, anche per i canali già configurati. La voce completa viene caricata dopo che il Gateway inizia ad ascoltare.

Se la tua voce di configurazione/completa registra metodi RPC del Gateway, mantienili su un prefisso specifico del Plugin. Gli spazi dei nomi di amministrazione core riservati (config.*, exec.approvals.*, wizard.*, update.*) restano di proprietà del core e si risolvono sempre in operator.admin.

Manifest del Plugin

Ogni Plugin nativo deve includere un openclaw.plugin.json nella radice del pacchetto. OpenClaw lo usa per validare la configurazione senza eseguire 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, aggiungi kind e channels:

{  "id": "my-channel",  "kind": "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  }}

Consulta Manifest del Plugin per il riferimento completo dello schema.

Pubblicazione su ClawHub

Per i pacchetti Plugin, usa il comando ClawHub specifico del pacchetto:

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

Voce di setup

Il file setup-entry.ts è un'alternativa leggera a index.ts che OpenClaw carica quando ha bisogno solo delle superfici di setup (onboarding, riparazione della config, ispezione dei canali disabilitati).

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

Questo evita di caricare codice runtime pesante (librerie crittografiche, registrazioni CLI, servizi in background) durante i flussi di setup.

I canali dell'area di lavoro inclusi nel bundle che mantengono esportazioni sicure per il setup in moduli sidecar possono usare defineBundledChannelSetupEntry(...) da openclaw/plugin-sdk/channel-entry-contract invece di defineSetupPluginEntry(...). Quel contratto incluso nel bundle supporta anche un'esportazione opzionale runtime, così il cablaggio runtime in fase di setup può restare leggero ed esplicito.

Import mirati degli helper di setup

Per percorsi critici solo di setup, preferisci le interfacce ristrette degli helper di setup rispetto al più ampio ombrello plugin-sdk/setup quando ti serve solo una parte della superficie di setup:

Usa l'interfaccia più ampia plugin-sdk/setup quando vuoi l'intero set di strumenti di setup condiviso, inclusi helper per patch di config come moveSingleAccountChannelSectionToDefaultAccount(...).

Gli adapter di patch del setup restano sicuri da importare nei percorsi critici. La loro ricerca della superficie del contratto di promozione per account singolo inclusa nel bundle è lazy, quindi importare plugin-sdk/setup-runtime non carica anticipatamente la discovery della superficie del contratto inclusa nel bundle prima che l'adapter venga effettivamente usato.

Promozione single-account di proprietà del canale

Quando un canale passa da una config top-level per account singolo a channels.<id>.accounts.*, il comportamento condiviso predefinito è spostare i valori promossi con ambito account in accounts.default.

I canali inclusi nel bundle possono restringere o sovrascrivere quella promozione tramite la loro superficie di contratto di setup:

• singleAccountKeysToMove: chiavi top-level aggiuntive che devono essere spostate nell'account promosso
• namedAccountPromotionKeys: quando esistono già account con nome, solo queste chiavi vengono spostate nell'account promosso; le chiavi condivise di policy/delivery restano alla radice del canale
• resolveSingleAccountPromotionTarget(...): sceglie quale account esistente riceve i valori promossi

Schema di config

La config del Plugin viene convalidata rispetto al JSON Schema nel tuo manifest. Gli utenti configurano i Plugin tramite:

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

Il tuo Plugin riceve questa config come api.pluginConfig durante la registrazione.

Per la config specifica del canale, usa invece la sezione di config del canale:

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

Costruire schemi di config dei canali

Usa buildChannelConfigSchema per convertire uno schema Zod nel wrapper ChannelConfigSchema usato dagli artefatti di config 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 hai già scritto il contratto come JSON Schema o TypeBox, usa l'helper diretto così OpenClaw può saltare la conversione da Zod a JSON Schema nei percorsi di metadati:

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

Per Plugin di terze parti, il contratto del percorso a freddo resta il manifest del Plugin: replica il JSON Schema generato in openclaw.plugin.json#channelConfigs così le superfici di schema di config, setup e UI possono ispezionare channels.<id> senza caricare codice runtime.

Wizard di setup

I Plugin di canale possono fornire wizard di setup interattivi per openclaw onboard. Il wizard è un oggetto ChannelSetupWizard sul 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),        };      },    },  ],};

Il tipo ChannelSetupWizard supporta credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize e altro. Vedi i pacchetti Plugin inclusi nel bundle (per esempio il Plugin Discord src/channel.setup.ts) per esempi completi.

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, poi 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: posizionali sotto l'albero dell'area di lavoro dei Plugin inclusi e vengono rilevati automaticamente durante la build.

Gli utenti possono installare:

openclaw plugins install <package-name>

I metadati dei pacchetti inclusi sono espliciti, non dedotti dal JavaScript compilato all'avvio del Gateway. Le dipendenze runtime appartengono al pacchetto Plugin che le possiede; l'avvio di OpenClaw pacchettizzato non ripara ne' replica mai le dipendenze dei Plugin.

Correlati

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