OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Building plugins

Creazione di plugin

I Plugin estendono OpenClaw senza modificare il core. Un Plugin può aggiungere un canale di messaggistica, un provider di modelli, un backend CLI locale, uno strumento per agenti, un hook, un provider multimediale o un'altra funzionalità gestita dal Plugin.

Non è necessario aggiungere un Plugin esterno al repository di OpenClaw. Pubblica il pacchetto su ClawHub e gli utenti lo installeranno con:

bash
openclaw plugins install clawhub:<package-name>

Durante la transizione al lancio, le specifiche dei pacchetti senza prefisso continuano a essere installate da npm. Usa il prefisso clawhub: quando vuoi la risoluzione tramite ClawHub.

Requisiti

  • Node 22.19+, Node 23.11+ o Node 24+ e npm o pnpm.
  • Moduli ESM TypeScript.
  • Per lavorare su un Plugin incluso nel repository, clona il repository ed esegui pnpm install. Lo sviluppo di Plugin da un checkout del codice sorgente supporta solo pnpm, perché OpenClaw rileva i Plugin inclusi dai pacchetti dell'area di lavoro extensions/*.

Scegli la struttura del Plugin

Plugin per canali

Collega OpenClaw a una piattaforma di messaggistica.
Plugin per provider

Aggiungi un provider di modelli, contenuti multimediali, ricerca, recupero, sintesi vocale o comunicazione in tempo reale.
Plugin per backend CLI

Esegui una CLI IA locale tramite il fallback dei modelli di OpenClaw.
Plugin per strumenti

Registra strumenti per agenti.

Guida rapida

Crea un Plugin per strumenti minimale registrando un unico strumento obbligatorio per agenti. Questa è la struttura di Plugin utile più breve e comprende pacchetto, manifesto, punto di ingresso e verifica locale.

  • Crea i metadati del pacchetto

    package.json
    {"name": "@myorg/openclaw-my-plugin","version": "1.0.0","type": "module","dependencies": {"typebox": "1.1.39"},"peerDependencies": {"openclaw": ">=2026.3.24-beta.2"},"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"}}}
    openclaw.plugin.json
    {"id": "my-plugin","name": "My Plugin","description": "Adds a custom tool to OpenClaw","contracts": {"tools": ["my_tool"]},"activation": {"onStartup": true},"configSchema": {"type": "object","additionalProperties": false}}

    I Plugin esterni pubblicati devono indirizzare i punti di ingresso del runtime verso file JavaScript compilati. Consulta Punti di ingresso dell'SDK per il contratto completo dei punti di ingresso.

    Ogni Plugin richiede un manifesto, anche in assenza di configurazione. Gli strumenti del runtime devono essere presenti in contracts.tools, affinché OpenClaw possa individuarne la titolarità senza caricare preventivamente il runtime di ogni Plugin. Imposta activation.onStartup consapevolmente; questo esempio viene caricato all'avvio del Gateway.

    Anche le superfici dei Plugin considerate attendibili dall'host sono soggette al manifesto e richiedono una dichiarazione esplicita per i Plugin installati: api.registerAgentToolResultMiddleware(...) richiede che ogni runtime di destinazione sia elencato in contracts.agentToolResultMiddleware, mentre api.registerTrustedToolPolicy(...) richiede che ogni identificativo di criterio sia presente in contracts.trustedToolPolicies. Queste dichiarazioni mantengono allineate l'ispezione durante l'installazione e la registrazione nel runtime.

    Per tutti i campi del manifesto, consulta Manifesto del Plugin.

  • Registra lo strumento

    index.ts
    import { Type } from "typebox";import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Adds a custom tool to OpenClaw",  register(api) {    api.registerTool({      name: "my_tool",      description: "Echo one input value",      parameters: Type.Object({ input: Type.String() }),      async execute(_id, params) {        return {          content: [{ type: "text", text: `Got: ${params.input}` }],        };      },    });  },});

    Usa definePluginEntry per i Plugin non destinati ai canali. I Plugin per canali usano invece defineChannelPluginEntry da openclaw/plugin-sdk/core.

  • Verifica il runtime

    Per un Plugin installato o esterno, esamina il runtime caricato:

    bash
    openclaw plugins inspect my-plugin --runtime --json

    Se il Plugin registra un comando CLI, esegui anche tale comando e verificane l'output, ad esempio openclaw demo-plugin ping.

    Per un Plugin incluso in questo repository, OpenClaw rileva i pacchetti dei Plugin nel checkout del codice sorgente dall'area di lavoro extensions/*. Esegui il test mirato più pertinente:

    bash
    pnpm test extensions/my-plugin/pnpm check

  • Verifica l'installazione del pacchetto

    Prima di pubblicare un Plugin pronto per essere distribuito come pacchetto, verifica la stessa modalità di installazione che riceveranno gli utenti. Aggiungi innanzitutto un passaggio di compilazione, indirizza le voci del runtime, come openclaw.extensions, verso file JavaScript compilati, ad esempio ./dist/index.js, e assicurati che npm pack includa l'output dist/. Le voci del codice sorgente TypeScript sono destinate esclusivamente ai checkout del codice sorgente e ai percorsi di sviluppo locale.

    Quindi crea il pacchetto del Plugin e installa il tarball con npm-pack::

    bash
    npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

    npm-pack: utilizza il progetto npm per Plugin gestito da OpenClaw, quindi rileva gli errori nelle dipendenze del runtime che i test sul checkout del codice sorgente possono nascondere. Verifica la struttura del pacchetto e delle dipendenze, non l'attendibilità ufficiale collegata al catalogo. Le importazioni del runtime devono trovarsi in dependencies o optionalDependencies; le dipendenze lasciate esclusivamente in devDependencies non verranno installate nel progetto runtime gestito.

    Non utilizzare un'installazione da archivio/percorso non elaborata come prova finale del comportamento di Plugin ufficiali o con privilegi. I sorgenti non elaborati sono utili per il debug locale, ma non dimostrano lo stesso percorso delle dipendenze delle installazioni tramite npm o ClawHub. Se il Plugin si basa sullo stato attendibile di Plugin ufficiale, aggiungi una seconda prova tramite un'installazione ufficiale supportata da catalogo o un percorso di pacchetto pubblicato che registri l'attendibilità ufficiale. Consulta Risoluzione delle dipendenze dei Plugin per i dettagli sulla radice di installazione e sulla proprietà delle dipendenze.

  • Pubblicazione

    Convalida il pacchetto prima della pubblicazione:

    bash
    clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

    Gli snippet canonici dei pacchetti ClawHub si trovano in docs/snippets/plugin-publish/.

  • Installazione

    Installa il pacchetto pubblicato tramite ClawHub:

    bash
    openclaw plugins install clawhub:your-org/your-plugin

    • Registrazione degli strumenti

    Gli strumenti possono essere obbligatori o facoltativi. Gli strumenti obbligatori sono sempre disponibili quando il Plugin è abilitato. Gli strumenti facoltativi richiedono l'adesione esplicita dell'utente prima che OpenClaw carichi il runtime del Plugin proprietario.

    Le factory degli strumenti ricevono un contesto di runtime attendibile, incluso deliveryContext, nativeChannelId per la conversazione attiva sulla piattaforma, quando disponibile, e requesterSenderId.

    typescript
    register(api) {  api.registerTool(    {      name: "workflow_tool",      description: "Run a workflow",      parameters: Type.Object({ pipeline: Type.String() }),      async execute(_id, params) {        return { content: [{ type: "text", text: params.pipeline }] };      },    },    { optional: true },  );}

    Ogni strumento registrato con api.registerTool(...) deve essere dichiarato anche nel manifest del Plugin:

    json
    {  "contracts": {    "tools": ["workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

    Gli utenti forniscono l'adesione tramite tools.allow:

    json5
    {  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for every tool from one plugin}

    Gli strumenti facoltativi determinano se uno strumento viene esposto al modello. Utilizza le richieste di autorizzazione dei Plugin quando uno strumento o un hook deve richiedere l'approvazione dopo che il modello lo ha selezionato e prima che l'azione venga eseguita.

    Utilizza strumenti facoltativi per effetti collaterali, binari insoliti o funzionalità che non devono essere esposte per impostazione predefinita. I nomi degli strumenti non devono entrare in conflitto con i nomi degli strumenti principali; i conflitti vengono ignorati e segnalati nella diagnostica dei Plugin. Le registrazioni non valide vengono ignorate e segnalate allo stesso modo: un name non vuoto mancante, un execute che non è una funzione o un descrittore dello strumento privo di un oggetto parameters.

    Le factory degli strumenti ricevono un oggetto di contesto fornito dal runtime. Utilizza ctx.activeModel quando uno strumento deve registrare, visualizzare o adattarsi al modello attivo per il turno corrente; può includere provider, modelId e modelRef. Consideralo un metadato informativo del runtime, non un confine di sicurezza nei confronti dell'operatore locale, del codice dei Plugin installati o di un runtime OpenClaw modificato. Gli strumenti locali sensibili devono comunque richiedere un'adesione esplicita del Plugin o dell'operatore e operare in modalità fail-closed quando i metadati del modello attivo sono mancanti o inadeguati.

    Il manifest dichiara la proprietà e l'individuazione; l'esecuzione richiama comunque l'implementazione registrata e attiva dello strumento. Mantieni toolMetadata.<tool>.optional: true allineato con api.registerTool(..., { optional: true }) affinché OpenClaw possa evitare di caricare il runtime del Plugin finché lo strumento non viene aggiunto esplicitamente all'elenco degli elementi consentiti.

    Convenzioni di importazione

    Importa dai sottopercorsi specifici dell'SDK:

    typescript

    Non importare dal barrel radice deprecato:

    typescript

    Nel pacchetto del Plugin, utilizza file barrel locali come api.ts e runtime-api.ts per le importazioni interne. Non importare il Plugin stesso tramite un percorso SDK. Gli helper specifici del provider devono rimanere nel pacchetto del provider, a meno che l'interfaccia non sia realmente generica.

    I metodi RPC personalizzati del Gateway costituiscono un punto di ingresso avanzato. Mantienili in un prefisso specifico del Plugin; gli spazi dei nomi amministrativi principali come config.*, exec.approvals.*, operator.admin.*, wizard.* e update.* restano riservati e vengono risolti in operator.admin. Il bridge openclaw/plugin-sdk/gateway-method-runtime è riservato alle route HTTP dei Plugin che dichiarano contracts.gatewayMethodDispatch: ["authenticated-request"].

    Per la mappa completa delle importazioni, consulta la panoramica dell'SDK dei Plugin.

    Elenco di controllo prima dell'invio

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json contiene i metadati openclaw corretti OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Il manifest openclaw.plugin.json è presente e valido OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Il punto di ingresso utilizza defineChannelPluginEntry o definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Tutte le importazioni utilizzano percorsi specifici plugin-sdk/<subpath> OPENCLAW_DOCS_MARKER:calloutClose:

    Was this useful?
    On this page

    On this page