---
read_when:
    - Stai creando un plugin OpenClaw
    - Devi distribuire uno schema di configurazione del plugin o eseguire il debug degli errori di convalida del plugin
summary: Requisiti del manifest del Plugin + schema JSON (convalida rigorosa della configurazione)
title: Manifest del Plugin
x-i18n:
    generated_at: "2026-04-19T01:11:09Z"
    model: gpt-5.4
    provider: openai
    source_hash: 2dfc00759108ddee7bfcda8c42acf7f2d47451676447ba3caf8b5950f8a1c181
    source_path: plugins/manifest.md
    workflow: 15
---

# Manifest del Plugin (`openclaw.plugin.json`)

Questa pagina riguarda solo il **manifest nativo del plugin OpenClaw**.

Per i layout di bundle compatibili, vedi [Bundle di plugin](/it/plugins/bundles).

I formati di bundle compatibili usano file manifest diversi:

- Bundle Codex: `.codex-plugin/plugin.json`
- Bundle Claude: `.claude-plugin/plugin.json` o il layout predefinito del componente Claude senza manifest
- Bundle Cursor: `.cursor-plugin/plugin.json`

OpenClaw rileva automaticamente anche quei layout di bundle, ma non vengono convalidati rispetto allo schema `openclaw.plugin.json` descritto qui.

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

Ogni plugin nativo OpenClaw **deve** includere un file `openclaw.plugin.json` nella **radice del plugin**. OpenClaw usa questo manifest per convalidare la configurazione **senza eseguire il codice del plugin**. I manifest mancanti o non validi sono trattati come errori del plugin e bloccano la convalida della configurazione.

Vedi la guida completa al sistema di plugin: [Plugin](/it/tools/plugin).
Per il modello di capacità nativo e le indicazioni attuali sulla compatibilità esterna:
[Modello di capacità](/it/plugins/architecture#public-capability-model).

## A cosa serve questo file

`openclaw.plugin.json` è il metadato che OpenClaw legge prima di caricare il codice del tuo plugin.

Usalo per:

- identità del plugin
- convalida della configurazione
- metadati di autenticazione e onboarding che devono essere disponibili senza avviare il runtime del plugin
- suggerimenti di attivazione leggeri che le superfici del control plane possono ispezionare prima che il runtime venga caricato
- descrittori di configurazione leggeri che le superfici di configurazione/onboarding possono ispezionare prima che il runtime venga caricato
- metadati di alias e auto-attivazione che devono essere risolti prima che il runtime del plugin venga caricato
- metadati abbreviati di proprietà della famiglia di modelli che devono attivare automaticamente il plugin prima che il runtime venga caricato
- snapshot statiche di proprietà delle capacità usate per il wiring di compatibilità dei bundle e la copertura dei contratti
- metadati leggeri del runner QA che l'host condiviso `openclaw qa` può ispezionare prima che il runtime del plugin venga caricato
- metadati di configurazione specifici del canale che devono essere uniti alle superfici di catalogo e convalida senza caricare il runtime
- suggerimenti UI per la configurazione

Non usarlo per:

- registrare comportamenti di runtime
- dichiarare entrypoint del codice
- metadati di installazione npm

Questi appartengono al codice del tuo plugin e a `package.json`.

## Esempio minimo

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

## Esempio completo

```json
{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "Plugin provider OpenRouter",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "providerEndpoints": [
    {
      "endpointClass": "xai-native",
      "hosts": ["api.x.ai"]
    }
  ],
  "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": "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

| Campo                               | Obbligatorio | Tipo                             | Significato                                                                                                                                                                                                 |
| ----------------------------------- | ------------ | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                | Sì           | `string`                         | ID canonico del plugin. È l'ID usato in `plugins.entries.<id>`.                                                                                                                                             |
| `configSchema`                      | Sì           | `object`                         | Schema JSON inline per la configurazione di questo plugin.                                                                                                                                                   |
| `enabledByDefault`                  | No           | `true`                           | Indica che un plugin bundle è abilitato per impostazione predefinita. Omettilo, oppure imposta qualsiasi valore diverso da `true`, per lasciare il plugin disabilitato per impostazione predefinita.      |
| `legacyPluginIds`                   | No           | `string[]`                       | ID legacy che vengono normalizzati a questo ID canonico del plugin.                                                                                                                                         |
| `autoEnableWhenConfiguredProviders` | No           | `string[]`                       | ID provider che devono abilitare automaticamente questo plugin quando auth, configurazione o riferimenti a modelli li menzionano.                                                                          |
| `kind`                              | No           | `"memory"` \| `"context-engine"` | Dichiara un tipo esclusivo di plugin usato da `plugins.slots.*`.                                                                                                                                            |
| `channels`                          | No           | `string[]`                       | ID dei canali posseduti da questo plugin. Usati per discovery e convalida della configurazione.                                                                                                             |
| `providers`                         | No           | `string[]`                       | ID dei provider posseduti da questo plugin.                                                                                                                                                                  |
| `modelSupport`                      | No           | `object`                         | Metadati abbreviati delle famiglie di modelli posseduti dal manifest, usati per caricare automaticamente il plugin prima del runtime.                                                                      |
| `providerEndpoints`                 | No           | `object[]`                       | Metadati di host/baseUrl degli endpoint posseduti dal manifest per le route del provider che il core deve classificare prima che il runtime del provider venga caricato.                                   |
| `cliBackends`                       | No           | `string[]`                       | ID dei backend di inferenza CLI posseduti da questo plugin. Usati per l'auto-attivazione all'avvio a partire da riferimenti espliciti nella configurazione.                                               |
| `syntheticAuthRefs`                 | No           | `string[]`                       | Riferimenti a provider o backend CLI i cui hook di auth sintetica posseduti dal plugin devono essere verificati durante la discovery a freddo dei modelli prima che il runtime venga caricato.            |
| `nonSecretAuthMarkers`              | No           | `string[]`                       | Valori segnaposto della chiave API posseduti dal plugin bundle che rappresentano uno stato di credenziali non segrete locale, OAuth o ambientale.                                                          |
| `commandAliases`                    | No           | `object[]`                       | Nomi di comandi posseduti da questo plugin che devono produrre diagnostica di configurazione e CLI consapevole del plugin prima che il runtime venga caricato.                                             |
| `providerAuthEnvVars`               | No           | `Record<string, string[]>`       | Metadati leggeri delle variabili d'ambiente di auth del provider che OpenClaw può ispezionare senza caricare il codice del plugin.                                                                         |
| `providerAuthAliases`               | No           | `Record<string, string>`         | ID provider che devono riutilizzare un altro ID provider per la ricerca dell'auth, per esempio un provider di coding che condivide la chiave API del provider di base e i profili di autenticazione.       |
| `channelEnvVars`                    | No           | `Record<string, string[]>`       | Metadati leggeri delle variabili d'ambiente del canale che OpenClaw può ispezionare senza caricare il codice del plugin. Usalo per superfici di configurazione o auth del canale guidate da env che gli helper generici di avvio/configurazione devono vedere. |
| `providerAuthChoices`               | No           | `object[]`                       | Metadati leggeri delle scelte di autenticazione per selettori di onboarding, risoluzione del provider preferito e semplice wiring dei flag CLI.                                                            |
| `activation`                        | No           | `object`                         | Suggerimenti di attivazione leggeri per caricamento attivato da provider, comando, canale, route e capacità. Solo metadati; il runtime del plugin continua a possedere il comportamento effettivo.        |
| `setup`                             | No           | `object`                         | Descrittori leggeri di configurazione/onboarding che le superfici di discovery e configurazione possono ispezionare senza caricare il runtime del plugin.                                                  |
| `qaRunners`                         | No           | `object[]`                       | Descrittori leggeri dei runner QA usati dall'host condiviso `openclaw qa` prima che il runtime del plugin venga caricato.                                                                                  |
| `contracts`                         | No           | `object`                         | Snapshot statica delle capacità bundle per speech, trascrizione realtime, voce realtime, media-understanding, generazione di immagini, generazione musicale, generazione video, web-fetch, ricerca web e proprietà degli strumenti. |
| `channelConfigs`                    | No           | `Record<string, object>`         | Metadati di configurazione del canale posseduti dal manifest uniti alle superfici di discovery e convalida prima che il runtime venga caricato.                                                            |
| `skills`                            | No           | `string[]`                       | Directory Skills da caricare, relative alla radice del plugin.                                                                                                                                              |
| `name`                              | No           | `string`                         | Nome leggibile del plugin.                                                                                                                                                                                   |
| `description`                       | No           | `string`                         | Breve riepilogo mostrato nelle superfici del plugin.                                                                                                                                                        |
| `version`                           | No           | `string`                         | Versione informativa del plugin.                                                                                                                                                                             |
| `uiHints`                           | No           | `Record<string, object>`         | Etichette UI, placeholder e suggerimenti di sensibilità per i campi di configurazione.                                                                                                                      |

## Riferimento `providerAuthChoices`

Ogni voce di `providerAuthChoices` descrive una scelta di onboarding o autenticazione.
OpenClaw la legge prima che il runtime del provider venga caricato.

| Campo                 | Obbligatorio | Tipo                                            | Significato                                                                                                      |
| --------------------- | ------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `provider`            | Sì           | `string`                                        | ID del provider a cui appartiene questa scelta.                                                                  |
| `method`              | Sì           | `string`                                        | ID del metodo di autenticazione a cui inoltrare.                                                                 |
| `choiceId`            | Sì           | `string`                                        | ID stabile della scelta di autenticazione usato dai flussi di onboarding e CLI.                                 |
| `choiceLabel`         | No           | `string`                                        | Etichetta visibile all'utente. Se omessa, OpenClaw usa `choiceId` come fallback.                                |
| `choiceHint`          | No           | `string`                                        | Breve testo di aiuto per il selettore.                                                                           |
| `assistantPriority`   | No           | `number`                                        | I valori più bassi vengono ordinati prima nei selettori interattivi guidati dall'assistente.                    |
| `assistantVisibility` | No           | `"visible"` \| `"manual-only"`                  | Nasconde la scelta dai selettori dell'assistente pur consentendo comunque la selezione manuale via CLI.         |
| `deprecatedChoiceIds` | No           | `string[]`                                      | ID legacy della scelta che devono reindirizzare gli utenti a questa scelta sostitutiva.                         |
| `groupId`             | No           | `string`                                        | ID di gruppo facoltativo per raggruppare scelte correlate.                                                       |
| `groupLabel`          | No           | `string`                                        | Etichetta visibile all'utente per quel gruppo.                                                                   |
| `groupHint`           | No           | `string`                                        | Breve testo di aiuto per il gruppo.                                                                              |
| `optionKey`           | No           | `string`                                        | Chiave di opzione interna per semplici flussi di autenticazione a flag singolo.                                 |
| `cliFlag`             | No           | `string`                                        | Nome del flag CLI, ad esempio `--openrouter-api-key`.                                                            |
| `cliOption`           | No           | `string`                                        | Forma completa dell'opzione CLI, ad esempio `--openrouter-api-key <key>`.                                       |
| `cliDescription`      | No           | `string`                                        | Descrizione usata nell'help della CLI.                                                                           |
| `onboardingScopes`    | No           | `Array<"text-inference" \| "image-generation">` | In quali superfici di onboarding deve apparire questa scelta. Se omesso, il valore predefinito è `["text-inference"]`. |

## Riferimento `commandAliases`

Usa `commandAliases` quando un plugin possiede un nome di comando di runtime che gli utenti possono erroneamente inserire in `plugins.allow` o provare a eseguire come comando CLI di root. OpenClaw usa questi metadati per la diagnostica senza importare il codice di runtime del plugin.

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

| Campo        | Obbligatorio | Tipo              | Significato                                                                     |
| ------------ | ------------ | ----------------- | ------------------------------------------------------------------------------- |
| `name`       | Sì           | `string`          | Nome del comando che appartiene a questo plugin.                                |
| `kind`       | No           | `"runtime-slash"` | Indica che l'alias è un comando slash della chat anziché un comando CLI di root. |
| `cliCommand` | No           | `string`          | Comando CLI di root correlato da suggerire per le operazioni CLI, se esiste.    |

## Riferimento `activation`

Usa `activation` quando il plugin può dichiarare in modo economico quali eventi del control plane dovrebbero attivarlo in seguito.

## Riferimento `qaRunners`

Usa `qaRunners` quando un plugin contribuisce uno o più runner di trasporto sotto la root condivisa `openclaw qa`. Mantieni questi metadati leggeri e statici; il runtime del plugin continua a possedere la registrazione CLI effettiva tramite una superficie leggera `runtime-api.ts` che esporta `qaRunnerCliRegistrations`.

```json
{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "Esegue la corsia QA Matrix live basata su Docker contro un homeserver usa e getta"
    }
  ]
}
```

| Campo         | Obbligatorio | Tipo     | Significato                                                         |
| ------------- | ------------ | -------- | ------------------------------------------------------------------- |
| `commandName` | Sì           | `string` | Sottocomando montato sotto `openclaw qa`, ad esempio `matrix`.      |
| `description` | No           | `string` | Testo di help di fallback usato quando l'host condiviso necessita di un comando stub. |

Questo blocco contiene solo metadati. Non registra comportamenti di runtime e non sostituisce `register(...)`, `setupEntry` o altri entrypoint di runtime/plugin.
I consumer attuali lo usano come suggerimento di restringimento prima di un caricamento più ampio del plugin, quindi l'assenza di metadati di attivazione di solito comporta solo un costo in termini di prestazioni; non dovrebbe modificare la correttezza finché esistono ancora fallback legacy di proprietà del manifest.

```json
{
  "activation": {
    "onProviders": ["openai"],
    "onCommands": ["models"],
    "onChannels": ["web"],
    "onRoutes": ["gateway-webhook"],
    "onCapabilities": ["provider", "tool"]
  }
}
```

| Campo            | Obbligatorio | Tipo                                                 | Significato                                                         |
| ---------------- | ------------ | ---------------------------------------------------- | ------------------------------------------------------------------- |
| `onProviders`    | No           | `string[]`                                           | ID dei provider che devono attivare questo plugin quando richiesti. |
| `onCommands`     | No           | `string[]`                                           | ID dei comandi che devono attivare questo plugin.                   |
| `onChannels`     | No           | `string[]`                                           | ID dei canali che devono attivare questo plugin.                    |
| `onRoutes`       | No           | `string[]`                                           | Tipi di route che devono attivare questo plugin.                    |
| `onCapabilities` | No           | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Suggerimenti ampi di capacità usati dalla pianificazione di attivazione del control plane. |

Consumer live attuali:

- la pianificazione CLI attivata da comando usa come fallback `commandAliases[].cliCommand` o `commandAliases[].name` legacy
- la pianificazione di configurazione/canale attivata da canale usa come fallback la proprietà legacy `channels[]` quando mancano metadati espliciti di attivazione del canale
- la pianificazione di configurazione/runtime attivata da provider usa come fallback la proprietà legacy `providers[]` e la proprietà di primo livello `cliBackends[]` quando mancano metadati espliciti di attivazione del provider

## Riferimento `setup`

Usa `setup` quando le superfici di configurazione e onboarding hanno bisogno di metadati economici posseduti dal plugin prima che il runtime venga caricato.

```json
{
  "setup": {
    "providers": [
      {
        "id": "openai",
        "authMethods": ["api-key"],
        "envVars": ["OPENAI_API_KEY"]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}
```

Il campo `cliBackends` di primo livello resta valido e continua a descrivere i backend di inferenza CLI. `setup.cliBackends` è la superficie descrittiva specifica della configurazione per i flussi del control plane/configurazione che devono rimanere solo metadati.

Quando presenti, `setup.providers` e `setup.cliBackends` sono la superficie di ricerca preferita, orientata prima ai descrittori, per la discovery della configurazione. Se il descrittore restringe solo il plugin candidato e la configurazione necessita comunque di hook di runtime più ricchi in fase di setup, imposta `requiresRuntime: true` e mantieni `setup-api` come percorso di esecuzione di fallback.

Poiché la ricerca della configurazione può eseguire codice `setup-api` posseduto dal plugin, i valori normalizzati di `setup.providers[].id` e `setup.cliBackends[]` devono rimanere univoci tra i plugin rilevati. Una proprietà ambigua fallisce in modalità chiusa invece di scegliere un vincitore in base all'ordine di discovery.

### Riferimento `setup.providers`

| Campo         | Obbligatorio | Tipo       | Significato                                                                              |
| ------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------- |
| `id`          | Sì           | `string`   | ID provider esposto durante la configurazione o l'onboarding. Mantieni gli ID normalizzati univoci globalmente. |
| `authMethods` | No           | `string[]` | ID dei metodi di configurazione/autenticazione supportati da questo provider senza caricare il runtime completo. |
| `envVars`     | No           | `string[]` | Variabili d'ambiente che le superfici generiche di configurazione/stato possono controllare prima che il runtime del plugin venga caricato. |

### Campi `setup`

| Campo              | Obbligatorio | Tipo       | Significato                                                                                         |
| ------------------ | ------------ | ---------- | --------------------------------------------------------------------------------------------------- |
| `providers`        | No           | `object[]` | Descrittori di configurazione del provider esposti durante la configurazione e l'onboarding.        |
| `cliBackends`      | No           | `string[]` | ID dei backend usati in fase di setup per la ricerca orientata prima ai descrittori. Mantieni gli ID normalizzati univoci globalmente. |
| `configMigrations` | No           | `string[]` | ID delle migrazioni di configurazione possedute dalla superficie di setup di questo plugin.         |
| `requiresRuntime`  | No           | `boolean`  | Indica se la configurazione necessita ancora dell'esecuzione di `setup-api` dopo la ricerca per descrittori. |

## Riferimento `uiHints`

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

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

Ogni suggerimento di campo può includere:

| Campo         | Tipo       | Significato                               |
| ------------- | ---------- | ----------------------------------------- |
| `label`       | `string`   | Etichetta del campo visibile all'utente.  |
| `help`        | `string`   | Breve testo di aiuto.                     |
| `tags`        | `string[]` | Tag UI facoltativi.                       |
| `advanced`    | `boolean`  | Indica il campo come avanzato.            |
| `sensitive`   | `boolean`  | Indica il campo come segreto o sensibile. |
| `placeholder` | `string`   | Testo segnaposto per gli input del modulo. |

## Riferimento `contracts`

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

```json
{
  "contracts": {
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}
```

Ogni elenco è facoltativo:

| Campo                            | Tipo       | Significato                                                        |
| -------------------------------- | ---------- | ------------------------------------------------------------------ |
| `speechProviders`                | `string[]` | ID dei provider speech posseduti da questo plugin.                 |
| `realtimeTranscriptionProviders` | `string[]` | ID dei provider di trascrizione realtime posseduti da questo plugin. |
| `realtimeVoiceProviders`         | `string[]` | ID dei provider di voce realtime posseduti da questo plugin.       |
| `mediaUnderstandingProviders`    | `string[]` | ID dei provider media-understanding posseduti da questo plugin.    |
| `imageGenerationProviders`       | `string[]` | ID dei provider di generazione immagini posseduti da questo plugin. |
| `videoGenerationProviders`       | `string[]` | ID dei provider di generazione video posseduti da questo plugin.   |
| `webFetchProviders`              | `string[]` | ID dei provider web-fetch posseduti da questo plugin.              |
| `webSearchProviders`             | `string[]` | ID dei provider di ricerca web posseduti da questo plugin.         |
| `tools`                          | `string[]` | Nomi degli strumenti dell'agente posseduti da questo plugin per i controlli dei contratti bundle. |

## Riferimento `channelConfigs`

Usa `channelConfigs` quando un plugin di canale ha bisogno di metadati di configurazione leggeri prima che il runtime venga caricato.

```json
{
  "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",
      "preferOver": ["matrix-legacy"]
    }
  }
}
```

Ogni voce di canale può includere:

| Campo         | Tipo                     | Significato                                                                                  |
| ------------- | ------------------------ | -------------------------------------------------------------------------------------------- |
| `schema`      | `object`                 | Schema JSON per `channels.<id>`. Obbligatorio per ogni voce dichiarata di configurazione del canale. |
| `uiHints`     | `Record<string, object>` | Etichette UI / placeholder / suggerimenti di sensibilità facoltativi per quella sezione di configurazione del canale. |
| `label`       | `string`                 | Etichetta del canale unita alle superfici di selezione e ispezione quando i metadati di runtime non sono pronti. |
| `description` | `string`                 | Breve descrizione del canale per le superfici di ispezione e catalogo.                      |
| `preferOver`  | `string[]`               | ID di plugin legacy o a priorità inferiore che questo canale deve superare nelle superfici di selezione. |

## Riferimento `modelSupport`

Usa `modelSupport` quando OpenClaw deve inferire il tuo plugin provider da ID abbreviati di modello come `gpt-5.4` o `claude-sonnet-4.6` prima che il runtime del plugin venga caricato.

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

OpenClaw applica questa precedenza:

- i riferimenti espliciti `provider/model` usano i metadati `providers` del manifest proprietario
- `modelPatterns` hanno precedenza su `modelPrefixes`
- se corrispondono sia un plugin non bundle sia un plugin bundle, vince il plugin non bundle
- l'ambiguità residua viene ignorata finché l'utente o la configurazione non specificano un provider

Campi:

| Campo           | Tipo       | Significato                                                                    |
| --------------- | ---------- | ------------------------------------------------------------------------------ |
| `modelPrefixes` | `string[]` | Prefissi confrontati con `startsWith` rispetto agli ID abbreviati dei modelli. |
| `modelPatterns` | `string[]` | Sorgenti regex confrontate con gli ID abbreviati dei modelli dopo la rimozione del suffisso del profilo. |

Le chiavi legacy di capacità 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à di capacità.

## Manifest rispetto a package.json

I due file svolgono compiti diversi:

| File                   | Usalo per                                                                                                                           |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | Discovery, convalida della configurazione, metadati delle scelte di autenticazione e suggerimenti UI che devono esistere prima dell'esecuzione del codice del plugin |
| `package.json`         | Metadati npm, installazione delle dipendenze e blocco `openclaw` usato per entrypoint, gating dell'installazione, setup o metadati di catalogo |

Se non sei sicuro di dove appartenga un metadato, usa questa regola:

- se OpenClaw deve conoscerlo prima di caricare il codice del plugin, inseriscilo in `openclaw.plugin.json`
- se riguarda packaging, file di entry o comportamento di installazione npm, inseriscilo in `package.json`

### Campi `package.json` che influenzano la discovery

Alcuni metadati del plugin precedenti al runtime vivono intenzionalmente in `package.json` sotto il blocco `openclaw` invece che in `openclaw.plugin.json`.

Esempi importanti:

| Campo                                                             | Significato                                                                                                                                   |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.extensions`                                             | Dichiara gli entrypoint nativi del plugin.                                                                                                    |
| `openclaw.setupEntry`                                             | Entry point leggero solo setup usato durante l'onboarding e l'avvio differito del canale.                                                    |
| `openclaw.channel`                                                | Metadati leggeri del catalogo dei canali come etichette, percorsi della documentazione, alias e testo di selezione.                         |
| `openclaw.channel.configuredState`                                | Metadati leggeri del controllo dello stato configurato che possono rispondere a "esiste già una configurazione solo env?" senza caricare il runtime completo del canale. |
| `openclaw.channel.persistedAuthState`                             | Metadati leggeri del controllo dello stato di autenticazione persistito che possono rispondere a "c'è già qualcosa connesso?" senza caricare il runtime completo del canale. |
| `openclaw.install.npmSpec` / `openclaw.install.localPath`         | Suggerimenti di installazione/aggiornamento per plugin bundle e plugin pubblicati esternamente.                                              |
| `openclaw.install.defaultChoice`                                  | Percorso di installazione preferito quando sono disponibili più origini di installazione.                                                    |
| `openclaw.install.minHostVersion`                                 | Versione minima supportata dell'host OpenClaw, usando un vincolo semver minimo come `>=2026.3.22`.                                          |
| `openclaw.install.allowInvalidConfigRecovery`                     | Consente un percorso limitato di recupero tramite reinstallazione del plugin bundle quando la configurazione non è valida.                   |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Consente il caricamento delle superfici del canale solo setup prima del plugin di canale completo durante l'avvio.                          |

`openclaw.install.minHostVersion` viene applicato durante l'installazione e il caricamento del registro dei manifest. I valori non validi vengono rifiutati; i valori validi ma più recenti saltano il plugin sugli host più vecchi.

`openclaw.install.allowInvalidConfigRecovery` è intenzionalmente limitato. Non rende installabili configurazioni arbitrarie non funzionanti. Oggi consente solo ai flussi di installazione di recuperare da specifici errori di aggiornamento obsoleti di plugin bundle, come un percorso mancante del plugin bundle o una voce obsoleta `channels.<id>` per quello stesso plugin bundle. Errori di configurazione non correlati continuano a bloccare l'installazione e indirizzano gli operatori a `openclaw doctor --fix`.

`openclaw.channel.persistedAuthState` è un metadato di package per un piccolo modulo di controllo:

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

Usalo quando i flussi di setup, doctor o stato configurato hanno bisogno di una verifica economica sì/no dell'autenticazione prima che il plugin completo del canale venga caricato. L'export di destinazione deve essere una piccola funzione che legge solo lo stato persistito; non instradarla attraverso il barrel completo del runtime del canale.

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

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

Usalo quando un canale può determinare lo stato configurato da env o da altri input minimi non di runtime. Se il controllo richiede la risoluzione completa della configurazione o il vero runtime del canale, mantieni invece quella logica nell'hook del plugin `config.hasConfiguredState`.

## Requisiti dello schema JSON

- **Ogni plugin deve includere uno schema JSON**, anche se non accetta alcuna configurazione.
- È accettabile uno schema vuoto, ad esempio `{ "type": "object", "additionalProperties": false }`.
- Gli schemi vengono convalidati al momento della lettura/scrittura della configurazione, non a runtime.

## Comportamento della convalida

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

Vedi [Riferimento della configurazione](/it/gateway/configuration) per lo schema completo `plugins.*`.

## Note

- Il manifest è **obbligatorio per i plugin nativi OpenClaw**, inclusi i caricamenti dal filesystem locale.
- Il runtime continua a caricare separatamente il modulo del plugin; il manifest serve solo per discovery + convalida.
- I manifest nativi vengono analizzati con JSON5, quindi commenti, virgole finali e chiavi senza virgolette sono accettati purché il valore finale resti un oggetto.
- Solo i campi del manifest documentati vengono letti dal loader del manifest. Evita di aggiungere qui chiavi personalizzate di primo livello.
- `providerAuthEnvVars` è il percorso di metadati leggero per probe di autenticazione, convalida di marcatori env e superfici simili di auth del provider che non devono avviare il runtime del plugin solo per ispezionare i nomi env.
- `providerAuthAliases` consente alle varianti del provider di riutilizzare le variabili d'ambiente di auth di un altro provider, i profili di autenticazione, l'auth basata sulla configurazione e la scelta di onboarding della chiave API senza hardcodare questa relazione nel core.
- `providerEndpoints` consente ai plugin provider di possedere semplici metadati di corrispondenza host/baseUrl degli endpoint. Usalo solo per classi di endpoint già supportate dal core; il plugin continua a possedere il comportamento di runtime.
- `syntheticAuthRefs` è il percorso di metadati leggero per hook di auth sintetica posseduti dal provider che devono essere visibili alla discovery a freddo dei modelli prima che esista il registro di runtime. Elenca solo i riferimenti il cui provider di runtime o backend CLI implementa davvero `resolveSyntheticAuth`.
- `nonSecretAuthMarkers` è il percorso di metadati leggero per chiavi API segnaposto possedute dal plugin bundle, come marcatori di credenziali locali, OAuth o ambientali. Il core le tratta come non segrete per la visualizzazione dell'auth e gli audit dei segreti senza hardcodare il provider proprietario.
- `channelEnvVars` è il percorso di metadati leggero per fallback dell'ambiente shell, prompt di setup e superfici simili del canale che non devono avviare il runtime del plugin solo per ispezionare i nomi env.
- `providerAuthChoices` è il percorso di metadati leggero per selettori di scelta dell'autenticazione, risoluzione di `--auth-choice`, mapping del provider preferito e semplice registrazione dei flag CLI di onboarding prima che il runtime del provider venga caricato. Per i metadati del wizard di runtime che richiedono codice del provider, vedi [Hook di runtime del provider](/it/plugins/architecture#provider-runtime-hooks).
- I tipi esclusivi di plugin vengono selezionati tramite `plugins.slots.*`.
  - `kind: "memory"` viene selezionato da `plugins.slots.memory`.
  - `kind: "context-engine"` viene selezionato da `plugins.slots.contextEngine` (predefinito: `legacy` integrato).
- `channels`, `providers`, `cliBackends` e `skills` possono essere omessi quando un plugin non ne ha bisogno.
- Se il tuo plugin dipende da moduli nativi, documenta i passaggi di build e gli eventuali requisiti di allowlist del gestore di pacchetti (ad esempio, pnpm `allow-build-scripts`
  - `pnpm rebuild <package>`).

## Correlati

- [Creazione di Plugin](/it/plugins/building-plugins) — introduzione ai plugin
- [Architettura dei Plugin](/it/plugins/architecture) — architettura interna
- [Panoramica dell'SDK](/it/plugins/sdk-overview) — riferimento del Plugin SDK
