Bundle di Plugin

OpenClaw può installare plugin da tre ecosistemi esterni: Codex, Claude e Cursor. Questi sono chiamati bundle, ovvero pacchetti di contenuti e metadati che OpenClaw mappa in funzionalità native come Skills, hook e strumenti MCP.

I bundle non sono equivalenti ai plugin nativi di OpenClaw. I plugin nativi vengono eseguiti nello stesso processo e possono registrare qualsiasi funzionalità. I bundle sono pacchetti di contenuti con una mappatura selettiva delle funzionalità e un perimetro di attendibilità più ristretto.

Perché esistono i bundle

Molti plugin utili sono pubblicati nel formato Codex, Claude o Cursor. Anziché richiedere agli autori di riscriverli come plugin nativi di OpenClaw, OpenClaw rileva questi formati e mappa i contenuti supportati nell’insieme di funzionalità native. È possibile installare un pacchetto di comandi Claude o un bundle di Skills Codex e utilizzarlo immediatamente.

Installare un bundle

Installa da una directory, un archivio o un marketplace

# Directory locale
openclaw plugins install ./my-bundle

# Archivio
openclaw plugins install ./my-bundle.tgz

# Marketplace Claude
openclaw plugins marketplace list <source>
openclaw plugins install <plugin> --marketplace <source>

<source> è un percorso/repository di marketplace locale oppure un’origine git/GitHub.

Verifica il rilevamento

openclaw plugins list
openclaw plugins inspect <id>

I bundle mostrano Format: bundle insieme a un valore Bundle format: pari a codex, claude o cursor.

Riavvia e utilizza

openclaw gateway restart

Le funzionalità mappate (Skills, hook, strumenti MCP, impostazioni predefinite LSP) sono disponibili nella sessione successiva.

Cosa mappa OpenClaw dai bundle

Attualmente non tutte le funzionalità dei bundle vengono eseguite in OpenClaw. Di seguito sono indicate quelle operative e quelle rilevate ma non ancora collegate.

Attualmente supportate

Funzionalità	Modalità di mappatura	Si applica a
Contenuti delle Skills	Le radici delle Skills del bundle vengono caricate come normali Skills di OpenClaw	Tutti i formati
Comandi	`commands/` e `.cursor/commands/` vengono trattate come radici delle Skills	Claude, Cursor
Pacchetti di hook	Strutture in stile OpenClaw con `HOOK.md` + `handler.ts`	Codex
Strumenti MCP	La configurazione MCP del bundle viene unita alle impostazioni integrate di OpenClaw; vengono caricati i server stdio e HTTP supportati	Tutti i formati
Server LSP	Il file `.lsp.json` di Claude e i percorsi `lspServers` dichiarati nel manifesto vengono uniti alle impostazioni predefinite LSP integrate di OpenClaw	Claude
Impostazioni	Il file `settings.json` di Claude viene importato come impostazioni predefinite integrate di OpenClaw	Claude

Contenuti delle Skills

Le radici delle Skills del bundle vengono caricate come normali radici delle Skills di OpenClaw.
Le radici commands/ di Claude vengono trattate come radici aggiuntive delle Skills.
Le radici .cursor/commands/ di Cursor vengono trattate come radici aggiuntive delle Skills.

I file di comando Markdown di Claude e quelli di Cursor funzionano entrambi tramite il normale caricatore delle Skills di OpenClaw.

Pacchetti di hook

Le radici degli hook dei bundle funzionano solo quando utilizzano la normale struttura dei pacchetti di hook di OpenClaw: HOOK.md insieme a handler.ts o handler.js. Attualmente ciò riguarda principalmente il caso compatibile con Codex.

MCP per OpenClaw integrato

I bundle abilitati possono fornire la configurazione dei server MCP.
OpenClaw unisce la configurazione MCP del bundle alle impostazioni effettive di OpenClaw integrato come mcpServers.
OpenClaw espone gli strumenti MCP supportati del bundle durante i turni dell’agente OpenClaw integrato avviando server stdio o connettendosi a server HTTP.
I profili degli strumenti coding e messaging includono per impostazione predefinita gli strumenti MCP dei bundle; utilizzare tools.deny: ["bundle-mcp"] per escluderli per un agente o un Gateway.
Le impostazioni locali del progetto per l’agente integrato vengono comunque applicate dopo le impostazioni predefinite del bundle, pertanto le impostazioni dell’area di lavoro possono sovrascrivere le voci MCP del bundle quando necessario.
I cataloghi degli strumenti MCP dei bundle vengono ordinati in modo deterministico prima della registrazione, affinché le modifiche a monte nell’ordine di listTools() non alterino continuamente i blocchi degli strumenti nella cache dei prompt.

Trasporti

I server MCP possono utilizzare il trasporto stdio o HTTP. Stdio avvia un processo figlio:

{
  "mcp": {
    "servers": {
      "my-server": {
        "command": "node",
        "args": ["server.js"],
        "env": { "PORT": "3000" }
      }
    }
  }
}

HTTP si connette a un server MCP in esecuzione, utilizzando per impostazione predefinita sse, salvo quando viene richiesto streamable-http:

{
  "mcp": {
    "servers": {
      "my-server": {
        "url": "http://localhost:3100/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer ${MY_SECRET_TOKEN}"
        },
        "connectionTimeoutMs": 30000
      }
    }
  }
}

transport accetta "streamable-http" o "sse"; se omesso, il valore predefinito è sse.
type: "http" è una struttura a valle nativa della CLI; nella configurazione di OpenClaw utilizzare transport: "streamable-http". openclaw mcp set e openclaw doctor --fix normalizzano l’alias comune.
Sono consentiti solo gli schemi URL http: e https:.
I valori di headers supportano l’interpolazione ${ENV_VAR}.
Una voce server contenente sia command sia url viene rifiutata.
Le credenziali presenti nell’URL (informazioni utente e parametri di query) vengono oscurate nelle descrizioni degli strumenti e nei registri.
connectionTimeoutMs sostituisce il timeout di connessione predefinito di 30 secondi per entrambi i trasporti stdio e HTTP. Il timeout predefinito delle richieste è di 60 secondi e può essere sostituito con requestTimeoutMs.

Denominazione degli strumenti

OpenClaw registra gli strumenti MCP dei bundle con nomi compatibili con i provider nel formato serverName__toolName. Ad esempio, un server identificato dalla chiave "vigil-harbor" che espone uno strumento memory_search viene registrato come vigil-harbor__memory_search.

I caratteri non compresi in A-Za-z0-9_- vengono sostituiti con -.
I frammenti che inizierebbero con un carattere diverso da una lettera ricevono un prefisso alfabetico, pertanto le chiavi numeriche dei server, come 12306, diventano prefissi degli strumenti compatibili con i provider.
I prefissi dei server sono limitati a 30 caratteri.
I nomi completi degli strumenti sono limitati a 64 caratteri.
Per i nomi dei server vuoti viene utilizzato mcp.
I nomi normalizzati che entrano in conflitto vengono distinti con suffissi numerici.
L’ordine finale degli strumenti esposti è deterministico in base al nome sicuro, mantenendo stabili rispetto alla cache i turni ripetuti dell’agente integrato.
Il filtraggio dei profili considera ogni strumento proveniente da un server MCP di un bundle come appartenente al plugin bundle-mcp, pertanto gli elenchi di inclusione/esclusione dei profili possono fare riferimento sia ai singoli nomi degli strumenti esposti sia alla chiave del plugin bundle-mcp.

Impostazioni di OpenClaw integrato

Il file settings.json di Claude viene importato come impostazioni predefinite di OpenClaw integrato quando il bundle è abilitato. OpenClaw rimuove le chiavi di sostituzione della shell prima di applicarle:

shellPath
shellCommandPrefix

LSP di OpenClaw integrato

I bundle Claude abilitati possono fornire la configurazione dei server LSP.
OpenClaw carica .lsp.json insieme agli eventuali percorsi lspServers dichiarati nel manifesto.
La configurazione LSP del bundle viene unita alle impostazioni predefinite LSP effettive di OpenClaw integrato.
Attualmente sono eseguibili solo i server LSP supportati basati su stdio; i trasporti non supportati vengono comunque visualizzati in openclaw plugins inspect <id>.

Rilevate ma non eseguite

Le seguenti funzionalità vengono riconosciute e mostrate nella diagnostica, ma OpenClaw non le esegue:

agents, automazione hooks/hooks.json e outputStyles di Claude
.cursor/agents, .cursor/hooks.json e .cursor/rules di Cursor
Metadati .app.json di Codex oltre alla segnalazione delle funzionalità

Formati dei bundle

Bundle Codex

Marcatori: .codex-plugin/plugin.jsonContenuti facoltativi: skills/, hooks/, .mcp.json, .app.jsonI bundle Codex si integrano al meglio con OpenClaw quando utilizzano le radici delle Skills e directory di pacchetti di hook in stile OpenClaw (HOOK.md + handler.ts).

Bundle Claude

Due modalità di rilevamento:

Basata sul manifesto: .claude-plugin/plugin.json
Senza manifesto: struttura predefinita di Claude (skills/, commands/, agents/, hooks/, .mcp.json, .lsp.json, settings.json)

Comportamento specifico di Claude:

commands/ viene trattata come contenuto delle Skills
settings.json viene importato nelle impostazioni di OpenClaw integrato (le chiavi di sostituzione della shell vengono rimosse)
.mcp.json espone gli strumenti stdio supportati a OpenClaw integrato
.lsp.json insieme ai percorsi lspServers dichiarati nel manifesto viene caricato nelle impostazioni predefinite LSP di OpenClaw integrato
hooks/hooks.json viene rilevato ma non eseguito
I percorsi personalizzati dei componenti nel manifesto sono aggiuntivi: estendono i valori predefiniti, non li sostituiscono

Bundle Cursor

Marcatori: .cursor-plugin/plugin.jsonContenuti facoltativi: skills/, .cursor/commands/, .cursor/agents/, .cursor/rules/, .cursor/hooks.json, .mcp.json

.cursor/commands/ viene trattata come contenuto delle Skills
.cursor/rules/, .cursor/agents/ e .cursor/hooks.json vengono soltanto rilevati

Precedenza del rilevamento

OpenClaw verifica innanzitutto il formato dei plugin nativi:

openclaw.plugin.json o un package.json valido con openclaw.extensions: viene trattato come plugin nativo
Marcatori dei bundle (.codex-plugin/, .claude-plugin/ o struttura predefinita di Claude/Cursor): vengono trattati come bundle

Se una directory contiene entrambi, OpenClaw utilizza il percorso nativo. Ciò impedisce che i pacchetti in doppio formato vengano installati parzialmente come bundle.

Dipendenze di runtime e pulizia

I bundle compatibili di terze parti non ricevono la riparazione tramite npm install all’avvio. Devono essere installati tramite openclaw plugins install e includere tutto ciò di cui hanno bisogno nella directory del plugin installato.
I plugin inclusi di proprietà di OpenClaw sono distribuiti in forma leggera nel core oppure scaricabili tramite il programma di installazione dei plugin. All’avvio, il Gateway non esegue mai un gestore di pacchetti per questi plugin.
openclaw doctor --fix rimuove i record obsoleti delle installazioni locali dei plugin inclusi e può ripristinare i plugin scaricabili mancanti dall’indice locale dei plugin quando la configurazione continua a farvi riferimento.

Sicurezza

I bundle hanno un perimetro di attendibilità più ristretto rispetto ai plugin nativi:

OpenClaw non carica nello stesso processo moduli di runtime arbitrari dei bundle.
I percorsi delle Skills e dei pacchetti di hook devono rimanere all’interno della radice del plugin (con verifica dei confini).
I file delle impostazioni vengono letti applicando le stesse verifiche dei confini.
I server MCP stdio supportati possono essere avviati come sottoprocessi.

Questo rende i bundle più sicuri per impostazione predefinita, ma è comunque necessario considerare i bundle di terze parti come contenuti attendibili per le funzionalità che espongono.

Risoluzione dei problemi

Il bundle viene rilevato ma le funzionalità non vengono eseguite

Eseguire openclaw plugins inspect <id>. Se una funzionalità è elencata ma contrassegnata come non collegata, si tratta di una limitazione del prodotto, non di un’installazione non riuscita.

I file dei comandi Claude non vengono visualizzati

Assicurarsi che il bundle sia abilitato e che i file Markdown si trovino all’interno di una radice commands/ o skills/ rilevata.

Le impostazioni Claude non vengono applicate

Sono supportate solo le impostazioni di OpenClaw integrato provenienti da settings.json. OpenClaw non tratta le impostazioni del bundle come modifiche dirette alla configurazione.

Gli hook Claude non vengono eseguiti

hooks/hooks.json viene soltanto rilevato. Se sono necessari hook eseguibili, utilizzare la struttura dei pacchetti di hook di OpenClaw oppure distribuire un plugin nativo.

Contenuti correlati

Installare e configurare i plugin
Creare plugin - creare un plugin nativo
Manifesto dei plugin - schema del manifesto nativo

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Perché esistono i bundle

Installare un bundle

Cosa mappa OpenClaw dai bundle

Attualmente supportate

Contenuti delle Skills

Pacchetti di hook

MCP per OpenClaw integrato

Trasporti

Denominazione degli strumenti

Impostazioni di OpenClaw integrato

LSP di OpenClaw integrato

Rilevate ma non eseguite

Formati dei bundle

Precedenza del rilevamento

Dipendenze di runtime e pulizia

Sicurezza

Risoluzione dei problemi

Contenuti correlati

​Perché esistono i bundle

​Installare un bundle

​Cosa mappa OpenClaw dai bundle

​Attualmente supportate

​Contenuti delle Skills

​Pacchetti di hook

​MCP per OpenClaw integrato

Trasporti

Denominazione degli strumenti

​Impostazioni di OpenClaw integrato

​LSP di OpenClaw integrato

​Rilevate ma non eseguite

​Formati dei bundle

​Precedenza del rilevamento

​Dipendenze di runtime e pulizia

​Sicurezza

​Risoluzione dei problemi

​Contenuti correlati

Perché esistono i bundle

Installare un bundle

Cosa mappa OpenClaw dai bundle

Attualmente supportate

Contenuti delle Skills

Pacchetti di hook

MCP per OpenClaw integrato

Impostazioni di OpenClaw integrato

LSP di OpenClaw integrato

Rilevate ma non eseguite

Formati dei bundle

Precedenza del rilevamento

Dipendenze di runtime e pulizia

Sicurezza

Risoluzione dei problemi

Contenuti correlati