Plugin

I Plugin estendono OmeniaClaw con nuove capacità: canali, provider di modelli, harness per agenti, strumenti, Skills, parlato, trascrizione realtime, voce realtime, comprensione dei media, generazione di immagini, generazione di video, recupero web, ricerca web e altro. Alcuni plugin sono core (distribuiti con OmeniaClaw), altri sono esterni. La maggior parte dei plugin esterni viene pubblicata e scoperta tramite ClawHub. Npm rimane supportato per le installazioni dirette e per un insieme temporaneo di pacchetti plugin di proprietà di OmeniaClaw mentre la migrazione viene completata.

Avvio rapido

Per esempi da copiare e incollare per installazione, elenco, disinstallazione, aggiornamento e pubblicazione, consulta Gestire i plugin.

OmeniaClaw plugins list

# Search ClawHub pluginsOmeniaClaw plugins search "calendar" # From ClawHubOmeniaClaw plugins install clawhub:OmeniaClaw-codex-app-server # From npmOmeniaClaw plugins install npm:@acme/OmeniaClaw-pluginOmeniaClaw plugins install npm-pack:./OmeniaClaw-plugin-1.2.3.tgz # From gitOmeniaClaw plugins install git:github.com/acme/[email protected] # From a local directory or archiveOmeniaClaw plugins install ./my-pluginOmeniaClaw plugins install ./my-plugin.tgz

OmeniaClaw gateway restart

OmeniaClaw plugins inspect <plugin-id> --runtime --json # If the plugin registered a CLI root, run one command from that root.OmeniaClaw <plugin-command> --help

Se preferisci il controllo nativo della chat, abilita commands.plugins: true e usa:

/plugin install clawhub:<package>/plugin show <plugin-id>/plugin enable <plugin-id>

Il percorso di installazione usa lo stesso resolver della CLI: percorso/archivio locale, clawhub:<pkg> esplicito, npm:<pkg> esplicito, npm-pack:<path.tgz> esplicito, git:<repo> esplicito, oppure specifica di pacchetto semplice tramite npm.

Se la configurazione non è valida, l'installazione normalmente fallisce chiusa e ti indirizza a OmeniaClaw doctor --fix. L'unica eccezione di recupero è un percorso ristretto di reinstallazione per plugin inclusi che aderiscono a OmeniaClaw.install.allowInvalidConfigRecovery. Durante l'avvio del Gateway, una configurazione plugin non valida fallisce chiusa come qualsiasi altra configurazione non valida. Esegui OmeniaClaw doctor --fix per mettere in quarantena la configurazione non valida del plugin disabilitando quella voce plugin e rimuovendo il relativo payload di configurazione non valido; il normale backup della configurazione mantiene i valori precedenti. Quando una configurazione di canale fa riferimento a un plugin che non è più rilevabile ma lo stesso ID plugin obsoleto rimane nella configurazione plugin o nei record di installazione, l'avvio del Gateway registra avvisi e salta quel canale invece di bloccare tutti gli altri canali. Esegui OmeniaClaw doctor --fix per rimuovere le voci canale/plugin obsolete; le chiavi canale sconosciute senza evidenza di plugin obsoleto continuano a fallire la validazione, così gli errori di battitura restano visibili. Se è impostato plugins.enabled: false, i riferimenti a plugin obsoleti sono trattati come inerti: l'avvio del Gateway salta il lavoro di scoperta/caricamento dei plugin e OmeniaClaw doctor conserva la configurazione plugin disabilitata invece di rimuoverla automaticamente. Riabilita i plugin prima di eseguire la pulizia con doctor se vuoi rimuovere gli ID plugin obsoleti.

L'installazione delle dipendenze dei plugin avviene solo durante flussi espliciti di installazione/aggiornamento o riparazione doctor. L'avvio del Gateway, il ricaricamento della configurazione e l'ispezione runtime non eseguono gestori di pacchetti né riparano alberi delle dipendenze. I plugin locali devono avere già le loro dipendenze installate, mentre i plugin npm, git e ClawHub vengono installati sotto le radici plugin gestite da OmeniaClaw. Le dipendenze npm possono essere hoistate all'interno della radice npm gestita da OmeniaClaw; installazione/aggiornamento scansiona quella radice gestita prima della fiducia e la disinstallazione rimuove i pacchetti gestiti da npm tramite npm. I plugin esterni e i percorsi di caricamento personalizzati devono comunque essere installati tramite OmeniaClaw plugins install. Usa OmeniaClaw plugins list --json per vedere lo stato statico dependencyStatus per ogni plugin visibile senza importare codice runtime o riparare dipendenze. Consulta Risoluzione delle dipendenze dei plugin per il ciclo di vita in fase di installazione.

Proprietà del percorso plugin bloccato

Se la diagnostica dei plugin dice blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) e la validazione della configurazione segue con plugin present but blocked, OmeniaClaw ha trovato file plugin di proprietà di un utente Unix diverso da quello del processo che li sta caricando. Mantieni la configurazione del plugin al suo posto; correggi la proprietà del filesystem o esegui OmeniaClaw come lo stesso utente che possiede la directory di stato.

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

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

Se esegui intenzionalmente OmeniaClaw come root, ripara invece la radice plugin gestita assegnandola a root:

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

Dopo aver corretto la proprietà, riesegui OmeniaClaw doctor --fix o OmeniaClaw plugins registry --refresh così il registro plugin persistito corrisponde ai file riparati.

Per installazioni npm, selettori mutabili come latest o un dist-tag vengono risolti prima dell'installazione e poi fissati alla versione esatta verificata nella radice npm gestita da OmeniaClaw. Dopo che npm ha terminato, OmeniaClaw verifica che la voce package-lock.json installata corrisponda ancora alla versione e all'integrità risolte. Se npm scrive metadati di pacchetto diversi, l'installazione fallisce e il pacchetto gestito viene ripristinato invece di accettare un artefatto plugin diverso. Le radici npm gestite ereditano anche gli overrides npm a livello di pacchetto di OmeniaClaw, quindi i pin di sicurezza che proteggono l'host pacchettizzato si applicano anche alle dipendenze dei plugin esterni hoistate.

I checkout sorgente sono workspace pnpm. Se cloni OmeniaClaw per lavorare sui plugin inclusi, esegui pnpm install; OmeniaClaw carica quindi i plugin inclusi da extensions/<id> così modifiche e dipendenze locali del pacchetto vengono usate direttamente. Le installazioni radice npm semplici sono per OmeniaClaw pacchettizzato, non per lo sviluppo da checkout sorgente.

Tipi di plugin

OmeniaClaw riconosce due formati di plugin:

Entrambi compaiono sotto OmeniaClaw plugins list. Consulta Bundle di plugin per i dettagli sui bundle.

Se stai scrivendo un plugin nativo, inizia con Creare plugin e la Panoramica del Plugin SDK.

Entry point dei pacchetti

I pacchetti npm di plugin nativi devono dichiarare OmeniaClaw.extensions in package.json. Ogni voce deve restare all'interno della directory del pacchetto e risolversi in un file runtime leggibile, oppure in un file sorgente TypeScript con un peer JavaScript compilato inferito, ad esempio da src/index.ts a dist/index.js. Le installazioni pacchettizzate devono includere quell'output runtime JavaScript. Il fallback al sorgente TypeScript è per checkout sorgente e percorsi di sviluppo locale, non per pacchetti npm installati nella radice plugin gestita da OmeniaClaw.

Le directory non tracciate inserite nella radice globale delle estensioni sono trattate come checkout sorgente locali e possono caricare direttamente entry TypeScript. Le directory ancora nominate da un record di installazione, incluso installPath o sourcePath, restano gestite e mantengono il requisito di output compilato anche quando la scansione globale le vede. Se intendi convertire un'installazione gestita in un checkout locale non tracciato, rimuovi prima il record di installazione obsoleto con la disinstallazione o la pulizia doctor.

Se un avviso di pacchetto gestito dice che requires compiled runtime output for TypeScript entry ..., il pacchetto è stato pubblicato senza i file JavaScript di cui OmeniaClaw ha bisogno in runtime. Questo è un problema di pacchettizzazione del plugin, non un problema di configurazione locale. Aggiorna o reinstalla il plugin dopo che il publisher ripubblica JavaScript compilato, oppure disabilita/disinstalla quel plugin finché non è disponibile un pacchetto corretto.

Usa OmeniaClaw.runtimeExtensions quando i file runtime pubblicati non si trovano negli stessi percorsi delle entry sorgente. Quando presente, runtimeExtensions deve contenere esattamente una voce per ogni voce extensions. Liste non corrispondenti fanno fallire installazione e scoperta dei plugin invece di ripiegare silenziosamente sui percorsi sorgente. Se pubblichi anche OmeniaClaw.setupEntry, usa OmeniaClaw.runtimeSetupEntry per il suo peer JavaScript compilato; quel file è obbligatorio quando dichiarato.

{  "name": "@acme/OmeniaClaw-plugin",  "OmeniaClaw": {    "extensions": ["./src/index.ts"],    "runtimeExtensions": ["./dist/index.js"]  }}

Plugin ufficiali

Pacchetti npm di proprietà di OmeniaClaw durante la migrazione

ClawHub è il percorso di distribuzione principale per la maggior parte dei plugin. Le versioni OmeniaClaw pacchettizzate correnti includono già molti plugin ufficiali, quindi quelli non richiedono installazioni npm separate nelle configurazioni normali. Finché ogni plugin di proprietà di OmeniaClaw non sarà migrato a ClawHub, OmeniaClaw continuerà a distribuire alcuni pacchetti plugin @OmeniaClaw/* su npm per installazioni meno recenti/personalizzate e flussi di lavoro npm diretti.

Se npm segnala un pacchetto plugin @OmeniaClaw/* come deprecato, quella versione del pacchetto proviene da una linea di pacchetti esterna più vecchia. Usa il plugin incluso nell'OmeniaClaw corrente o un checkout locale finché non viene pubblicato un pacchetto npm più recente.

Core (distribuiti con OmeniaClaw)

Cerchi Plugin di terze parti? Vedi ClawHub.

Configurazione

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

plugins.allow è esclusivo. Quando non è vuoto, possono essere caricati o esporre strumenti solo i Plugin elencati, anche se tools.allow contiene "*" o il nome specifico di uno strumento posseduto da un Plugin. Se un elenco consentiti degli strumenti fa riferimento a strumenti Plugin, aggiungi gli id dei Plugin proprietari a plugins.allow oppure rimuovi plugins.allow; OmeniaClaw doctor avvisa di questa configurazione.

plugins.bundledDiscovery usa come valore predefinito "allowlist" per le nuove configurazioni, quindi un inventario restrittivo plugins.allow blocca anche i Plugin provider inclusi omessi, inclusa la discovery dei provider di ricerca web runtime. Durante la migrazione, doctor marca le configurazioni restrittive più vecchie dell'elenco consentiti con "compat" così gli upgrade mantengono il comportamento legacy dei provider inclusi finché l'operatore non sceglie la modalità più rigorosa. Un plugins.allow vuoto viene comunque trattato come non impostato/aperto.

Le modifiche di configurazione eseguite tramite /plugins enable o /plugins disable attivano una ricarica in-process dei Plugin del Gateway. I nuovi turni dell'agente ricostruiscono il proprio elenco di strumenti dal registro Plugin aggiornato. Le operazioni che modificano il sorgente, come installazione, aggiornamento e disinstallazione, riavviano comunque il processo Gateway perché i moduli Plugin già importati non possono essere sostituiti in sicurezza sul posto.

OmeniaClaw plugins list è uno snapshot locale del registro/configurazione dei Plugin. Un Plugin enabled lì significa che il registro persistito e la configurazione corrente consentono al Plugin di partecipare. Non dimostra che un Gateway remoto già in esecuzione abbia ricaricato o riavviato lo stesso codice Plugin. Nelle configurazioni VPS/container con processi wrapper, invia i riavvii o le scritture che attivano la ricarica al processo effettivo OmeniaClaw gateway run, oppure usa OmeniaClaw gateway restart sul Gateway in esecuzione quando la ricarica segnala un errore.

Discovery e precedenza

OmeniaClaw cerca i Plugin in questo ordine (vince la prima corrispondenza):

Le installazioni pacchettizzate e le immagini Docker normalmente risolvono i Plugin inclusi dall'albero compilato dist/extensions. Se una directory sorgente di un Plugin incluso viene montata tramite bind sopra il percorso sorgente pacchettizzato corrispondente, per esempio /app/extensions/synology-chat, OmeniaClaw tratta quella directory sorgente montata come overlay sorgente incluso e la scopre prima del bundle pacchettizzato /app/dist/extensions/synology-chat. Questo mantiene funzionanti i cicli container dei maintainer senza riportare ogni Plugin incluso al sorgente TypeScript. Imposta OmeniaClaw_DISABLE_BUNDLED_SOURCE_OVERLAYS=1 per forzare i bundle dist pacchettizzati anche quando sono presenti mount overlay sorgente.

Regole di abilitazione

• plugins.enabled: false disabilita tutti i Plugin e salta il lavoro di discovery/caricamento dei Plugin
• plugins.deny ha sempre la precedenza su allow
• plugins.entries.\<id\>.enabled: false disabilita quel Plugin
• I Plugin originati dall'area di lavoro sono disabilitati per impostazione predefinita (devono essere abilitati esplicitamente)
• I Plugin inclusi seguono l'insieme integrato abilitato per impostazione predefinita salvo override
• Gli slot esclusivi possono forzare l'abilitazione del Plugin selezionato per quello slot
• Alcuni Plugin inclusi opt-in vengono abilitati automaticamente quando la configurazione nomina una superficie posseduta da un Plugin, come un riferimento modello provider, configurazione di canale o runtime harness
• La configurazione Plugin obsoleta viene preservata mentre plugins.enabled: false è attivo; riabilita i Plugin prima di eseguire la pulizia doctor se vuoi rimuovere gli id obsoleti
• Le route Codex della famiglia OpenAI mantengono confini Plugin separati: openai-codex/* appartiene al Plugin OpenAI, mentre il Plugin app-server Codex incluso viene selezionato da riferimenti agente canonici openai/*, da agentRuntime.id: "codex" esplicito provider/model o dai riferimenti modello legacy codex/*

Risoluzione dei problemi degli hook runtime

Se un Plugin appare in plugins list ma gli effetti collaterali o gli hook di register(api) non vengono eseguiti nel traffico chat live, controlla prima questi punti:

• Esegui OmeniaClaw gateway status --deep --require-rpc e conferma che URL, profilo, percorso di configurazione e processo del Gateway attivo siano quelli che stai modificando.
• Riavvia il Gateway live dopo modifiche a installazione/configurazione/codice dei Plugin. Nei container wrapper, PID 1 potrebbe essere solo un supervisor; riavvia o invia un segnale al processo figlio OmeniaClaw gateway run.
• Usa OmeniaClaw plugins inspect <id> --runtime --json per confermare registrazioni degli hook e diagnostica. Gli hook di conversazione non inclusi come before_model_resolve, before_agent_reply, before_agent_run, llm_input, llm_output, before_agent_finalize e agent_end richiedono plugins.entries.<id>.hooks.allowConversationAccess=true.
• Per il cambio di modello, preferisci before_model_resolve. Viene eseguito prima della risoluzione del modello per i turni agente; llm_output viene eseguito solo dopo che un tentativo di modello produce output dell'assistente.
• Come prova del modello effettivo della sessione, usa OmeniaClaw sessions o le superfici session/status del Gateway e, durante il debug dei payload provider, avvia il Gateway con --raw-stream --raw-stream-path <path>.

Configurazione lenta degli strumenti Plugin

Se i turni dell'agente sembrano bloccarsi durante la preparazione degli strumenti, abilita il logging trace e controlla le righe sui tempi delle factory degli strumenti Plugin:

OmeniaClaw config set logging.level traceOmeniaClaw logs --follow

Cerca:

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

Il riepilogo elenca il tempo totale delle factory e le factory degli strumenti Plugin più lente, inclusi id Plugin, nomi degli strumenti dichiarati, forma del risultato e se lo strumento è opzionale. Le righe lente vengono promosse ad avvisi quando una singola factory impiega almeno 1 s oppure la preparazione totale delle factory degli strumenti Plugin impiega almeno 5 s.

OmeniaClaw memorizza nella cache i risultati riusciti delle factory degli strumenti Plugin per risoluzioni ripetute con lo stesso contesto effettivo della richiesta. La chiave cache include configurazione runtime effettiva, area di lavoro, id agente/sessione, criterio sandbox, impostazioni browser, contesto di delivery, identità del richiedente e stato di proprietà, quindi le factory che dipendono da questi campi attendibili vengono rieseguite quando il contesto cambia.

Se un Plugin domina i tempi, ispeziona le sue registrazioni runtime:

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

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

Proprietà duplicata di canale o strumento

Sintomi:

• channel already registered: <channel-id> (<plugin-id>)
• channel setup already registered: <channel-id> (<plugin-id>)
• plugin tool name conflict (<plugin-id>): <tool-name>

Questi indicano che più di un Plugin abilitato sta cercando di possedere lo stesso canale, flusso di configurazione o nome strumento. La causa più comune è un Plugin di canale esterno installato accanto a un Plugin incluso che ora fornisce lo stesso id canale.

Passaggi di debug:

• Esegui OmeniaClaw plugins list --enabled --verbose per vedere ogni Plugin abilitato e la sua origine.
• Esegui OmeniaClaw plugins inspect <id> --runtime --json per ogni Plugin sospetto e confronta channels, channelConfigs, tools e diagnostica.
• Esegui OmeniaClaw plugins registry --refresh dopo aver installato o rimosso pacchetti Plugin, così i metadati persistiti riflettono l'installazione corrente.
• Riavvia il Gateway dopo modifiche a installazione, registro o configurazione.

Opzioni di correzione:

• Se un Plugin sostituisce intenzionalmente un altro per lo stesso id canale, il Plugin preferito dovrebbe dichiarare channelConfigs.<channel-id>.preferOver con l'id Plugin a priorità inferiore. Vedi /plugins/manifest#replacing-another-channel-plugin.
• Se il duplicato è accidentale, disabilita un lato con plugins.entries.<plugin-id>.enabled: false oppure rimuovi l'installazione obsoleta del Plugin.
• Se hai abilitato esplicitamente entrambi i Plugin, OmeniaClaw mantiene quella richiesta e segnala il conflitto. Scegli un solo proprietario per il canale o rinomina gli strumenti posseduti dai Plugin in modo che la superficie runtime sia univoca.

Slot Plugin (categorie esclusive)

Alcune categorie sono esclusive (solo una attiva alla volta):

{  plugins: {    slots: {      memory: "memory-core", // or "none" to disable      contextEngine: "legacy", // or a plugin id    },  },}

Riferimento CLI

OmeniaClaw plugins list                       # compact inventoryOmeniaClaw plugins list --enabled            # only enabled pluginsOmeniaClaw plugins list --verbose            # per-plugin detail linesOmeniaClaw plugins list --json               # machine-readable inventoryOmeniaClaw plugins search <query>            # search ClawHub plugin catalogOmeniaClaw plugins inspect <id>              # static detailOmeniaClaw plugins inspect <id> --runtime    # registered hooks/tools/CLI/gateway methodsOmeniaClaw plugins inspect <id> --json       # machine-readableOmeniaClaw plugins inspect --all             # fleet-wide tableOmeniaClaw plugins info <id>                 # inspect aliasOmeniaClaw plugins doctor                    # diagnosticsOmeniaClaw plugins registry                  # inspect persisted registry stateOmeniaClaw plugins registry --refresh        # rebuild persisted registryOmeniaClaw doctor --fix                      # repair plugin registry state OmeniaClaw plugins install <package>         # install from npm by defaultOmeniaClaw plugins install clawhub:<pkg>     # install from ClawHub onlyOmeniaClaw plugins install npm:<pkg>         # install from npm onlyOmeniaClaw plugins install git:<repo>        # install from gitOmeniaClaw plugins install git:<repo>@<ref>  # install from git refOmeniaClaw plugins install <spec> --force    # overwrite existing installOmeniaClaw plugins install <path>            # install from local pathOmeniaClaw plugins install -l <path>         # link (no copy) for devOmeniaClaw plugins install <plugin> --marketplace <source>OmeniaClaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>OmeniaClaw plugins install <spec> --pin      # record exact resolved npm specOmeniaClaw plugins install <spec> --dangerously-force-unsafe-installOmeniaClaw plugins update <id-or-npm-spec> # update one pluginOmeniaClaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-installOmeniaClaw plugins update --all            # update allOmeniaClaw plugins uninstall <id>          # remove config and plugin index recordsOmeniaClaw plugins uninstall <id> --keep-filesOmeniaClaw plugins marketplace list <source>OmeniaClaw plugins marketplace list <source> --json # Verify runtime registrations after install.OmeniaClaw plugins inspect <id> --runtime --json # Run plugin-owned CLI commands directly from the OmeniaClaw root CLI.OmeniaClaw <plugin-command> --help OmeniaClaw plugins enable <id>OmeniaClaw plugins disable <id>

I Plugin inclusi vengono distribuiti con OmeniaClaw. Molti sono abilitati per impostazione predefinita (per esempio provider di modelli inclusi, provider vocali inclusi e il Plugin browser incluso). Altri Plugin inclusi richiedono comunque OmeniaClaw plugins enable <id>.

--force sovrascrive sul posto un Plugin installato o un hook pack esistente. Usa OmeniaClaw plugins update <id-or-npm-spec> per gli aggiornamenti ordinari dei Plugin npm tracciati. Non è supportato con --link, che riutilizza il percorso sorgente invece di copiarlo sopra una destinazione di installazione gestita.

Quando plugins.allow è già impostato, OmeniaClaw plugins install aggiunge l'id del Plugin installato a quella allowlist prima di abilitarlo. Se lo stesso id Plugin è presente in plugins.deny, l'installazione rimuove quella voce deny obsoleta, così l'installazione esplicita è caricabile subito dopo il riavvio.

OmeniaClaw mantiene un registro locale persistente dei Plugin come modello di lettura a freddo per l'inventario dei Plugin, la proprietà dei contributi e la pianificazione dell'avvio. I flussi di installazione, aggiornamento, disinstallazione, abilitazione e disabilitazione aggiornano quel registro dopo aver modificato lo stato dei Plugin. Lo stesso file plugins/installs.json mantiene metadati di installazione durevoli in installRecords di primo livello e metadati di manifesto ricostruibili in plugins. Se il registro è mancante, obsoleto o non valido, OmeniaClaw plugins registry --refresh ricostruisce la sua vista del manifesto dai record di installazione, dai criteri di configurazione e dai metadati di manifesto/pacchetto senza caricare moduli runtime dei Plugin.

In modalità Nix (OmeniaClaw_NIX_MODE=1), i modificatori del ciclo di vita dei Plugin sono disabilitati. Gestisci invece la selezione dei pacchetti Plugin e la configurazione tramite il sorgente Nix dell'installazione; per nix-OmeniaClaw, inizia dalla Quick Start orientata prima all'agente. OmeniaClaw plugins update <id-or-npm-spec> si applica alle installazioni tracciate. Passare una specifica di pacchetto npm con un dist-tag o una versione esatta risolve il nome del pacchetto riportandolo al record del Plugin tracciato e registra la nuova specifica per aggiornamenti futuri. Passare il nome del pacchetto senza una versione riporta un'installazione bloccata a una versione esatta alla linea di rilascio predefinita del registro. Se il Plugin npm installato corrisponde già alla versione risolta e all'identità dell'artefatto registrata, OmeniaClaw salta l'aggiornamento senza scaricare, reinstallare o riscrivere la configurazione. Quando OmeniaClaw update viene eseguito sul canale beta, i record Plugin npm e ClawHub della linea predefinita provano prima @beta e ripiegano su default/latest quando non esiste alcuna release beta del Plugin. Le versioni esatte e i tag espliciti restano bloccati.

--pin è solo per npm. Non è supportato con --marketplace, perché le installazioni da marketplace persistono metadati della sorgente marketplace invece di una specifica npm.

--dangerously-force-unsafe-install è una deroga di emergenza per falsi positivi dello scanner integrato di codice pericoloso. Consente alle installazioni e agli aggiornamenti dei Plugin di proseguire oltre i rilevamenti critical integrati, ma non aggira comunque i blocchi dei criteri before_install dei Plugin né il blocco per errori di scansione. Le scansioni di installazione ignorano file e directory di test comuni come tests/, __tests__/, *.test.* e *.spec.* per evitare di bloccare mock di test pacchettizzati; gli entrypoint runtime dichiarati dei Plugin vengono comunque scansionati anche se usano uno di quei nomi.

Questo flag CLI si applica solo ai flussi di installazione/aggiornamento dei Plugin. Le installazioni di dipendenze delle Skills supportate dal Gateway usano invece l'override di richiesta corrispondente dangerouslyForceUnsafeInstall, mentre OmeniaClaw skills install rimane il flusso separato di download/installazione delle Skills ClawHub.

Se un Plugin che hai pubblicato su ClawHub è nascosto o bloccato da una scansione, apri la dashboard ClawHub o esegui clawhub package rescan <name> per chiedere a ClawHub di controllarlo di nuovo. --dangerously-force-unsafe-install influisce solo sulle installazioni sulla tua macchina; non chiede a ClawHub di rieseguire la scansione del Plugin né rende pubblica una release bloccata.

I bundle compatibili partecipano allo stesso flusso list/inspect/enable/disable dei Plugin. Il supporto runtime attuale include Skills dei bundle, command-skills Claude, impostazioni predefinite Claude settings.json, impostazioni predefinite Claude .lsp.json e lspServers dichiarate dal manifesto, command-skills Cursor e directory di hook Codex compatibili.

OmeniaClaw plugins inspect <id> segnala anche le funzionalità bundle rilevate più le voci server MCP e LSP supportate o non supportate per i Plugin supportati da bundle.

Le sorgenti marketplace possono essere un nome di marketplace noto Claude da ~/.claude/plugins/known_marketplaces.json, una radice marketplace locale o un percorso marketplace.json, una forma abbreviata GitHub come owner/repo, un URL di repository GitHub o un URL git. Per i marketplace remoti, le voci Plugin devono restare all'interno del repository marketplace clonato e usare solo sorgenti con percorsi relativi.

Consulta il riferimento CLI OmeniaClaw plugins per tutti i dettagli.

Panoramica dell'API Plugin

I Plugin nativi esportano un oggetto entry che espone register(api). I Plugin meno recenti possono ancora usare activate(api) come alias legacy, ma i nuovi Plugin dovrebbero usare register.

export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  register(api) {    api.registerProvider({      /* ... */    });    api.registerTool({      /* ... */    });    api.registerChannel({      /* ... */    });  },});

OmeniaClaw carica l'oggetto entry e chiama register(api) durante l'attivazione del Plugin. Il loader ripiega ancora su activate(api) per i Plugin meno recenti, ma i Plugin inclusi e i nuovi Plugin esterni dovrebbero considerare register il contratto pubblico.

api.registrationMode indica a un Plugin perché la sua entry viene caricata:

Le entry dei Plugin che aprono socket, database, worker in background o client di lunga durata dovrebbero proteggere quei side effect con api.registrationMode === "full". I caricamenti di discovery sono memorizzati in cache separatamente dai caricamenti di attivazione e non sostituiscono il registro Gateway in esecuzione. La discovery è non attivante, non priva di import: OmeniaClaw può valutare la entry del Plugin attendibile o il modulo Plugin del canale per costruire lo snapshot. Mantieni i top level dei moduli leggeri e privi di side effect, e sposta client di rete, sottoprocessi, listener, letture di credenziali e avvio di servizi dietro percorsi full-runtime.

Metodi di registrazione comuni:

Comportamento di guardia degli hook per gli hook tipizzati del ciclo di vita:

• before_tool_call: { block: true } è terminale; gli handler con priorità inferiore vengono saltati.
• before_tool_call: { block: false } è un no-op e non cancella un blocco precedente.
• before_install: { block: true } è terminale; gli handler con priorità inferiore vengono saltati.
• before_install: { block: false } è un no-op e non cancella un blocco precedente.
• message_sending: { cancel: true } è terminale; gli handler con priorità inferiore vengono saltati.
• message_sending: { cancel: false } è un no-op e non cancella un annullamento precedente.

Il server app nativo di Codex esegue il bridge degli eventi degli strumenti nativi di Codex verso questa superficie di hook. I Plugin possono bloccare gli strumenti nativi di Codex tramite before_tool_call, osservare i risultati tramite after_tool_call e partecipare alle approvazioni Codex PermissionRequest. Il bridge non riscrive ancora gli argomenti degli strumenti nativi di Codex. Il confine esatto del supporto del runtime Codex si trova nel contratto di supporto Codex harness v1.

Per il comportamento completo degli hook tipizzati, consulta la panoramica dell'SDK.

Correlati

• Creazione di Plugin - crea il tuo Plugin
• Bundle di Plugin - compatibilità dei bundle Codex/Claude/Cursor
• Manifest del Plugin - schema del manifest
• Registrazione degli strumenti - aggiungi strumenti agente in un Plugin
• Internals dei Plugin - modello di capability e pipeline di caricamento
• ClawHub - scoperta di Plugin di terze parti