Punti di ingresso dei Plugin

​

Entry del pacchetto

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

• extensions e setupEntry sono entry sorgente, utilizzate per lo sviluppo nell’area di lavoro e nei checkout git.
• runtimeExtensions e runtimeSetupEntry sono preferite per i pacchetti installati: consentono ai pacchetti npm di evitare la compilazione TypeScript in fase di esecuzione.
• runtimeExtensions, se presente, deve corrispondere a extensions per lunghezza dell’array (le entry vengono associate per posizione). runtimeSetupEntry richiede setupEntry.
• Se viene dichiarato un artefatto runtimeExtensions/runtimeSetupEntry ma questo è assente, l’installazione/rilevamento non riesce e restituisce un errore di pacchettizzazione; OpenClaw non ricorre silenziosamente al sorgente. Il fallback sul sorgente (descritto di seguito) si applica solo quando non viene dichiarata alcuna entry di runtime.
• Se un pacchetto installato dichiara soltanto un’entry sorgente TypeScript, OpenClaw cerca una entry compilata corrispondente dist/*.js (oppure .mjs/.cjs) e la utilizza; in caso contrario, ricorre al sorgente TypeScript.
• Tutti i percorsi delle entry devono rimanere all’interno della directory del pacchetto del plugin. Le entry di runtime e le entry JavaScript compilate dedotte non rendono valido un percorso sorgente extensions o setupEntry che esce dalla directory.

​

defineToolPlugin

import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

export default defineToolPlugin({
  id: "stock-quotes",
  name: "Stock Quotes",
  description: "Fetch stock quotes.",
  configSchema: Type.Object({
    apiKey: Type.Optional(Type.String({ description: "API key." })),
  }),
  tools: (tool) => [
    tool({
      name: "quote",
      label: "Quote",
      description: "Fetch a quote.",
      parameters: Type.Object({
        symbol: Type.String({ description: "Ticker symbol." }),
      }),
      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
    }),
  ],
});

• configSchema è facoltativo; omettendolo viene utilizzato uno schema rigoroso a oggetto vuoto (il manifesto generato include comunque configSchema).
• execute restituisce una semplice stringa o un valore serializzabile in JSON; l’helper lo racchiude in un risultato testuale dello strumento con details impostato sul valore restituito originale (non convertito in stringa).
• Per risultati personalizzati degli strumenti, openclaw/plugin-sdk/tool-results esporta textResult e jsonResult.
• I nomi degli strumenti sono statici, pertanto openclaw plugins build ricava contracts.tools dagli strumenti dichiarati senza duplicare manualmente i nomi.
• Il caricamento in fase di esecuzione rimane rigoroso: i plugin installati richiedono comunque openclaw.plugin.json e package.json openclaw.extensions. OpenClaw non esegue mai il codice del plugin per dedurre i dati mancanti del manifesto.

​

definePluginEntry

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({/* ... */});
  },
});

• id deve corrispondere al manifesto openclaw.plugin.json.
• I cataloghi delle sessioni esterne utilizzano openclaw/plugin-sdk/session-catalog e api.registerSessionCatalog({ id, label, list, read, continueSession?, archive? }). Il core gestisce i metodi Gateway sessions.catalog.*; i provider restituiscono proiezioni di host, sessione e trascrizione normalizzata senza registrare RPC.
• kind è deprecato: dichiarare invece uno slot esclusivo ("memory" o "context-engine") nel campo kind del manifesto openclaw.plugin.json. Il valore kind dell’entry di runtime rimane soltanto come fallback di compatibilità per i plugin meno recenti.
• configSchema può essere una funzione per la valutazione differita. OpenClaw risolve e memorizza lo schema al primo accesso, pertanto i generatori di schemi onerosi vengono eseguiti una sola volta.
• Un descrittore nodeHostCommands può definire isAvailable({ config, env }). La restituzione di false omette tale comando e la relativa funzionalità dalla dichiarazione Gateway del nodo headless. OpenClaw lo valuta rispetto alla configurazione di avvio locale del nodo; i gestori dei comandi devono comunque convalidarne la disponibilità al momento dell’invocazione.

​

defineChannelPluginEntry

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(/* ... */);
  },
});

• setRuntime viene eseguito in ogni modalità tranne "cli-metadata" e "tool-discovery". Archiviare qui il riferimento al runtime, in genere tramite createPluginRuntimeStore.
• registerCliMetadata viene eseguito per "cli-metadata", "discovery" e "full". Utilizzarlo come posizione canonica per i descrittori CLI gestiti dal canale, in modo che la guida principale non attivi il plugin, le istantanee di rilevamento includano i metadati statici dei comandi e la normale registrazione CLI rimanga compatibile con i caricamenti completi del plugin.
• registerFull viene eseguito soltanto per "full" e "tool-discovery". Per "tool-discovery" viene eseguito al posto della registrazione del canale: OpenClaw ignora completamente registerChannel/setRuntime e chiama soltanto registerFull, pertanto qualsiasi registrazione di provider/strumenti necessaria al canale per il rilevamento o l’esecuzione autonoma degli strumenti deve risiedere lì, non dietro la normale configurazione del canale.
• La registrazione per il rilevamento non attiva il plugin, ma può eseguirne le importazioni: OpenClaw può valutare l’entry attendibile del plugin e il modulo del plugin di canale per creare l’istantanea. Mantenere prive di effetti collaterali le importazioni di primo livello e collocare socket, client, worker e servizi dietro percorsi riservati a "full".
• Come definePluginEntry, configSchema può essere una factory differita; OpenClaw memorizza lo schema risolto al primo accesso.

• Utilizzare api.registerCli(..., { descriptors: [...] }) per i comandi CLI principali gestiti dal plugin che devono essere caricati in modo differito senza scomparire dall’albero di analisi della CLI principale. I nomi dei descrittori devono contenere lettere, numeri, trattini e trattini bassi e iniziare con una lettera o un numero; OpenClaw rifiuta le altre forme e rimuove dalle descrizioni le sequenze di controllo del terminale prima di mostrare la guida. Includere ogni radice di comando di primo livello esposta dal registrar. commands da solo rimane nel percorso di compatibilità con caricamento anticipato.
• Utilizzare api.registerNodeCliFeature(...) per i comandi delle funzionalità dei nodi associati, affinché vengano inseriti sotto openclaw nodes (equivalente a registerCli(registrar, { parentPath: ["nodes"], ... })).
• Per gli altri comandi annidati del plugin, aggiungere parentPath e registrare i comandi nell’oggetto program passato al registrar; OpenClaw lo risolve nel comando padre prima di chiamare il plugin.
• Per i plugin di canale, registrare i descrittori CLI da registerCliMetadata e mantenere registerFull incentrato esclusivamente sulle operazioni di runtime.
• Se registerFull registra anche metodi RPC del Gateway, mantenerli sotto un prefisso specifico del plugin. Gli spazi dei nomi amministrativi riservati del core (config.*, exec.approvals.*, wizard.*, update.*) vengono sempre convertiti in operator.admin.

​

defineSetupPluginEntry

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

export default defineSetupPluginEntry(myChannelPlugin);

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",
  },
  registerSetupRuntime(api) {
    api.registerHttpRoute({
      path: "/my-channel/events",
      auth: "plugin",
      handler: async (req, res) => {
        /* route sicura per la configurazione iniziale */
      },
    });
  },
});

​

Modalità di registrazione

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

  if (api.registrationMode === "tool-discovery") {
    // Registrare solo le superfici delle funzionalità (provider/strumenti), senza il canale.
    return;
  }

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

  // Registrazioni pesanti riservate al runtime
  api.registerService(/* ... */);
}

api.registerService({
  id: "index-events",
  start(ctx) {
    ctx.gatewayEvents?.emit("changed", { revision: 1 }, { scope: "operator.read" });
  },
});

​

Forme dei plugin

​

Risorse correlate

• Panoramica dell’SDK - API di registrazione e riferimento dei percorsi secondari
• Helper di runtime - api.runtime e createPluginRuntimeStore
• Configurazione iniziale e configurazione - manifest, voce di configurazione iniziale, caricamento differito
• Plugin dei canali - creazione dell’oggetto ChannelPlugin
• Plugin dei provider - registrazione dei provider e hook