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 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 openclaw

# openclaw.channel

openclaw.channel è un metadato di pacchetto leggero per il rilevamento dei canali e le superfici di setup prima del caricamento a 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 setup/configurazione
• docs: contrassegna il canale come pubblico nelle superfici di documentazione/navigazione

# openclaw.install

openclaw.install è metadato di pacchetto, non metadato 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 attivare 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 setup/completa registra metodi RPC del Gateway, tienili 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-run
clawhub 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 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 del 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 runtime facoltativa, così il cablaggio runtime in fase di setup può restare leggero ed esplicito.

# Import mirati degli helper di setup

Per percorsi caldi solo di setup, preferisci le interfacce helper di setup mirate rispetto all’ombrello più ampio 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 toolkit di setup condiviso, inclusi helper per patch di configurazione come moveSingleAccountChannelSectionToDefaultAccount(...).

Gli adapter di patch del setup restano sicuri da importare nei percorsi caldi. La ricerca della superficie del contratto inclusa per la promozione ad account singolo è lazy, quindi importare plugin-sdk/setup-runtime non carica immediatamente il rilevamento della superficie del contratto inclusa prima che l’adapter venga effettivamente usato.

# Promozione ad account singolo di proprietà del canale

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

I canali inclusi possono restringere o sovrascrivere quella promozione tramite la propria superficie del contratto di setup:

• singleAccountKeysToMove: chiavi top-level aggiuntive che devono spostarsi nell’account promosso
• namedAccountPromotionKeys: quando esistono già account denominati, solo queste chiavi si spostano nell’account promosso; le chiavi condivise di policy/consegna restano alla 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 tuo 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ò saltare 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 del percorso freddo resta il manifest del Plugin: replica il JSON Schema generato in openclaw.plugin.json#channelConfigs così lo schema di configurazione, il setup e le superfici 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 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 inclusi (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: collocali nell'albero dell'area di lavoro dei Plugin inclusi in bundle 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 dettagliata
• Manifest del Plugin — riferimento completo allo schema del manifest
• Punti di ingresso dell'SDK — definePluginEntry e defineChannelPluginEntry