Creazione di plugin

I plugin estendono OpenClaw con nuove capacità: canali, provider di modelli, speech, trascrizione in tempo reale, voce in tempo reale, comprensione dei media, generazione di immagini, generazione video, recupero web, ricerca web, strumenti agente o qualsiasi combinazione. Non è necessario aggiungere il tuo plugin al repository OpenClaw. Pubblicalo su ClawHub o su npm e gli utenti lo installano con openclaw plugins install <package-name>. OpenClaw prova prima ClawHub e passa automaticamente a npm in fallback.

Prerequisiti

Node >= 22 e un gestore di pacchetti (npm o pnpm)
Familiarità con TypeScript (ESM)
Per i plugin nel repository: repository clonato e pnpm install eseguito

Che tipo di plugin?

Plugin di canale

Collega OpenClaw a una piattaforma di messaggistica (Discord, IRC, ecc.)

Plugin provider

Aggiungi un provider di modelli (LLM, proxy o endpoint personalizzato)

Plugin tool / hook

Registra strumenti agente, hook di eventi o servizi — continua sotto

Se un plugin di canale è facoltativo e potrebbe non essere installato quando viene eseguito l’onboarding/setup, usa createOptionalChannelSetupSurface(...) da openclaw/plugin-sdk/channel-setup. Produce una coppia adattatore di setup + procedura guidata che segnala il requisito di installazione e fallisce in modo chiuso sulle scritture di configurazione reali finché il plugin non è installato.

Avvio rapido: plugin tool

Questa guida crea un plugin minimo che registra uno strumento agente. I plugin di canale e provider hanno guide dedicate collegate sopra.

Crea il pacchetto e il manifest

{
  "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"
    }
  }
}

Ogni plugin ha bisogno di un manifest, anche senza configurazione. Vedi Manifest per lo schema completo. Gli snippet canonici per la pubblicazione su ClawHub si trovano in docs/snippets/plugin-publish/.

Scrivi il punto di ingresso

// index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Adds a custom tool to OpenClaw",
  register(api) {
    api.registerTool({
      name: "my_tool",
      description: "Do a thing",
      parameters: Type.Object({ input: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: `Got: ${params.input}` }] };
      },
    });
  },
});

definePluginEntry è per i plugin non di canale. Per i canali, usa defineChannelPluginEntry — vedi Plugin di canale. Per le opzioni complete del punto di ingresso, vedi Punti di ingresso.

Testa e pubblica

Plugin esterni: convalida e pubblica con ClawHub, poi installa:

clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
openclaw plugins install clawhub:@myorg/openclaw-my-plugin

OpenClaw controlla anche ClawHub prima di npm per specifiche di pacchetto semplici come @myorg/openclaw-my-plugin.Plugin nel repository: inseriscili nell’albero workspace dei plugin inclusi — vengono rilevati automaticamente.

pnpm test -- <bundled-plugin-root>/my-plugin/

Capacità dei plugin

Un singolo plugin può registrare un numero qualsiasi di capacità tramite l’oggetto api:

Capacità	Metodo di registrazione	Guida dettagliata
Inferenza di testo (LLM)	`api.registerProvider(...)`	Plugin provider
Backend di inferenza CLI	`api.registerCliBackend(...)`	Backend CLI
Canale / messaggistica	`api.registerChannel(...)`	Plugin di canale
Speech (TTS/STT)	`api.registerSpeechProvider(...)`	Plugin provider
Trascrizione in tempo reale	`api.registerRealtimeTranscriptionProvider(...)`	Plugin provider
Voce in tempo reale	`api.registerRealtimeVoiceProvider(...)`	Plugin provider
Comprensione dei media	`api.registerMediaUnderstandingProvider(...)`	Plugin provider
Generazione di immagini	`api.registerImageGenerationProvider(...)`	Plugin provider
Generazione musicale	`api.registerMusicGenerationProvider(...)`	Plugin provider
Generazione video	`api.registerVideoGenerationProvider(...)`	Plugin provider
Recupero web	`api.registerWebFetchProvider(...)`	Plugin provider
Ricerca web	`api.registerWebSearchProvider(...)`	Plugin provider
Strumenti agente	`api.registerTool(...)`	Sotto
Comandi personalizzati	`api.registerCommand(...)`	Punti di ingresso
Hook di eventi	`api.registerHook(...)`	Punti di ingresso
Route HTTP	`api.registerHttpRoute(...)`	Internals
Sottocomandi CLI	`api.registerCli(...)`	Punti di ingresso

Per l’API di registrazione completa, vedi Panoramica SDK. Se il tuo plugin registra metodi RPC gateway personalizzati, mantienili su un prefisso specifico del plugin. Gli spazi dei nomi admin core (config.*, exec.approvals.*, wizard.*, update.*) restano riservati e vengono sempre risolti in operator.admin, anche se un plugin richiede un ambito più ristretto. Semantica delle guardie hook da tenere presente:

before_tool_call: { block: true } è terminale e ferma gli handler con priorità inferiore.
before_tool_call: { block: false } viene trattato come nessuna decisione.
before_tool_call: { requireApproval: true } mette in pausa l’esecuzione dell’agente e richiede l’approvazione dell’utente tramite overlay di approvazione exec, pulsanti Telegram, interazioni Discord o il comando /approve su qualsiasi canale.
before_install: { block: true } è terminale e ferma gli handler con priorità inferiore.
before_install: { block: false } viene trattato come nessuna decisione.
message_sending: { cancel: true } è terminale e ferma gli handler con priorità inferiore.
message_sending: { cancel: false } viene trattato come nessuna decisione.

Il comando /approve gestisce sia le approvazioni exec sia quelle dei plugin con fallback limitato: quando un ID di approvazione exec non viene trovato, OpenClaw riprova lo stesso ID tramite le approvazioni del plugin. L’inoltro delle approvazioni del plugin può essere configurato in modo indipendente tramite approvals.plugin nella config. Se una logica di approvazione personalizzata deve rilevare quel medesimo caso di fallback limitato, preferisci isApprovalNotFoundError da openclaw/plugin-sdk/error-runtime invece di fare il matching manuale delle stringhe di scadenza dell’approvazione. Vedi Semantica delle decisioni hook nella panoramica SDK per i dettagli.

Registrazione degli strumenti agente

Gli strumenti sono funzioni tipizzate che l’LLM può chiamare. Possono essere obbligatori (sempre disponibili) o facoltativi (attivazione esplicita dell’utente):

register(api) {
  // Required tool — always available
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({ input: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });

  // Optional tool — user must add to allowlist
  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 },
  );
}

Gli utenti abilitano gli strumenti facoltativi nella config:

{
  tools: { allow: ["workflow_tool"] },
}

I nomi degli strumenti non devono entrare in conflitto con gli strumenti core (i conflitti vengono saltati)
Usa optional: true per strumenti con effetti collaterali o requisiti binari aggiuntivi
Gli utenti possono abilitare tutti gli strumenti di un plugin aggiungendo l’ID del plugin a tools.allow

Convenzioni di importazione

Importa sempre da percorsi mirati openclaw/plugin-sdk/<subpath>:

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

// Wrong: monolithic root (deprecated, will be removed)
import { ... } from "openclaw/plugin-sdk";

Per il riferimento completo ai sottopercorsi, vedi Panoramica SDK. All’interno del tuo plugin, usa file barrel locali (api.ts, runtime-api.ts) per le importazioni interne — non importare mai il tuo stesso plugin tramite il suo percorso SDK. Per i plugin provider, mantieni gli helper specifici del provider in quei barrel alla radice del pacchetto, a meno che il punto di estensione non sia davvero generico. Esempi inclusi attuali:

Anthropic: wrapper di stream Claude e helper service_tier / beta
OpenAI: builder dei provider, helper per il modello predefinito, provider realtime
OpenRouter: builder del provider più helper di onboarding/config

Se un helper è utile solo all’interno di un pacchetto provider incluso, mantienilo su quel punto di estensione alla radice del pacchetto invece di promuoverlo in openclaw/plugin-sdk/*. Esistono ancora alcuni punti di estensione helper generati openclaw/plugin-sdk/<bundled-id> per la manutenzione e la compatibilità dei plugin inclusi, ad esempio plugin-sdk/feishu-setup o plugin-sdk/zalo-setup. Trattali come superfici riservate, non come il modello predefinito per nuovi plugin di terze parti.

Checklist pre-invio

package.json ha metadati openclaw corretti

Il manifest openclaw.plugin.json è presente e valido

Il punto di ingresso usa defineChannelPluginEntry o definePluginEntry

Tutte le importazioni usano percorsi mirati plugin-sdk/<subpath>

Le importazioni interne usano moduli locali, non auto-importazioni SDK

I test passano (pnpm test -- <bundled-plugin-root>/my-plugin/)

pnpm check passa (plugin nel repository)

Test delle beta release

Tieni d’occhio i tag delle release GitHub su openclaw/openclaw e iscriviti tramite Watch > Releases. I tag beta hanno un aspetto simile a v2026.3.N-beta.1. Puoi anche attivare le notifiche per l’account X ufficiale di OpenClaw @openclaw per gli annunci delle release.
Testa il tuo plugin con il tag beta non appena compare. La finestra prima della stabile di solito dura solo poche ore.
Scrivi nel thread del tuo plugin nel canale Discord plugin-forum dopo il test con all good oppure con ciò che si è rotto. Se non hai ancora un thread, creane uno.
Se qualcosa si rompe, apri o aggiorna un issue con titolo Beta blocker: <plugin-name> - <summary> e applica l’etichetta beta-blocker. Inserisci il link dell’issue nel tuo thread.
Apri una PR verso main con titolo fix(<plugin-id>): beta blocker - <summary> e collega l’issue sia nella PR sia nel tuo thread Discord. I contributor non possono etichettare le PR, quindi il titolo è il segnale lato PR per maintainer e automazione. I blocker con una PR vengono uniti; i blocker senza PR potrebbero comunque essere rilasciati. I maintainer osservano questi thread durante i test beta.
Il silenzio significa verde. Se perdi la finestra, probabilmente la tua correzione finirà nel ciclo successivo.

Passaggi successivi

Plugin di canale

Crea un plugin di canale di messaggistica

Plugin provider

Crea un plugin provider di modelli

Panoramica SDK

Riferimento della mappa di importazione e dell’API di registrazione

Helper di runtime

TTS, ricerca, sottoagente tramite api.runtime

Testing

Utilità e pattern di test

Manifest del plugin

Riferimento completo dello schema del manifest

Correlati

Architettura dei plugin — approfondimento sull’architettura interna
Panoramica SDK — riferimento del Plugin SDK
Manifest — formato del manifest del plugin
Plugin di canale — creazione di plugin di canale
Plugin provider — creazione di plugin provider

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

Creazione di plugin

Creazione di plugin

Prerequisiti

Che tipo di plugin?

Plugin di canale

Plugin provider

Plugin tool / hook

Avvio rapido: plugin tool

Capacità dei plugin

Registrazione degli strumenti agente

Convenzioni di importazione

Checklist pre-invio

Test delle beta release

Passaggi successivi

Plugin di canale

Plugin provider

Panoramica SDK

Helper di runtime

Testing

Manifest del plugin

Correlati

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

​Creazione di plugin

​Prerequisiti

​Che tipo di plugin?

Plugin di canale

Plugin provider

Plugin tool / hook

​Avvio rapido: plugin tool

​Capacità dei plugin

​Registrazione degli strumenti agente

​Convenzioni di importazione

​Checklist pre-invio

​Test delle beta release

​Passaggi successivi

Plugin di canale

Plugin provider

Panoramica SDK

Helper di runtime

Testing

Manifest del plugin

​Correlati

Creazione di plugin

Prerequisiti

Che tipo di plugin?

Avvio rapido: plugin tool

Capacità dei plugin

Registrazione degli strumenti agente

Convenzioni di importazione

Checklist pre-invio

Test delle beta release

Passaggi successivi

Correlati