Configurazione e impostazioni del Plugin

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

Metadati del pacchetto

Il tuo package.json deve avere un campo openclaw che indica al sistema dei 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 di openclaw

openclaw.channel

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

openclaw.install

openclaw.install è metadato di pacchetto, non 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 optare per 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 precedente all'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 amministrativi core riservati (config.*, exec.approvals.*, wizard.*, update.*) restano di proprietà del core e vengono sempre risolti in operator.admin.

Manifest del Plugin

Ogni plugin nativo deve includere un openclaw.plugin.json nella radice del pacchetto. OpenClaw lo usa per convalidare 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  }}

Vedi 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 gli servono solo le 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 bundled del workspace 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 bundled supporta anche un’esportazione opzionale runtime, così il cablaggio runtime in fase di setup può restare leggero ed esplicito.

Import stretti degli helper di setup

Per percorsi caldi solo di setup, preferisci le seam strette degli helper di setup rispetto all’umbrella più ampio plugin-sdk/setup quando ti serve solo una parte della superficie di setup:

Usa la seam più ampia plugin-sdk/setup quando vuoi l’intero toolkit di setup condiviso, inclusi helper di patch della config come moveSingleAccountChannelSectionToDefaultAccount(...).

Usa createSetupTranslator(...) per testi fissi della procedura guidata di setup. Segue la locale 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 ufficiale dei Plugin bundled.

Gli adapter di patch del setup restano sicuri da importare nei percorsi caldi. La loro ricerca della superficie di contratto per la promozione single-account bundled è lazy, quindi importare plugin-sdk/setup-runtime non carica in modo eager la discovery della superficie di contratto bundled prima che l’adapter venga effettivamente usato.

Promozione single-account di proprietà del canale

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

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

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

Schema di config

La config del Plugin viene validata 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"],    },  },}

Costruzione degli 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 scrivi già 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 metadata:

  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 cold-path resta il manifest del Plugin: rispecchia il JSON Schema generato in openclaw.plugin.json#channelConfigs così schema di config, setup e superfici UI possono ispezionare channels.<id> senza caricare codice runtime.

Procedure guidate di setup

I Plugin di canale possono fornire procedure guidate di setup 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. Vedi i pacchetti Plugin bundled (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, 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: posizionali 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

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