Vai al contenuto principale
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

1

Trova il Plugin

Cerca in ClawHub i pacchetti Plugin pubblici:
openclaw plugins search "calendar"
ClawHub è la superficie primaria di scoperta per i Plugin della community. Durante il passaggio di lancio, le normali specifiche di pacchetto bare installano ancora da npm a meno che non corrispondano a un id di Plugin ufficiale. Le specifiche di pacchetto @openclaw/* raw che corrispondono ai Plugin inclusi usano la copia inclusa della build OpenClaw corrente. Usa un prefisso esplicito quando ti serve una sorgente specifica.
2

Installa il Plugin

# 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-plugin
openclaw plugins install --link ./my-plugin
Tratta le installazioni dei Plugin come esecuzione di codice. Preferisci versioni fissate quando ti servono installazioni di produzione riproducibili.
3

Configuralo e abilitalo

Configura le impostazioni specifiche del Plugin in plugins.entries.<id>.config. Abilita il Plugin quando non è già abilitato:
openclaw plugins enable <plugin-id>
Se la tua configurazione usa un elenco plugins.allow restrittivo, l’id del Plugin installato deve essere presente lì prima che il Plugin possa essere caricato. openclaw plugins install aggiunge l’id installato a un elenco plugins.allow esistente e rimuove lo stesso id da plugins.deny in modo che l’installazione esplicita possa caricarsi dopo il riavvio.
4

Lascia ricaricare il Gateway

L’installazione, l’aggiornamento o la disinstallazione del codice del Plugin richiedono un riavvio del Gateway. Quando un Gateway gestito è già in esecuzione con la ricarica della configurazione abilitata, OpenClaw rileva il record di installazione del Plugin modificato e riavvia il Gateway automaticamente. Se il Gateway non è gestito o la ricarica è disabilitata, riavvialo tu:
openclaw gateway restart
Le operazioni di abilitazione e disabilitazione aggiornano la configurazione e aggiornano il registro a freddo. Un’ispezione del runtime resta comunque il percorso di verifica più chiaro per le superfici di runtime live.
5

Verifica la registrazione del runtime

openclaw plugins inspect <plugin-id> --runtime --json
Usa --runtime quando devi dimostrare strumenti, hook, servizi, metodi Gateway o comandi CLI posseduti dal Plugin registrati. inspect semplice è un controllo a freddo di manifest e registro.

​
Configurazione

​
Scegli una sorgente di installazione

SorgenteUsala quandoEsempio
ClawHubVuoi scoperta nativa di OpenClaw, scansioni, metadati di versione e suggerimenti di installazioneopenclaw plugins install clawhub:<package>
npmTi servono workflow diretti del registro npm o dist-tagopenclaw plugins install npm:<package>
gitTi serve un branch, tag o commit da un repositoryopenclaw plugins install git:github.com/<owner>/<repo>@<ref>
percorso localeStai sviluppando o testando un Plugin sulla stessa macchinaopenclaw plugins install --link ./my-plugin
marketplaceStai installando un Plugin marketplace compatibile con Claudeopenclaw plugins install <plugin> --marketplace <source>
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:
FormatoCome viene caricatoUsalo quando
Plugin OpenClaw nativoopenclaw.plugin.json più un modulo runtime caricato nel processoStai installando o creando capacità di runtime specifiche di OpenClaw
Bundle compatibileLayout Plugin Codex, Claude o Cursor mappato nell’inventario Plugin OpenClawStai riutilizzando Skills, comandi, hook o metadati bundle compatibili
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-rpc
openclaw plugins inspect <plugin-id> --runtime --json
openclaw 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

SintomoControlloCorrezione
Il Plugin appare in plugins list ma gli hook runtime non vengono eseguitiUsa openclaw plugins inspect <id> --runtime --json e conferma il Gateway attivo con gateway status --deep --require-rpcRiavvia il Gateway live dopo modifiche di installazione, aggiornamento, configurazione o sorgente
Compaiono diagnostiche di proprieta duplicate di canale o strumentoEsegui openclaw plugins list --enabled --verbose, ispeziona ogni plugin sospetto con --runtime --json e confronta la proprieta di canali/strumentiDisabilita un proprietario, rimuovi installazioni obsolete oppure usa preferOver del manifesto per la sostituzione intenzionale
La configurazione indica che manca un pluginControlla Inventario dei plugin per sapere se e bundled, esterno ufficiale o solo sorgenteInstalla il pacchetto esterno, abilita il plugin bundled oppure rimuovi la configurazione obsoleta
La configurazione non e valida durante l’installazioneLeggi il messaggio di validazione ed esegui openclaw doctor --fix quando indica uno stato plugin obsoletoDoctor puo mettere in quarantena la configurazione plugin non valida disabilitando la voce e rimuovendo il payload non valido
Il percorso del plugin e bloccato per proprieta o permessi sospettiIspeziona la diagnostica prima dell’errore di configurazioneCorreggi proprieta/permessi del filesystem, poi esegui openclaw plugins registry --refresh
OPENCLAW_NIX_MODE=1 blocca i comandi del ciclo di vitaConferma che l’installazione sia gestita da NixModifica la selezione dei plugin nel sorgente Nix invece di usare i comandi mutatori dei plugin
L’importazione di una dipendenza fallisce a runtimeControlla se il plugin e stato installato tramite npm/git/ClawHub o caricato da un percorso localeEsegui openclaw plugins update <id>, reinstalla il sorgente oppure installa manualmente le dipendenze del plugin locale
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 trace
openclaw 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