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.

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

# Directory localeopenclaw plugins install ./my-bundle # Archivioopenclaw plugins install ./my-bundle.tgz # Marketplace Claudeopenclaw plugins marketplace list <source>openclaw plugins install <plugin> --marketplace <source>

openclaw plugins listopenclaw plugins inspect <id>

openclaw gateway restart

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

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

Precedenza del rilevamento

OpenClaw verifica innanzitutto il formato dei plugin nativi:

1. openclaw.plugin.json o un package.json valido con openclaw.extensions: viene trattato come plugin nativo
2. 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

Contenuti correlati

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