Plugin

I Plugin estendono OpenClaw con canali, provider di modelli, harness di agenti, strumenti, skill, parlato, trascrizione in tempo reale, voce, comprensione dei media, generazione, recupero web, ricerca web e altre capacità di runtime.

Usa questa pagina quando vuoi installare un Plugin, riavviare il Gateway, verificare che il runtime lo abbia caricato e indirizzare gli errori comuni di configurazione. Per esempi solo di comandi, vedi Gestire i Plugin. Per l'inventario generato completo dei Plugin inclusi, ufficiali esterni e solo sorgente, vedi Inventario dei Plugin.

Requisiti

Prima di installare un Plugin, assicurati di avere:

• un checkout o un'installazione di OpenClaw con la CLI openclaw disponibile
• accesso di rete alla sorgente selezionata, come ClawHub, npm o un host git
• eventuali credenziali, chiavi di configurazione o strumenti del sistema operativo specifici del Plugin indicati dalla documentazione di configurazione di quel Plugin
• autorizzazione per il Gateway che serve i tuoi canali a ricaricarsi o riavviarsi

Avvio rapido

openclaw plugins search "calendar"

# From ClawHub.openclaw plugins install clawhub:<package> # From npm.openclaw plugins install npm:<package> # From git.openclaw plugins install git:github.com/<owner>/<repo>@<ref> # From a local development checkout.openclaw plugins install ./my-pluginopenclaw plugins install --link ./my-plugin

openclaw plugins enable <plugin-id>

openclaw gateway restart

openclaw plugins inspect <plugin-id> --runtime --json

Configurazione

Scegli una sorgente di installazione

Le specifiche di pacchetto bare hanno uno speciale comportamento di compatibilità. Se il nome bare corrisponde a un id di Plugin incluso, OpenClaw usa quella sorgente inclusa. Se corrisponde a un id di Plugin ufficiale esterno, OpenClaw usa il catalogo ufficiale dei pacchetti. Le altre normali specifiche di pacchetto bare vengono installate tramite npm durante il passaggio di lancio. Anche le specifiche di pacchetto @openclaw/* raw che corrispondono a Plugin inclusi si risolvono alla copia inclusa prima del fallback npm. Usa npm:@openclaw/<plugin>@<version> quando vuoi deliberatamente il pacchetto npm esterno invece della copia inclusa posseduta dall'immagine. Usa clawhub:, npm:, git: o npm-pack: quando ti serve una selezione deterministica della sorgente. Vedi openclaw plugins per il contratto completo del comando.

Per le installazioni npm, le specifiche di pacchetto non fissate e @latest scelgono il pacchetto stabile più recente che dichiara compatibilità con questa build OpenClaw. Se la release latest corrente di npm dichiara un openclaw.compat.pluginApi o openclaw.install.minHostVersion più recente, OpenClaw analizza le versioni stabili più vecchie del pacchetto e installa la più recente compatibile. Versioni esatte e tag di canale espliciti come @beta restano fissati al pacchetto selezionato e falliscono se incompatibili.

Policy di installazione dell'operatore

Configura security.installPolicy per eseguire un comando di policy locale attendibile prima che l'installazione o l'aggiornamento del Plugin proceda. La policy riceve metadati più il percorso sorgente preparato e può consentire o bloccare l'installazione. Copre i percorsi di installazione/aggiornamento dei Plugin basati su CLI e Gateway. Gli hook before_install del Plugin vengono eseguiti più tardi solo nei processi OpenClaw in cui gli hook del Plugin sono caricati, quindi usa security.installPolicy per decisioni di installazione possedute dall'operatore. Il flag deprecato --dangerously-force-unsafe-install è accettato per compatibilità ma non aggira la policy di installazione o la denylist integrata delle dipendenze Plugin di OpenClaw.

Vedi Configurazione Skills per lo schema exec security.installPolicy condiviso usato sia da skills sia da Plugin.

Configura la policy dei Plugin

La forma comune della configurazione dei Plugin è:

{  plugins: {    enabled: true,    allow: ["voice-call"],    deny: ["untrusted-plugin"],    load: { paths: ["~/Projects/oss/voice-call-plugin"] },    slots: { memory: "memory-core" },    entries: {      "voice-call": { enabled: true, config: { provider: "twilio" } },    },  },}

Regole principali della policy:

• plugins.enabled: false disabilita tutti i Plugin e salta il lavoro di scoperta/caricamento dei Plugin. I riferimenti obsoleti ai Plugin sono inerti mentre questa opzione è attiva; riabilita i Plugin prima di eseguire la pulizia doctor quando vuoi rimuovere gli id obsoleti.
• plugins.deny prevale su allow e sull'abilitazione per Plugin.
• plugins.allow è un allowlist esclusivo. Gli strumenti posseduti dai Plugin fuori dall' allowlist restano non disponibili, anche quando tools.allow include "*".
• plugins.entries.<id>.enabled: false disabilita un Plugin preservandone la configurazione.
• plugins.load.paths aggiunge file o directory di Plugin locali espliciti. I percorsi locali gestiti da plugins install devono essere directory o archivi di Plugin; usa plugins.load.paths per file Plugin autonomi.
• I Plugin di origine workspace sono disabilitati per impostazione predefinita; abilitali esplicitamente o inseriscili nell'allowlist prima di usare codice locale del workspace.
• I Plugin inclusi seguono i propri metadati integrati default-on/default-off a meno che la configurazione non li sovrascriva esplicitamente.
• plugins.slots.<slot> sceglie un Plugin per categorie esclusive come motori di memoria e contesto. La selezione dello slot forza l'abilitazione del Plugin selezionato per quello slot contando come attivazione esplicita; può caricarsi anche quando altrimenti sarebbe opt-in. plugins.deny e plugins.entries.<id>.enabled: false lo bloccano comunque.
• I Plugin inclusi opt-in possono auto-attivarsi quando la configurazione nomina una delle loro superfici possedute, come un riferimento provider/modello, configurazione canale, backend CLI o runtime harness di agente.
• Il routing Codex della famiglia OpenAI mantiene separati i confini di provider e Plugin di runtime: i riferimenti legacy ai modelli Codex sono configurazione legacy riparata da doctor, mentre il Plugin incluso codex possiede il runtime app-server Codex per i riferimenti agente canonici openai/*, agentRuntime.id: "codex" esplicito e riferimenti legacy codex/*.

Quando plugins.allow non è impostato e Plugin non inclusi vengono scoperti automaticamente dalle radici Plugin del workspace o globali, i log di avvio riportano plugins.allow is empty; discovered non-bundled plugins may auto-load: .... L'avviso include gli id dei Plugin scoperti e, per elenchi brevi, uno snippet minimale plugins.allow. Esegui openclaw plugins list --enabled --verbose o openclaw plugins inspect <id> con l'id Plugin elencato prima di copiare Plugin attendibili in openclaw.json. La stessa guida di trust-pinning si applica quando la diagnostica dice che un Plugin è stato caricato without install/load-path provenance: ispeziona quell'id Plugin, poi fissa l'id attendibile in plugins.allow o reinstalla da una sorgente attendibile in modo che OpenClaw registri la provenienza dell'installazione.

Esegui openclaw doctor o openclaw doctor --fix quando la validazione della configurazione segnala id Plugin obsoleti, mismatch allowlist/strumenti o percorsi legacy dei Plugin inclusi.

Comprendere i formati dei Plugin

OpenClaw riconosce due formati di Plugin:

Entrambi i formati compaiono in openclaw plugins list, openclaw plugins inspect, openclaw plugins enable e openclaw plugins disable. Vedi Bundle dei Plugin per il confine di compatibilità dei bundle e Creazione di Plugin per l'authoring di Plugin nativi.

Hook dei Plugin

I Plugin possono registrare hook a runtime, ma esistono due API diverse con compiti diversi.

• Usa hook tipizzati tramite api.on(...) per gli hook del ciclo di vita runtime. Questa è la superficie preferita per middleware, policy, riscrittura dei messaggi, modellazione del prompt e controllo degli strumenti.
• Usa api.registerHook(...) solo quando vuoi partecipare al sistema di hook interno descritto in Hook. Questo serve principalmente per effetti collaterali grossolani di comando/ciclo di vita e compatibilità con automazioni esistenti in stile HOOK.

Regola rapida:

• Se l'handler richiede priorità, semantica di merge o comportamento di blocco/annullamento, usa gli hook Plugin tipizzati.
• Se l'handler reagisce semplicemente a command:new, command:reset, message:sent o eventi grossolani simili, api.registerHook(...) va bene.

Gli hook interni gestiti dai Plugin compaiono in openclaw hooks list con plugin:<id>. Non puoi abilitarli o disabilitarli tramite openclaw hooks; abilita o disabilita invece il Plugin.

Verifica il Gateway attivo

openclaw plugins list e il semplice openclaw plugins inspect leggono lo stato a freddo di configurazione, manifesto e registro. Non dimostrano che un Gateway gia in esecuzione abbia importato lo stesso codice del plugin.

Quando un plugin risulta installato ma il traffico chat live non lo usa:

openclaw gateway status --deep --require-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw gateway restart

I Gateway gestiti si riavviano automaticamente dopo modifiche di installazione, aggiornamento e disinstallazione dei plugin che alterano il sorgente del plugin. Su installazioni VPS o container, assicurati che qualsiasi riavvio manuale punti al vero processo figlio openclaw gateway run che serve i tuoi canali, non solo a un wrapper o supervisore.

Risoluzione dei problemi

Quando una configurazione plugin obsoleta nomina ancora un plugin di canale non piu individuabile, l'avvio del Gateway salta quel canale supportato dal plugin invece di bloccare ogni altro canale. Esegui openclaw doctor --fix per rimuovere voci obsolete di plugin e canali. Le chiavi di canale sconosciute senza evidenza di plugin obsoleto continuano a fallire la validazione, cosi gli errori di battitura restano visibili.

Per la sostituzione intenzionale di un canale, il plugin preferito dovrebbe dichiarare channelConfigs.<channel-id>.preferOver con l'id del plugin legacy o a priorita inferiore. Se entrambi i plugin sono abilitati esplicitamente, OpenClaw mantiene quella richiesta e segnala diagnostiche di canali o strumenti duplicati invece di scegliere silenziosamente un proprietario.

Se un pacchetto installato segnala che requires compiled runtime output for TypeScript entry ..., il pacchetto e stato pubblicato senza i file JavaScript necessari a OpenClaw a runtime. Aggiorna o reinstalla dopo che il publisher avra distribuito JavaScript compilato, oppure disabilita/disinstalla il plugin fino ad allora.

Proprieta bloccata del percorso del plugin

Se le diagnostiche del plugin indicano blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) e la validazione della configurazione prosegue con plugin present but blocked, OpenClaw ha trovato file del plugin di proprieta di un utente Unix diverso da quello del processo che li sta caricando. Mantieni la configurazione del plugin; correggi la proprieta del filesystem oppure esegui OpenClaw con lo stesso utente che possiede la directory di stato.

Per le installazioni Docker, l'immagine ufficiale viene eseguita come node (uid 1000), quindi le directory di configurazione e workspace OpenClaw montate in bind dall'host dovrebbero normalmente essere di proprieta dell'uid 1000:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

Se esegui intenzionalmente OpenClaw come root, ripara invece la root dei plugin gestiti impostandone la proprieta a root:

sudo chown -R root:root /path/to/openclaw-config/npm

Dopo aver corretto la proprieta, riesegui openclaw doctor --fix oppure openclaw plugins registry --refresh in modo che il registro persistente dei plugin corrisponda ai file riparati.

Configurazione lenta degli strumenti dei plugin

Se i turni dell'agente sembrano bloccarsi durante la preparazione degli strumenti, abilita il logging di trace e controlla le righe di temporizzazione delle factory degli strumenti dei plugin:

openclaw config set logging.level traceopenclaw logs --follow

Cerca:

[trace:plugin-tools] factory timings ...

Il riepilogo elenca il tempo totale delle factory e le factory degli strumenti dei plugin piu lente, inclusi id del plugin, nomi degli strumenti dichiarati, forma del risultato e se lo strumento e opzionale. Le righe lente vengono promosse ad avvisi quando una singola factory richiede almeno 1s o la preparazione totale delle factory degli strumenti dei plugin richiede almeno 5s.

OpenClaw memorizza nella cache i risultati riusciti delle factory degli strumenti dei plugin per risoluzioni ripetute con lo stesso contesto di richiesta effettivo. La chiave della cache include la configurazione runtime effettiva, il workspace, gli id agente/sessione, la policy sandbox, le impostazioni del browser, il contesto di consegna, l'identita del richiedente e lo stato di proprieta, quindi le factory che dipendono da questi campi attendibili vengono rieseguite quando il contesto cambia. Se le temporizzazioni restano alte, il plugin potrebbe svolgere lavoro costoso prima di restituire le definizioni degli strumenti.

Se un plugin domina la temporizzazione, ispeziona le sue registrazioni runtime:

openclaw plugins inspect <plugin-id> --runtime --json

Poi aggiorna, reinstalla o disabilita quel plugin. Gli autori di plugin dovrebbero spostare il caricamento costoso delle dipendenze dietro il percorso di esecuzione dello strumento invece di farlo dentro la factory dello strumento.

Per root delle dipendenze, validazione dei metadati dei pacchetti, record del registro, comportamento di ricaricamento all'avvio e pulizia legacy, consulta Risoluzione delle dipendenze dei plugin.

Correlati

• Gestire i plugin - esempi di comandi per elenco, installazione, aggiornamento, disinstallazione e pubblicazione
• openclaw plugins - riferimento CLI completo
• Inventario dei plugin - elenco generato dei plugin bundled ed esterni
• Riferimento dei plugin - pagine di riferimento generate per plugin
• Plugin della community - individuazione ClawHub e policy per le PR alla documentazione
• Risoluzione delle dipendenze dei plugin - root di installazione, record del registro e confini runtime
• Creare plugin - guida all'autorialita dei plugin nativi
• Panoramica del Plugin SDK - registrazione runtime, hook e campi API
• Manifesto del plugin - manifesto e metadati del pacchetto