Manifesto del Plugin

Questa pagina riguarda solo il manifesto Plugin nativo di OpenClaw.

Per i layout di pacchetti compatibili, consulta Pacchetti Plugin.

I formati di pacchetto compatibili usano file manifesto diversi:

• Pacchetto Codex: .codex-plugin/plugin.json
• Pacchetto Claude: .claude-plugin/plugin.json o il layout predefinito dei componenti Claude senza manifesto
• Pacchetto Cursor: .cursor-plugin/plugin.json

OpenClaw rileva automaticamente anche questi layout di pacchetti, ma non vengono validati rispetto allo schema openclaw.plugin.json descritto qui.

Per i pacchetti compatibili, OpenClaw attualmente legge i metadati del pacchetto più le radici delle skill dichiarate, le radici dei comandi Claude, i valori predefiniti di settings.json del pacchetto Claude, i valori predefiniti LSP del pacchetto Claude e i pacchetti di hook supportati quando il layout corrisponde alle aspettative del runtime di OpenClaw.

Ogni Plugin nativo di OpenClaw deve includere un file openclaw.plugin.json nella radice del plugin. OpenClaw usa questo manifesto per validare la configurazione senza eseguire il codice del plugin. I manifesti mancanti o non validi vengono trattati come errori del plugin e bloccano la validazione della configurazione.

Consulta la guida completa del sistema di plugin: Plugin. Per il modello di capacità nativo e le indicazioni attuali sulla compatibilità esterna: Modello di capacità.

Cosa fa questo file

openclaw.plugin.json è il metadato che OpenClaw legge prima di caricare il tuo codice del plugin. Tutto ciò che segue deve essere abbastanza leggero da ispezionare senza avviare il runtime del plugin.

Usalo per:

• identità del plugin, validazione della configurazione e suggerimenti per l'interfaccia di configurazione
• metadati di autenticazione, onboarding e configurazione iniziale (alias, abilitazione automatica, variabili di ambiente del provider, scelte di autenticazione)
• suggerimenti di attivazione per le superfici del piano di controllo
• proprietà abbreviata delle famiglie di modelli
• snapshot statici della proprietà delle capacità (contracts)
• metadati del runner QA che l'host condiviso openclaw qa può ispezionare
• metadati di configurazione specifici del canale uniti nelle superfici di catalogo e validazione

Non usarlo per: registrare comportamenti di runtime, dichiarare entrypoint del codice o metadati di installazione npm. Questi appartengono al codice del plugin e a package.json.

Esempio minimo

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

Esempio completo

{  "id": "openrouter",  "name": "OpenRouter",  "description": "OpenRouter provider plugin",  "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"],  "providerAuthEnvVars": {    "openrouter": ["OPENROUTER_API_KEY"]  },  "providerAuthAliases": {    "openrouter-coding": "openrouter"  },  "channelEnvVars": {    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "OpenRouter API key",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "OpenRouter API key",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "API key",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

Riferimento dei campi di primo livello

Riferimento ai metadati del provider di generazione

I campi dei metadati del 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, così gli strumenti core possono decidere se un provider di generazione è disponibile senza importare ogni Plugin provider.

Usa questi campi solo per fatti economici e dichiarativi. Trasporto, trasformazioni delle richieste, refresh dei token, validazione delle credenziali e 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 guard mode supporta:

Ogni voce authSignals supporta:

Ogni guard providerBaseUrl supporta:

Riferimento ai metadati degli strumenti

toolMetadata usa le stesse forme configSignals e authSignals dei metadati del provider di generazione, indicizzate per nome strumento. contracts.tools dichiara la proprietà. toolMetadata dichiara prove economiche di disponibilità, così OpenClaw può evitare di importare un runtime del Plugin solo per far restituire null alla sua factory dello strumento.

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

Se uno strumento non ha toolMetadata, OpenClaw preserva il comportamento esistente e carica il Plugin proprietario quando il contratto dello strumento corrisponde alla policy. Per gli strumenti su hot-path la cui factory dipende da autenticazione/configurazione, gli autori dei Plugin devono dichiarare toolMetadata invece di fare importare al core 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 manifest, scelte di configurazione derivate dal descrittore e metadati del catalogo di installazione senza caricare il runtime del provider.

Riferimento a commandAliases

Usa commandAliases quando un Plugin possiede un nome di comando runtime che gli utenti potrebbero erroneamente inserire in plugins.allow o provare a 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

Usa activation quando il Plugin può dichiarare in modo economico quali eventi del piano di controllo dovrebbero includerlo in un piano di attivazione/caricamento.

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

Preferisci i metadati più ristretti che descrivono già la proprietà. Usa providers, channels, commandAliases, descrittori di setup o contracts quando quei campi esprimono la relazione. Usa activation per suggerimenti aggiuntivi del pianificatore che non possono essere rappresentati da quei campi di proprietà. Usa cliBackends di primo livello per alias runtime CLI come claude-cli, codex-cli o google-gemini-cli; activation.onAgentHarnesses è solo per id di harness agente incorporati che non hanno già un campo di proprietà.

Questo blocco è solo metadati. Non registra comportamento runtime e non sostituisce register(...), setupEntry o altri entrypoint runtime/Plugin. I consumer attuali lo usano come suggerimento di restringimento prima di un caricamento più ampio dei Plugin, quindi la mancanza di metadati di attivazione non di startup di solito costa solo prestazioni; non dovrebbe cambiare la correttezza finché esistono ancora fallback di proprietà del manifest.

Ogni Plugin dovrebbe impostare activation.onStartup intenzionalmente. Impostalo su true solo quando il Plugin deve essere eseguito durante l'avvio del Gateway. Impostalo su false quando il Plugin è inerte all'avvio e deve caricarsi solo da trigger più ristretti. Omettere onStartup non carica più implicitamente il Plugin all'avvio; usa metadati di attivazione espliciti per startup, canale, configurazione, agent-harness, memoria o altri trigger di attivazione più ristretti.

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

Consumer live attuali:

• La pianificazione di startup del Gateway usa activation.onStartup per l'importazione esplicita all'avvio
• la pianificazione CLI attivata da comando ricorre ai commandAliases[].cliCommand o commandAliases[].name legacy
• la pianificazione di startup agent-runtime usa activation.onAgentHarnesses per harness incorporati e cliBackends[] di primo livello per alias runtime CLI
• la pianificazione setup/canale attivata da canale ricorre alla proprietà legacy channels[] quando mancano metadati di attivazione canale espliciti
• la pianificazione Plugin di startup usa activation.onConfigPaths per superfici di configurazione radice non di canale, come il blocco browser del Plugin browser in bundle
• la pianificazione setup/runtime attivata da provider ricorre alla proprietà legacy providers[] e cliBackends[] di primo livello quando mancano metadati di attivazione provider espliciti

La diagnostica del pianificatore può distinguere i suggerimenti di attivazione espliciti dal fallback di proprietà del manifest. Per esempio, activation-command-hint significa che activation.onCommands ha trovato una corrispondenza, mentre manifest-command-alias significa che il pianificatore ha usato invece la proprietà commandAliases. Queste etichette di motivo sono per diagnostica host e test; gli autori di Plugin dovrebbero continuare a dichiarare i metadati che descrivono meglio la proprietà.

Riferimento di qaRunners

Usa qaRunners quando un Plugin contribuisce uno o più runner di trasporto sotto la radice condivisa openclaw qa. Mantieni questi metadati economici e statici; il runtime del Plugin possiede comunque la registrazione CLI effettiva tramite una superficie runtime-api.ts leggera che esporta qaRunnerCliRegistrations.

{  "qaRunners": [    {      "commandName": "matrix",      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"    }  ]}

Riferimento di setup

Usa setup quando le superfici di setup e onboarding necessitano di metadati economici 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": "openai local credentials"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

cliBackends di primo livello resta valido e continua a descrivere i backend di inferenza CLI. setup.cliBackends è la superficie descrittore specifica del setup per flussi di piano di controllo/setup che dovrebbero restare solo metadati.

Quando presenti, setup.providers e setup.cliBackends sono la superficie di ricerca descriptor-first preferita per la discovery di setup. Se il descrittore restringe solo il Plugin candidato e il setup necessita ancora di hook runtime in fase di setup più ricchi, imposta requiresRuntime: true e mantieni setup-api come percorso di esecuzione di fallback.

OpenClaw include anche setup.providers[].envVars nelle ricerche generiche di auth provider ed env-var. providerAuthEnvVars resta supportato tramite un adapter di compatibilità durante la finestra di deprecazione, ma i Plugin non in bundle che lo usano ancora ricevono una diagnostica del manifest. I nuovi Plugin dovrebbero mettere i metadati env di setup/status su setup.providers[].envVars.

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

Imposta requiresRuntime: false solo quando quei descrittori sono sufficienti per la superficie di setup. OpenClaw tratta false esplicito come contratto solo descrittore e non eseguirà setup-api o openclaw.setupEntry per la ricerca di setup. Se un Plugin solo descrittore distribuisce comunque una di quelle voci runtime di setup, OpenClaw segnala una diagnostica additiva e continua a ignorarla. L'omissione di requiresRuntime mantiene il comportamento di fallback legacy, così i Plugin esistenti che hanno aggiunto descrittori senza il flag non si rompono.

Poiché la ricerca di setup può eseguire codice setup-api di proprietà del Plugin, i valori normalizzati setup.providers[].id e setup.cliBackends[] devono restare unici tra i Plugin scoperti. La proprietà ambigua fallisce in modo chiuso invece di scegliere un vincitore dall'ordine di discovery.

Quando il runtime di setup viene eseguito, la diagnostica del registro di setup segnala deriva dei descrittori se setup-api registra un provider o backend CLI che i descrittori del manifest non dichiarano, o se un descrittore non ha una registrazione runtime corrispondente. Queste diagnostiche sono additive e non rifiutano i Plugin legacy.

Riferimento di setup.providers

authEvidence serve per marcatori di credenziali locali di proprietà del provider che possono essere verificati senza caricare codice runtime. Questi controlli devono restare economici e locali: nessuna chiamata di rete, nessuna lettura da keychain o secret manager, nessun comando shell e nessun probe API del provider.

Voci di evidenza supportate:

Campi setup

Riferimento uiHints

uiHints è una mappa dai nomi dei campi di configurazione a piccoli suggerimenti di rendering.

{  "uiHints": {    "apiKey": {      "label": "API key",      "help": "Used for OpenRouter requests",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

Ogni suggerimento di campo può includere:

Riferimento contracts

Usa contracts solo per metadati statici di proprietà delle capability che OpenClaw può leggere senza importare il runtime del plugin.

{  "contracts": {    "agentToolResultMiddleware": ["pi", "codex"],    "externalAuthProviders": ["acme-ai"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai", "openai-codex"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "migrationProviders": ["hermes"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

Ogni elenco è facoltativo:

contracts.embeddedExtensionFactories viene mantenuto per le factory di estensione in bundle solo per il server app Codex. Le trasformazioni dei risultati degli strumenti in bundle dovrebbero dichiarare contracts.agentToolResultMiddleware e registrarsi invece con api.registerAgentToolResultMiddleware(...). I plugin esterni non possono registrare middleware dei risultati degli strumenti perché il punto di integrazione può riscrivere output di strumenti ad alta fiducia prima che il modello lo veda.

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

I plugin provider che implementano resolveExternalAuthProfiles dovrebbero dichiarare contracts.externalAuthProviders. I plugin senza la dichiarazione passano ancora attraverso un fallback di compatibilità deprecato, ma quel fallback è più lento e verrà rimosso dopo la finestra di migrazione.

I provider di embedding della memoria in bundle dovrebbero dichiarare contracts.memoryEmbeddingProviders per ogni ID adattatore che espongono, inclusi adattatori integrati come local. I percorsi CLI standalone usano questo contratto del manifest per caricare solo il plugin proprietario prima che il runtime Gateway completo abbia registrato i provider.

Riferimento mediaUnderstandingProviderMetadata

Usa mediaUnderstandingProviderMetadata quando un provider di comprensione dei media ha modelli predefiniti, priorità di fallback per autenticazione automatica o supporto nativo dei documenti di cui gli helper core generici hanno bisogno 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"]    }  }}

Ogni voce del provider può includere:

Riferimento channelConfigs

Usa channelConfigs quando un plugin di canale ha bisogno di metadati di configurazione economici prima del caricamento del runtime. La scoperta setup/stato del canale in sola lettura può usare questi metadati direttamente per canali esterni configurati quando non è disponibile alcuna voce setup, o quando setup.requiresRuntime: false dichiara che il runtime setup non è necessario.

channelConfigs è metadato del manifest del plugin, non una nuova sezione di configurazione utente di primo livello. Gli utenti configurano ancora le istanze dei canali sotto channels.<channel-id>. OpenClaw legge i metadati del manifest per decidere quale plugin possiede quel canale configurato prima che il codice runtime del plugin venga eseguito.

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 in bundle che dichiarano channels[] dovrebbero dichiarare anche voci channelConfigs corrispondenti. Senza di esse, OpenClaw può ancora caricare il plugin, ma lo schema di configurazione del percorso a freddo, setup e le superfici Control UI non possono conoscere la forma delle opzioni di proprietà del canale fino all'esecuzione del runtime del plugin.

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

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

Ogni voce del canale può includere:

Sostituire un altro Plugin di canale

Usa preferOver quando il tuo Plugin è il proprietario preferito per un ID di canale che anche un altro Plugin può fornire. Casi comuni sono un ID Plugin rinominato, un Plugin autonomo che sostituisce un Plugin incluso, o un fork mantenuto che mantiene lo stesso ID di canale per 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 del canale sia l'ID 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 possieda il canale e i suoi strumenti. La selezione esplicita dell'utente prevale comunque: se l'utente abilita esplicitamente entrambi i Plugin, OpenClaw preserva quella scelta e segnala diagnostiche di canali/strumenti duplicati invece di modificare silenziosamente l'insieme di Plugin richiesto.

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

Riferimento modelSupport

Usa modelSupport quando OpenClaw deve dedurre il tuo Plugin provider da ID modello abbreviati come gpt-5.5 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 espliciti provider/model usano i metadati del manifesto providers proprietario
• modelPatterns prevale su modelPrefixes
• se un Plugin non incluso e un Plugin incluso corrispondono entrambi, vince il Plugin non incluso
• l'ambiguità rimanente viene ignorata finché l'utente o la configurazione non specifica un provider

Campi:

Riferimento modelCatalog

Usa modelCatalog quando OpenClaw deve conoscere i metadati dei modelli del provider prima di caricare il runtime del Plugin. Questa è la fonte posseduta dal manifesto per righe fisse del catalogo, alias dei provider, regole di soppressione e modalità di rilevamento. L'aggiornamento runtime resta nel codice runtime del provider, ma il manifesto indica al core quando il runtime è richiesto.

{  "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": "not available on Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

Campi di primo livello:

aliases partecipa alla ricerca della proprietà del provider per la pianificazione del catalogo modelli. Le destinazioni degli alias devono essere provider di primo livello posseduti dallo stesso Plugin. Quando un elenco filtrato per provider usa un alias, OpenClaw può leggere il manifesto proprietario e applicare override di API/base URL dell'alias senza caricare il runtime del provider. Gli alias non espandono gli elenchi di catalogo non filtrati; gli elenchi ampi emettono solo le righe del provider canonico proprietario.

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

Campi del provider:

Campi del modello:

Campi di soppressione:

Non inserire dati solo runtime in modelCatalog. Usa static solo quando le righe del manifest sono abbastanza complete da consentire alle superfici di elenco filtrato per provider e di selezione di saltare il rilevamento di registry/runtime. Usa refreshable quando le righe del manifest sono semi elencabili o supplementi utili, ma un aggiornamento/cache può aggiungere altre righe in seguito; le righe refreshable non sono autorevoli da sole. Usa runtime quando OpenClaw deve caricare il runtime del provider per conoscere l'elenco.

Riferimento modelIdNormalization

Usa modelIdNormalization per una pulizia economica degli ID modello di proprietà del provider che deve avvenire prima del caricamento del runtime del provider. Questo mantiene alias come nomi modello brevi, ID legacy locali al provider e regole di prefisso proxy nel manifest del plugin proprietario, invece che nelle tabelle core di selezione del modello.

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

Campi del provider:

Riferimento providerEndpoints

Usa providerEndpoints per la classificazione degli endpoint che la policy generica delle richieste deve conoscere prima del caricamento del runtime del provider. Il core possiede ancora il significato di ogni endpointClass; i manifest dei plugin possiedono i metadati di host e URL base.

Campi degli endpoint:

Riferimento providerRequest

Usa providerRequest per metadati economici di compatibilità delle richieste di cui la policy generica delle richieste ha bisogno senza caricare il runtime del provider. Mantieni la riscrittura dei payload specifica del comportamento negli hook runtime del provider o negli helper condivisi della famiglia di provider.

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

Campi del provider:

Riferimento modelPricing

Usa modelPricing quando un provider richiede comportamento di pricing del control plane prima del caricamento del runtime. La cache dei prezzi del Gateway legge questi metadati senza importare codice runtime del provider.

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

Campi del provider:

Campi sorgente:

Indice dei provider OpenClaw

L'Indice dei provider OpenClaw è un metadato di anteprima di proprietà di OpenClaw per provider i cui plugin potrebbero non essere ancora installati. Non fa parte di un manifest di plugin. I manifest dei plugin rimangono l'autorità per i plugin installati. L'Indice dei provider è il contratto di fallback interno che le future superfici di provider installabili e selezione modello pre-installazione consumeranno quando un plugin provider non è installato.

Ordine di autorità del catalogo:

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

L'Indice dei provider non deve contenere segreti, stato abilitato, hook runtime o dati modello live specifici dell'account. I suoi cataloghi di anteprima usano la stessa forma di riga provider modelCatalog dei manifest dei plugin, ma dovrebbero restare limitati a metadati di visualizzazione stabili, a meno che campi dell'adapter runtime come api, baseUrl, pricing o flag di compatibilità siano mantenuti intenzionalmente allineati con il manifest del plugin installato. I provider con rilevamento live /models dovrebbero scrivere righe aggiornate tramite il percorso esplicito della cache del catalogo modelli invece di far chiamare API provider al normale elenco o onboarding.

Le voci dell'Indice dei provider possono anche contenere metadati di plugin installabili per provider il cui plugin è stato spostato fuori dal core o non è altrimenti ancora installato. Questi metadati rispecchiano il pattern del catalogo canali: nome del pacchetto, spec di installazione npm, integrità prevista ed etichette economiche di scelta dell'autenticazione sono sufficienti per mostrare un'opzione di setup installabile. Una volta installato il plugin, il suo manifest prevale e la voce dell'Indice dei provider viene ignorata per quel provider.

Le chiavi di capability legacy di primo livello sono deprecate. Usa openclaw doctor --fix per spostare speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders e webSearchProviders sotto contracts; il caricamento normale del manifest non tratta più quei campi di primo livello come proprietà delle capability.

Manifest rispetto a package.json

I due file svolgono compiti diversi:

Se non sai con certezza dove appartenga un metadato, usa questa regola:

• se OpenClaw deve conoscerlo prima di caricare il codice del plugin, mettilo in openclaw.plugin.json
• se riguarda packaging, file di ingresso o comportamento di installazione npm, mettilo in package.json

Campi package.json che influenzano il rilevamento

Alcuni metadati pre-runtime dei plugin vivono intenzionalmente in package.json sotto il blocco openclaw invece che in openclaw.plugin.json. openclaw.bundle e openclaw.bundle.json non sono contratti di plugin OpenClaw; i plugin nativi devono usare openclaw.plugin.json più i campi supportati package.json#openclaw qui sotto.

Esempi importanti:

I metadati del manifest decidono quali scelte di provider/canale/configurazione appaiono nell'onboarding prima del caricamento del runtime. package.json#openclaw.install indica all'onboarding come scaricare o abilitare quel Plugin quando l'utente seleziona una di quelle scelte. Non spostare i suggerimenti di installazione in openclaw.plugin.json.

openclaw.install.minHostVersion viene applicato durante l'installazione e il caricamento del registro dei manifest per sorgenti Plugin non incluse. I valori non validi vengono rifiutati; i valori piu recenti ma validi fanno saltare i Plugin esterni sugli host meno recenti. Si presume che i Plugin sorgente inclusi abbiano la stessa versione del checkout dell'host.

I metadati ufficiali di installazione su richiesta devono usare clawhubSpec quando il Plugin e pubblicato su ClawHub; l'onboarding lo tratta come sorgente remota preferita e registra i dati dell'artefatto ClawHub dopo l'installazione. npmSpec rimane il fallback di compatibilita per i pacchetti che non sono ancora passati a ClawHub.

Il blocco esatto della versione npm risiede gia in npmSpec, per esempio "npmSpec": "@wecom/[email protected]". Le voci ufficiali del catalogo esterno devono associare specifiche esatte a expectedIntegrity in modo che i flussi di aggiornamento falliscano in modo chiuso se l'artefatto npm scaricato non corrisponde piu alla release bloccata. L'onboarding interattivo offre ancora specifiche npm di registri attendibili, inclusi nomi di pacchetto semplici e dist-tag, per compatibilita. La diagnostica del catalogo puo distinguere sorgenti esatte, mobili, bloccate tramite integrita, prive di integrita, con mancata corrispondenza del nome pacchetto e con scelta predefinita non valida. Avvisa inoltre quando expectedIntegrity e presente ma non esiste una sorgente npm valida a cui possa applicare il blocco. Quando expectedIntegrity e presente, i flussi di installazione/aggiornamento la applicano; quando e omessa, la risoluzione del registro viene registrata senza un blocco di integrita.

I Plugin canale devono fornire openclaw.setupEntry quando le scansioni di stato, elenco canali o SecretRef devono identificare account configurati senza caricare il runtime completo. L'entry di configurazione deve esporre metadati del canale piu adattatori sicuri per la configurazione, lo stato e i segreti; tieni client di rete, listener Gateway e runtime di trasporto nell'entrypoint dell'estensione principale.

I campi degli entrypoint runtime non sovrascrivono i controlli dei confini di pacchetto per i campi degli entrypoint sorgente. Per esempio, openclaw.runtimeExtensions non puo rendere caricabile un percorso openclaw.extensions in uscita.

openclaw.install.allowInvalidConfigRecovery e volutamente ristretto. Non rende installabili configurazioni arbitrarie rotte. Oggi consente solo ai flussi di installazione di recuperare da specifici errori obsoleti di aggiornamento di Plugin inclusi, come un percorso Plugin incluso mancante o una voce channels.<id> obsoleta per quello 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 e metadato di pacchetto per un minuscolo modulo di controllo:

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

Usalo quando i flussi di configurazione, doctor, stato o presenza in sola lettura hanno bisogno di una sonda di autenticazione si/no economica prima del caricamento del Plugin canale completo. Lo stato di autenticazione persistito non e lo stato configurato del canale: non usare questi metadati per abilitare automaticamente Plugin, riparare dipendenze runtime o decidere se un runtime canale debba caricarsi. L'export di destinazione deve essere una piccola funzione che legge solo lo stato persistito; non instradarlo attraverso il barrel del runtime completo del canale.

openclaw.channel.configuredState segue la stessa forma per controlli economici dello stato configurato solo env:

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "specifier": "./configured-state",        "exportName": "hasTelegramConfiguredState"      }    }  }}

Usalo quando un canale puo rispondere sullo stato configurato da env o da altri input minimi non runtime. Se il controllo richiede la risoluzione completa della configurazione o il runtime reale del canale, mantieni quella logica nell'hook config.hasConfiguredState del Plugin.

Precedenza di rilevamento (id Plugin duplicati)

OpenClaw rileva Plugin da varie radici (inclusi, installazione globale, workspace, percorsi selezionati esplicitamente dalla configurazione). Se due rilevamenti condividono lo stesso id, viene mantenuto solo il manifest con precedenza piu alta; i duplicati con precedenza inferiore vengono scartati invece di essere caricati accanto a esso.

Precedenza, dalla piu alta alla piu bassa:

1. Selezionato dalla configurazione — un percorso bloccato esplicitamente in plugins.entries.<id>
2. Incluso — Plugin distribuiti con OpenClaw
3. Installazione globale — Plugin installati nella radice globale dei Plugin OpenClaw
4. Workspace — Plugin rilevati relativamente al workspace corrente

Implicazioni:

• Una copia forkata o obsoleta di un Plugin incluso presente nel workspace non oscurera la build inclusa.
• Per sovrascrivere realmente un Plugin incluso con uno locale, bloccalo tramite plugins.entries.<id> in modo che vinca per precedenza invece di affidarti al rilevamento del workspace.
• Gli scarti di duplicati vengono registrati nei log in modo che Doctor e la diagnostica di avvio possano indicare la copia scartata.
• Le sovrascritture duplicate selezionate dalla configurazione sono formulate come sovrascritture esplicite nella diagnostica, ma avvisano comunque affinche fork obsoleti e ombreggiamenti accidentali restino visibili.

Requisiti dello schema JSON

• Ogni Plugin deve distribuire uno schema JSON, anche se non accetta configurazione.
• Uno schema vuoto e accettabile (per esempio, { "type": "object", "additionalProperties": false }).
• Gli schemi vengono validati in fase di lettura/scrittura della configurazione, non a runtime.
• Quando estendi o crei un fork di un Plugin incluso con nuove chiavi di configurazione, aggiorna contemporaneamente il configSchema di openclaw.plugin.json di quel 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 verra rifiutata prima del caricamento del runtime del Plugin.

Esempio di estensione dello schema:

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

Comportamento di validazione

• Le chiavi channels.* sconosciute sono errori, a meno che l'id canale sia dichiarato da un manifest Plugin.
• plugins.entries.<id>, plugins.allow, plugins.deny e plugins.slots.* devono fare riferimento a id Plugin rilevabili. Gli id sconosciuti sono errori.
• Se un Plugin e installato ma ha un manifest o uno schema rotto o mancante, la validazione fallisce e Doctor segnala l'errore del Plugin.
• Se la configurazione del Plugin esiste ma il Plugin e disabilitato, la configurazione viene mantenuta e un avviso viene mostrato in Doctor e nei log.

Consulta il Riferimento di configurazione per lo schema completo plugins.*.

Note

• Il manifest è obbligatorio per i Plugin OpenClaw nativi, inclusi i caricamenti dal filesystem locale. Il runtime carica comunque il modulo del Plugin separatamente; il manifest serve solo per discovery e convalida.
• I manifest nativi vengono analizzati con JSON5, quindi commenti, virgole finali e chiavi senza virgolette sono accettati purché il valore finale sia comunque un oggetto.
• Il caricatore del manifest legge solo i campi documentati del manifest. Evita chiavi personalizzate di primo livello.
• channels, providers, cliBackends e skills possono essere tutti omessi quando un Plugin non ne ha bisogno.
• providerCatalogEntry deve restare leggero e non dovrebbe importare codice runtime ampio; usalo per metadati statici del catalogo dei provider o descrittori di discovery mirati, non per l'esecuzione al momento della richiesta. providerDiscoveryEntry è la grafia legacy e funziona ancora per i Plugin esistenti.
• I tipi di Plugin esclusivi vengono selezionati tramite plugins.slots.*: kind: "memory" tramite plugins.slots.memory, kind: "context-engine" tramite plugins.slots.contextEngine (predefinito legacy).
• Dichiara il tipo di Plugin esclusivo in questo manifest. OpenClawPluginDefinition.kind della voce runtime è deprecato e resta solo come fallback di compatibilità per i Plugin più vecchi.
• I metadati delle variabili d'ambiente (setup.providers[].envVars, providerAuthEnvVars deprecato e channelEnvVars) sono solo dichiarativi. Stato, audit, convalida della consegna Cron e altre superfici di sola lettura applicano comunque l'attendibilità del Plugin e la policy di attivazione effettiva prima di considerare una variabile d'ambiente come configurata.
• Per i metadati runtime della procedura guidata che richiedono codice del provider, vedi hook runtime dei provider.
• Se il tuo Plugin dipende da moduli nativi, documenta i passaggi di build e qualsiasi requisito di allowlist del gestore pacchetti (ad esempio, pnpm allow-build-scripts + pnpm rebuild <package>).

Correlati