Manifeste du Plugin

Cette page présente le manifeste natif des plugins OpenClaw, openclaw.plugin.json. Pour les structures de bundles compatibles (Codex, Claude, Cursor), consultez Bundles de plugins.

Les formats de bundles compatibles utilisent plutôt leurs propres fichiers de manifeste :

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

OpenClaw détecte automatiquement ces structures, mais ne les valide pas par rapport au schéma openclaw.plugin.json ci-dessous. Pour un bundle compatible, OpenClaw lit les métadonnées du bundle, les racines de Skills déclarées, les racines des commandes Claude, les valeurs par défaut du fichier settings.json de Claude, les valeurs par défaut du LSP de Claude et les ensembles de hooks pris en charge, lorsque la structure correspond aux attentes d’exécution d’OpenClaw.

Chaque plugin OpenClaw natif doit fournir openclaw.plugin.json à la racine du plugin. OpenClaw le lit pour valider la configuration sans exécuter le code du plugin. Un manifeste manquant ou non valide bloque la validation de la configuration et est traité comme une erreur de plugin.

Consultez Plugins pour le guide complet du système de plugins et Modèle de capacités pour le modèle de capacités natif et les recommandations actuelles en matière de compatibilité externe.

Rôle de ce fichier

openclaw.plugin.json contient les métadonnées qu’OpenClaw lit avant de charger le code de votre plugin. L’inspection de tous ses éléments doit être suffisamment peu coûteuse pour ne pas nécessiter le démarrage de l’environnement d’exécution du plugin.

Utilisez-le pour :

• l’identité du plugin, la validation de la configuration et les indications de l’interface de configuration
• les métadonnées d’authentification, d’intégration initiale et de configuration (alias, activation automatique, variables d’environnement du fournisseur, choix d’authentification)
• les indications d’activation pour les interfaces du plan de contrôle
• la propriété des familles de modèles sous forme abrégée
• les instantanés statiques de propriété des capacités (contracts)
• les métadonnées de l’exécuteur d’assurance qualité que l’hôte partagé openclaw qa peut inspecter
• les métadonnées de configuration propres aux canaux, fusionnées dans les interfaces du catalogue et de validation

Ne l’utilisez pas pour : enregistrer un comportement d’exécution, déclarer des points d’entrée de code ou définir les métadonnées d’installation npm. Ces éléments doivent figurer dans le code de votre plugin et dans package.json.

Exemple minimal

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

Exemple détaillé

{  "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"],  "setup": {    "providers": [      {        "id": "openrouter",        "envVars": ["OPENROUTER_API_KEY"]      }    ]  },  "providerAuthAliases": {    "openrouter-coding": "openrouter"  },  "channelEnvVars": {    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "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 de catalog

catalog fournit des indications d’affichage facultatives aux navigateurs de Plugins. Les hôtes peuvent ignorer ces indications. Elles n’installent ni n’activent jamais le Plugin et ne modifient ni son comportement à l’exécution ni son niveau de confiance.

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

Référence des métadonnées des fournisseurs de génération

Les champs de métadonnées des fournisseurs de génération décrivent les signaux d’authentification statiques des fournisseurs déclarés dans la liste contracts.*GenerationProviders correspondante. OpenClaw lit ces champs avant le chargement de l’environnement d’exécution du fournisseur afin que les outils du cœur puissent déterminer si un fournisseur de génération est disponible sans importer chaque Plugin de fournisseur.

Utilisez ces champs uniquement pour des informations déclaratives peu coûteuses à vérifier. Le transport, les transformations des requêtes, le renouvellement des jetons, la validation des identifiants et le comportement réel de génération restent dans l’environnement d’exécution du 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"]          }        }      ]    }  }}

Chaque entrée de métadonnées prend en charge les champs suivants :

Chaque entrée de configSignals prend en charge les champs suivants :

Chaque condition mode prend en charge les champs suivants :

Chaque entrée de authSignals prend en charge les champs suivants :

Chaque condition providerBaseUrl prend en charge les champs suivants :

Référence des métadonnées des outils

toolMetadata utilise les mêmes structures configSignals et authSignals que les métadonnées des fournisseurs de génération, indexées par nom d’outil. contracts.tools déclare la propriété. toolMetadata déclare des éléments de preuve de disponibilité peu coûteux afin qu’OpenClaw puisse éviter d’importer l’environnement d’exécution d’un Plugin uniquement pour que sa fabrique d’outils renvoie null.

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

Les entrées toolMetadata acceptent également optional (indique que l’outil n’est pas requis pour l’activation du Plugin) et replaySafe (indique que l’exécution de l’outil peut être répétée sans risque après un tour de modèle incomplet), en plus des champs communs configSignals et authSignals décrits ci-dessus.

Si un outil ne possède aucune entrée toolMetadata, OpenClaw conserve le comportement existant et charge le Plugin propriétaire lorsque le contrat de l’outil correspond à la politique. Pour les outils situés sur un chemin critique dont la fabrique dépend de l’authentification ou de la configuration, les auteurs de Plugins doivent déclarer toolMetadata plutôt que de contraindre le cœur à importer l’environnement d’exécution pour l’interroger.

Référence de providerAuthChoices

Chaque entrée de providerAuthChoices décrit un choix d’intégration initiale ou d’authentification. OpenClaw la lit avant le chargement de l’environnement d’exécution du fournisseur. Les listes de configuration des fournisseurs utilisent ces choix du manifeste, les choix de configuration dérivés des descripteurs et les métadonnées du catalogue d’installation sans charger l’environnement d’exécution du fournisseur.

Référence de commandAliases

Utilisez commandAliases lorsqu'un plugin possède un nom de commande d'exécution que les utilisateurs pourraient placer par erreur dans plugins.allow ou tenter d'exécuter comme commande CLI racine. OpenClaw utilise ces métadonnées pour les diagnostics sans importer le code d'exécution du plugin.

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

Référence d'activation

Utilisez activation lorsque le plugin peut déclarer à faible coût quels événements du plan de contrôle doivent l'inclure dans un plan d'activation ou de chargement.

Ce bloc contient des métadonnées de planification, et non une API de cycle de vie. Il n'enregistre aucun comportement d'exécution, ne remplace pas register(...) et ne garantit pas que le code du plugin a déjà été exécuté. Le planificateur d'activation utilise ces champs pour restreindre les plugins candidats avant de se rabattre sur les métadonnées de propriété existantes du manifeste, telles que providers, channels, commandAliases, setup.providers, contracts.tools et les hooks.

Préférez les métadonnées les plus précises qui décrivent déjà la propriété. Utilisez providers, channels, commandAliases, les descripteurs de configuration ou contracts lorsque ces champs expriment la relation. Utilisez activation pour fournir des indications supplémentaires au planificateur qui ne peuvent pas être représentées par ces champs de propriété. Utilisez cliBackends au niveau supérieur pour les alias d'exécution de CLI tels que claude-cli, my-cli ou google-gemini-cli ; activation.onAgentHarnesses est réservé aux identifiants de harnais d'agent intégrés qui ne disposent pas déjà d'un champ de propriété.

Chaque plugin doit définir délibérément activation.onStartup. Définissez-le sur true uniquement lorsque le plugin doit s'exécuter au démarrage du Gateway. Définissez-le sur false lorsque le plugin est inactif au démarrage et ne doit être chargé qu'à partir de déclencheurs plus précis. L'omission de onStartup ne provoque plus implicitement le chargement du plugin au démarrage ; utilisez des métadonnées d'activation explicites pour le démarrage, le canal, la configuration, le harnais d'agent, la mémoire ou d'autres déclencheurs d'activation plus précis.

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

Consommateurs actifs actuels :

• La planification du démarrage du Gateway utilise activation.onStartup pour l'importation explicite au démarrage.
• La planification de la CLI déclenchée par une commande se rabat sur l'ancien commandAliases[].cliCommand ou commandAliases[].name.
• La planification du démarrage de l'exécution de l'agent utilise activation.onAgentHarnesses pour les harnais intégrés et cliBackends[] au niveau supérieur pour les alias d'exécution de la CLI.
• La planification de la configuration ou des canaux déclenchée par un canal se rabat sur l'ancienne propriété channels[] lorsque les métadonnées explicites d'activation du canal sont absentes.
• La planification des plugins au démarrage utilise activation.onConfigPaths pour les surfaces de configuration racine hors canal, telles que le bloc browser du plugin de navigateur fourni.
• La planification de la configuration ou de l'exécution déclenchée par un fournisseur se rabat sur les anciennes propriétés providers[] et cliBackends[] au niveau supérieur lorsque les métadonnées explicites d'activation du fournisseur sont absentes.

Les diagnostics du planificateur peuvent distinguer les indications d'activation explicites du repli sur la propriété du manifeste. Par exemple, activation-command-hint signifie que activation.onCommands correspond, tandis que manifest-command-alias signifie que le planificateur a utilisé la propriété commandAliases. Ces libellés de motif sont destinés aux diagnostics de l'hôte et aux tests ; les auteurs de plugins doivent continuer à déclarer les métadonnées qui décrivent le mieux la propriété.

Référence de qaRunners

Utilisez qaRunners lorsqu'un plugin fournit un ou plusieurs exécuteurs de transport sous la racine partagée openclaw qa. Conservez ces métadonnées légères et statiques ; l'exécution du plugin reste responsable de l'enregistrement réel dans la CLI au moyen d'une surface runtime-api.ts légère qui exporte les qaRunnerCliRegistrations correspondantes. Une adapterFactory facultative expose le transport aux scénarios d'assurance qualité partagés sans modifier l'exécuteur de la commande enregistrée.

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

L’identifiant adapterFactory doit correspondre à commandName. N’exportez pas d’enregistrements pour les commandes absentes du manifeste.

Référence de setup

Utilisez setup lorsque les surfaces de configuration et d’intégration ont besoin de métadonnées peu coûteuses appartenant au Plugin avant le chargement de l’environnement d’exécution.

{  "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  }}

Le champ cliBackends de premier niveau reste valide et continue de décrire les backends d’inférence CLI. setup.cliBackends est la surface de descripteurs propre à la configuration pour les flux de plan de contrôle et de configuration qui doivent rester fondés uniquement sur les métadonnées.

Lorsqu’ils sont présents, setup.providers et setup.cliBackends constituent la surface de recherche privilégiée, fondée d’abord sur les descripteurs, pour la découverte de la configuration. Si le descripteur ne fait que restreindre le Plugin candidat et que la configuration nécessite encore des hooks d’exécution plus riches au moment de la configuration, définissez requiresRuntime: true et conservez setup-api comme chemin d’exécution de secours.

OpenClaw inclut également setup.providers[].envVars dans les recherches génériques d’authentification des fournisseurs et de variables d’environnement. providerAuthEnvVars reste pris en charge par un adaptateur de compatibilité pendant la période d’obsolescence, mais les Plugins non intégrés qui l’utilisent encore reçoivent un diagnostic de manifeste. Les nouveaux Plugins doivent placer les métadonnées d’environnement de configuration et d’état dans setup.providers[].envVars.

Utilisez providerUsageAuthEnvVars lorsqu’un identifiant de facturation ou de niveau organisationnel doit activer resolveUsageAuth sans devenir un identifiant d’inférence. Ces noms sont ajoutés au blocage des fichiers dotenv de l’espace de travail, à leur suppression dans les processus enfants ACP, au filtrage des secrets du bac à sable et au nettoyage général des secrets. L’environnement d’exécution du fournisseur continue de lire et de classifier la valeur dans resolveUsageAuth.

OpenClaw peut également déduire des choix de configuration simples à partir de setup.providers[].authMethods lorsqu’aucune entrée de configuration n’est disponible, ou lorsque setup.requiresRuntime: false indique que l’environnement d’exécution de configuration est inutile. Les entrées explicites providerAuthChoices restent privilégiées pour les libellés personnalisés, les indicateurs CLI, la portée de l’intégration et les métadonnées de l’assistant.

Définissez requiresRuntime: false uniquement lorsque ces descripteurs suffisent à la surface de configuration. OpenClaw traite la valeur explicite false comme un contrat fondé uniquement sur les descripteurs et n’exécute ni setup-api ni openclaw.setupEntry pour la recherche de configuration. Si un Plugin fondé uniquement sur les descripteurs fournit malgré tout l’une de ces entrées d’exécution de configuration, OpenClaw signale un diagnostic supplémentaire et continue de l’ignorer. L’omission de requiresRuntime conserve le comportement de secours historique afin de ne pas interrompre les Plugins existants qui ont ajouté des descripteurs sans cet indicateur.

Comme la recherche de configuration peut exécuter du code setup-api appartenant au Plugin, les valeurs normalisées setup.providers[].id et setup.cliBackends[] doivent rester uniques parmi les Plugins découverts. Une propriété ambiguë provoque un échec sécurisé au lieu de choisir un gagnant selon l’ordre de découverte.

Lorsque l’environnement d’exécution de configuration est effectivement exécuté, les diagnostics du registre de configuration signalent une divergence des descripteurs si setup-api enregistre un fournisseur ou un backend CLI que les descripteurs du manifeste ne déclarent pas, ou si un descripteur ne possède aucun enregistrement d’exécution correspondant. Ces diagnostics sont supplémentaires et ne rejettent pas les Plugins historiques.

Référence de setup.providers

authEvidence est destiné aux marqueurs locaux d’identifiants appartenant au fournisseur qui peuvent être vérifiés sans charger le code d’exécution. Ces vérifications doivent rester peu coûteuses et locales : aucun appel réseau, aucune lecture du trousseau ou d’un gestionnaire de secrets, aucune commande d’interpréteur de commandes et aucune interrogation de l’API du fournisseur.

Entrées de preuve prises en charge :

Champs de setup

Référence de uiHints

uiHints est une table de correspondance entre les noms des champs de configuration et de petites indications de rendu. Les clés peuvent contenir des points pour les champs de configuration imbriqués, mais aucun segment de chemin ne peut être __proto__, constructor ou prototype ; la configuration rejette ces noms.

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

Chaque indication de champ peut inclure :

Référence de contracts

Utilisez contracts uniquement pour les métadonnées statiques de propriété des capacités qu’OpenClaw peut lire sans importer l’environnement d’exécution du Plugin.

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

Chaque liste est facultative :

contracts.embeddedExtensionFactories est conservé pour les fabriques d’extensions intégrées réservées au serveur d’application Codex. Les transformations intégrées des résultats d’outils doivent plutôt déclarer contracts.agentToolResultMiddleware et s’enregistrer avec api.registerAgentToolResultMiddleware(...). Les Plugins installés peuvent utiliser le même point d’intégration d’intergiciel uniquement lorsqu’il est explicitement activé et seulement pour les environnements d’exécution qu’ils déclarent dans contracts.agentToolResultMiddleware.

Les Plugins installés qui ont besoin du niveau de stratégie pré-outil approuvé par l’hôte doivent déclarer chaque identifiant local enregistré dans contracts.trustedToolPolicies et être explicitement activés. Les Plugins intégrés conservent le chemin de stratégie approuvée existant, mais les Plugins installés dont les identifiants de stratégie ne sont pas déclarés sont rejetés avant l’enregistrement. Les identifiants de stratégie sont limités au Plugin qui les enregistre : deux Plugins peuvent donc tous deux déclarer et enregistrer workflow-budget, mais un même Plugin ne peut pas enregistrer deux fois le même identifiant local.

Les enregistrements d’exécution api.registerTool(...) doivent correspondre à contracts.tools. La découverte des outils utilise cette liste pour charger uniquement les environnements d’exécution des Plugins susceptibles de gérer les outils demandés.

Les Plugins fournisseurs qui implémentent resolveExternalAuthProfiles doivent déclarer contracts.externalAuthProviders ; les hooks d’authentification externe non déclarés sont ignorés.

Les Plugins fournisseurs qui implémentent à la fois resolveUsageAuth et fetchUsageSnapshot doivent déclarer dans contracts.usageProviders chaque identifiant de fournisseur découvert automatiquement. La découverte de l’utilisation lit ce contrat avant de charger le code d’exécution, puis vérifie les deux hooks après avoir chargé uniquement les propriétaires déclarés.

Les fournisseurs généraux d’incorporation doivent déclarer contracts.embeddingProviders pour chaque adaptateur enregistré avec api.registerEmbeddingProvider(...). Utilisez le contrat général pour la génération vectorielle réutilisable, y compris pour les fournisseurs utilisés par la recherche en mémoire. contracts.memoryEmbeddingProviders est une compatibilité obsolète propre à l’incorporation en mémoire et n’est conservé que pendant la migration des fournisseurs existants vers le point d’intégration générique des fournisseurs d’incorporation.

Les fournisseurs de workers doivent déclarer dans contracts.workerProviders chaque identifiant utilisé avec api.registerWorkerProvider(...). Le cœur persiste l’intention durable avant d’appeler provision ; les fournisseurs valident leurs paramètres avant toute allocation externe, et les appels répétés avec le même identifiant d’opération doivent adopter la même location. Le cœur persiste également cet instantané des paramètres validés et le transmet avec leaseId à inspect({ leaseId, profile }) et destroy({ leaseId, profile }), y compris après la modification ou la suppression du profil nommé. La destruction est idempotente, l’inspection renvoie l’union fermée des états active / destroyed / unknown, et le contenu de la clé privée SSH n’est référencé que par SecretRef. Les points de terminaison SSH provisionnés doivent également inclure une valeur publique hostKey issue d’un résultat de provisionnement approuvé, exactement sous la forme algorithm base64, sans nom d’hôte ni commentaire, afin que le cœur puisse épingler l’hôte avant la connexion. Les fournisseurs qui créent des références d’identité dynamiques peuvent implémenter la méthode faisant autorité resolveSshIdentity({ leaseId, profile, keyRef }) ; les fournisseurs qui ne l’implémentent pas utilisent le résolveur générique de secrets du cœur. Une réponse faisant autorité unknown rend orphelin un enregistrement local actif ; après une demande de destruction persistée, elle confirme la suppression.

contracts.gatewayMethodDispatch accepte actuellement "authenticated-request". Il s’agit d’un garde-fou d’hygiène d’API pour les routes HTTP natives d’un Plugin qui distribuent intentionnellement des méthodes du plan de contrôle du Gateway au sein du processus, et non d’un bac à sable contre les Plugins natifs malveillants. Utilisez-le uniquement pour des surfaces intégrées ou opérateur étroitement contrôlées qui exigent déjà l’authentification HTTP du Gateway. Une route autorisée reste accessible lorsque l’admission des travaux racine du Gateway est fermée uniquement si elle déclare aussi auth: "gateway" et la valeur propre à la route gatewayRuntimeScopeSurface: "trusted-operator" ; les routes sœurs ordinaires du même Plugin restent derrière la frontière d’admission. Cela permet de garder accessibles l’état de suspension et la reprise sans accorder à l’ensemble du Plugin un contournement de l’admission. Maintenez l’analyse et la mise en forme des réponses dans des limites strictes hors de la distribution ; tout travail substantiel ou entraînant une mutation doit passer par la distribution de méthodes du Gateway, qui gère l’admission et l’application de la portée.

Référence de configContracts

Utilisez configContracts pour le comportement de configuration détenu par le manifeste dont les utilitaires génériques du cœur ont besoin sans importer l’environnement d’exécution du Plugin : détection des indicateurs dangereux, cibles de migration SecretRef et restriction des chemins de configuration hérités.

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

Chaque entrée dangerousFlags prend en charge :

secretInputs prend en charge :

Référence de mediaUnderstandingProviderMetadata

Utilisez mediaUnderstandingProviderMetadata lorsqu’un fournisseur de compréhension multimédia possède des modèles par défaut, une priorité de repli d’authentification automatique ou une prise en charge native des documents dont les utilitaires génériques du cœur ont besoin avant le chargement de l’exécution. Les clés doivent également être déclarées dans contracts.mediaUnderstandingProviders.

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

Chaque entrée de fournisseur peut inclure :

Référence de channelConfigs

Utilisez channelConfigs lorsqu’un Plugin de canal a besoin de métadonnées de configuration peu coûteuses avant le chargement de l’exécution. La découverte en lecture seule de la configuration et de l’état du canal peut utiliser directement ces métadonnées pour les canaux externes configurés lorsqu’aucune entrée de configuration n’est disponible, ou lorsque setup.requiresRuntime: false indique que l’exécution n’est pas nécessaire à la configuration.

channelConfigs constitue une métadonnée du manifeste du Plugin, et non une nouvelle section de configuration utilisateur de premier niveau. Les utilisateurs configurent toujours les instances de canal sous channels.<channel-id>. OpenClaw lit les métadonnées du manifeste pour déterminer quel Plugin possède ce canal configuré avant l’exécution du code du Plugin.

Pour un Plugin de canal, configSchema et channelConfigs décrivent des chemins différents :

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

Les Plugins non intégrés qui déclarent channels[] doivent également déclarer les entrées channelConfigs correspondantes. Sans elles, OpenClaw peut toujours charger le Plugin, mais le schéma de configuration du chemin à froid, la configuration et les surfaces de l’interface de contrôle ne peuvent pas connaître la forme des options appartenant au canal avant l’exécution du Plugin.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled et nativeSkillsAutoEnabled peuvent déclarer des valeurs statiques par défaut pour auto lors des vérifications de configuration des commandes exécutées avant le chargement de l’exécution du canal. Les canaux intégrés peuvent également publier les mêmes valeurs par défaut via package.json#openclaw.channel.commands, avec leurs autres métadonnées de catalogue de canaux appartenant au paquet.

{  "channelConfigs": {    "matrix": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "homeserverUrl": { "type": "string" }        }      },      "uiHints": {        "homeserverUrl": {          "label": "URL du serveur d’accueil",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "Connexion au serveur d’accueil Matrix",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

Chaque entrée de canal peut inclure :

Remplacement d’un autre Plugin de canal

Utilisez preferOver lorsque votre Plugin est le propriétaire privilégié d’un identifiant de canal qu’un autre Plugin peut également fournir. Les cas courants comprennent le renommage de l’identifiant d’un Plugin, un Plugin autonome qui remplace un Plugin intégré ou un fork maintenu qui conserve le même identifiant de canal pour assurer la compatibilité de la configuration.

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

Lorsque channels.chat est configuré, OpenClaw tient compte à la fois de l’identifiant du canal et de l’identifiant du Plugin privilégié. Si le Plugin de priorité inférieure a été sélectionné uniquement parce qu’il est intégré ou activé par défaut, OpenClaw le désactive dans la configuration d’exécution effective afin qu’un seul Plugin possède le canal et ses outils. La sélection explicite de l’utilisateur reste prioritaire : si l’utilisateur active explicitement les deux Plugins (via plugins.allow ou une configuration substantielle de plugins.entries), OpenClaw préserve ce choix et signale des diagnostics de duplication de canal ou d’outil au lieu de modifier silencieusement l’ensemble de Plugins demandé.

Limitez preferOver aux identifiants de Plugins qui peuvent réellement fournir le même canal. Il ne s’agit pas d’un champ de priorité général et il ne renomme pas les clés de configuration utilisateur.

Référence de modelSupport

Utilisez modelSupport lorsqu’OpenClaw doit déduire votre Plugin fournisseur à partir d’identifiants abrégés de modèles tels que gpt-5.6-sol ou claude-sonnet-4.6 avant le chargement de l’exécution du Plugin.

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

OpenClaw applique l’ordre de priorité suivant :

• les références explicites provider/model utilisent les métadonnées du manifeste providers du propriétaire
• modelPatterns est prioritaire sur modelPrefixes
• si un Plugin non intégré et un Plugin intégré correspondent tous deux, le Plugin non intégré est prioritaire
• toute ambiguïté restante est ignorée jusqu’à ce que l’utilisateur ou la configuration précise un fournisseur

Champs :

Les entrées modelPatterns sont compilées via compileSafeRegex, qui rejette les motifs contenant des répétitions imbriquées (par exemple (a+)+$). Les motifs qui échouent au contrôle de sécurité sont ignorés silencieusement, tout comme les expressions régulières syntaxiquement invalides. Gardez les motifs simples et évitez les quantificateurs imbriqués.

Référence de modelCatalog

Utilisez modelCatalog lorsqu’OpenClaw doit connaître les métadonnées des modèles du fournisseur avant de charger l’exécution du Plugin. Il s’agit de la source appartenant au manifeste pour les lignes fixes du catalogue, les alias de fournisseurs, les règles de suppression et le mode de découverte. L’actualisation à l’exécution relève toujours du code d’exécution du fournisseur, mais le manifeste indique au cœur quand l’exécution est nécessaire.

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

Champs de premier niveau :

aliases participe à la recherche de la propriété du fournisseur pour la planification du catalogue de modèles. Les cibles d'alias doivent être des fournisseurs de niveau supérieur appartenant au même plugin. Lorsqu'une liste filtrée par fournisseur utilise un alias, OpenClaw peut lire le manifeste propriétaire et appliquer les remplacements d'API et d'URL de base de l'alias sans charger l'environnement d'exécution du fournisseur. Les alias n'étendent pas les listes de catalogue non filtrées ; les listes générales n'affichent que les entrées du fournisseur canonique propriétaire.

suppressions remplace l'ancien hook suppressBuiltInModel de l'environnement d'exécution du fournisseur. Les entrées de suppression ne sont prises en compte que lorsque le fournisseur appartient au plugin ou est déclaré comme clé de modelCatalog.aliases ciblant un fournisseur détenu. Les hooks de suppression de l'environnement d'exécution ne sont plus appelés pendant la résolution du modèle.

Champs des fournisseurs :

Champs des modèles :

Champs de suppression :

Ne placez pas de données disponibles uniquement à l'exécution dans modelCatalog. Utilisez static uniquement lorsque les entrées du manifeste sont suffisamment complètes pour permettre aux listes filtrées par fournisseur et aux interfaces de sélection d'ignorer la découverte du registre et de l'environnement d'exécution. Utilisez refreshable lorsque les entrées du manifeste constituent des données initiales ou complémentaires utiles et affichables, mais qu'une actualisation ou un cache peut ajouter d'autres entrées ultérieurement ; les entrées actualisables ne font pas autorité à elles seules. Utilisez runtime lorsqu'OpenClaw doit charger l'environnement d'exécution du fournisseur pour connaître la liste.

Référence de modelIdNormalization

Utilisez modelIdNormalization pour le nettoyage peu coûteux des identifiants de modèles appartenant au fournisseur qui doit avoir lieu avant le chargement de l'environnement d'exécution du fournisseur. Cela permet de conserver les alias tels que les noms courts de modèles, les anciens identifiants locaux au fournisseur et les règles de préfixe de proxy dans le manifeste du plugin propriétaire plutôt que dans les tables centrales de sélection des modèles.

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

Champs des fournisseurs :

Référence de providerEndpoints

Utilisez providerEndpoints pour la classification des points de terminaison que la politique générique de requêtes doit connaître avant le chargement de l'environnement d'exécution du fournisseur. Le cœur définit toujours la signification de chaque endpointClass ; les manifestes des plugins définissent les métadonnées d'hôte et d'URL de base.

Les plugins de fournisseurs officiellement externalisés sont exclus de la distribution principale ; leurs manifestes restent donc invisibles jusqu'à leur installation. Leurs providerEndpoints doivent également être reproduits dans scripts/lib/official-external-provider-catalog.json afin que la classification des points de terminaison continue de fonctionner sans le plugin ; un test de contrat garantit cette reproduction.

Champs des points de terminaison :

Référence de providerRequest

Utilisez providerRequest pour les métadonnées légères de compatibilité des requêtes dont la politique générique de requêtes a besoin sans charger l’environnement d’exécution du fournisseur. Conservez la réécriture des charges utiles propre au comportement dans les hooks d’exécution du fournisseur ou dans les assistants partagés de la famille de fournisseurs.

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

Champs du fournisseur :

Référence de secretProviderIntegrations

Utilisez secretProviderIntegrations lorsqu’un plugin peut publier un préréglage réutilisable de fournisseur d’exécution SecretRef. OpenClaw lit ces métadonnées avant le chargement de l’environnement d’exécution du plugin, enregistre l’appartenance au plugin dans secrets.providers.<alias>.pluginIntegration et confie la résolution effective des secrets à l’environnement d’exécution SecretRef. Les préréglages sont exposés uniquement pour les plugins intégrés et les plugins installés découverts depuis les racines d’installation de plugins gérées, comme les installations git et ClawHub.

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

La clé de la table de correspondance est l’identifiant de l’intégration. Si providerAlias est omis, OpenClaw utilise l’identifiant de l’intégration comme alias du fournisseur SecretRef. Les alias de fournisseurs doivent respecter le format normal des alias de fournisseurs SecretRef, par exemple team-secrets ou onepassword-work.

Lorsqu’un opérateur sélectionne le préréglage, OpenClaw écrit une référence de fournisseur telle que :

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

Au démarrage ou au rechargement, OpenClaw résout ce fournisseur en chargeant les métadonnées actuelles du manifeste du plugin, en vérifiant que le plugin propriétaire est installé et actif, puis en matérialisant la commande d’exécution à partir du manifeste. La désactivation ou la suppression du plugin révoque le fournisseur pour les SecretRefs actifs. Les opérateurs qui souhaitent une configuration d’exécution autonome peuvent toujours définir directement des fournisseurs manuels command/args.

Seuls les préréglages source: "exec" sont actuellement pris en charge. command doit être ${node}, et args[0] doit être un script de résolution ./ relatif à la racine du plugin. Au démarrage ou au rechargement, OpenClaw le matérialise en utilisant l’exécutable Node actuel et le chemin absolu du script dans le plugin. Les options Node telles que --require, --import, --loader, --env-file, --eval et --print ne font pas partie du contrat des préréglages du manifeste. Les opérateurs qui ont besoin de commandes autres que Node peuvent configurer directement des fournisseurs d’exécution manuels autonomes.

OpenClaw déduit trustedDirs pour les préréglages du manifeste à partir de la racine du plugin et, pour les préréglages ${node}, du répertoire de l’exécutable Node actuel. Les trustedDirs définis dans le manifeste sont ignorés. Les autres options du fournisseur d’exécution, telles que timeoutMs, noOutputTimeoutMs, maxOutputBytes, jsonOnly, env, passEnv et allowInsecurePath, sont transmises à la configuration normale du fournisseur d’exécution SecretRef.

Référence de modelPricing

Utilisez modelPricing lorsqu’un fournisseur doit définir le comportement de tarification du plan de contrôle avant le chargement de l’environnement d’exécution. Le cache de tarification du Gateway lit ces métadonnées sans importer le code d’exécution du fournisseur.

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

Champs du fournisseur :

Champs de la source :

Index des fournisseurs OpenClaw

L’index des fournisseurs OpenClaw est un ensemble de métadonnées d’aperçu détenues par OpenClaw pour les fournisseurs dont les plugins ne sont peut-être pas encore installés. Il ne fait pas partie d’un manifeste de plugin. Les manifestes de plugins restent la référence pour les plugins installés. L’index des fournisseurs est le contrat interne de secours que les futures interfaces de sélection de fournisseurs installables et de modèles avant installation utiliseront lorsqu’un plugin de fournisseur n’est pas installé.

Ordre de priorité du catalogue :

1. Configuration utilisateur.
2. modelCatalog du manifeste du plugin installé.
3. Cache du catalogue de modèles issu d’une actualisation explicite.
4. Lignes d’aperçu de l’index des fournisseurs OpenClaw.

L’index des fournisseurs ne doit contenir ni secrets, ni état d’activation, ni hooks d’exécution, ni données de modèles propres à un compte actif. Ses catalogues d’aperçu utilisent la même structure de ligne de fournisseur modelCatalog que les manifestes de plugins, mais doivent rester limités aux métadonnées d’affichage stables, sauf si des champs de l’adaptateur d’exécution tels que api, baseUrl, la tarification ou les indicateurs de compatibilité sont intentionnellement maintenus alignés sur le manifeste du plugin installé. Les fournisseurs disposant d’une découverte dynamique via /models doivent écrire les lignes actualisées par le chemin explicite du cache du catalogue de modèles plutôt que de faire appeler les API des fournisseurs par les processus normaux d’affichage de la liste ou d’intégration.

Les entrées de l’index des fournisseurs peuvent également contenir des métadonnées de plugin installable pour les fournisseurs dont le plugin a été extrait du cœur ou n’est pas encore installé pour une autre raison. Ces métadonnées reproduisent le modèle du catalogue des canaux : le nom du paquet, la spécification d’installation npm, l’intégrité attendue et de simples libellés de choix d’authentification suffisent pour afficher une option de configuration installable. Une fois le plugin installé, son manifeste prévaut et l’entrée de l’index des fournisseurs est ignorée pour ce fournisseur.

openclaw doctor --fix migre vers contracts.* un petit ensemble fermé de clés de capacité historiques situées au niveau supérieur du manifeste : speechProviders, mediaUnderstandingProviders, imageGenerationProviders et tools. Aucune d’entre elles, ni aucune autre liste de capacités, n’est désormais lue comme champ de premier niveau du manifeste ; le chargement normal du manifeste ne les reconnaît que sous contracts.

Manifeste ou package.json

Les deux fichiers remplissent des rôles différents :

Si vous ne savez pas à quel emplacement une métadonnée doit appartenir, appliquez cette règle :

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

Champs de package.json qui influent sur la découverte

Certaines métadonnées de plugin antérieures à l’exécution résident intentionnellement dans le bloc openclaw de package.json plutôt que dans openclaw.plugin.json. openclaw.bundle et openclaw.bundle.json ne sont pas des contrats de plugin OpenClaw ; les plugins natifs doivent utiliser openclaw.plugin.json ainsi que les champs package.json#openclaw pris en charge ci-dessous.

Exemples importants :

Les métadonnées du manifeste déterminent les choix de fournisseur, de canal et de configuration qui apparaissent lors de l’intégration avant le chargement de l’environnement d’exécution. package.json#openclaw.install indique au processus d’intégration comment récupérer ou activer ce Plugin lorsque l’utilisateur sélectionne l’un de ces choix. Ne déplacez pas les indications d’installation dans openclaw.plugin.json.

openclaw.install.minHostVersion est appliqué pendant l’installation et le chargement du registre des manifestes pour les sources de Plugins non intégrées. Les valeurs non valides sont rejetées ; les valeurs valides mais plus récentes entraînent l’exclusion des Plugins externes sur les hôtes plus anciens. Les Plugins sources intégrés sont supposés avoir la même version que le dépôt de travail de l’hôte.

openclaw.install.requiredPlatformPackages est destiné aux paquets npm qui fournissent les binaires natifs requis au moyen d’alias facultatifs propres à chaque plateforme. Indiquez le nom nu du paquet npm pour chaque alias de plateforme pris en charge. Pendant l’installation npm, OpenClaw vérifie uniquement l’alias déclaré dont les contraintes dans le fichier de verrouillage correspondent à l’hôte actuel. Si npm signale une réussite mais omet cet alias, OpenClaw réessaie une fois avec un cache neuf et annule l’installation si l’alias est toujours absent.

openclaw.compat.pluginApi est appliqué pendant l’installation des paquets provenant de sources de Plugins non intégrées. Utilisez-le pour définir la version minimale de l’API du SDK ou de l’environnement d’exécution des Plugins OpenClaw avec laquelle le paquet a été compilé. Cette valeur peut être plus stricte que minHostVersion lorsqu’un paquet de Plugin nécessite une API plus récente tout en conservant une indication d’installation inférieure pour d’autres processus. Par défaut, la synchronisation des versions officielles d’OpenClaw relève les versions minimales existantes des API des Plugins officiels à la version de la publication d’OpenClaw, mais les publications propres à un Plugin peuvent conserver une version minimale inférieure lorsque le paquet prend intentionnellement en charge des hôtes plus anciens. N’utilisez pas uniquement la version du paquet comme contrat de compatibilité. peerDependencies.openclaw reste une métadonnée de paquet npm ; OpenClaw utilise le contrat openclaw.compat.pluginApi pour les décisions de compatibilité lors de l’installation.

Les métadonnées officielles d’installation à la demande doivent utiliser clawhubSpec lorsque le Plugin est publié sur ClawHub ; le processus d’intégration considère alors ClawHub comme la source distante privilégiée et enregistre les informations sur l’artefact ClawHub après l’installation. npmSpec reste la solution de repli de compatibilité pour les paquets qui n’ont pas encore migré vers ClawHub.

L’épinglage exact de la version npm se trouve déjà dans npmSpec, par exemple "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". Les entrées officielles du catalogue externe doivent associer les spécifications exactes à expectedIntegrity afin que les processus de mise à jour échouent de manière sûre si l’artefact npm récupéré ne correspond plus à la version épinglée. Pour des raisons de compatibilité, l’intégration interactive continue de proposer les spécifications npm provenant de registres de confiance, notamment les noms de paquets nus et les balises de distribution. Les diagnostics du catalogue peuvent distinguer les sources exactes, flottantes, épinglées par intégrité, sans intégrité, présentant une incohérence de nom de paquet ou un choix par défaut non valide. Ils avertissent également lorsque expectedIntegrity est présent sans qu’aucune source npm valide ne permette de l’épingler. Lorsque expectedIntegrity est présent, les processus d’installation et de mise à jour l’appliquent ; lorsqu’il est omis, la résolution du registre est enregistrée sans épinglage d’intégrité.

Les Plugins de canal doivent fournir openclaw.setupEntry lorsque les analyses de l’état, de la liste des canaux ou des SecretRef doivent identifier les comptes configurés sans charger l’environnement d’exécution complet. Le point d’entrée de configuration doit exposer les métadonnées du canal ainsi que des adaptateurs de configuration, d’état et de secrets utilisables sans risque pendant la configuration ; conservez les clients réseau, les processus d’écoute du Gateway et les environnements d’exécution de transport dans le point d’entrée principal de l’extension.

Les champs de point d’entrée de l’environnement d’exécution ne remplacent pas les vérifications des limites du paquet appliquées aux champs de point d’entrée source. Par exemple, openclaw.runtimeExtensions ne peut pas rendre chargeable un chemin openclaw.extensions qui sort du paquet.

openclaw.install.allowInvalidConfigRecovery est volontairement limité. Il ne permet pas d’installer des configurations arbitrairement défectueuses. À l’heure actuelle, il permet uniquement aux processus d’installation de récupérer après certaines défaillances obsolètes de mise à niveau de Plugins intégrés, comme l’absence du chemin d’un Plugin intégré ou une entrée channels.<id> obsolète correspondant à ce même Plugin intégré. Les erreurs de configuration sans rapport bloquent toujours l’installation et orientent les opérateurs vers openclaw doctor --fix.

openclaw.channel.persistedAuthState est une métadonnée de paquet destinée à un petit module de vérification :

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

Utilisez-la lorsque les processus de configuration, de diagnostic, d’état ou de détection en lecture seule nécessitent une vérification booléenne peu coûteuse de l’authentification avant le chargement complet du Plugin de canal. L’état d’authentification persistante n’est pas l’état configuré du canal : n’utilisez pas ces métadonnées pour activer automatiquement des Plugins, réparer les dépendances d’exécution ou décider si l’environnement d’exécution d’un canal doit être chargé. L’exportation ciblée doit être une petite fonction qui lit uniquement l’état persistant ; ne la faites pas transiter par le module d’exportation principal de l’environnement d’exécution complet du canal.

openclaw.channel.configuredState suit la même structure pour les vérifications peu coûteuses d’un état configuré reposant uniquement sur l’environnement :

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

Utilisez-la lorsqu’un canal peut déterminer son état configuré à partir de l’environnement ou d’autres entrées légères ne relevant pas de l’environnement d’exécution. Si la vérification nécessite la résolution complète de la configuration ou l’environnement d’exécution réel du canal, conservez plutôt cette logique dans le hook config.hasConfiguredState du Plugin.

Ordre de priorité de la découverte (identifiants de Plugins en double)

OpenClaw découvre les Plugins à partir de trois racines, vérifiées dans cet ordre : les Plugins intégrés fournis avec OpenClaw, la racine d’installation globale (~/.openclaw/extensions) et la racine de l’espace de travail actuel (<workspace>/.openclaw/extensions), auxquelles s’ajoutent toutes les entrées explicites de plugins.load.paths.

Si deux éléments découverts partagent le même id, seul le manifeste ayant la priorité la plus élevée est conservé ; les doublons de priorité inférieure sont supprimés au lieu d’être chargés à ses côtés. Ordre de priorité, du plus élevé au plus faible :

1. Sélectionné par la configuration — chemin explicitement épinglé dans plugins.entries.<id>
2. Installation globale correspondant à un enregistrement d’installation suivi — Plugin installé via openclaw plugin install/openclaw plugin update et reconnu par le suivi des installations d’OpenClaw pour ce même identifiant, même lorsque celui-ci appartient également à un Plugin intégré
3. Intégré — Plugins fournis avec OpenClaw
4. Espace de travail — Plugins découverts relativement à l’espace de travail actuel
5. Tout autre candidat découvert

Conséquences :

• Une copie dérivée ou obsolète d’un Plugin intégré, présente sans suivi dans l’espace de travail ou la racine globale, ne masquera pas la version intégrée.
• Pour remplacer un Plugin intégré, exécutez openclaw plugin install pour cet identifiant afin que l’installation globale suivie ait priorité sur la copie intégrée, ou épinglez un chemin précis via plugins.entries.<id> afin qu’il l’emporte grâce à la priorité de sélection par la configuration.
• Les doublons supprimés sont consignés afin que Doctor et les diagnostics de démarrage puissent signaler la copie écartée.
• Dans les diagnostics, les remplacements de doublons sélectionnés par la configuration sont présentés comme des remplacements explicites, mais génèrent tout de même un avertissement afin que les dérivations obsolètes et les masquages accidentels restent visibles.

Exigences du schéma JSON

• Chaque plugin doit fournir un schéma JSON, 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 ou de l’écriture de la configuration, et non lors de l’exécution.
• Lorsque vous étendez ou dupliquez un plugin intégré avec de nouvelles clés de configuration, mettez simultanément à jour le configSchema du fichier openclaw.plugin.json de ce plugin. Les schémas des plugins intégrés sont stricts : ajouter plugins.entries.<id>.config.myNewKey à la configuration utilisateur sans ajouter myNewKey à configSchema.properties entraînera donc un rejet avant le chargement de l’environnement d’exécution du plugin.

Exemple d’extension de schéma :

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

Comportement de validation

• Les clés channels.* inconnues sont des erreurs, sauf si l’identifiant du canal est déclaré par le manifeste d’un plugin. Si le même identifiant figure également dans plugins.allow, plugins.entries ou plugins.installs (un plugin référencé, mais actuellement introuvable), OpenClaw transforme plutôt cette erreur en avertissement.
• Les références à des identifiants de plugins inconnus dans plugins.entries.<id>, plugins.allow et plugins.deny sont des avertissements (« entrée de configuration obsolète ignorée »), et non des erreurs, afin que les mises à niveau et les plugins supprimés ou renommés ne bloquent pas le démarrage du Gateway.
• La référence à un identifiant de plugin inconnu dans plugins.slots.memory est une erreur, à l’exception du plugin externe officiel connu memory-lancedb, qui génère plutôt un avertissement.
• Si un plugin est installé, mais que son manifeste ou son schéma est absent ou défectueux, la validation échoue et Doctor signale l’erreur du plugin.
• Si la configuration d’un plugin existe, mais que le plugin est désactivé, la configuration est conservée et un avertissement est affiché dans Doctor et les journaux.

Consultez la référence de configuration pour le schéma plugins.* complet.

Remarques

• Le manifeste est obligatoire pour les plugins OpenClaw natifs, y compris ceux chargés depuis le système de fichiers local. L’environnement d’exécution charge toujours le module du plugin séparément ; le manifeste sert uniquement à la découverte et à la validation.
• Les manifestes natifs sont analysés avec JSON5 ; les commentaires, les virgules finales et les clés sans guillemets sont donc acceptés, à condition que la valeur finale reste un objet.
• Seuls les champs de manifeste documentés sont lus par le chargeur de manifestes. Évitez les clés personnalisées de premier niveau.
• channels, providers, cliBackends et skills peuvent tous être omis lorsqu’un plugin n’en a pas besoin.
• providerCatalogEntry doit rester léger et ne doit pas importer de code d’exécution étendu ; utilisez-le pour les métadonnées statiques du catalogue de fournisseurs ou des descripteurs de découverte ciblés, et non pour l’exécution lors du traitement des requêtes.
• Les types de plugins exclusifs sont sélectionnés au moyen de plugins.slots.* : kind: "memory" via plugins.slots.memory (memory-core par défaut), et kind: "context-engine" via plugins.slots.contextEngine (legacy par défaut).
• Déclarez le type de plugin exclusif dans ce manifeste. La propriété OpenClawPluginDefinition.kind du point d’entrée d’exécution est obsolète et n’est conservée que comme solution de repli de compatibilité pour les anciens plugins.
• Les métadonnées de variables d’environnement (setup.providers[].envVars, providerAuthEnvVars obsolète et channelEnvVars) sont uniquement déclaratives. L’état, l’audit, la validation de la remise Cron et les autres surfaces en lecture seule continuent d’appliquer la politique de confiance et d’activation effective des plugins avant de considérer une variable d’environnement comme configurée.
• Pour les métadonnées de l’assistant d’exécution qui nécessitent le code du fournisseur, consultez les hooks d’exécution des fournisseurs.
• Si votre plugin dépend de modules natifs, documentez les étapes de compilation et toutes les exigences relatives à la liste d’autorisation du gestionnaire de paquets (par exemple, allow-build-scripts de pnpm et pnpm rebuild <package>).

Pages connexes