Impostazione e configurazione del Plugin

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

Metadati del pacchetto

Il tuo package.json richiede un campo openclaw che indica 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",  "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 openclaw

openclaw.channel

openclaw.channel è un metadato di pacchetto leggero per il rilevamento dei canali e le superfici di setup 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 configurate/in stile stato
• setup: include il canale nei selettori interattivi di setup/configurazione
• docs: contrassegna il canale come pubblico nelle superfici di documentazione/navigazione

openclaw.install

openclaw.install è un metadato di pacchetto, non un metadato di 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 è abilitato, OpenClaw carica solo setupEntry durante la fase di avvio pre-listen, anche per i canali già configurati. La voce completa viene caricata dopo che il gateway inizia ad ascoltare.

Se la tua voce di setup/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 distribuire 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 distribuire 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 per 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 servono solo le superfici di setup (onboarding, riparazione della configurazione, 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 workspace inclusi 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 supporta anche un'esportazione opzionale runtime, così il cablaggio runtime in fase di setup può restare leggero ed esplicito.

Import ristretti degli helper di setup

Per percorsi caldi solo di setup, preferisci i punti di integrazione ristretti degli helper di setup rispetto all'ombrello più ampio plugin-sdk/setup quando ti serve solo una parte della superficie di setup:

Usa il punto di integrazione più ampio plugin-sdk/setup quando vuoi l'intero toolbox di setup condiviso, inclusi helper di patch della configurazione come moveSingleAccountChannelSectionToDefaultAccount(...).

Usa createSetupTranslator(...) per il testo fisso della procedura guidata di setup. Segue la lingua della procedura guidata CLI (OPENCLAW_LOCALE, poi le variabili di locale di sistema) e ripiega sull'inglese. Mantieni il testo di setup specifico del Plugin nel codice di proprietà del Plugin e usa chiavi di catalogo condivise solo per etichette di setup comuni, testo di stato e testo di setup dei Plugin ufficiali inclusi.

Gli adattatori di patch del setup restano sicuri da importare nei percorsi caldi. La loro ricerca della superficie del contratto di promozione single-account inclusa è lazy, quindi importare plugin-sdk/setup-runtime non carica anticipatamente la discovery delle superfici di contratto incluse prima che l'adattatore venga effettivamente usato.

Promozione single-account di proprietà del canale

Quando un canale passa da una configurazione di primo livello con account singolo a channels.<id>.accounts.*, il comportamento condiviso predefinito consiste nello spostare i valori promossi con ambito account in accounts.default.

I canali in bundle possono restringere o sovrascrivere tale promozione tramite la superficie del loro contratto di configurazione:

• singleAccountKeysToMove: chiavi aggiuntive di primo livello che devono essere spostate nell'account promosso
• namedAccountPromotionKeys: quando esistono già account denominati, solo queste chiavi vengono spostate nell'account promosso; le chiavi condivise di criterio/consegna restano nella radice del canale
• resolveSingleAccountPromotionTarget(...): sceglie quale account esistente riceve i valori promossi

Schema di configurazione

La configurazione del Plugin viene validata rispetto al JSON Schema nel manifest. Gli utenti configurano i plugin tramite:

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

Il tuo plugin riceve questa configurazione come api.pluginConfig durante la registrazione.

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

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

Creazione degli schemi di configurazione dei canali

Usa 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 scrivi già il contratto come JSON Schema o TypeBox, usa l'helper diretto così OpenClaw può evitare la conversione da Zod a JSON Schema 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 nel percorso a freddo resta il manifest del plugin: rispecchia il JSON Schema generato in openclaw.plugin.json#channelConfigs così lo schema di configurazione, la configurazione guidata e le superfici dell'interfaccia utente possono ispezionare channels.<id> senza caricare codice runtime.

Configurazioni guidate

I plugin di canale possono fornire configurazioni guidate interattive per openclaw onboard. La procedura guidata è un oggetto ChannelSetupWizard su 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. Consulta i pacchetti dei plugin in 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: inseriscili sotto l'albero dell'area di lavoro dei Plugin inclusi e verranno 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 di runtime appartengono al pacchetto Plugin che le possiede; l'avvio di OpenClaw pacchettizzato non ripara né replica mai le dipendenze dei Plugin.

Correlati

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