​

Manifeste de plugin (openclaw.plugin.json)

• Bundle Codex : .codex-plugin/plugin.json
• Bundle Claude : .claude-plugin/plugin.json ou la structure de composant Claude par défaut sans manifeste
• Bundle Cursor : .cursor-plugin/plugin.json

​

À quoi sert ce fichier

• l’identité du plugin
• la validation de configuration
• les métadonnées d’authentification et d’onboarding qui doivent être disponibles sans démarrer le runtime du plugin
• les métadonnées d’alias et d’activation automatique qui doivent être résolues avant le chargement du runtime du plugin
• les métadonnées abrégées de propriété de famille de modèles qui doivent auto-activer le plugin avant le chargement du runtime
• les instantanés statiques de propriété de capacités utilisés pour le câblage de compatibilité groupée et la couverture de contrat
• les métadonnées de configuration spécifiques à un canal qui doivent être fusionnées dans les surfaces de catalogue et de validation sans charger le runtime
• les indications d’interface de configuration

• enregistrer le comportement du runtime
• déclarer les points d’entrée du code
• les métadonnées d’installation npm

​

Exemple minimal

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

​

Exemple enrichi

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider plugin",
  "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": "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"
      }
    }
  }
}

​

Référence des champs de premier niveau

​

Référence providerAuthChoices

​

Référence uiHints

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

​

Référence 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"]
  }
}

​

Référence channelConfigs

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

​

Référence modelSupport

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

• les références explicites provider/model utilisent les métadonnées de manifeste providers du propriétaire
• modelPatterns l’emporte sur modelPrefixes
• si un plugin non groupé et un plugin groupé correspondent tous deux, le plugin non groupé l’emporte
• l’ambiguïté restante est ignorée jusqu’à ce que l’utilisateur ou la configuration spécifie un fournisseur

​

Manifeste versus package.json

• si OpenClaw doit la connaître avant de charger le code du plugin, placez-la dans openclaw.plugin.json
• si elle concerne le packaging, les fichiers de point d’entrée ou le comportement d’installation npm, placez-la dans package.json

​

Champs de package.json qui affectent la découverte

​

Exigences JSON Schema

• Chaque plugin doit fournir un JSON Schema, même s’il n’accepte aucune configuration.
• Un schéma vide est acceptable (par exemple { "type": "object", "additionalProperties": false }).
• Les schémas sont validés lors de la lecture/écriture de configuration, pas au runtime.

​

Comportement de validation

• Les clés inconnues channels.* sont des erreurs, sauf si l’ID du canal est déclaré par un manifeste de plugin.
• plugins.entries.<id>, plugins.allow, plugins.deny, et plugins.slots.* doivent référencer des IDs de plugin détectables. Les IDs inconnus sont des erreurs.
• Si un plugin est installé mais possède un manifeste ou un schéma cassé ou manquant, la validation échoue et Doctor signale l’erreur du plugin.
• Si une configuration de plugin existe mais que le plugin est désactivé, la configuration est conservée et un avertissement est affiché dans Doctor + les journaux.

​

Remarques

• Le manifeste est obligatoire pour les plugins natifs OpenClaw, y compris les chargements locaux depuis le système de fichiers.
• Le runtime charge toujours le module du plugin séparément ; le manifeste sert uniquement à la découverte + validation.
• Les manifestes natifs sont analysés avec JSON5, donc les commentaires, virgules finales et clés non citées sont acceptés tant que la valeur finale reste un objet.
• Seuls les champs de manifeste documentés sont lus par le chargeur de manifeste. Évitez d’ajouter ici des clés personnalisées au niveau supérieur.
• providerAuthEnvVars est le chemin léger de métadonnées pour les sondes d’authentification, la validation de marqueurs env et les surfaces similaires d’authentification fournisseur qui ne doivent pas démarrer le runtime du plugin juste pour inspecter des noms de variables d’environnement.
• providerAuthChoices est le chemin léger de métadonnées pour les sélecteurs de choix d’authentification, la résolution --auth-choice, le mapping du fournisseur préféré, et l’enregistrement simple des drapeaux CLI d’onboarding avant le chargement du runtime fournisseur. Pour les métadonnées d’assistant runtime qui nécessitent le code du fournisseur, voir Hooks runtime de fournisseur.
• Les types exclusifs de plugin sont sélectionnés via plugins.slots.*.
  • kind: "memory" est sélectionné par plugins.slots.memory.
  • kind: "context-engine" est sélectionné par plugins.slots.contextEngine (par défaut : legacy intégré).
• channels, providers, cliBackends, et skills peuvent être omis lorsqu’un plugin n’en a pas besoin.
• Si votre plugin dépend de modules natifs, documentez les étapes de build et toute exigence de liste d’autorisation du gestionnaire de paquets (par exemple, pnpm allow-build-scripts
  • pnpm rebuild <package>).

​

Lié

• Créer des plugins — démarrer avec les plugins
• Architecture des plugins — architecture interne
• Vue d’ensemble du SDK — référence du SDK de plugin