Manifeste de Plugin

Cette page concerne uniquement le manifeste natif de Plugin OpenClaw.

Pour les dispositions de bundles compatibles, consultez Bundles de Plugin.

Les formats de bundle compatibles utilisent des fichiers de manifeste différents :

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

OpenClaw détecte également automatiquement ces dispositions de bundles, mais elles ne sont pas validées avec le schéma openclaw.plugin.json décrit ici.

Pour les bundles compatibles, OpenClaw lit actuellement les métadonnées du bundle ainsi que les racines de Skills déclarées, les racines de commandes Claude, les valeurs par défaut settings.json du bundle Claude, les valeurs par défaut LSP du bundle Claude, et les packs de hooks pris en charge lorsque la disposition correspond aux attentes du runtime OpenClaw.

Chaque Plugin OpenClaw natif doit inclure un fichier openclaw.plugin.json à la racine du Plugin. OpenClaw utilise ce manifeste pour valider la configuration sans exécuter le code du Plugin. Les manifestes manquants ou invalides sont traités comme des erreurs de Plugin et bloquent la validation de la configuration.

Consultez le guide complet du système de Plugin : Plugins. Pour le modèle de capacité natif et les recommandations actuelles de compatibilité externe : Modèle de capacité.

Ce que fait ce fichier

openclaw.plugin.json contient les métadonnées qu’OpenClaw lit avant de charger votre code de Plugin. Tout ce qui suit doit être suffisamment léger pour être inspecté sans démarrer le runtime du Plugin.

Utilisez-le pour :

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

Ne l’utilisez pas pour : enregistrer un comportement runtime, déclarer des points d’entrée de code, ou des métadonnées d’installation npm. Ces éléments appartiennent au code de votre Plugin et à package.json.

Exemple minimal

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

Exemple complet

{  "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 des métadonnées de fournisseur de génération

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

Utilisez ces champs uniquement pour des faits déclaratifs peu coûteux. Le transport, les transformations de requêtes, le rafraîchissement de jetons, la validation des identifiants et le comportement de génération réel restent dans l’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 :

Chaque entrée configSignals prend en charge :

Chaque garde mode prend en charge :

Chaque entrée authSignals prend en charge :

Chaque garde providerBaseUrl prend en charge :

Référence des métadonnées d’outil

toolMetadata utilise les mêmes formes configSignals et authSignals que les métadonnées de fournisseur de génération, indexées par nom d’outil. contracts.tools déclare la propriété. toolMetadata déclare des preuves de disponibilité peu coûteuses afin qu’OpenClaw puisse éviter d’importer l’exécution d’un Plugin uniquement pour que sa fabrique d’outils retourne 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"]        }      ]    }  }}

Si un outil n’a pas de toolMetadata, OpenClaw conserve le comportement existant et charge le Plugin propriétaire lorsque le contrat d’outil correspond à la politique. Pour les outils des chemins critiques dont la fabrique dépend de l’authentification ou de la configuration, les auteurs de Plugin doivent déclarer toolMetadata au lieu de faire importer l’exécution au cœur pour l’interroger.

Référence providerAuthChoices

Chaque entrée providerAuthChoices décrit un choix d’intégration ou d’authentification. OpenClaw lit ceci avant le chargement de l’exécution du fournisseur. Les listes de configuration de fournisseur utilisent ces choix de manifeste, les choix de configuration dérivés des descripteurs et les métadonnées du catalogue d’installation sans charger l’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 peuvent placer par erreur dans plugins.allow ou essayer 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/de chargement.

Ce bloc est constitué de métadonnées de planification, pas d’une API de cycle de vie. Il n’enregistre pas de 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 réduire les Plugins candidats avant de se rabattre sur les métadonnées existantes de propriété du manifeste comme providers, channels, commandAliases, setup.providers, contracts.tools et les hooks.

Préférez les métadonnées les plus étroites 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 les indications supplémentaires du planificateur qui ne peuvent pas être représentées par ces champs de propriété. Utilisez cliBackends de premier niveau pour les alias d’exécution CLI comme claude-cli, my-cli ou google-gemini-cli; activation.onAgentHarnesses est réservé aux identifiants de harnais d’agents intégrés qui ne disposent pas déjà d’un champ de propriété.

Ce bloc contient uniquement des métadonnées. Il n’enregistre pas de comportement d’exécution et ne remplace pas register(...), setupEntry ni d’autres points d’entrée d’exécution/de Plugin. Les consommateurs actuels l’utilisent comme indication de réduction avant un chargement plus large des Plugins, donc l’absence de métadonnées d’activation hors démarrage ne coûte généralement que des performances ; elle ne doit pas modifier la correction tant que les replis de propriété du manifeste existent encore.

Chaque Plugin doit définir activation.onStartup intentionnellement. Définissez-le sur true uniquement lorsque le Plugin doit s’exécuter pendant le démarrage du Gateway. Définissez-le sur false lorsque le Plugin est inerte au démarrage et ne doit se charger qu’à partir de déclencheurs plus étroits. Omettre onStartup ne charge plus implicitement le Plugin au démarrage ; utilisez des métadonnées d’activation explicites pour le démarrage, les canaux, la configuration, le harnais d’agent, la mémoire ou d’autres déclencheurs d’activation plus étroits.

{  "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 CLI déclenchée par commande se rabat sur l’ancien commandAliases[].cliCommand ou commandAliases[].name
• la planification du démarrage de l’exécution d’agent utilise activation.onAgentHarnesses pour les harnais intégrés et cliBackends[] de premier niveau pour les alias d’exécution CLI
• la planification de configuration/de canal déclenchée par canal se rabat sur l’ancienne propriété channels[] lorsque les métadonnées explicites d’activation de canal sont absentes
• la planification des Plugins au démarrage utilise activation.onConfigPaths pour les surfaces de configuration racine hors canal, comme le bloc browser du Plugin de navigateur groupé
• la planification de configuration/d’exécution déclenchée par fournisseur se rabat sur l’ancienne propriété providers[] et cliBackends[] de premier niveau lorsque les métadonnées explicites d’activation de 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 correspondait, tandis que manifest-command-alias signifie que le planificateur a utilisé la propriété commandAliases à la place. Ces libellés de raison 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. Gardez ces métadonnées légères et statiques ; l’exécution du Plugin possède toujours l’enregistrement CLI réel via une surface runtime-api.ts légère qui exporte qaRunnerCliRegistrations.

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

référence setup

Utilisez setup lorsque les surfaces de configuration initiale et d’onboarding ont besoin de métadonnées peu coûteuses propres au plugin avant le chargement du runtime.

{  "setup": {    "providers": [      {        "id": "openai",        "authMethods": ["api-key"],        "envVars": ["OPENAI_API_KEY"],        "authEvidence": [          {            "type": "local-file-with-env",            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",            "requiresAllEnv": ["OPENAI_PROJECT"],            "credentialMarker": "openai-local-credentials",            "source": "openai local credentials"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

Le cliBackends de premier niveau reste valide et continue de décrire les backends d’inférence CLI. setup.cliBackends est la surface de descripteur propre à la configuration initiale pour les flux de plan de contrôle/configuration initiale qui doivent rester limités aux métadonnées.

Lorsqu’ils sont présents, setup.providers et setup.cliBackends sont la surface de recherche à descripteur prioritaire préférée pour la découverte de configuration initiale. Si le descripteur ne fait que restreindre le plugin candidat et que la configuration initiale a encore besoin de hooks runtime plus riches au moment de la configuration initiale, définissez requiresRuntime: true et conservez setup-api en place comme chemin d’exécution de repli.

OpenClaw inclut aussi setup.providers[].envVars dans les recherches génériques d’authentification de fournisseur et de variables d’environnement. providerAuthEnvVars reste pris en charge via un adaptateur de compatibilité pendant la fenêtre de dépréciation, 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 initiale/état sur setup.providers[].envVars.

OpenClaw peut aussi déduire des choix simples de configuration initiale à partir de setup.providers[].authMethods lorsqu’aucune entrée de configuration initiale n’est disponible, ou lorsque setup.requiresRuntime: false déclare que le runtime de configuration initiale est inutile. Les entrées explicites providerAuthChoices restent préférées pour les libellés personnalisés, les indicateurs CLI, le périmètre d’onboarding et les métadonnées d’assistant.

Définissez requiresRuntime: false uniquement lorsque ces descripteurs suffisent pour la surface de configuration initiale. OpenClaw traite false explicite comme un contrat limité aux descripteurs et n’exécutera pas setup-api ni openclaw.setupEntry pour la recherche de configuration initiale. Si un plugin limité aux descripteurs fournit encore l’une de ces entrées runtime de configuration initiale, OpenClaw signale un diagnostic additif et continue de l’ignorer. L’omission de requiresRuntime conserve le comportement de repli hérité afin que les plugins existants qui ont ajouté des descripteurs sans l’indicateur ne soient pas cassés.

Comme la recherche de configuration initiale peut exécuter du code setup-api propre au plugin, les valeurs normalisées setup.providers[].id et setup.cliBackends[] doivent rester uniques parmi les plugins découverts. Une propriété ambiguë échoue de façon fermée au lieu de choisir un gagnant selon l’ordre de découverte.

Lorsque le runtime de configuration initiale s’exécute, les diagnostics du registre de configuration initiale signalent une dérive de descripteur si setup-api enregistre un fournisseur ou un backend CLI que les descripteurs de manifeste ne déclarent pas, ou si un descripteur n’a aucun enregistrement runtime correspondant. Ces diagnostics sont additifs et ne rejettent pas les plugins hérités.

référence setup.providers

authEvidence est destiné aux marqueurs d’identifiants locaux propres au fournisseur qui peuvent être vérifiés sans charger de code runtime. Ces vérifications doivent rester peu coûteuses et locales : aucun appel réseau, aucune lecture de trousseau ou de gestionnaire de secrets, aucune commande shell, et aucune sonde d’API fournisseur.

Entrées de preuve prises en charge :

champs setup

référence uiHints

uiHints est une table de correspondance entre les noms de champs de configuration et de petites indications de rendu.

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

Utilisez contracts uniquement pour les métadonnées statiques de propriété de capacités qu’OpenClaw peut lire sans importer le runtime 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"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "migrationProviders": ["hermes"],    "gatewayMethodDispatch": ["authenticated-request"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

Chaque liste est optionnelle :

contracts.embeddedExtensionFactories est conservé pour les fabriques d’extensions uniquement destinées au serveur d’application Codex intégré. Les transformations intégrées de résultats d’outils doivent déclarer contracts.agentToolResultMiddleware et s’enregistrer avec api.registerAgentToolResultMiddleware(...) à la place. Les plugins installés peuvent utiliser le même point de middleware uniquement lorsqu’il est explicitement activé et uniquement pour les runtimes qu’ils déclarent dans contracts.agentToolResultMiddleware.

Les plugins installés qui ont besoin du niveau de politique 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 politique approuvée existant, mais les plugins installés avec des identifiants de politique non déclarés sont rejetés avant l’enregistrement. Les identifiants de politique sont limités au plugin qui les enregistre, donc deux plugins peuvent tous deux déclarer et enregistrer workflow-budget; un seul plugin ne peut pas enregistrer deux fois le même identifiant local.

Les enregistrements runtime api.registerTool(...) doivent correspondre à contracts.tools. La découverte des outils utilise cette liste pour charger uniquement les runtimes de plugins pouvant posséder 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 fournisseurs d’embeddings généraux 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 les fournisseurs consommés par la recherche en mémoire. contracts.memoryEmbeddingProviders est une compatibilité obsolète propre à la mémoire et reste uniquement pendant que les fournisseurs existants migrent vers le point d’intégration générique des fournisseurs d’embeddings.

contracts.gatewayMethodDispatch accepte actuellement "authenticated-request". C’est un garde-fou d’hygiène d’API pour les routes HTTP natives de plugins qui dispatchent intentionnellement des méthodes du plan de contrôle Gateway dans le processus, et non un bac à sable contre les plugins natifs malveillants. Utilisez-le uniquement pour des surfaces intégrées ou opérateur étroitement relues qui exigent déjà l’authentification HTTP Gateway.

Référence mediaUnderstandingProviderMetadata

Utilisez mediaUnderstandingProviderMetadata lorsqu’un fournisseur de compréhension des médias a des modèles par défaut, une priorité de fallback d’authentification automatique ou une prise en charge native des documents dont les helpers génériques du cœur ont besoin avant le chargement du runtime. 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"]    }  }}

Chaque entrée de fournisseur peut inclure :

Référence channelConfigs

Utilisez channelConfigs lorsqu’un plugin de canal a besoin de métadonnées de config peu coûteuses avant le chargement du runtime. La découverte en lecture seule de la configuration ou du statut du canal peut utiliser ces métadonnées directement pour les canaux externes configurés lorsqu’aucune entrée de configuration n’est disponible, ou lorsque setup.requiresRuntime: false déclare que le runtime de configuration est inutile.

channelConfigs est une métadonnée de manifeste de plugin, pas une nouvelle section de config utilisateur de niveau supérieur. Les utilisateurs configurent toujours les instances de canaux sous channels.<channel-id>. OpenClaw lit les métadonnées du manifeste pour décider quel plugin possède ce canal configuré avant l’exécution du code runtime 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 aussi déclarer les entrées channelConfigs correspondantes. Sans elles, OpenClaw peut toujours charger le plugin, mais les surfaces de schéma de config en chemin froid, de configuration et de Control UI ne peuvent pas connaître la forme des options possédées par le canal avant l’exécution du runtime du plugin.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled et nativeSkillsAutoEnabled peuvent déclarer des valeurs par défaut statiques auto pour les vérifications de config de commandes qui s’exécutent avant le chargement du runtime du canal. Les canaux intégrés peuvent aussi 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 package.

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

Chaque entrée de canal peut inclure :

Remplacer un autre plugin de canal

Utilisez preferOver lorsque votre plugin est le propriétaire préféré d’un identifiant de canal qu’un autre plugin peut également fournir. Les cas courants sont un identifiant de plugin renommé, un plugin autonome qui remplace un plugin intégré, ou un fork maintenu qui conserve le même identifiant de canal pour la compatibilité de config.

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

Lorsque channels.chat est configuré, OpenClaw prend en compte à la fois l’identifiant de canal et l’identifiant du plugin préféré. 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 config runtime effective afin qu’un seul plugin possède le canal et ses outils. La sélection explicite de l’utilisateur l’emporte toujours : si l’utilisateur active explicitement les deux plugins, OpenClaw préserve ce choix et signale des diagnostics de doublons de canal ou d’outil au lieu de modifier silencieusement l’ensemble de plugins demandé.

Gardez preferOver limité aux identifiants de plugins qui peuvent réellement fournir le même canal. Ce n’est pas un champ de priorité général et il ne renomme pas les clés de config utilisateur.

Référence modelSupport

Utilisez modelSupport quand OpenClaw doit déduire votre plugin de fournisseur à partir d’identifiants de modèle abrégés comme gpt-5.5 ou claude-sonnet-4.6 avant le chargement du runtime du plugin.

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

OpenClaw applique cette priorité :

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

Champs :

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

Référence modelCatalog

Utilisez modelCatalog quand OpenClaw doit connaître les métadonnées de modèle du fournisseur avant de charger le runtime du plugin. C’est la source détenue par le manifeste pour les lignes de catalogue fixes, les alias de fournisseur, les règles de suppression et le mode de découverte. L’actualisation au runtime reste dans le code de runtime du fournisseur, mais le manifeste indique au cœur quand le runtime est requis.

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

Champs de premier niveau :

aliases participe à la recherche de propriété du fournisseur pour la planification du catalogue de modèles. Les cibles d’alias doivent être des fournisseurs de premier niveau détenus par le même plugin. Quand une liste filtrée par fournisseur utilise un alias, OpenClaw peut lire le manifeste propriétaire et appliquer les remplacements d’API/de base URL de l’alias sans charger le runtime du fournisseur. Les alias n’étendent pas les listes de catalogue non filtrées ; les listes larges émettent uniquement les lignes du fournisseur canonique propriétaire.

suppressions remplace l’ancien hook de runtime fournisseur suppressBuiltInModel. Les entrées de suppression sont honorées uniquement quand le fournisseur est détenu par le plugin ou déclaré comme clé modelCatalog.aliases ciblant un fournisseur détenu. Les hooks de suppression runtime ne sont plus appelés pendant la résolution de modèle.

Champs de fournisseur :

Champs de modèle :

Champs de suppression :

Ne mettez pas de données uniquement runtime dans modelCatalog. Utilisez static uniquement quand les lignes du manifeste sont assez complètes pour permettre aux surfaces de liste filtrée par fournisseur et de sélection d’ignorer la découverte registre/runtime. Utilisez refreshable quand les lignes du manifeste sont des graines listables utiles ou des compléments, mais qu’une actualisation/un cache peut ajouter d’autres lignes plus tard ; les lignes actualisables ne font pas autorité à elles seules. Utilisez runtime quand OpenClaw doit charger le runtime du fournisseur pour connaître la liste.

Référence modelIdNormalization

Utilisez modelIdNormalization pour un nettoyage peu coûteux des identifiants de modèle détenu par le fournisseur qui doit se produire avant le chargement du runtime du fournisseur. Cela conserve les alias comme les noms de modèle courts, les identifiants hérités 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 principales de sélection de modèle.

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

Champs de fournisseur :

Référence providerEndpoints

Utilisez providerEndpoints pour la classification des points de terminaison que la stratégie générique de requête doit connaître avant le chargement du runtime du fournisseur. Le cœur détient toujours la signification de chaque endpointClass ; les manifestes de plugin détiennent les métadonnées d’hôte et de base URL.

Champs d’endpoint :

Référence providerRequest

Utilisez providerRequest pour des métadonnées économiques de compatibilité des requêtes dont la politique de requête générique a besoin sans charger le runtime du fournisseur. Conservez la réécriture de charge utile propre au comportement dans les hooks de runtime du fournisseur ou dans les helpers partagés de famille de fournisseurs.

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

Champs du fournisseur :

Référence secretProviderIntegrations

Utilisez secretProviderIntegrations lorsqu’un plugin peut publier un préréglage réutilisable de fournisseur exec SecretRef. OpenClaw lit ces métadonnées avant le chargement du runtime du plugin, stocke la propriété du plugin dans secrets.providers.<alias>.pluginIntegration et laisse la résolution effective des secrets au runtime SecretRef. Les préréglages ne sont exposés que pour les plugins groupés et les plugins installés découverts à partir des 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 map est l’id d’intégration. Si providerAlias est omis, OpenClaw utilise l’id d’intégration comme alias de fournisseur SecretRef. Les alias de fournisseur doivent correspondre au modèle normal d’alias de fournisseur 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 comme :

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

Au démarrage/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 exec à partir du manifeste. Désactiver ou supprimer le plugin révoque le fournisseur pour les SecretRefs actifs. Les opérateurs qui veulent une configuration exec autonome peuvent toujours écrire directement des fournisseurs command/args manuels.

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 avec ./. OpenClaw le matérialise au démarrage/rechargement vers l’exécutable Node actuel et le chemin absolu du script dans le plugin. Les options Node comme --require, --import, --loader, --env-file, --eval et --print ne font pas partie du contrat de préréglage de manifeste. Les opérateurs qui ont besoin de commandes non Node peuvent configurer directement des fournisseurs exec manuels autonomes.

OpenClaw dérive trustedDirs pour les préréglages de 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 par le manifeste sont ignorés. Les autres options de fournisseur exec comme timeoutMs, maxOutputBytes, jsonOnly, env, passEnv et allowInsecurePath sont transmises à la configuration normale du fournisseur exec SecretRef.

Référence modelPricing

Utilisez modelPricing lorsqu’un fournisseur doit contrôler le comportement de tarification du plan de contrôle avant le chargement du runtime. Le cache de tarification du Gateway lit ces métadonnées sans importer le code de runtime du fournisseur.

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

Champs du fournisseur :

Champs de source :

Index des fournisseurs OpenClaw

L’Index des fournisseurs OpenClaw est une métadonnée d’aperçu détenue 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 l’autorité pour les plugins installés. L’Index des fournisseurs est le contrat de repli interne que les futures surfaces de sélection de modèle avant installation et de fournisseurs installables consommeront lorsqu’un plugin de fournisseur n’est pas installé.

Ordre d’autorité du catalogue :

1. Configuration utilisateur.
2. Manifeste modelCatalog du plugin installé.
3. Cache de catalogue de modèles issu d’un rafraîchissement explicite.
4. Lignes d’aperçu de l’Index des fournisseurs OpenClaw.

L’Index des fournisseurs ne doit pas contenir de secrets, d’état activé, de hooks de runtime ni de données de modèle spécifiques à un compte en direct. Ses catalogues d’aperçu utilisent la même forme 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 d’adaptateur de runtime comme api, baseUrl, la tarification ou les indicateurs de compatibilité sont intentionnellement maintenus alignés avec le manifeste du plugin installé. Les fournisseurs avec découverte /models en direct doivent écrire les lignes rafraîchies via le chemin explicite du cache de catalogue de modèles au lieu de faire appeler les API du fournisseur par l’affichage normal de liste ou l’onboarding.

Les entrées de l’Index des fournisseurs peuvent aussi transporter des métadonnées de plugin installable pour les fournisseurs dont le plugin a été déplacé hors du noyau ou n’est pas encore installé pour une autre raison. Ces métadonnées reflètent le modèle du catalogue de canaux : nom de package, spécification d’installation npm, intégrité attendue et libellés économiques de choix d’authentification suffisent à afficher une option de configuration installable. Une fois le plugin installé, son manifeste l’emporte et l’entrée de l’Index des fournisseurs est ignorée pour ce fournisseur.

Les clés de capacité de niveau supérieur héritées sont obsolètes. Utilisez openclaw doctor --fix pour déplacer speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders et webSearchProviders sous contracts ; le chargement normal du manifeste ne traite plus ces champs de niveau supérieur comme propriété de capacité.

Manifeste ou package.json

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

Si vous ne savez pas où placer une métadonnée, utilisez 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 l’empaquetage, les fichiers d’entrée ou le comportement d’installation npm, placez-la dans package.json

Champs package.json qui affectent la découverte

Certaines métadonnées de plugin pré-runtime résident intentionnellement dans package.json sous le bloc openclaw au lieu de 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 plus les champs package.json#openclaw pris en charge ci-dessous.

Exemples importants :

Les métadonnées du manifeste déterminent quels choix de provider/canal/configuration apparaissent dans l’intégration avant le chargement de l’exécution. package.json#openclaw.install indique à l’intégration comment récupérer ou activer ce Plugin lorsque l’utilisateur choisit 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 de manifestes pour les sources de Plugins non groupés. Les valeurs invalides sont rejetées ; les valeurs plus récentes mais valides ignorent les Plugins externes sur les hôtes plus anciens. Les Plugins source groupés sont supposés être co-versionnés avec le checkout de l’hôte.

openclaw.install.requiredPlatformPackages est destiné aux packages npm qui exposent des binaires natifs requis via des alias optionnels propres à la plateforme. Listez le nom nu du package npm pour chaque alias de plateforme pris en charge. Pendant l’installation npm, OpenClaw vérifie uniquement l’alias déclaré dont les contraintes de lockfile correspondent à l’hôte actuel. Si npm signale une réussite mais omet cet alias, OpenClaw réessaie une fois avec un cache frais et annule l’installation si l’alias est toujours manquant.

openclaw.compat.pluginApi est appliqué pendant l’installation du package pour les sources de Plugins non groupés. Utilisez-le pour le plancher de l’API SDK/runtime Plugin OpenClaw contre lequel le package a été construit. Il peut être plus strict que minHostVersion lorsqu’un package Plugin nécessite une API plus récente tout en conservant une indication d’installation plus basse pour d’autres flux. La synchronisation des releases officielles OpenClaw augmente par défaut les planchers d’API des Plugins officiels existants à la version de release OpenClaw, mais les releases limitées aux Plugins peuvent conserver un plancher plus bas lorsque le package prend intentionnellement en charge des hôtes plus anciens. N’utilisez pas la seule version du package comme contrat de compatibilité. peerDependencies.openclaw reste une métadonnée de package npm ; OpenClaw utilise le contrat openclaw.compat.pluginApi pour les décisions de compatibilité d’installation.

Les métadonnées officielles d’installation à la demande doivent utiliser clawhubSpec lorsque le Plugin est publié sur ClawHub ; l’intégration traite cela comme la source distante préférée et enregistre les faits d’artefact ClawHub après l’installation. npmSpec reste le repli de compatibilité pour les packages qui ne sont pas encore passés à ClawHub.

L’épinglage exact de version npm réside déjà dans npmSpec, par exemple "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". Les entrées de catalogue externes officielles doivent associer des specs exactes à expectedIntegrity afin que les flux de mise à jour échouent de manière fermée si l’artefact npm récupéré ne correspond plus à la release épinglée. L’intégration interactive propose toujours des specs npm de registre de confiance, y compris les noms de packages nus et les dist-tags, pour compatibilité. Les diagnostics de catalogue peuvent distinguer les sources exactes, flottantes, épinglées par intégrité, sans intégrité, avec incompatibilité de nom de package et avec choix par défaut invalide. Ils avertissent aussi lorsque expectedIntegrity est présent mais qu’il n’existe aucune source npm valide qu’il peut épingler. Lorsque expectedIntegrity est présent, les flux d’installation/mise à jour l’appliquent ; lorsqu’il est omis, la résolution du registre est enregistrée sans épingle d’intégrité.

Les Plugins de canal doivent fournir openclaw.setupEntry lorsque l’état, la liste des canaux ou les analyses SecretRef doivent identifier les comptes configurés sans charger l’exécution complète. L’entrée de configuration doit exposer les métadonnées de canal ainsi que des adaptateurs de configuration, d’état et de secrets sûrs pour la configuration ; gardez les clients réseau, les écouteurs Gateway et les runtimes de transport dans le point d’entrée principal de l’extension.

Les champs de point d’entrée d’exécution ne remplacent pas les contrôles de frontière de package pour les champs de point d’entrée source. Par exemple, openclaw.runtimeExtensions ne peut pas rendre chargeable un chemin openclaw.extensions qui s’échappe.

openclaw.install.allowInvalidConfigRecovery est intentionnellement étroit. Il ne rend pas installables des configurations arbitrairement cassées. Aujourd’hui, il autorise seulement les flux d’installation à récupérer après des échecs spécifiques de mise à niveau de Plugins groupés obsolètes, comme un chemin de Plugin groupé manquant ou une entrée channels.<id> obsolète pour ce même Plugin groupé. Les erreurs de configuration sans rapport bloquent toujours l’installation et envoient les opérateurs vers openclaw doctor --fix.

openclaw.channel.persistedAuthState est une métadonnée de package pour un minuscule module de vérification :

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

Utilisez-la lorsque les flux de configuration, doctor, état ou présence en lecture seule nécessitent une sonde d’authentification oui/non peu coûteuse avant le chargement du Plugin de canal complet. L’état d’authentification persistée n’est pas l’état de canal configuré : n’utilisez pas ces métadonnées pour activer automatiquement des Plugins, réparer des dépendances d’exécution ou décider si l’exécution d’un canal doit se charger. L’export cible doit être une petite fonction qui lit uniquement l’état persisté ; ne le routez pas via le barrel complet de l’exécution du canal.

openclaw.channel.configuredState suit la même forme pour les vérifications peu coûteuses de configuration uniquement par env :

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

Utilisez-la lorsqu’un canal peut répondre à l’état configuré à partir de l’env ou d’autres petites entrées hors exécution. Si la vérification nécessite une résolution complète de configuration ou la vraie exécution du canal, conservez cette logique dans le hook Plugin config.hasConfiguredState à la place.

Précédence de découverte (ids de Plugins en double)

OpenClaw découvre les Plugins à partir de plusieurs racines. Pour l’ordre brut d’analyse du système de fichiers, consultez Ordre d’analyse des Plugins . Si deux découvertes partagent le même id, seul le manifeste à la précédence la plus élevée est conservé ; les doublons de précédence inférieure sont supprimés au lieu d’être chargés à côté de lui.

Précédence, de la plus élevée à la plus basse :

1. Sélectionné par la configuration — un chemin explicitement épinglé dans plugins.entries.<id>
2. Groupé — Plugins livrés avec OpenClaw
3. Installation globale — Plugins installés dans la racine globale des Plugins OpenClaw
4. Workspace — Plugins découverts relativement au workspace actuel

Implications :

• Une copie forkée ou obsolète d’un Plugin groupé présente dans le workspace ne masquera pas la build groupée.
• Pour remplacer réellement un Plugin groupé par un Plugin local, épinglez-le via plugins.entries.<id> afin qu’il gagne par précédence plutôt que de dépendre de la découverte du workspace.
• Les suppressions de doublons sont journalisées afin que Doctor et les diagnostics de démarrage puissent pointer vers la copie écartée.
• Les remplacements de doublons sélectionnés par la configuration sont formulés comme des remplacements explicites dans les diagnostics, mais émettent tout de même un avertissement afin que les forks obsolètes et les masquages accidentels restent visibles.

Exigences du JSON Schema

• 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 au moment de la lecture/écriture de la configuration, pas à l’exécution.
• Lors de l’extension ou du fork d’un plugin intégré avec de nouvelles clés de configuration, mettez à jour en même temps le configSchema du openclaw.plugin.json de ce plugin. Les schémas des plugins intégrés sont stricts, donc l’ajout de plugins.entries.<id>.config.myNewKey dans la configuration utilisateur sans ajouter myNewKey à configSchema.properties sera rejeté avant le chargement du runtime 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’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 plugins découvrables. 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.

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

Notes

• Le manifeste est obligatoire pour les plugins OpenClaw natifs, y compris les chargements depuis le système de fichiers local. 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, les virgules finales et les 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 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 runtime étendu ; utilisez-le pour des métadonnées statiques de catalogue de fournisseurs ou des descripteurs de découverte ciblés, pas pour une exécution au moment des requêtes.
• Les types de plugins exclusifs sont sélectionnés via plugins.slots.* : kind: "memory" via plugins.slots.memory, kind: "context-engine" via plugins.slots.contextEngine (legacy par défaut).
• Déclarez le type de plugin exclusif dans ce manifeste. OpenClawPluginDefinition.kind dans l’entrée runtime est obsolète et reste uniquement comme fallback de compatibilité pour les plugins plus anciens.
• Les métadonnées de variables d’environnement (setup.providers[].envVars, providerAuthEnvVars obsolète et channelEnvVars) sont uniquement déclaratives. Le statut, l’audit, la validation de livraison cron et les autres surfaces en lecture seule appliquent toujours la politique de confiance du plugin et d’activation effective avant de considérer une variable d’environnement comme configurée.
• Pour les métadonnées de l’assistant runtime nécessitant du code fournisseur, consultez les hooks de runtime fournisseur.
• 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>).

Connexe