​

Manifest del plugin (openclaw.plugin.json)

• 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

​

Cosa fa questo file

• identità del plugin
• validazione della configurazione
• metadati di autenticazione e onboarding che devono essere disponibili senza avviare il runtime del plugin
• metadati di alias e auto-enable che devono essere risolti prima del caricamento del runtime del plugin
• metadati shorthand della famiglia di modelli che devono attivare automaticamente il plugin prima del caricamento del runtime
• snapshot statici della proprietà delle capacità usati per il wiring di compatibilità dei bundle e la copertura dei contratti
• metadati di configurazione specifici del canale che devono essere uniti nelle superfici di catalogo e validazione senza caricare il runtime
• suggerimenti UI per la configurazione

• registrare il comportamento runtime
• dichiarare entrypoint del codice
• metadati di installazione npm

​

Esempio minimo

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

​

Esempio completo

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "Plugin provider OpenRouter",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "cliBackends": ["openrouter-cli"],
  "providerAuthEnvVars": {
    "openrouter": ["OPENROUTER_API_KEY"]
  },
  "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 providerAuthChoices

​

Riferimento uiHints

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

​

Riferimento contracts

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

​

Riferimento channelConfigs

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

​

Riferimento modelSupport

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

• i riferimenti espliciti provider/model usano i metadati providers gestiti dal manifest
• modelPatterns ha precedenza 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 specificano un provider

​

Manifest versus package.json

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

​

Campi package.json che influiscono sulla discovery

​

Requisiti JSON Schema

• Ogni plugin deve distribuire un JSON Schema, anche se non accetta configurazione.
• Uno schema vuoto è accettabile (per esempio { "type": "object", "additionalProperties": false }).
• Gli schemi vengono validati al momento della lettura/scrittura della configurazione, non a runtime.

​

Comportamento della validazione

• Le chiavi channels.* sconosciute sono errori, a meno che l’id del canale non sia dichiarato da un manifest del 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 è installato ma ha un manifest o uno schema danneggiato o mancante, la validazione fallisce 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 + nei log.

​

Note

• Il manifest è obbligatorio per i plugin nativi OpenClaw, inclusi i caricamenti dal filesystem locale.
• Il runtime carica comunque separatamente il modulo del plugin; il manifest serve solo per discovery + validazione.
• I manifest nativi vengono analizzati con JSON5, quindi sono accettati commenti, virgole finali e chiavi senza virgolette purché il valore finale resti comunque un oggetto.
• Il loader del manifest legge solo i campi del manifest documentati. Evita di aggiungere qui chiavi di primo livello personalizzate.
• providerAuthEnvVars è il percorso di metadati a basso costo per probe di autenticazione, validazione dei marker env e superfici simili di autenticazione del provider che non dovrebbero avviare il runtime del plugin solo per ispezionare i nomi env.
• providerAuthChoices è il percorso di metadati a basso costo per selettori di scelta auth, risoluzione di --auth-choice, mappatura del provider preferito e semplice registrazione dei flag CLI di onboarding prima del caricamento del runtime del provider. Per i metadati del runtime wizard che richiedono codice del provider, vedi Hook runtime del provider.
• 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 ed eventuali requisiti di allowlist del package manager (ad esempio pnpm allow-build-scripts
  • pnpm rebuild <package>).

​

Correlati

• Creare plugin — come iniziare con i plugin
• Architettura dei plugin — architettura interna
• Panoramica SDK — riferimento del Plugin SDK