Creare 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 agente, un hook, un provider multimediale o un'altra funzionalità di proprietà del Plugin.

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

openclaw plugins install clawhub:<package-name>

Le specifiche di pacchetto semplici continuano a installare da npm durante il passaggio del lancio. Usa il prefisso clawhub: quando vuoi la risoluzione ClawHub.

Requisiti

• Usa Node 22.19+, Node 23.11+ o Node 24+ e un package manager come npm o pnpm.
• Familiarità con i moduli TypeScript ESM.
• Per lavorare su Plugin in bundle nel repository, clona il repository ed esegui pnpm install. Lo sviluppo di Plugin da checkout del sorgente è solo pnpm perché OpenClaw carica i Plugin in bundle dai pacchetti workspace extensions/*.

Scegli la forma del Plugin

Avvio rapido

Crea un Plugin strumento minimo registrando uno strumento agente obbligatorio. Questa è la forma di Plugin utile più breve e mostra il pacchetto, il manifest, l'entry point e la prova locale.

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

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

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}` }],        };      },    });  },});

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

pnpm test -- extensions/my-plugin/pnpm check

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

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

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

Registrazione degli strumenti

Gli strumenti possono essere obbligatori o opzionali. Gli strumenti obbligatori sono sempre disponibili quando il Plugin è abilitato. Gli strumenti opzionali richiedono l'opt-in dell'utente.

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 anche essere dichiarato nel manifest del Plugin:

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

Gli utenti effettuano l'opt-in con tools.allow:

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

Gli strumenti opzionali controllano se uno strumento viene esposto al modello. Usa le richieste di autorizzazione del Plugin quando uno strumento o un hook deve chiedere approvazione dopo che il modello lo seleziona e prima che l'azione venga eseguita.

Usa strumenti opzionali 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 gli strumenti core; i conflitti vengono ignorati e segnalati nella diagnostica del Plugin. Le registrazioni malformate, inclusi descrittori di strumenti senza parameters, vengono ignorate e segnalate nello stesso modo. Gli strumenti registrati sono funzioni tipizzate che il modello può chiamare dopo il superamento dei controlli di policy e allowlist.

Le factory degli strumenti ricevono un oggetto di contesto fornito dal runtime. Usa ctx.activeModel quando uno strumento deve registrare, mostrare o adattarsi al modello attivo per il turno corrente. L'oggetto può includere provider, modelId e modelRef. Trattalo come metadati runtime informativi, non come un confine di sicurezza contro l'operatore locale, il codice dei Plugin installati o un runtime OpenClaw modificato. Gli strumenti locali sensibili devono comunque richiedere un opt-in esplicito del Plugin o dell'operatore e fallire in modo chiuso quando i metadati del modello attivo mancano o non sono adatti.

Il manifest dichiara proprietà e discovery; l'esecuzione chiama comunque l'implementazione live dello strumento registrato. Mantieni toolMetadata.<tool>.optional: true allineato con api.registerTool(..., { optional: true }) in modo che OpenClaw possa evitare di caricare quel runtime di Plugin finché lo strumento non viene esplicitamente inserito nell'allowlist.

Convenzioni di importazione

Importa dai sottopercorsi SDK focalizzati:

Non importare dal barrel radice deprecato:

All'interno del tuo pacchetto Plugin, usa file barrel locali come api.ts e runtime-api.ts per gli import interni. Non importare il tuo Plugin tramite un percorso SDK. Gli helper specifici del provider devono restare nel pacchetto provider, a meno che il punto di raccordo non sia davvero generico.

I metodi RPC Gateway personalizzati sono un entry point avanzato. Mantienili su un prefisso specifico del Plugin; gli spazi dei nomi di amministrazione core come config.*, exec.approvals.*, operator.admin.*, wizard.* e update.* restano riservati e si risolvono 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 degli import, vedi panoramica Plugin SDK.

Checklist prima dell'invio

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json ha 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 L'entry point usa defineChannelPluginEntry o definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Tutti gli import usano percorsi focalizzati plugin-sdk/<subpath> OPENCLAW_DOCS_MARKER:calloutClose: