Punti di ingresso dei Plugin

Ogni plugin esporta un oggetto voce predefinito. L’SDK fornisce tre helper per crearli. Per i plugin installati, package.json dovrebbe indirizzare il caricamento runtime al JavaScript compilato quando disponibile:

{
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"],
    "setupEntry": "./src/setup-entry.ts",
    "runtimeSetupEntry": "./dist/setup-entry.js"
  }
}

extensions e setupEntry rimangono voci sorgente valide per lo sviluppo da workspace e checkout git. runtimeExtensions e runtimeSetupEntry sono preferite quando OpenClaw carica un pacchetto installato e consentono ai pacchetti npm di evitare la compilazione TypeScript a runtime. Le voci runtime esplicite sono obbligatorie: runtimeSetupEntry richiede setupEntry, e gli artifact mancanti di runtimeExtensions o runtimeSetupEntry fanno fallire installazione/discovery invece di ripiegare silenziosamente sul sorgente. Se un pacchetto installato dichiara solo una voce sorgente TypeScript, OpenClaw userà un peer compilato dist/*.js corrispondente quando esiste, quindi ripiegherà sul sorgente TypeScript. Tutti i percorsi delle voci devono restare all’interno della directory del pacchetto del plugin. Le voci runtime e i peer JavaScript compilati inferiti non rendono valido un percorso sorgente extensions o setupEntry che esce dalla directory.

Cerchi una guida passo passo? Consulta Plugin di canale o Plugin provider per guide passo passo.

`definePluginEntry`

Importazione: openclaw/plugin-sdk/plugin-entry Per plugin provider, plugin di strumenti, plugin di hook e tutto ciò che non è un canale di messaggistica.

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
  },
});

Campo	Tipo	Obbligatorio	Predefinito
`id`	`string`	Sì	-
`name`	`string`	Sì	-
`description`	`string`	Sì	-
`kind`	`string`	No	-
`configSchema`	`OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema`	No	Schema oggetto vuoto
`register`	`(api: OpenClawPluginApi) => void`	Sì	-

id deve corrispondere al tuo manifest openclaw.plugin.json.
kind serve per slot esclusivi: "memory" o "context-engine".
configSchema può essere una funzione per la valutazione lazy.
OpenClaw risolve e memorizza quello schema al primo accesso, quindi i builder di schema costosi vengono eseguiti una sola volta.

`defineChannelPluginEntry`

Importazione: openclaw/plugin-sdk/channel-core Avvolge definePluginEntry con cablaggio specifico per i canali. Chiama automaticamente api.registerChannel({ plugin }), espone un seam opzionale di metadati CLI per l’help root e limita registerFull in base alla modalità di registrazione.

import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerCliMetadata(api) {
    api.registerCli(/* ... */);
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});

Campo	Tipo	Obbligatorio	Predefinito
`id`	`string`	Sì	-
`name`	`string`	Sì	-
`description`	`string`	Sì	-
`plugin`	`ChannelPlugin`	Sì	-
`configSchema`	`OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema`	No	Schema oggetto vuoto
`setRuntime`	`(runtime: PluginRuntime) => void`	No	-
`registerCliMetadata`	`(api: OpenClawPluginApi) => void`	No	-
`registerFull`	`(api: OpenClawPluginApi) => void`	No	-

setRuntime viene chiamato durante la registrazione così puoi memorizzare il riferimento runtime (tipicamente tramite createPluginRuntimeStore). Viene saltato durante la cattura dei metadati CLI.
registerCliMetadata viene eseguito durante api.registrationMode === "cli-metadata", api.registrationMode === "discovery" e api.registrationMode === "full". Usalo come punto canonico per i descrittori CLI posseduti dal canale, così l’help root resta non attivante, gli snapshot di discovery includono metadati statici dei comandi e la normale registrazione dei comandi CLI rimane compatibile con i caricamenti completi dei plugin.
La registrazione di discovery è non attivante, non priva di importazioni. OpenClaw può valutare la voce del plugin attendibile e il modulo del plugin di canale per costruire lo snapshot, quindi mantieni gli import di primo livello privi di effetti collaterali e metti socket, client, worker e servizi dietro percorsi solo "full".
registerFull viene eseguito solo quando api.registrationMode === "full". Viene saltato durante il caricamento solo setup.
Come definePluginEntry, configSchema può essere una factory lazy e OpenClaw memorizza lo schema risolto al primo accesso.
Per i comandi CLI root posseduti dal plugin, preferisci api.registerCli(..., { descriptors: [...] }) quando vuoi che il comando resti caricato in modo lazy senza scomparire dall’albero di parsing della CLI root. Per i comandi di funzionalità dei nodi accoppiati, preferisci api.registerNodeCliFeature(...) così il comando finisce sotto openclaw nodes. Per altri comandi di plugin annidati, aggiungi parentPath e registra i comandi sull’oggetto program passato al registrar; OpenClaw lo risolve al comando padre prima di chiamare il plugin. Per i plugin di canale, preferisci registrare quei descrittori da registerCliMetadata(...) e mantieni registerFull(...) concentrato sul lavoro solo runtime.
Se registerFull(...) registra anche metodi RPC del Gateway, tienili su un prefisso specifico del plugin. Gli spazi dei nomi admin core riservati (config.*, exec.approvals.*, wizard.*, update.*) sono sempre forzati a operator.admin.

`defineSetupPluginEntry`

Importazione: openclaw/plugin-sdk/channel-core Per il file leggero setup-entry.ts. Restituisce solo { plugin }, senza cablaggio runtime o CLI.

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);

OpenClaw carica questo invece della voce completa quando un canale è disabilitato, non configurato o quando il caricamento differito è abilitato. Consulta Setup e configurazione per capire quando è rilevante. In pratica, abbina defineSetupPluginEntry(...) alle famiglie ristrette di helper di setup:

openclaw/plugin-sdk/setup-runtime per helper di setup sicuri per il runtime come adapter di patch di setup sicuri da importare, output di note di lookup, promptResolvedAllowFrom, splitSetupEntries e proxy di setup delegati
openclaw/plugin-sdk/channel-setup per superfici di setup a installazione opzionale
openclaw/plugin-sdk/setup-tools per helper CLI/archive/docs di setup/installazione

Mantieni SDK pesanti, registrazione CLI e servizi runtime di lunga durata nella voce completa. I canali workspace in bundle che separano superfici di setup e runtime possono usare invece defineBundledChannelSetupEntry(...) da openclaw/plugin-sdk/channel-entry-contract. Quel contratto consente alla voce di setup di mantenere export plugin/secret sicuri per il setup pur esponendo ancora un setter runtime:

import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";

export default defineBundledChannelSetupEntry({
  importMetaUrl: import.meta.url,
  plugin: {
    specifier: "./channel-plugin-api.js",
    exportName: "myChannelPlugin",
  },
  runtime: {
    specifier: "./runtime-api.js",
    exportName: "setMyChannelRuntime",
  },
});

Usa quel contratto in bundle solo quando i flussi di setup hanno davvero bisogno di un setter runtime leggero prima che la voce completa del canale venga caricata.

Modalità di registrazione

api.registrationMode indica al tuo plugin come è stato caricato:

Modalità	Quando	Cosa registrare
`"full"`	Avvio normale del Gateway	Tutto
`"discovery"`	Discovery delle capacità sola lettura	Registrazione del canale più descrittori CLI statici; il codice della voce può caricarsi, ma salta socket, worker, client e servizi
`"setup-only"`	Canale disabilitato/non configurato	Solo registrazione del canale
`"setup-runtime"`	Flusso di setup con runtime disponibile	Registrazione del canale più solo il runtime leggero necessario prima che la voce completa venga caricata
`"cli-metadata"`	Cattura help root / metadati CLI	Solo descrittori CLI

defineChannelPluginEntry gestisce automaticamente questa separazione. Se usi definePluginEntry direttamente per un canale, controlla tu stesso la modalità:

register(api) {
  if (
    api.registrationMode === "cli-metadata" ||
    api.registrationMode === "discovery" ||
    api.registrationMode === "full"
  ) {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // Heavy runtime-only registrations
  api.registerService(/* ... */);
}

La modalità discovery costruisce uno snapshot del registro non attivante. Può comunque valutare la voce del plugin e l’oggetto del plugin di canale affinché OpenClaw possa registrare capacità del canale e descrittori CLI statici. Tratta la valutazione dei moduli in discovery come attendibile ma leggera: niente client di rete, sottoprocessi, listener, connessioni a database, worker in background, letture di credenziali o altri effetti collaterali runtime live al primo livello. Tratta "setup-runtime" come la finestra in cui le superfici di avvio solo setup devono esistere senza rientrare nel runtime completo del canale in bundle. Buoni casi d’uso sono registrazione del canale, route HTTP sicure per il setup, metodi Gateway sicuri per il setup e helper di setup delegati. Servizi pesanti in background, registrar CLI e bootstrap di SDK provider/client appartengono ancora a "full". Per i registrar CLI in particolare:

usa descriptors quando il registratore possiede uno o più comandi radice e vuoi che OpenClaw carichi in modo lazy il modulo CLI reale alla prima invocazione
assicurati che quei descrittori coprano ogni radice di comando di primo livello esposta dal registratore
limita i nomi dei comandi dei descrittori a lettere, numeri, trattino e underscore, iniziando con una lettera o un numero; OpenClaw rifiuta i nomi dei descrittori fuori da questa forma e rimuove le sequenze di controllo del terminale dalle descrizioni prima di visualizzare l’aiuto
usa solo commands soltanto per percorsi di compatibilità con caricamento immediato

Forme dei Plugin

OpenClaw classifica i plugin caricati in base al loro comportamento di registrazione:

Forma	Descrizione
plain-capability	Un solo tipo di capacità (ad es. solo provider)
hybrid-capability	Più tipi di capacità (ad es. provider + voce)
hook-only	Solo hook, nessuna capacità
non-capability	Strumenti/comandi/servizi ma nessuna capacità

Usa openclaw plugins inspect <id> per vedere la forma di un plugin.

Correlati

Panoramica SDK - API di registrazione e riferimento ai sottopercorsi
Helper di runtime - api.runtime e createPluginRuntimeStore
Configurazione e setup - manifest, voce di setup, caricamento differito
Plugin di canale - creazione dell’oggetto ChannelPlugin
Plugin provider - registrazione del provider e hook

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Release and CI

Punti di ingresso dei Plugin

`definePluginEntry`

`defineChannelPluginEntry`

`defineSetupPluginEntry`

Modalità di registrazione

Forme dei Plugin

Correlati

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Release and CI

Documentation Index

​definePluginEntry

​defineChannelPluginEntry

​defineSetupPluginEntry

​Modalità di registrazione

​Forme dei Plugin

​Correlati

`definePluginEntry`

`defineChannelPluginEntry`

`defineSetupPluginEntry`

Modalità di registrazione

Forme dei Plugin

Correlati