Vai al contenuto principale

​
Punti di ingresso del Plugin

Ogni Plugin esporta un oggetto di ingresso predefinito. L’SDK fornisce tre helper per crearli.
Cerchi una guida passo passo? Consulta Plugin di canale o Provider Plugins per guide dettagliate.

​
definePluginEntry

Importa: openclaw/plugin-sdk/plugin-entry Per i provider plugin, i tool plugin, gli hook plugin e qualsiasi cosa che non sia 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({
      /* ... */
    });
  },
});
CampoTipoObbligatorioPredefinito
idstringSì—
namestringSì—
descriptionstringSì—
kindstringNo—
configSchemaOpenClawPluginConfigSchema | () => OpenClawPluginConfigSchemaNoSchema oggetto vuoto
register(api: OpenClawPluginApi) => voidSì—
  • id deve corrispondere al tuo manifest openclaw.plugin.json.
  • kind serve per slot esclusivi: "memory" o "context-engine".
  • configSchema può essere una funzione per una valutazione lazy.
  • OpenClaw risolve e memorizza quello schema al primo accesso, quindi i builder di schema costosi vengono eseguiti una sola volta.

​
defineChannelPluginEntry

Importa: openclaw/plugin-sdk/channel-core Avvolge definePluginEntry con wiring 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(/* ... */);
  },
});
CampoTipoObbligatorioPredefinito
idstringSì—
namestringSì—
descriptionstringSì—
pluginChannelPluginSì—
configSchemaOpenClawPluginConfigSchema | () => OpenClawPluginConfigSchemaNoSchema oggetto vuoto
setRuntime(runtime: PluginRuntime) => voidNo—
registerCliMetadata(api: OpenClawPluginApi) => voidNo—
registerFull(api: OpenClawPluginApi) => voidNo—
  • setRuntime viene chiamato durante la registrazione così puoi memorizzare il riferimento al runtime (in genere tramite createPluginRuntimeStore). Viene saltato durante la raccolta dei metadati CLI.
  • registerCliMetadata viene eseguito sia quando api.registrationMode === "cli-metadata" sia quando api.registrationMode === "full". Usalo come punto canonico per i descrittori CLI posseduti dal canale, in modo che l’help root resti non attivante mentre la normale registrazione dei comandi CLI rimane compatibile con i caricamenti completi del Plugin.
  • 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 lazy-loaded senza scomparire dall’albero di parsing della CLI root. Per i channel plugin, preferisci registrare quei descrittori da registerCliMetadata(...) e mantenere registerFull(...) focalizzato sul lavoro solo runtime.
  • Se registerFull(...) registra anche metodi RPC del Gateway, mantienili su un prefisso specifico del Plugin. Gli spazi dei nomi admin core riservati (config.*, exec.approvals.*, wizard.*, update.*) vengono sempre forzati a operator.admin.

​
defineSetupPluginEntry

Importa: openclaw/plugin-sdk/channel-core Per il file leggero setup-entry.ts. Restituisce solo { plugin } senza wiring di runtime o CLI. 
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);
OpenClaw lo carica al posto dell’ingresso completo quando un canale è disabilitato, non configurato oppure quando il caricamento differito è abilitato. Consulta Setup e configurazione per capire quando questo è importante. In pratica, abbina defineSetupPluginEntry(...) alle famiglie ristrette di helper per il setup:
  • openclaw/plugin-sdk/setup-runtime per helper di setup sicuri per il runtime come adattatori di patch setup import-safe, output di note di lookup, promptResolvedAllowFrom, splitSetupEntries e proxy di setup delegati
  • openclaw/plugin-sdk/channel-setup per superfici di setup di installazione opzionale
  • openclaw/plugin-sdk/setup-tools per helper CLI/archivio/documentazione di setup/installazione
Mantieni SDK pesanti, registrazione CLI e servizi runtime a lunga durata nell’ingresso completo. I canali workspace bundled che separano le superfici di setup e runtime possono usare invece defineBundledChannelSetupEntry(...) da openclaw/plugin-sdk/channel-entry-contract. Quel contratto consente al punto di ingresso di setup di mantenere esportazioni di plugin/secrets sicure per il setup, continuando comunque a esporre un setter del 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 bundled solo quando i flussi di setup hanno davvero bisogno di un setter del runtime leggero prima che venga caricato il punto di ingresso completo del canale.

​
Modalità di registrazione

api.registrationMode indica al tuo Plugin come è stato caricato:
ModalitàQuandoCosa registrare
"full"Avvio normale del GatewayTutto
"setup-only"Canale disabilitato/non configuratoSolo registrazione del canale
"setup-runtime"Flusso di setup con runtime disponibileRegistrazione del canale più solo il runtime leggero necessario prima che venga caricato il punto di ingresso completo
"cli-metadata"Help root / acquisizione metadati CLISolo descrittori CLI
defineChannelPluginEntry gestisce automaticamente questa suddivisione. Se usi direttamente definePluginEntry per un canale, controlla tu stesso la modalità: 
register(api) {
  if (api.registrationMode === "cli-metadata" || api.registrationMode === "full") {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

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

  // Registrazioni pesanti solo runtime
  api.registerService(/* ... */);
}
Considera "setup-runtime" come la finestra in cui le superfici di avvio solo setup devono esistere senza rientrare nel runtime completo del canale bundled. Buoni casi d’uso sono la registrazione del canale, route HTTP sicure per il setup, metodi Gateway sicuri per il setup e helper di setup delegati. Servizi background pesanti, registrar CLI e bootstrap di SDK provider/client continuano invece ad appartenere a "full". Per i registrar CLI nello specifico:
  • usa descriptors quando il registrar possiede uno o più comandi root e tu vuoi che OpenClaw carichi lazy il vero modulo CLI alla prima invocazione
  • assicurati che quei descrittori coprano ogni root command di primo livello esposto dal registrar
  • usa solo commands solo per percorsi di compatibilità eager

​
Forme del Plugin

OpenClaw classifica i Plugin caricati in base al loro comportamento di registrazione:
FormaDescrizione
plain-capabilityUn solo tipo di capacità (ad es. solo provider)
hybrid-capabilityPiù tipi di capacità (ad es. provider + speech)
hook-onlySolo hook, nessuna capacità
non-capabilityTool/comandi/servizi ma nessuna capacità
Usa openclaw plugins inspect <id> per vedere la forma di un Plugin.

​
Correlati