Manifest del Plugin

Questa pagina descrive il manifest nativo dei plugin OpenClaw, openclaw.plugin.json. Per i layout di bundle compatibili (Codex, Claude, Cursor), consultare Bundle di plugin.

I formati di bundle compatibili usano invece i propri file manifest:

• Bundle Codex: .codex-plugin/plugin.json
• Bundle Claude: .claude-plugin/plugin.json, oppure il layout predefinito dei componenti Claude senza manifest
• Bundle Cursor: .cursor-plugin/plugin.json

OpenClaw rileva automaticamente questi layout, ma non li convalida rispetto allo schema openclaw.plugin.json riportato di seguito. Per un bundle compatibile, OpenClaw legge i metadati del bundle, le radici delle Skills dichiarate, le radici dei comandi Claude, le impostazioni predefinite settings.json di Claude, le impostazioni predefinite LSP di Claude e i pacchetti di hook supportati, quando il layout corrisponde alle aspettative di runtime di OpenClaw.

Ogni plugin nativo OpenClaw deve includere openclaw.plugin.json nella radice del plugin. OpenClaw lo legge per convalidare la configurazione senza eseguire il codice del plugin. Un manifest mancante o non valido blocca la convalida della configurazione ed è considerato un errore del plugin.

Consultare Plugin per la guida completa al sistema di plugin e Modello delle funzionalità per il modello nativo delle funzionalità e le attuali indicazioni sulla compatibilità esterna.

Funzione di questo file

openclaw.plugin.json contiene metadati che OpenClaw legge prima di caricare il codice del plugin. Tutto ciò che contiene deve poter essere esaminato con un costo sufficientemente basso senza avviare il runtime del plugin.

Utilizzarlo per:

• identità del plugin, convalida della configurazione e suggerimenti per l'interfaccia di configurazione
• metadati di autenticazione, onboarding e configurazione (alias, abilitazione automatica, variabili d'ambiente del provider, opzioni di autenticazione)
• indicazioni di attivazione per le superfici del piano di controllo
• titolarità abbreviata delle famiglie di modelli
• istantanee statiche della titolarità delle funzionalità (contracts)
• metadati dell'esecutore QA che l'host condiviso openclaw qa può esaminare
• metadati di configurazione specifici del canale, combinati nelle superfici di catalogo e convalida

Non utilizzarlo per: registrare il comportamento del runtime, dichiarare punti di ingresso del codice o specificare metadati di installazione npm. Questi elementi devono essere definiti nel codice del plugin e in package.json.

Esempio minimo

{  "id": "voice-call",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

Esempio completo

{  "id": "openrouter",  "name": "OpenRouter",  "description": "Plugin del provider OpenRouter",  "version": "1.0.0",  "providers": ["openrouter"],  "modelSupport": {    "modelPrefixes": ["router-"]  },  "modelIdNormalization": {    "providers": {      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  },  "providerEndpoints": [    {      "endpointClass": "openrouter",      "hostSuffixes": ["openrouter.ai"]    }  ],  "providerRequest": {    "providers": {      "openrouter": {        "family": "openrouter"      }    }  },  "cliBackends": ["openrouter-cli"],  "syntheticAuthRefs": ["openrouter-cli"],  "setup": {    "providers": [      {        "id": "openrouter",        "envVars": ["OPENROUTER_API_KEY"]      }    ]  },  "providerAuthAliases": {    "openrouter-coding": "openrouter"  },  "channelEnvVars": {    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "Chiave API OpenRouter",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "Chiave API OpenRouter",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "Chiave API",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

Riferimento dei campi di primo livello

riferimento al catalogo

catalog fornisce indicazioni di visualizzazione facoltative ai browser dei plugin. Gli host possono ignorare queste indicazioni. Non installano né abilitano mai il plugin e non ne modificano il comportamento in fase di esecuzione o il livello di attendibilità.

{  "catalog": {    "featured": true,    "order": 10  }}

riferimento ai metadati dei provider di generazione

I campi dei metadati dei provider di generazione descrivono segnali di autenticazione statici per i provider dichiarati nell'elenco contracts.*GenerationProviders corrispondente. OpenClaw legge questi campi prima del caricamento del runtime del provider, affinché gli strumenti principali possano determinare se un provider di generazione è disponibile senza importare ogni plugin del provider.

Usare questi campi solo per informazioni dichiarative e poco onerose da valutare. Il trasporto, le trasformazioni delle richieste, l'aggiornamento dei token, la convalida delle credenziali e il comportamento effettivo di generazione restano nel runtime del plugin.

{  "contracts": {    "imageGenerationProviders": ["example-image"]  },  "imageGenerationProviderMetadata": {    "example-image": {      "aliases": ["example-image-oauth"],      "authProviders": ["example-image"],      "configSignals": [        {          "rootPath": "plugins.entries.example-image.config",          "overlayPath": "image",          "mode": {            "path": "mode",            "default": "local",            "allowed": ["local"]          },          "requiredAny": ["workflow", "workflowPath"],          "required": ["promptNodeId"]        }      ],      "authSignals": [        {          "provider": "example-image"        },        {          "provider": "example-image-oauth",          "providerBaseUrl": {            "provider": "example-image",            "defaultBaseUrl": "https://api.example.com/v1",            "allowedBaseUrls": ["https://api.example.com/v1"]          }        }      ]    }  }}

Ogni voce di metadati supporta:

Ogni voce configSignals supporta:

Ogni vincolo mode supporta:

Ogni voce authSignals supporta:

Ogni vincolo providerBaseUrl supporta:

riferimento ai metadati degli strumenti

toolMetadata usa le stesse strutture configSignals e authSignals dei metadati dei provider di generazione, indicizzate in base al nome dello strumento. contracts.tools dichiara la proprietà. toolMetadata dichiara evidenze di disponibilità poco onerose da valutare, affinché OpenClaw possa evitare di importare il runtime di un plugin solo per ottenere null dalla relativa factory dello strumento.

{  "setup": {    "providers": [      {        "id": "example",        "envVars": ["EXAMPLE_API_KEY"]      }    ]  },  "contracts": {    "tools": ["example_search"]  },  "toolMetadata": {    "example_search": {      "authSignals": [        {          "provider": "example"        }      ],      "configSignals": [        {          "rootPath": "plugins.entries.example.config",          "overlayPath": "search",          "required": ["apiKey"]        }      ]    }  }}

Le voci toolMetadata accettano inoltre optional (contrassegna lo strumento come non obbligatorio per l'attivazione del plugin) e replaySafe (indica che è sicuro ripetere l'esecuzione dello strumento dopo un turno incompleto del modello), oltre ai campi condivisi configSignals/authSignals descritti sopra.

Se uno strumento non dispone di toolMetadata, OpenClaw mantiene il comportamento esistente e carica il plugin proprietario quando il contratto dello strumento corrisponde alla policy. Per gli strumenti del percorso critico la cui factory dipende dall'autenticazione o dalla configurazione, gli autori dei plugin devono dichiarare toolMetadata anziché fare in modo che il nucleo importi il runtime per interrogarlo.

riferimento a providerAuthChoices

Ogni voce providerAuthChoices descrive una scelta di onboarding o autenticazione. OpenClaw la legge prima del caricamento del runtime del provider. Gli elenchi di configurazione dei provider usano queste scelte del manifesto, le scelte di configurazione derivate dai descrittori e i metadati del catalogo di installazione senza caricare il runtime del provider.

Quando appGuidedDiscovery è true, il metodo di autenticazione del provider corrispondente deve esporre appGuidedSetup.detect e appGuidedSetup.prepare. Il rilevamento deve essere in sola lettura: nessun accesso, pull del modello, download o scrittura della configurazione. La preparazione verifica nuovamente il modello esatto selezionato e restituisce una proposta di configurazione; OpenClaw esegue un test live di tale proposta in isolamento e la applica solo dopo il successo.

Riferimento di commandAliases

Usare commandAliases quando un plugin possiede un nome di comando runtime che gli utenti potrebbero inserire per errore in plugins.allow o tentare di eseguire come comando CLI radice. OpenClaw usa questi metadati per la diagnostica senza importare il codice runtime del plugin.

{  "commandAliases": [    {      "name": "dreaming",      "kind": "runtime-slash",      "cliCommand": "memory"    }  ]}

Riferimento di activation

Usare activation quando il plugin può dichiarare con costi minimi quali eventi del piano di controllo devono includerlo in un piano di attivazione/caricamento.

Questo blocco contiene metadati per il pianificatore, non è un'API del ciclo di vita. Non registra il comportamento runtime, non sostituisce register(...) e non garantisce che il codice del plugin sia già stato eseguito. Il pianificatore dell'attivazione usa questi campi per restringere l'insieme dei plugin candidati prima di ricorrere ai metadati esistenti sulla proprietà del manifest, come providers, channels, commandAliases, setup.providers, contracts.tools e gli hook.

Preferire i metadati più specifici che descrivono già la proprietà. Usare providers, channels, commandAliases, i descrittori di configurazione o contracts quando tali campi esprimono la relazione. Usare activation per indicazioni aggiuntive destinate al pianificatore che non possono essere rappresentate da tali campi di proprietà. Usare cliBackends di primo livello per gli alias runtime della CLI, come claude-cli, my-cli o google-gemini-cli; activation.onAgentHarnesses è riservato agli ID degli harness incorporati per agenti che non dispongono già di un campo di proprietà.

Ogni plugin deve impostare activation.onStartup intenzionalmente. Impostarlo su true solo quando il plugin deve essere eseguito durante l'avvio del Gateway. Impostarlo su false quando il plugin è inattivo all'avvio e deve essere caricato solo da trigger più specifici. L'omissione di onStartup non determina più implicitamente il caricamento del plugin all'avvio; usare metadati di attivazione espliciti per l'avvio, il canale, la configurazione, l'harness dell'agente, la memoria o altri trigger di attivazione più specifici.

{  "activation": {    "onStartup": false,    "onProviders": ["openai"],    "onCommands": ["models"],    "onChannels": ["web"],    "onRoutes": ["gateway-webhook"],    "onConfigPaths": ["browser"],    "onCapabilities": ["provider", "tool"]  }}

Consumer live attuali:

• La pianificazione dell'avvio del Gateway usa activation.onStartup per l'importazione esplicita all'avvio.
• La pianificazione della CLI attivata da comandi ricorre ai valori legacy commandAliases[].cliCommand o commandAliases[].name.
• La pianificazione dell'avvio del runtime dell'agente usa activation.onAgentHarnesses per gli harness incorporati e cliBackends[] di primo livello per gli alias del runtime CLI.
• La pianificazione della configurazione o del canale attivata dal canale ricorre alla proprietà legacy channels[] quando mancano metadati espliciti di attivazione del canale.
• La pianificazione dei Plugin all'avvio usa activation.onConfigPaths per le superfici di configurazione radice non relative ai canali, come il blocco browser del Plugin browser incluso.
• La pianificazione della configurazione o del runtime attivata dal provider ricorre alla proprietà legacy providers[] e a quella di primo livello cliBackends[] quando mancano metadati espliciti di attivazione del provider.

La diagnostica del pianificatore può distinguere le indicazioni di attivazione esplicite dal fallback alla proprietà del manifest. Ad esempio, activation-command-hint indica che activation.onCommands ha trovato una corrispondenza, mentre manifest-command-alias indica che il pianificatore ha usato invece la proprietà commandAliases. Queste etichette del motivo sono destinate alla diagnostica dell'host e ai test; gli autori dei Plugin devono continuare a dichiarare i metadati che descrivono meglio la proprietà.

Riferimento di qaRunners

Usare qaRunners quando un Plugin fornisce uno o più runner di trasporto sotto la radice condivisa openclaw qa. Mantenere questi metadati leggeri e statici; il runtime del Plugin continua a gestire la registrazione effettiva della CLI tramite una superficie leggera runtime-api.ts che esporta valori qaRunnerCliRegistrations corrispondenti. Un valore facoltativo adapterFactory espone il trasporto agli scenari QA condivisi senza modificare il runner del comando registrato.

{  "qaRunners": [    {      "commandName": "matrix",      "description": "Esegue il percorso QA live di Matrix basato su Docker su un homeserver usa e getta"    }  ]}

L'id adapterFactory deve corrispondere a commandName. Non esportare registrazioni per comandi assenti dal manifest.

Riferimento di setup

Usare setup quando le superfici di configurazione e onboarding necessitano di metadati leggeri di proprietà del Plugin prima del caricamento del runtime.

{  "setup": {    "providers": [      {        "id": "openai",        "authMethods": ["api-key"],        "envVars": ["OPENAI_API_KEY"],        "authEvidence": [          {            "type": "local-file-with-env",            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",            "requiresAllEnv": ["OPENAI_PROJECT"],            "credentialMarker": "openai-local-credentials",            "source": "credenziali locali openai"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

Il valore di primo livello cliBackends rimane valido e continua a descrivere i backend di inferenza della CLI. setup.cliBackends è la superficie dei descrittori specifica per la configurazione, destinata ai flussi del piano di controllo e di configurazione che devono rimanere basati esclusivamente sui metadati.

Quando presenti, setup.providers e setup.cliBackends costituiscono la superficie di ricerca preferita basata innanzitutto sui descrittori per il rilevamento della configurazione. Se il descrittore restringe soltanto il Plugin candidato e la configurazione necessita comunque di hook del runtime più completi in fase di configurazione, impostare requiresRuntime: true e mantenere setup-api come percorso di esecuzione di fallback.

OpenClaw include inoltre setup.providers[].envVars nelle ricerche generiche dell'autenticazione del provider e delle variabili d'ambiente. providerAuthEnvVars rimane supportato tramite un adattatore di compatibilità durante il periodo di deprecazione, ma i Plugin non inclusi che continuano a usarlo ricevono una diagnostica del manifest. I nuovi Plugin devono inserire i metadati delle variabili d'ambiente per configurazione e stato in setup.providers[].envVars.

Usare providerUsageAuthEnvVars quando una credenziale di fatturazione o a livello di organizzazione deve attivare resolveUsageAuth senza diventare una credenziale di inferenza. Questi nomi vengono inclusi nel blocco dei file dotenv dell'area di lavoro, nella rimozione dai processi figlio ACP, nel filtraggio dei segreti della sandbox e nell'eliminazione generale dei segreti. Il runtime del provider continua a leggere e classificare il valore all'interno di resolveUsageAuth.

OpenClaw può inoltre ricavare semplici opzioni di configurazione da setup.providers[].authMethods quando non è disponibile alcuna voce di configurazione o quando setup.requiresRuntime: false dichiara che il runtime di configurazione non è necessario. Le voci esplicite providerAuthChoices restano preferite per etichette personalizzate, flag CLI, ambito dell'onboarding e metadati dell'assistente.

Impostare requiresRuntime: false solo quando tali descrittori sono sufficienti per la superficie di configurazione. OpenClaw considera il valore esplicito false un contratto basato esclusivamente sui descrittori e non eseguirà setup-api o openclaw.setupEntry per la ricerca della configurazione. Se un Plugin basato esclusivamente sui descrittori fornisce comunque una di queste voci del runtime di configurazione, OpenClaw segnala una diagnostica aggiuntiva e continua a ignorarla. L'omissione di requiresRuntime mantiene il comportamento di fallback legacy, affinché i Plugin esistenti che hanno aggiunto descrittori senza il flag non smettano di funzionare.

Poiché la ricerca della configurazione può eseguire codice setup-api di proprietà del Plugin, i valori normalizzati setup.providers[].id e setup.cliBackends[] devono rimanere univoci tra i Plugin rilevati. In presenza di una proprietà ambigua, l'operazione non riesce in modo sicuro anziché scegliere un vincitore in base all'ordine di rilevamento.

Quando il runtime di configurazione viene eseguito, la diagnostica del registro di configurazione segnala una divergenza dei descrittori se setup-api registra un provider o un backend CLI non dichiarato dai descrittori del manifest oppure se un descrittore non dispone di una registrazione runtime corrispondente. Queste diagnostiche sono aggiuntive e non rifiutano i Plugin legacy.

Riferimento di setup.providers

authEvidence è destinato ai marcatori delle credenziali locali di proprietà del provider che possono essere verificati senza caricare il codice del runtime. Queste verifiche devono rimanere leggere e locali: nessuna chiamata di rete, nessuna lettura dal portachiavi o da gestori di segreti, nessun comando shell e nessuna interrogazione dell'API del provider.

Voci di prova supportate:

Campi di setup

Riferimento di uiHints

uiHints è una mappa dai nomi dei campi di configurazione a piccoli suggerimenti di rendering. Le chiavi possono usare punti per i campi di configurazione annidati, ma nessun segmento del percorso può essere __proto__, constructor o prototype; la configurazione rifiuta tali nomi.

{  "uiHints": {    "apiKey": {      "label": "Chiave API",      "help": "Usata per le richieste OpenRouter",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

Ogni suggerimento per un campo può includere:

Riferimento di contracts

Usare contracts solo per i metadati statici di proprietà delle funzionalità che OpenClaw può leggere senza importare il runtime del Plugin.

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"],    "trustedToolPolicies": ["workflow-budget"],    "externalAuthProviders": ["acme-ai"],    "embeddingProviders": ["openai-compatible"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "musicGenerationProviders": ["stability-audio"],    "documentExtractors": ["example-docs"],    "webContentExtractors": ["firecrawl"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "workerProviders": ["example-worker"],    "usageProviders": ["acme-ai"],    "migrationProviders": ["hermes"],    "gatewayMethodDispatch": ["authenticated-request"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

Ogni elenco è facoltativo:

contracts.embeddedExtensionFactories viene mantenuto per le factory di estensioni incluse destinate esclusivamente al server applicativo Codex. Le trasformazioni incluse dei risultati degli strumenti devono invece dichiarare contracts.agentToolResultMiddleware e registrarsi con api.registerAgentToolResultMiddleware(...). I plugin installati possono utilizzare lo stesso punto di integrazione del middleware solo quando sono abilitati esplicitamente e solo per i runtime dichiarati in contracts.agentToolResultMiddleware.

I plugin installati che richiedono il livello di policy pre-strumento considerato attendibile dall'host devono dichiarare ogni ID locale registrato in contracts.trustedToolPolicies ed essere abilitati esplicitamente. I plugin inclusi mantengono il percorso esistente delle policy attendibili, ma i plugin installati con ID di policy non dichiarati vengono rifiutati prima della registrazione. Gli ID delle policy sono circoscritti al plugin che li registra, quindi due plugin possono entrambi dichiarare e registrare workflow-budget; un singolo plugin non può registrare due volte lo stesso ID locale.

Le registrazioni api.registerTool(...) del runtime devono corrispondere a contracts.tools. Il rilevamento degli strumenti usa questo elenco per caricare solo i runtime dei plugin che possono gestire gli strumenti richiesti.

I plugin dei provider che implementano resolveExternalAuthProfiles devono dichiarare contracts.externalAuthProviders; gli hook di autenticazione esterna non dichiarati vengono ignorati.

I plugin dei provider che implementano sia resolveUsageAuth sia fetchUsageSnapshot devono dichiarare in contracts.usageProviders ogni ID di provider rilevato automaticamente. Il rilevamento dell'utilizzo legge questo contratto prima di caricare il codice del runtime, quindi verifica entrambi gli hook dopo aver caricato solo i gestori dichiarati.

I provider generali di incorporamento devono dichiarare contracts.embeddingProviders per ogni adattatore registrato con api.registerEmbeddingProvider(...). Utilizzare il contratto generale per la generazione riutilizzabile di vettori, inclusi i provider usati dalla ricerca nella memoria. contracts.memoryEmbeddingProviders è una compatibilità deprecata specifica per la memoria e viene mantenuta solo durante la migrazione dei provider esistenti al punto di integrazione generico dei provider di incorporamento.

I provider di worker devono dichiarare ogni ID api.registerWorkerProvider(...) in contracts.workerProviders. Il core rende persistente l'intento durevole prima di chiamare provision; i provider convalidano le proprie impostazioni prima dell'allocazione esterna e le chiamate ripetute con lo stesso ID operazione devono adottare lo stesso lease. Il core rende persistente anche l'istantanea delle impostazioni convalidate e la passa con leaseId a inspect({ leaseId, profile }) e destroy({ leaseId, profile }), anche dopo la modifica o la rimozione del profilo denominato. La distruzione è idempotente, l'ispezione restituisce l'unione chiusa degli stati active / destroyed / unknown e il materiale della chiave privata SSH viene referenziato solo tramite SecretRef. Gli endpoint SSH sottoposti a provisioning devono includere anche un valore pubblico hostKey proveniente dall'output attendibile del provisioning, esattamente nel formato algorithm base64, senza nome host né commento, affinché il core possa fissare l'host prima della connessione. I provider che generano riferimenti dinamici alle identità possono implementare l'autorevole resolveSshIdentity({ leaseId, profile, keyRef }); i provider che ne sono privi usano il risolutore generico dei segreti del core. Un unknown autorevole rende orfano un record locale attivo; dopo una richiesta di distruzione persistente, ne conferma la dismissione.

contracts.gatewayMethodDispatch attualmente accetta "authenticated-request". È un controllo di correttezza dell'API per le route HTTP native dei plugin che inoltrano intenzionalmente i metodi del piano di controllo del Gateway all'interno del processo, non una sandbox contro plugin nativi malevoli. Utilizzarlo solo per superfici incluse o dell'operatore sottoposte a verifica rigorosa che richiedono già l'autenticazione HTTP del Gateway. Una route autorizzata rimane raggiungibile mentre l'ammissione del lavoro radice del Gateway è chiusa solo quando dichiara anche auth: "gateway" e il valore gatewayRuntimeScopeSurface: "trusted-operator" specifico della route; le normali route correlate dello stesso plugin rimangono dietro il confine di ammissione. In questo modo, lo stato di sospensione e la ripresa restano raggiungibili senza concedere all'intero plugin un'esclusione dall'ammissione. Mantenere limitate l'analisi e la definizione della risposta al di fuori dell'inoltro; il lavoro sostanziale o con effetti di modifica deve passare attraverso l'inoltro dei metodi del Gateway, che gestisce l'ammissione e l'applicazione dell'ambito.

Riferimento di configContracts

Utilizzare configContracts per il comportamento di configurazione gestito dal manifest che gli helper generici del core richiedono senza importare il runtime del plugin: rilevamento dei flag pericolosi, destinazioni di migrazione SecretRef e limitazione dei percorsi di configurazione legacy.

{  "configContracts": {    "compatibilityMigrationPaths": ["legacyProvider"],    "compatibilityRuntimePaths": ["legacyProvider.webhook"],    "dangerousFlags": [      {        "path": "accounts.*.allowUnverifiedSenders",        "equals": true      }    ],    "secretInputs": {      "bundledDefaultEnabled": false,      "paths": [        {          "path": "apiKey",          "expected": "string"        }      ]    }  }}

Ogni voce dangerousFlags supporta:

secretInputs supporta:

Riferimento di mediaUnderstandingProviderMetadata

Utilizzare mediaUnderstandingProviderMetadata quando un provider per la comprensione dei contenuti multimediali dispone di modelli predefiniti, priorità di fallback per l'autenticazione automatica o supporto nativo dei documenti necessari agli helper generici del core prima del caricamento del runtime. Le chiavi devono essere dichiarate anche in contracts.mediaUnderstandingProviders.

{  "contracts": {    "mediaUnderstandingProviders": ["example"]  },  "mediaUnderstandingProviderMetadata": {    "example": {      "capabilities": ["image", "audio"],      "defaultModels": {        "image": "example-vision-latest",        "audio": "example-transcribe-latest"      },      "autoPriority": {        "image": 40      },      "nativeDocumentInputs": ["pdf"],      "documentModels": {        "pdf": {          "textExtraction": "example-doc-text-latest",          "image": "example-doc-vision-latest"        }      }    }  }}

Ogni voce del provider può includere:

Riferimento di channelConfigs

Utilizzare channelConfigs quando un plugin di canale necessita di metadati di configurazione leggeri prima del caricamento del runtime. Il rilevamento in sola lettura della configurazione e dello stato del canale può utilizzare direttamente questi metadati per i canali esterni configurati quando non è disponibile alcuna voce di configurazione o quando setup.requiresRuntime: false dichiara che il runtime di configurazione non è necessario.

channelConfigs rappresenta i metadati del manifesto del plugin, non una nuova sezione di configurazione utente di primo livello. Gli utenti continuano a configurare le istanze dei canali in channels.<channel-id>. OpenClaw legge i metadati del manifesto per determinare quale plugin è proprietario del canale configurato prima dell'esecuzione del codice runtime del plugin.

Per un plugin di canale, configSchema e channelConfigs descrivono percorsi diversi:

• configSchema convalida plugins.entries.<plugin-id>.config
• channelConfigs.<channel-id>.schema convalida channels.<channel-id>

I plugin non inclusi che dichiarano channels[] devono dichiarare anche le voci channelConfigs corrispondenti. Senza di esse, OpenClaw può comunque caricare il plugin, ma lo schema di configurazione del percorso a freddo, la configurazione e le superfici della Control UI non possono conoscere la struttura delle opzioni di proprietà del canale finché non viene eseguito il runtime del plugin.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled e nativeSkillsAutoEnabled possono dichiarare valori predefiniti statici auto per i controlli della configurazione dei comandi eseguiti prima del caricamento del runtime del canale. I canali inclusi possono inoltre pubblicare gli stessi valori predefiniti tramite package.json#openclaw.channel.commands, insieme agli altri metadati del catalogo dei canali di proprietà del pacchetto.

{  "channelConfigs": {    "matrix": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "homeserverUrl": { "type": "string" }        }      },      "uiHints": {        "homeserverUrl": {          "label": "URL dell'homeserver",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "Connessione all'homeserver Matrix",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

Ogni voce del canale può includere:

Sostituzione di un altro plugin di canale

Utilizzare preferOver quando il proprio plugin è il proprietario preferito di un ID canale che può essere fornito anche da un altro plugin. I casi comuni includono un ID plugin rinominato, un plugin autonomo che sostituisce un plugin incluso o un fork mantenuto che conserva lo stesso ID canale per la compatibilità della configurazione.

{  "id": "acme-chat",  "channels": ["chat"],  "channelConfigs": {    "chat": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "webhookUrl": { "type": "string" }        }      },      "preferOver": ["chat"]    }  }}

Quando channels.chat è configurato, OpenClaw considera sia l'ID canale sia l'ID del plugin preferito. Se il plugin con priorità inferiore è stato selezionato solo perché incluso o abilitato per impostazione predefinita, OpenClaw lo disabilita nella configurazione runtime effettiva, in modo che un solo plugin sia proprietario del canale e dei relativi strumenti. La selezione esplicita dell'utente prevale comunque: se l'utente abilita esplicitamente entrambi i plugin (tramite plugins.allow o una configurazione plugins.entries sostanziale), OpenClaw conserva tale scelta e segnala la diagnostica relativa alla duplicazione di canali e strumenti anziché modificare silenziosamente l'insieme di plugin richiesto.

Limitare preferOver agli ID di plugin che possono realmente fornire lo stesso canale. Non è un campo di priorità generale e non rinomina le chiavi della configurazione utente.

Riferimento di modelSupport

Utilizzare modelSupport quando OpenClaw deve dedurre il plugin del provider da ID modello abbreviati come gpt-5.6-sol o claude-sonnet-4.6 prima del caricamento del runtime del plugin.

{  "modelSupport": {    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],    "modelPatterns": ["^computer-use-preview"]  }}

OpenClaw applica questa precedenza:

• i riferimenti provider/model espliciti utilizzano i metadati del manifesto providers proprietario
• modelPatterns prevalgono su modelPrefixes
• se un plugin non incluso e uno incluso corrispondono entrambi, prevale il plugin non incluso
• l'ambiguità residua viene ignorata finché l'utente o la configurazione non specifica un provider

Campi:

Le voci modelPatterns vengono compilate tramite compileSafeRegex, che rifiuta i modelli contenenti ripetizioni annidate (ad esempio (a+)+$). I modelli che non superano il controllo di sicurezza vengono ignorati silenziosamente, analogamente alle regex sintatticamente non valide. Mantenere i modelli semplici ed evitare quantificatori annidati.

Riferimento di modelCatalog

Utilizzare modelCatalog quando OpenClaw deve conoscere i metadati dei modelli del provider prima di caricare il runtime del plugin. Questa è la fonte di proprietà del manifesto per le righe fisse del catalogo, gli alias dei provider, le regole di soppressione e la modalità di rilevamento. L'aggiornamento durante il runtime rimane responsabilità del codice runtime del provider, ma il manifesto indica al core quando il runtime è necessario.

{  "providers": ["openai"],  "modelCatalog": {    "providers": {      "openai": {        "baseUrl": "https://api.openai.com/v1",        "api": "openai-responses",        "models": [          {            "id": "gpt-5.4",            "name": "GPT-5.4",            "input": ["text", "image"],            "reasoning": true,            "contextWindow": 256000,            "maxTokens": 128000,            "cost": {              "input": 1.25,              "output": 10,              "cacheRead": 0.125            },            "status": "available",            "tags": ["default"]          }        ]      }    },    "aliases": {      "azure-openai-responses": {        "provider": "openai",        "api": "azure-openai-responses"      }    },    "suppressions": [      {        "provider": "azure-openai-responses",        "model": "gpt-5.3-codex-spark",        "reason": "non disponibile in Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

Campi di primo livello:

aliases partecipa alla ricerca della proprietà del provider per la pianificazione del catalogo dei modelli. Le destinazioni degli alias devono essere provider di livello superiore di proprietà dello stesso plugin. Quando un elenco filtrato per provider utilizza un alias, OpenClaw può leggere il manifest proprietario e applicare le sostituzioni dell'API e dell'URL di base dell'alias senza caricare il runtime del provider. Gli alias non espandono gli elenchi di catalogo non filtrati; gli elenchi generali emettono solo le righe del provider canonico proprietario.

suppressions sostituisce il precedente hook suppressBuiltInModel del runtime del provider. Le voci di soppressione vengono rispettate solo quando il provider è di proprietà del plugin o è dichiarato come chiave modelCatalog.aliases che punta a un provider di proprietà. Gli hook di soppressione del runtime non vengono più chiamati durante la risoluzione del modello.

Campi del provider:

Campi del modello:

Campi di soppressione:

Non inserire dati disponibili solo durante il runtime in modelCatalog. Utilizzare static solo quando le righe del manifest sono sufficientemente complete da consentire agli elenchi filtrati per provider e alle interfacce dei selettori di ignorare il rilevamento del registro o del runtime. Utilizzare refreshable quando le righe del manifest costituiscono elementi iniziali o integrativi utili per gli elenchi, ma un aggiornamento o la cache possono aggiungere altre righe in seguito; le righe aggiornabili non sono autorevoli da sole. Utilizzare runtime quando OpenClaw deve caricare il runtime del provider per conoscere l'elenco.

Riferimento di modelIdNormalization

Utilizzare modelIdNormalization per la normalizzazione economica degli ID dei modelli di proprietà del provider che deve avvenire prima del caricamento del runtime del provider. In questo modo, alias come i nomi brevi dei modelli, gli ID legacy locali al provider e le regole dei prefissi proxy rimangono nel manifest del plugin proprietario anziché nelle tabelle principali di selezione dei modelli.

{  "providers": ["anthropic", "openrouter"],  "modelIdNormalization": {    "providers": {      "anthropic": {        "aliases": {          "sonnet-4.6": "claude-sonnet-4-6"        }      },      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  }}

Campi del provider:

Riferimento di providerEndpoints

Utilizzare providerEndpoints per la classificazione degli endpoint che i criteri generici delle richieste devono conoscere prima del caricamento del runtime del provider. Il core mantiene la proprietà del significato di ogni endpointClass; i manifest dei plugin mantengono la proprietà dei metadati dell'host e dell'URL di base.

I plugin dei provider ufficialmente esternalizzati sono esclusi dalla distribuzione del core, pertanto i relativi manifest non sono visibili finché non vengono installati. Anche i relativi providerEndpoints devono essere replicati in scripts/lib/official-external-provider-catalog.json, affinché la classificazione degli endpoint continui a funzionare senza il plugin; un test del contratto verifica la replica.

Campi dell'endpoint:

Riferimento providerRequest

Usare providerRequest per metadati leggeri sulla compatibilità delle richieste, necessari ai criteri generici delle richieste senza caricare il runtime del provider. Mantenere la riscrittura del payload specifica del comportamento negli hook del runtime del provider o negli helper condivisi della famiglia di provider.

{  "providerRequest": {    "providers": {      "vllm": {        "family": "vllm",        "openAICompletions": {          "supportsStreamingUsage": true        }      }    }  }}

Campi del provider:

Riferimento secretProviderIntegrations

Usare secretProviderIntegrations quando un plugin può pubblicare una preimpostazione riutilizzabile del provider exec SecretRef. OpenClaw legge questi metadati prima del caricamento del runtime del plugin, memorizza la proprietà del plugin in secrets.providers.<alias>.pluginIntegration e lascia l'effettiva risoluzione dei segreti al runtime SecretRef. Le preimpostazioni sono esposte solo per i plugin inclusi e per i plugin installati rilevati nelle directory radice gestite di installazione dei plugin, ad esempio le installazioni da git e ClawHub.

{  "secretProviderIntegrations": {    "secret-store": {      "providerAlias": "team-secrets",      "displayName": "Team secrets",      "source": "exec",      "command": "${node}",      "args": ["./bin/resolve-secrets.mjs"]    }  }}

La chiave della mappa è l'ID dell'integrazione. Se providerAlias viene omesso, OpenClaw usa l'ID dell'integrazione come alias del provider SecretRef. Gli alias dei provider devono rispettare il normale schema degli alias dei provider SecretRef, ad esempio team-secrets o onepassword-work.

Quando un operatore seleziona la preimpostazione, OpenClaw scrive un riferimento al provider simile al seguente:

{  "secrets": {    "providers": {      "team-secrets": {        "source": "exec",        "pluginIntegration": {          "pluginId": "acme-secrets",          "integrationId": "secret-store"        }      }    }  }}

All'avvio o al ricaricamento, OpenClaw risolve tale provider caricando i metadati correnti del manifest del plugin, verificando che il plugin proprietario sia installato e attivo e materializzando il comando exec dal manifest. La disabilitazione o la rimozione del plugin revoca il provider per i SecretRef attivi. Gli operatori che desiderano una configurazione exec autonoma possono comunque scrivere direttamente provider manuali command/args.

Attualmente sono supportate solo le preimpostazioni source: "exec". command deve essere ${node} e args[0] deve essere uno script di risoluzione ./ relativo alla directory radice del plugin. OpenClaw lo materializza all'avvio o al ricaricamento usando l'eseguibile Node corrente e il percorso assoluto dello script nel plugin. Le opzioni di Node quali --require, --import, --loader, --env-file, --eval e --print non fanno parte del contratto delle preimpostazioni del manifest. Gli operatori che necessitano di comandi non Node possono configurare direttamente provider exec manuali autonomi.

OpenClaw ricava trustedDirs per le preimpostazioni del manifest dalla directory radice del plugin e, per le preimpostazioni ${node}, dalla directory dell'eseguibile Node corrente. Gli trustedDirs definiti nel manifest vengono ignorati. Le altre opzioni del provider exec, quali timeoutMs, noOutputTimeoutMs, maxOutputBytes, jsonOnly, env, passEnv e allowInsecurePath, vengono trasmesse alla normale configurazione del provider exec SecretRef.

Riferimento modelPricing

Usare modelPricing quando un provider necessita del comportamento dei prezzi del piano di controllo prima del caricamento del runtime. La cache dei prezzi del Gateway legge questi metadati senza importare il codice del runtime del provider.

{  "providers": ["ollama", "openrouter"],  "modelPricing": {    "providers": {      "ollama": {        "external": false      },      "openrouter": {        "openRouter": {          "passthroughProviderModel": true        },        "liteLLM": false      }    }  }}

Campi del provider:

Campi dell'origine:

Indice dei provider OpenClaw

L'Indice dei provider OpenClaw è costituito da metadati di anteprima di proprietà di OpenClaw per provider i cui plugin potrebbero non essere ancora installati. Non fa parte del manifest di un plugin. I manifest dei plugin restano la fonte autorevole per i plugin installati. L'Indice dei provider è il contratto di fallback interno che verrà utilizzato dalle future interfacce per provider installabili e dalla selezione dei modelli prima dell'installazione quando un plugin del provider non è installato.

Ordine di autorità del catalogo:

1. Configurazione utente.
2. Manifest del plugin installato modelCatalog.
3. Cache del catalogo dei modelli da aggiornamento esplicito.
4. Righe di anteprima dell'Indice dei provider OpenClaw.

L'Indice dei provider non deve contenere segreti, stato di abilitazione, hook di runtime o dati dei modelli specifici di account attivi. I relativi cataloghi di anteprima usano la stessa struttura delle righe del provider modelCatalog dei manifest dei plugin, ma devono rimanere limitati a metadati di visualizzazione stabili, a meno che campi dell'adattatore di runtime quali api, baseUrl, prezzi o flag di compatibilità non vengano intenzionalmente mantenuti allineati con il manifest del plugin installato. I provider con rilevamento /models attivo devono scrivere le righe aggiornate tramite il percorso esplicito della cache del catalogo dei modelli, anziché fare in modo che la normale elencazione o l'onboarding chiamino le API dei provider.

Le voci dell'Indice dei provider possono anche includere metadati dei plugin installabili per provider il cui plugin è stato spostato fuori dal core o non è ancora installato per altri motivi. Questi metadati rispecchiano lo schema del catalogo dei canali: il nome del pacchetto, la specifica di installazione npm, l'integrità prevista e semplici etichette per le opzioni di autenticazione sono sufficienti per mostrare un'opzione di configurazione installabile. Una volta installato il plugin, il relativo manifest prevale e la voce dell'Indice dei provider viene ignorata per quel provider.

openclaw doctor --fix migra un insieme piccolo e chiuso di chiavi di funzionalità legacy di primo livello del manifest in contracts.*: speechProviders, mediaUnderstandingProviders, imageGenerationProviders e tools. Nessuna di queste, né qualsiasi altro elenco di funzionalità, viene più letta come campo di primo livello del manifest; il normale caricamento del manifest le riconosce solo sotto contracts.

Manifest rispetto a package.json

I due file svolgono funzioni diverse:

In caso di dubbi su dove collocare un elemento di metadati, applicare questa regola:

• se OpenClaw deve conoscerlo prima di caricare il codice del plugin, inserirlo in openclaw.plugin.json
• se riguarda la creazione del pacchetto, i file di ingresso o il comportamento dell'installazione npm, inserirlo in package.json

Campi di package.json che influiscono sul rilevamento

Alcuni metadati dei plugin precedenti al runtime risiedono intenzionalmente in package.json, nel blocco openclaw, anziché in openclaw.plugin.json. openclaw.bundle e openclaw.bundle.json non sono contratti dei plugin OpenClaw; i plugin nativi devono usare openclaw.plugin.json insieme ai campi package.json#openclaw supportati riportati di seguito.

Esempi importanti:

I metadati del manifest determinano quali opzioni di provider, canale e configurazione vengono visualizzate nell'onboarding prima del caricamento del runtime. package.json#openclaw.install indica all'onboarding come recuperare o abilitare il plugin quando viene selezionata una di queste opzioni. Non spostare le indicazioni di installazione in openclaw.plugin.json.

openclaw.install.minHostVersion viene applicato durante l'installazione e il caricamento del registro dei manifest per le origini dei plugin non inclusi. I valori non validi vengono rifiutati; i valori più recenti ma validi fanno sì che i plugin esterni vengano ignorati sugli host meno recenti. Si presume che i plugin di origine inclusi abbiano la stessa versione del checkout dell'host.

openclaw.install.requiredPlatformPackages è destinato ai pacchetti npm che espongono i binari nativi richiesti tramite alias facoltativi specifici per piattaforma. Elencare il nome semplice del pacchetto npm per ogni alias di piattaforma supportato. Durante l'installazione npm, OpenClaw verifica esclusivamente l'alias dichiarato i cui vincoli nel lockfile corrispondono all'host corrente. Se npm segnala l'esito positivo ma omette tale alias, OpenClaw riprova una volta con una cache nuova e annulla l'installazione se l'alias risulta ancora mancante.

openclaw.compat.pluginApi viene applicato durante l'installazione dei pacchetti per le origini dei plugin non inclusi. Utilizzarlo per indicare il limite inferiore dell'API SDK/runtime dei plugin OpenClaw rispetto al quale è stato compilato il pacchetto. Può essere più restrittivo di minHostVersion quando un pacchetto plugin richiede un'API più recente, ma mantiene un'indicazione di installazione inferiore per altri flussi. Per impostazione predefinita, la sincronizzazione delle versioni ufficiali di OpenClaw aggiorna i limiti inferiori esistenti delle API dei plugin ufficiali alla versione di OpenClaw, ma le versioni relative esclusivamente ai plugin possono mantenere un limite inferiore quando il pacchetto supporta intenzionalmente host meno recenti. Non utilizzare soltanto la versione del pacchetto come contratto di compatibilità. peerDependencies.openclaw rimane un metadato del pacchetto npm; OpenClaw utilizza il contratto openclaw.compat.pluginApi per le decisioni sulla compatibilità dell'installazione.

I metadati ufficiali per l'installazione su richiesta devono utilizzare clawhubSpec quando il plugin è pubblicato su ClawHub; l'onboarding considera questa l'origine remota preferita e registra i dati dell'artefatto ClawHub dopo l'installazione. npmSpec rimane il ripiego di compatibilità per i pacchetti che non sono ancora passati a ClawHub.

Il blocco a una versione npm esatta è già definito in npmSpec, ad esempio "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". Le voci ufficiali del catalogo esterno devono associare le specifiche esatte a expectedIntegrity, affinché i flussi di aggiornamento si interrompano in modo sicuro se l'artefatto npm recuperato non corrisponde più alla versione bloccata. Per compatibilità, l'onboarding interattivo continua a proporre specifiche npm provenienti da registri attendibili, inclusi nomi semplici di pacchetti e dist-tag. La diagnostica del catalogo è in grado di distinguere origini esatte, mobili, bloccate tramite integrità, prive di integrità, con nome del pacchetto non corrispondente e con scelta predefinita non valida. Inoltre, genera un avviso quando expectedIntegrity è presente ma non esiste un'origine npm valida a cui possa essere associato. Quando expectedIntegrity è presente, i flussi di installazione e aggiornamento lo applicano; quando viene omesso, la risoluzione del registro viene registrata senza un vincolo di integrità.

I plugin dei canali devono fornire openclaw.setupEntry quando le scansioni dello stato, dell'elenco dei canali o dei SecretRef devono identificare gli account configurati senza caricare l'intero runtime. L'entrypoint di configurazione deve esporre i metadati del canale insieme agli adattatori di configurazione, stato e segreti sicuri per la configurazione; mantenere i client di rete, i listener del Gateway e i runtime di trasporto nell'entrypoint principale dell'estensione.

I campi degli entrypoint del runtime non sostituiscono i controlli dei limiti del pacchetto per i campi degli entrypoint del codice sorgente. Ad esempio, openclaw.runtimeExtensions non può rendere caricabile un percorso openclaw.extensions che fuoriesce dal pacchetto.

openclaw.install.allowInvalidConfigRecovery è intenzionalmente circoscritto. Non rende installabili configurazioni non valide arbitrarie. Attualmente consente ai flussi di installazione di recuperare soltanto da specifici errori obsoleti di aggiornamento dei plugin inclusi, ad esempio un percorso mancante di un plugin incluso o una voce channels.<id> obsoleta per lo stesso plugin incluso. Gli errori di configurazione non correlati continuano a bloccare l'installazione e indirizzano gli operatori a openclaw doctor --fix.

openclaw.channel.persistedAuthState è un metadato del pacchetto per un piccolo modulo di controllo:

{  "openclaw": {    "channel": {      "id": "whatsapp",      "persistedAuthState": {        "specifier": "./auth-presence",        "exportName": "hasAnyWhatsAppAuth"      }    }  }}

Utilizzarlo quando i flussi di configurazione, Doctor, stato o verifica della presenza in sola lettura richiedono un controllo di autenticazione sì/no poco oneroso prima del caricamento del plugin completo del canale. Lo stato di autenticazione persistente non corrisponde allo stato configurato del canale: non utilizzare questi metadati per abilitare automaticamente i plugin, riparare le dipendenze del runtime o decidere se caricare il runtime di un canale. L'esportazione di destinazione deve essere una piccola funzione che legge esclusivamente lo stato persistente; non instradarla tramite il barrel completo del runtime del canale.

openclaw.channel.configuredState supporta controlli poco onerosi della configurazione. Preferire metadati dichiarativi delle variabili d'ambiente quando queste sono sufficienti:

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "env": {          "allOf": ["TELEGRAM_BOT_TOKEN"]        }      }    }  }}

Utilizzare env.allOf quando sono richieste tutte le variabili elencate e env.anyOf quando è sufficiente una qualsiasi variabile non vuota. Se un piccolo controllo non relativo al runtime richiede più dei metadati delle variabili d'ambiente, utilizzare specifier insieme a exportName, come mostrato per persistedAuthState; quando env è presente, OpenClaw lo utilizza senza caricare tale modulo. Se il controllo richiede la risoluzione completa della configurazione o il runtime effettivo del canale, mantenere tale logica nell'hook config.hasConfiguredState del plugin.

Precedenza del rilevamento (ID dei plugin duplicati)

OpenClaw rileva i plugin da tre radici, controllate in questo ordine: i plugin inclusi distribuiti con OpenClaw, la radice di installazione globale (~/.openclaw/extensions) e la radice dello spazio di lavoro corrente (<workspace>/.openclaw/extensions), oltre alle eventuali voci esplicite plugins.load.paths.

Se due elementi rilevati condividono lo stesso id, viene mantenuto soltanto il manifest con la precedenza più alta; i duplicati con precedenza inferiore vengono eliminati anziché essere caricati insieme a esso. Precedenza, dalla più alta alla più bassa:

1. Selezionato dalla configurazione — un percorso bloccato esplicitamente in plugins.entries.<id>
2. Installazione globale corrispondente a un record di installazione monitorato — un plugin installato tramite openclaw plugin install/openclaw plugin update che il monitoraggio delle installazioni di OpenClaw riconosce per lo stesso ID, anche quando l'ID appartiene anche a un plugin incluso
3. Incluso — plugin distribuiti con OpenClaw
4. Spazio di lavoro — plugin rilevati relativamente allo spazio di lavoro corrente
5. Qualsiasi altro candidato rilevato

Implicazioni:

• Una copia derivata o obsoleta di un plugin incluso, presente senza essere monitorata nello spazio di lavoro o nella radice globale, non sostituirà la compilazione inclusa.
• Per sostituire un plugin incluso, eseguire openclaw plugin install per tale ID affinché l'installazione globale monitorata abbia precedenza sulla copia inclusa, oppure bloccare un percorso specifico tramite plugins.entries.<id> affinché prevalga grazie alla precedenza della selezione tramite configurazione.
• Le eliminazioni dei duplicati vengono registrate, affinché Doctor e la diagnostica di avvio possano indicare la copia scartata.
• Le sostituzioni dei duplicati selezionate dalla configurazione vengono descritte nella diagnostica come sostituzioni esplicite, ma generano comunque un avviso affinché le derivazioni obsolete e le sostituzioni accidentali rimangano visibili.

Requisiti dello schema JSON

• Ogni plugin deve includere un JSON Schema, anche se non accetta alcuna configurazione.
• È accettabile uno schema vuoto (ad esempio, { "type": "object", "additionalProperties": false }).
• Gli schemi vengono convalidati durante la lettura/scrittura della configurazione, non in fase di runtime.
• Quando si estende o si crea un fork di un plugin incluso aggiungendo nuove chiavi di configurazione, aggiornare contemporaneamente anche openclaw.plugin.json configSchema del plugin. Gli schemi dei plugin inclusi sono rigorosi, quindi l'aggiunta di plugins.entries.<id>.config.myNewKey nella configurazione utente senza aggiungere myNewKey a configSchema.properties verrà rifiutata prima del caricamento del runtime del plugin.

Esempio di estensione dello schema:

{  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "myNewKey": {        "type": "string"      }    }  }}

Comportamento della convalida

• Le chiavi channels.* sconosciute sono errori, a meno che l'ID del canale non sia dichiarato dal manifesto di un plugin. Se lo stesso ID compare anche in plugins.allow, plugins.entries o plugins.installs (un plugin a cui si fa riferimento ma che al momento non è rilevabile), OpenClaw lo declassa invece a avviso.
• plugins.entries.<id>, plugins.allow e plugins.deny che fanno riferimento a ID di plugin sconosciuti generano avvisi ("voce di configurazione obsoleta ignorata"), non errori, in modo che gli aggiornamenti e i plugin rimossi o rinominati non impediscano l'avvio del Gateway.
• plugins.slots.memory che fa riferimento a un ID di plugin sconosciuto genera un errore, fatta eccezione per il noto plugin esterno ufficiale memory-lancedb, che genera invece un avviso.
• Se un plugin è installato ma ha un manifesto o uno schema danneggiato o mancante, la convalida non riesce e Doctor segnala l'errore del plugin.
• Se esiste una configurazione del plugin ma il plugin è disabilitato, la configurazione viene mantenuta e viene mostrato un avviso in Doctor e nei log.

Consultare il riferimento della configurazione per lo schema plugins.* completo.

Note

• Il manifesto è obbligatorio per i plugin nativi di OpenClaw, inclusi i caricamenti dal file system locale. Il runtime carica comunque separatamente il modulo del plugin; il manifesto serve solo per il rilevamento e la convalida.
• I manifesti nativi vengono analizzati con JSON5, quindi sono accettati commenti, virgole finali e chiavi senza virgolette, purché il valore finale sia comunque un oggetto.
• Il caricatore del manifesto legge solo i campi documentati del manifesto. Evitare chiavi personalizzate di primo livello.
• channels, providers, cliBackends e skills possono essere omessi quando un plugin non ne ha bisogno.
• providerCatalogEntry deve rimanere leggero e non dovrebbe importare ampie porzioni di codice del runtime; utilizzarlo per i metadati statici del catalogo dei provider o per descrittori di rilevamento circoscritti, non per l'esecuzione al momento della richiesta.
• I tipi di plugin esclusivi vengono selezionati tramite plugins.slots.*: kind: "memory" mediante plugins.slots.memory (valore predefinito memory-core), kind: "context-engine" mediante plugins.slots.contextEngine (valore predefinito legacy).
• Dichiarare il tipo di plugin esclusivo in questo manifesto. OpenClawPluginDefinition.kind della voce di runtime è deprecato e rimane solo come meccanismo di compatibilità per i plugin meno recenti.
• I metadati delle variabili di ambiente (setup.providers[].envVars, providerAuthEnvVars deprecato e channelEnvVars) sono esclusivamente dichiarativi. Stato, controllo, convalida della consegna Cron e altre superfici di sola lettura applicano comunque i criteri di attendibilità del plugin e di attivazione effettiva prima di considerare configurata una variabile di ambiente.
• Per i metadati della procedura guidata di runtime che richiedono il codice del provider, consultare gli hook di runtime del provider.
• Se il plugin dipende da moduli nativi, documentare i passaggi di compilazione ed eventuali requisiti relativi all'elenco di elementi consentiti del gestore di pacchetti (ad esempio, pnpm allow-build-scripts + pnpm rebuild <package>).

Contenuti correlati