English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Plugins

Manifeste de Plugin

Cette page concerne uniquement le manifeste de Plugin OpenClaw natif.

Pour les agencements de bundles compatibles, consultez bundles de Plugin.

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

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

OpenClaw détecte aussi automatiquement ces agencements de bundles, mais ils ne sont pas validés par rapport au 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 skill 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 l’agencement correspond aux attentes du runtime OpenClaw.

Chaque Plugin OpenClaw natif doit fournir un fichier openclaw.plugin.json dans 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 Plugins : Plugins. Pour le modèle de capacités natif et les recommandations actuelles de compatibilité externe : modèle de capacités.

Rôle de ce fichier

openclaw.plugin.json contient les métadonnées qu’OpenClaw lit avant de charger votre code de Plugin. Tous les éléments ci-dessous doivent être assez peu coûteux à inspecter sans démarrer le runtime du Plugin.

Utilisez-le pour :

  • l’identité du Plugin, la validation de la 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 runner QA que l’hôte partagé openclaw qa peut inspecter
  • les métadonnées de configuration propres au canal, 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 définir les métadonnées d’installation npm. Ces éléments appartiennent à votre code de Plugin et à 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"],
  "providerAuthEnvVars": {
    "openrouter": ["OPENROUTER_API_KEY"]
  },
  "providerAuthAliases": {
    "openrouter-coding": "openrouter"
  },
  "channelEnvVars": {
    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]
  },
  "providerAuthChoices": [
    {
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
      "choiceLabel": "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

Champ Obligatoire Type Signification
id Oui string ID canonique du Plugin. C’est l’ID utilisé dans plugins.entries.<id>.
configSchema Oui object JSON Schema en ligne pour la configuration de ce Plugin.
enabledByDefault Non true Marque un Plugin intégré comme activé par défaut. Omettez-le, ou définissez une valeur autre que true, pour laisser le Plugin désactivé par défaut.
enabledByDefaultOnPlatforms Non string[] Marque un Plugin intégré comme activé par défaut uniquement sur les plateformes Node.js listées, par exemple ["darwin"]. La configuration explicite reste prioritaire.
legacyPluginIds Non string[] Anciens ID qui se normalisent vers cet ID canonique de Plugin.
autoEnableWhenConfiguredProviders Non string[] ID de fournisseurs qui doivent activer automatiquement ce Plugin lorsque l’authentification, la configuration ou les références de modèles les mentionnent.
kind Non "memory" | "context-engine" Déclare un type exclusif de Plugin utilisé par plugins.slots.*.
channels Non string[] ID de canaux possédés par ce Plugin. Utilisés pour la découverte et la validation de configuration.
providers Non string[] ID de fournisseurs possédés par ce Plugin.
providerDiscoveryEntry Non string Chemin du module léger de découverte de fournisseur, relatif à la racine du Plugin, pour les métadonnées de catalogue de fournisseurs limitées au manifeste qui peuvent être chargées sans activer tout le runtime du Plugin.
modelSupport Non object Métadonnées abrégées de familles de modèles, possédées par le manifeste, utilisées pour charger automatiquement le Plugin avant le runtime.
modelCatalog Non object Métadonnées déclaratives de catalogue de modèles pour les fournisseurs possédés par ce Plugin. Il s’agit du contrat de plan de contrôle pour les futurs listings en lecture seule, l’onboarding, les sélecteurs de modèles, les alias et la suppression sans charger le runtime du Plugin.
modelPricing Non object Politique de recherche de tarification externe possédée par le fournisseur. Utilisez-la pour exclure les fournisseurs locaux/auto-hébergés des catalogues de tarification distants ou mapper les références de fournisseurs vers les ID de catalogue OpenRouter/LiteLLM sans coder en dur les ID de fournisseurs dans le cœur.
modelIdNormalization Non object Nettoyage des alias/préfixes d’ID de modèles possédé par le fournisseur, qui doit s’exécuter avant le chargement du runtime du fournisseur.
providerEndpoints Non object[] Métadonnées host/baseUrl de points de terminaison, possédées par le manifeste, pour les routes de fournisseurs que le cœur doit classifier avant le chargement du runtime du fournisseur.
providerRequest Non object Métadonnées légères de famille de fournisseurs et de compatibilité de requêtes utilisées par la politique de requête générique avant le chargement du runtime du fournisseur.
cliBackends Non string[] ID de backends d’inférence CLI possédés par ce Plugin. Utilisés pour l’auto-activation au démarrage depuis des références de configuration explicites.
syntheticAuthRefs Non string[] Références de fournisseurs ou de backends CLI dont le hook d’authentification synthétique possédé par le Plugin doit être sondé pendant la découverte à froid des modèles avant le chargement du runtime.
nonSecretAuthMarkers Non string[] Valeurs d’API key d’espace réservé possédées par le Plugin intégré, représentant un état d’identifiants non secrets locaux, OAuth ou ambiants.
commandAliases Non object[] Noms de commandes possédés par ce Plugin qui doivent produire des diagnostics de configuration et de CLI conscients du Plugin avant le chargement du runtime.
providerAuthEnvVars Non Record<string, string[]> Métadonnées d’environnement de compatibilité obsolètes pour la recherche d’authentification/statut des fournisseurs. Préférez setup.providers[].envVars pour les nouveaux Plugins ; OpenClaw les lit encore pendant la fenêtre de dépréciation.
providerAuthAliases Non Record<string, string> ID de fournisseurs qui doivent réutiliser un autre ID de fournisseur pour la recherche d’authentification, par exemple un fournisseur de codage qui partage l’API key et les profils d’authentification du fournisseur de base.
channelEnvVars Non Record<string, string[]> Métadonnées légères d’environnement de canal qu’OpenClaw peut inspecter sans charger le code du Plugin. Utilisez-les pour la configuration de canaux pilotée par l’environnement ou les surfaces d’authentification que les assistants génériques de démarrage/configuration doivent voir.
providerAuthChoices Non object[] Métadonnées légères de choix d’authentification pour les sélecteurs d’onboarding, la résolution de fournisseur préféré et le câblage simple des indicateurs CLI.
activation Non object Métadonnées légères de planificateur d’activation pour le chargement déclenché par le démarrage, les fournisseurs, les commandes, les canaux, les routes et les capacités. Métadonnées uniquement ; le runtime du Plugin reste propriétaire du comportement réel.
setup Non object Descripteurs légers de configuration/onboarding que les surfaces de découverte et de configuration peuvent inspecter sans charger le runtime du Plugin.
qaRunners Non object[] Descripteurs légers d’exécuteurs QA utilisés par l’hôte partagé openclaw qa avant le chargement du runtime du Plugin.
contracts Non object Instantané statique de propriété des capacités pour les hooks d’authentification externes, la parole, la transcription en temps réel, la voix en temps réel, la compréhension des médias, la génération d’images, la génération de musique, la génération de vidéos, web-fetch, la recherche web et la propriété des outils.
mediaUnderstandingProviderMetadata Non Record<string, object> Valeurs par défaut légères de compréhension des médias pour les ID de fournisseurs déclarés dans contracts.mediaUnderstandingProviders.
imageGenerationProviderMetadata Non Record<string, object> Métadonnées légères d’authentification de génération d’images pour les ID de fournisseurs déclarés dans contracts.imageGenerationProviders, y compris les alias d’authentification possédés par le fournisseur et les protections de base-url.
videoGenerationProviderMetadata Non Record<string, object> Métadonnées légères d’authentification de génération de vidéos pour les ID de fournisseurs déclarés dans contracts.videoGenerationProviders, y compris les alias d’authentification possédés par le fournisseur et les protections de base-url.
musicGenerationProviderMetadata Non Record<string, object> Métadonnées légères d’authentification de génération de musique pour les ID de fournisseurs déclarés dans contracts.musicGenerationProviders, y compris les alias d’authentification possédés par le fournisseur et les protections de base-url.
toolMetadata Non Record<string, object> Métadonnées légères de disponibilité pour les outils possédés par le Plugin déclarés dans contracts.tools. Utilisez-les lorsqu’un outil ne doit pas charger le runtime sauf s’il existe une preuve de configuration, d’environnement ou d’authentification.
channelConfigs Non Record<string, object> Métadonnées de configuration de canal possédées par le manifeste, fusionnées dans les surfaces de découverte et de validation avant le chargement du runtime.
skills Non string[] Répertoires Skills à charger, relatifs à la racine du Plugin.
name Non string Nom du plugin lisible par l’humain.
description Non string Court résumé affiché dans les interfaces du plugin.
version Non string Version du plugin à titre informatif.
uiHints Non Record<string, object> Libellés d’interface, placeholders et indications de sensibilité pour les champs de configuration.

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 les 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 noyau 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, l’actualisation des jetons, la validation des identifiants et le comportement réel de génération 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 :

Champ Obligatoire Type Signification
aliases Non string[] Identifiants de fournisseur supplémentaires qui doivent compter comme alias d’authentification statiques pour le fournisseur de génération.
authProviders Non string[] Identifiants de fournisseur dont les profils d’authentification configurés doivent compter comme authentification pour ce fournisseur de génération.
configSignals Non object[] Signaux de disponibilité peu coûteux fondés uniquement sur la configuration pour les fournisseurs locaux ou auto-hébergés qui peuvent être configurés sans profils d’authentification ni variables d’environnement.
authSignals Non object[] Signaux d’authentification explicites. Lorsqu’ils sont présents, ils remplacent l’ensemble de signaux par défaut issu de l’identifiant du fournisseur, de aliases et de authProviders.

Chaque entrée configSignals prend en charge :

Champ Obligatoire Type Signification
rootPath Oui string Chemin à points vers l’objet de configuration appartenant au Plugin à inspecter, par exemple plugins.entries.example.config.
overlayPath Non string Chemin à points dans la configuration racine dont l’objet doit se superposer à l’objet racine avant d’évaluer le signal. Utilisez-le pour une configuration propre à une capacité, comme image, video ou music.
required Non string[] Chemins à points dans la configuration effective qui doivent avoir des valeurs configurées. Les chaînes doivent être non vides ; les objets et tableaux ne doivent pas être vides.
requiredAny Non string[] Chemins à points dans la configuration effective dont au moins un doit avoir une valeur configurée.
mode Non object Garde optionnelle de mode chaîne dans la configuration effective. Utilisez-la lorsque la disponibilité fondée uniquement sur la configuration ne s’applique qu’à un mode.

Chaque garde mode prend en charge :

Champ Obligatoire Type Signification
path Non string Chemin à points dans la configuration effective. Par défaut : mode.
default Non string Valeur de mode à utiliser lorsque la configuration omet le chemin.
allowed Non string[] Si présent, le signal réussit uniquement lorsque le mode effectif fait partie de ces valeurs.
disallowed Non string[] Si présent, le signal échoue lorsque le mode effectif fait partie de ces valeurs.

Chaque entrée authSignals prend en charge :

Champ Obligatoire Type Signification
provider Oui string Identifiant de fournisseur à vérifier dans les profils d’authentification configurés.
providerBaseUrl Non object Garde optionnelle qui fait compter le signal uniquement lorsque le fournisseur configuré référencé utilise une URL de base autorisée. Utilisez-la lorsqu’un alias d’authentification n’est valide que pour certaines API.

Chaque garde providerBaseUrl prend en charge :

Champ Obligatoire Type Signification
provider Oui string Identifiant de configuration de fournisseur dont baseUrl doit être vérifiée.
defaultBaseUrl Non string URL de base à supposer lorsque la configuration du fournisseur omet baseUrl.
allowedBaseUrls Oui string[] URL de base autorisées pour ce signal d’authentification. Le signal est ignoré lorsque l’URL de base configurée ou par défaut ne correspond à aucune de ces valeurs normalisées.

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 renvoie null.

{
  "providerAuthEnvVars": {
    "example": ["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 de chemin critique 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 par le noyau pour interroger.

Référence de 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.

Champ Obligatoire Type Signification
provider Oui string Identifiant de fournisseur auquel ce choix appartient.
method Oui string Identifiant de méthode d’authentification vers lequel distribuer.
choiceId Oui string Identifiant stable de choix d’authentification utilisé par les flux d’intégration et de CLI.
choiceLabel Non string Libellé destiné à l’utilisateur. S’il est omis, OpenClaw se rabat sur choiceId.
choiceHint Non string Court texte d’aide pour le sélecteur.
assistantPriority Non number Les valeurs plus basses sont triées plus tôt dans les sélecteurs interactifs pilotés par l’assistant.
assistantVisibility Non "visible" | "manual-only" Masquer le choix dans les sélecteurs de l’assistant tout en autorisant toujours la sélection manuelle par CLI.
deprecatedChoiceIds Non string[] Identifiants de choix hérités qui doivent rediriger les utilisateurs vers ce choix de remplacement.
groupId Non string Identifiant de groupe optionnel pour regrouper les choix associés.
groupLabel Non string Libellé destiné à l’utilisateur pour ce groupe.
groupHint Non string Court texte d’aide pour le groupe.
optionKey Non string Clé d’option interne pour les flux d’authentification simples à indicateur unique.
cliFlag Non string Nom de drapeau CLI, comme --openrouter-api-key.
cliOption Non string Forme complète de l’option CLI, comme --openrouter-api-key <key>.
cliDescription Non string Description utilisée dans l’aide CLI.
onboardingScopes Non Array<"text-inference" | "image-generation"> Surfaces d’intégration dans lesquelles ce choix doit apparaître. S’il est omis, la valeur par défaut est ["text-inference"].

Référence de commandAliases

Utilisez commandAliases lorsqu’un Plugin possède un nom de commande d’exécution que les utilisateurs peuvent mettre 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"
    }
  ]
}
Champ Obligatoire Type Signification
name Oui string Nom de commande appartenant à ce Plugin.
kind Non "runtime-slash" Marque l’alias comme commande slash de chat plutôt que comme commande CLI racine.
cliCommand Non string Commande CLI racine associée à suggérer pour les opérations CLI, s’il en existe une.

référence 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/chargement.

Ce bloc est une métadonnée de planificateur, pas 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 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 ciblées 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 des indications de planificateur supplémentaires 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 tels que claude-cli, codex-cli ou google-gemini-cli ; activation.onAgentHarnesses sert uniquement aux identifiants de harnais d’agent 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/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 devrait pas modifier la correction tant que les replis de propriété du manifeste existent toujours.

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 ciblés. 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, les harnais d’agent, la mémoire ou d’autres déclencheurs d’activation plus ciblés.

{
  "activation": {
    "onStartup": false,
    "onProviders": ["openai"],
    "onCommands": ["models"],
    "onChannels": ["web"],
    "onRoutes": ["gateway-webhook"],
    "onConfigPaths": ["browser"],
    "onCapabilities": ["provider", "tool"]
  }
}
Champ Obligatoire Type Signification
onStartup Non boolean Activation explicite au démarrage du Gateway. Chaque Plugin doit définir ce champ. true importe le Plugin pendant le démarrage ; false le garde paresseux au démarrage sauf si un autre déclencheur correspondant exige son chargement.
onProviders Non string[] Identifiants de fournisseurs qui doivent inclure ce Plugin dans les plans d’activation/chargement.
onAgentHarnesses Non string[] Identifiants d’exécution de harnais d’agent intégrés qui doivent inclure ce Plugin dans les plans d’activation/chargement. Utilisez cliBackends de premier niveau pour les alias de backend CLI.
onCommands Non string[] Identifiants de commandes qui doivent inclure ce Plugin dans les plans d’activation/chargement.
onChannels Non string[] Identifiants de canaux qui doivent inclure ce Plugin dans les plans d’activation/chargement.
onRoutes Non string[] Types de routes qui doivent inclure ce Plugin dans les plans d’activation/chargement.
onConfigPaths Non string[] Chemins de configuration relatifs à la racine qui doivent inclure ce Plugin dans les plans de démarrage/chargement lorsque le chemin est présent et n’est pas explicitement désactivé.
onCapabilities Non Array<"provider" | "channel" | "tool" | "hook"> Indications de capacités générales utilisées par la planification d’activation du plan de contrôle. Préférez des champs plus ciblés lorsque c’est possible.

Consommateurs actifs actuels :

  • la planification du démarrage du Gateway utilise activation.onStartup pour l’import explicite au démarrage
  • la planification CLI déclenchée par commande se rabat sur les anciens 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/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, telles que le bloc browser du Plugin de navigateur fourni
  • la planification de configuration/exécution déclenchée par fournisseur se rabat sur les anciennes propriétés 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 a correspondu, 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 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 reste responsable de l’enregistrement CLI réel via une surface légère runtime-api.ts qui exporte qaRunnerCliRegistrations.

{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
    }
  ]
}
Champ Obligatoire Type Signification
commandName Oui string Sous-commande montée sous openclaw qa, par exemple matrix.
description Non string Texte d’aide de repli utilisé lorsque l’hôte partagé a besoin d’une commande factice.

référence setup

Utilisez setup lorsque les surfaces de configuration et d’onboarding ont besoin de métadonnées possédées par le Plugin à faible coût avant le chargement de l’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
  }
}

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 pour les flux de plan de contrôle/configuration qui doivent rester uniquement des métadonnées.

Lorsqu’ils sont présents, setup.providers et setup.cliBackends sont la surface de recherche préférée, fondée sur les descripteurs, pour la découverte de configuration. Si le descripteur ne fait que réduire le Plugin candidat et que la configuration a encore besoin de 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 repli.

OpenClaw inclut également setup.providers[].envVars dans les recherches génériques d’authentification 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 fournis qui l’utilisent encore reçoivent un diagnostic de manifeste. Les nouveaux Plugins doivent placer les métadonnées d’environnement de configuration/statut sur setup.providers[].envVars.

OpenClaw peut également dériver des choix de configuration simples depuis setup.providers[].authMethods lorsqu’aucune entrée de configuration n’est disponible, ou lorsque setup.requiresRuntime: false déclare que l’exécution de configuration n’est pas nécessaire. Les entrées explicites providerAuthChoices restent préférées pour les libellés personnalisés, les indicateurs CLI, la portée d’onboarding et les métadonnées d’assistant.

Définissez requiresRuntime: false uniquement lorsque ces descripteurs suffisent pour la surface de configuration. OpenClaw traite false explicite comme un contrat uniquement basé sur des descripteurs et n’exécutera pas setup-api ni openclaw.setupEntry pour la recherche de configuration. Si un Plugin uniquement basé sur des descripteurs fournit tout de même l’une de ces entrées d’exécution de configuration, 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 cassent pas.

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

Lorsque l’exécution de configuration s’exécute, les diagnostics du registre de configuration signalent une dérive 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 n’a pas d’enregistrement d’exécution correspondant. Ces diagnostics sont additifs et ne rejettent pas les Plugins hérités.

référence setup.providers

Champ Obligatoire Type Signification
id Oui string Identifiant de fournisseur exposé pendant la configuration ou l’onboarding. Gardez les identifiants normalisés globalement uniques.
authMethods Non string[] Identifiants de méthodes de configuration/authentification pris en charge par ce fournisseur sans charger toute l’exécution.
envVars Non string[] Variables d’environnement que les surfaces génériques de configuration/statut peuvent vérifier avant le chargement de l’exécution du Plugin.
authEvidence Non object[] Vérifications légères de preuves d’authentification locales pour les fournisseurs qui peuvent s’authentifier via des marqueurs non secrets.

authEvidence sert aux marqueurs d’identifiants locaux détenus par le fournisseur qui peuvent être vérifiés sans charger de code d’exécution. 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 :

Champ Requis Type Signification
type Oui string Actuellement local-file-with-env.
fileEnvVar Non string Variable d’environnement contenant un chemin explicite vers un fichier d’identifiants.
fallbackPaths Non string[] Chemins locaux de fichiers d’identifiants vérifiés lorsque fileEnvVar est absent ou vide. Prend en charge ${HOME} et ${APPDATA}.
requiresAnyEnv Non string[] Au moins une variable d’environnement listée doit être non vide pour que la preuve soit valide.
requiresAllEnv Non string[] Chaque variable d’environnement listée doit être non vide pour que la preuve soit valide.
credentialMarker Oui string Marqueur non secret renvoyé lorsque la preuve est présente.
source Non string Libellé de source visible par l’utilisateur pour la sortie d’authentification/statut.

champs de configuration

Champ Requis Type Signification
providers Non object[] Descripteurs de configuration de fournisseur exposés pendant la configuration et l’intégration.
cliBackends Non string[] Identifiants de backends utilisés au moment de la configuration pour la recherche basée sur les descripteurs. Gardez les identifiants normalisés globalement uniques.
configMigrations Non string[] Identifiants de migration de configuration détenus par la surface de configuration de ce plugin.
requiresRuntime Non boolean Indique si la configuration nécessite encore l’exécution de setup-api après la recherche de descripteur.

référence uiHints

uiHints est une table qui associe les noms de champs de configuration à 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 :

Champ Type Signification
label string Libellé de champ visible par l’utilisateur.
help string Court texte d’aide.
tags string[] Tags d’interface facultatifs.
advanced boolean Marque le champ comme avancé.
sensitive boolean Marque le champ comme secret ou sensible.
placeholder string Texte d’espace réservé pour les entrées de formulaire.

référence contracts

Utilisez contracts uniquement pour les métadonnées statiques de propriété des capacités qu’OpenClaw peut lire sans importer le runtime du plugin.

{
  "contracts": {
    "agentToolResultMiddleware": ["pi", "codex"],
    "externalAuthProviders": ["acme-ai"],
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "memoryEmbeddingProviders": ["local"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "migrationProviders": ["hermes"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

Chaque liste est facultative :

Champ Type Signification
embeddedExtensionFactories string[] Identifiants de fabriques d’extensions du serveur d’app Codex, actuellement codex-app-server.
agentToolResultMiddleware string[] Identifiants de runtime pour lesquels un plugin groupé peut enregistrer un middleware de résultat d’outil.
externalAuthProviders string[] Identifiants de fournisseurs dont ce plugin possède le hook de profil d’authentification externe.
speechProviders string[] Identifiants de fournisseurs de parole que ce plugin possède.
realtimeTranscriptionProviders string[] Identifiants de fournisseurs de transcription en temps réel que ce plugin possède.
realtimeVoiceProviders string[] Identifiants de fournisseurs de voix en temps réel que ce plugin possède.
memoryEmbeddingProviders string[] Identifiants de fournisseurs d’embeddings mémoire que ce plugin possède.
mediaUnderstandingProviders string[] Identifiants de fournisseurs de compréhension des médias que ce plugin possède.
imageGenerationProviders string[] Identifiants de fournisseurs de génération d’images que ce plugin possède.
videoGenerationProviders string[] Identifiants de fournisseurs de génération vidéo que ce plugin possède.
webFetchProviders string[] Identifiants de fournisseurs de récupération web que ce plugin possède.
webSearchProviders string[] Identifiants de fournisseurs de recherche web que ce plugin possède.
migrationProviders string[] Identifiants de fournisseurs d’importation que ce plugin possède pour openclaw migrate.
tools string[] Noms d’outils d’agent que ce plugin possède.

contracts.embeddedExtensionFactories est conservé pour les fabriques d’extensions groupées réservées au serveur d’app Codex. Les transformations groupées de résultats d’outils doivent déclarer contracts.agentToolResultMiddleware et s’enregistrer avec api.registerAgentToolResultMiddleware(...) à la place. Les plugins externes ne peuvent pas enregistrer de middleware de résultat d’outil, car cette interface peut réécrire la sortie d’outils à haute confiance avant que le modèle ne la voie.

Les enregistrements runtime api.registerTool(...) doivent correspondre à contracts.tools. La découverte des outils utilise cette liste pour charger uniquement les runtimes de plugins qui peuvent posséder les outils demandés.

Les plugins fournisseurs qui implémentent resolveExternalAuthProfiles doivent déclarer contracts.externalAuthProviders. Les plugins sans cette déclaration passent encore par un repli de compatibilité obsolète, mais ce repli est plus lent et sera supprimé après la fenêtre de migration.

Les fournisseurs groupés d’embeddings mémoire doivent déclarer contracts.memoryEmbeddingProviders pour chaque identifiant d’adaptateur qu’ils exposent, y compris les adaptateurs intégrés tels que local. Les chemins CLI autonomes utilisent ce contrat de manifeste pour charger uniquement le plugin propriétaire avant que le runtime Gateway complet ait enregistré les fournisseurs.

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 repli d’authentification automatique, ou une prise en charge native des documents dont les assistants génériques du cœur ont besoin avant le chargement du runtime. Les clés doivent aussi ê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 :

Champ Type Signification
capabilities ("image" | "audio" | "video")[] Capacités multimédias exposées par ce fournisseur.
defaultModels Record<string, string> Valeurs par défaut de modèle par capacité utilisées lorsque la configuration ne spécifie pas de modèle.
autoPriority Record<string, number> Les nombres plus faibles sont triés plus tôt pour le repli automatique de fournisseur basé sur les identifiants.
nativeDocumentInputs "pdf"[] Entrées de documents natives prises en charge par le fournisseur.

référence channelConfigs

Utilisez channelConfigs lorsqu’un plugin de canal a besoin de métadonnées de configuration peu coûteuses avant le chargement du runtime. La découverte en lecture seule de la configuration/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 le runtime de configuration inutile.

channelConfigs correspond à des métadonnées de manifeste de 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 de 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 groupé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 configuration à froid, de configuration et de Control UI ne peuvent pas connaître la forme des options détenues 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 configuration des commandes qui s’exécutent avant le chargement du runtime du canal. Les canaux groupés peuvent aussi publier les mêmes valeurs par défaut via package.json#openclaw.channel.commands en plus de leurs autres métadonnées de catalogue de canal détenues par le 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 :

Champ Type Signification
schema object Schéma JSON pour channels.<id>. Obligatoire pour chaque entrée de configuration de canal déclarée.
uiHints Record<string, object> Libellés d'interface utilisateur, textes indicatifs et indications de sensibilité facultatifs pour cette section de configuration de canal.
label string Libellé du canal fusionné dans les surfaces de sélection et d'inspection lorsque les métadonnées d'exécution ne sont pas prêtes.
description string Brève description du canal pour les surfaces d'inspection et de catalogue.
commands object Commande native statique et valeurs par défaut automatiques de Skills natifs pour les vérifications de configuration avant l'exécution.
preferOver string[] Identifiants de plugins hérités ou de priorité inférieure que ce canal doit devancer dans les surfaces de sélection.

Remplacer 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 sont un identifiant de plugin renommé, un plugin autonome qui remplace un plugin intégré, ou un dérivé maintenu qui conserve le même identifiant de canal pour la compatibilité de 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 prend en compte à la fois l'identifiant de canal et l'identifiant du plugin privilégié. Si le plugin de priorité inférieure n'a été sélectionné que 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, OpenClaw conserve ce choix et signale des diagnostics de canaux/outils dupliqués 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 configuration utilisateur.

Référence modelSupport

Utilisez modelSupport lorsqu'OpenClaw doit déduire votre plugin de fournisseur à partir d'identifiants de modèles abrégés comme gpt-5.5 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 cet ordre de priorité :

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

Champs :

Champ Type Signification
modelPrefixes string[] Préfixes comparés avec startsWith aux identifiants de modèles abrégés.
modelPatterns string[] Sources d'expressions régulières comparées aux identifiants de modèles abrégés après suppression du suffixe de profil.

Référence modelCatalog

Utilisez modelCatalog lorsqu'OpenClaw doit connaître les métadonnées de modèles du fournisseur avant le chargement de l'exécution du plugin. Il s'agit de 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. Le rafraîchissement à l'exécution relève toujours du code d'exécution du fournisseur, mais le manifeste indique au cœur lorsque l'exécution est requise.

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

Champ Type Signification
providers Record<string, object> Lignes de catalogue pour les identifiants de fournisseurs détenus par ce plugin. Les clés doivent aussi apparaître dans providers au premier niveau.
aliases Record<string, object> Alias de fournisseurs qui doivent se résoudre vers un fournisseur détenu pour la planification du catalogue ou des suppressions.
suppressions object[] Lignes de modèles provenant d'une autre source que ce plugin supprime pour une raison propre au fournisseur.
discovery Record<string, "static" | "refreshable" | "runtime"> Indique si le catalogue du fournisseur peut être lu depuis les métadonnées du manifeste, rafraîchi dans le cache ou nécessite l'exécution.

aliases participe à la recherche de propriété des fournisseurs 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. 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'exécution 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 point d'extension d'exécution de fournisseur suppressBuiltInModel. Les entrées de suppression ne sont respectées que lorsque le fournisseur est détenu par le plugin ou déclaré comme clé modelCatalog.aliases ciblant un fournisseur détenu. Les points d'extension de suppression à l'exécution ne sont plus appelés pendant la résolution des modèles.

Champs de fournisseur :

Champ Type Signification
baseUrl string URL de base par défaut facultative pour les modèles de ce catalogue de fournisseur.
api ModelApi Adaptateur d'API par défaut facultatif pour les modèles de ce catalogue de fournisseur.
headers Record<string, string> En-têtes statiques facultatifs qui s'appliquent à ce catalogue de fournisseur.
models object[] Lignes de modèles obligatoires. Les lignes sans id sont ignorées.

Champs de modèle :

Champ Type Signification
id string Identifiant de modèle local au fournisseur, sans le préfixe provider/.
name string Nom d'affichage facultatif.
api ModelApi Remplacement d'API facultatif par modèle.
baseUrl string Remplacement d'URL de base facultatif par modèle.
headers Record<string, string> En-têtes statiques facultatifs par modèle.
input Array<"text" | "image" | "document" | "audio" | "video"> Modalités acceptées par le modèle.
reasoning boolean Indique si le modèle expose un comportement de raisonnement.
contextWindow number Fenêtre de contexte native du fournisseur.
contextTokens number Limite de contexte effective à l'exécution facultative lorsqu'elle diffère de contextWindow.
maxTokens number Nombre maximal de jetons de sortie lorsqu'il est connu.
cost object Tarification facultative en USD par million de jetons, incluant éventuellement tieredPricing.
compat object Indicateurs de compatibilité facultatifs correspondant à la compatibilité de configuration de modèles OpenClaw.
status "available" | "preview" | "deprecated" | "disabled" Statut d'affichage. À supprimer uniquement lorsque la ligne ne doit pas apparaître du tout.
statusReason string Raison facultative affichée avec un statut non disponible.
replaces string[] Anciens identifiants de modèles locaux au fournisseur que ce modèle remplace.
replacedBy string Identifiant de modèle local au fournisseur de remplacement pour les lignes obsolètes.
tags string[] Étiquettes stables utilisées par les sélecteurs et les filtres.

Champs de suppression :

Champ Type Signification
provider string Identifiant de fournisseur pour la ligne amont à supprimer. Il doit être détenu par ce plugin ou déclaré comme alias détenu.
model string Identifiant de modèle local au fournisseur à supprimer.
reason string Message facultatif affiché lorsque la ligne supprimée est demandée directement.
when.baseUrlHosts string[] Liste facultative des hôtes d'URL de base effectifs du fournisseur requis avant que la suppression s'applique.
when.providerConfigApiIn string[] Liste facultative des valeurs exactes api de configuration de fournisseur requises avant que la suppression s'applique.

N’ajoutez pas de données présentes uniquement à l’exécution dans modelCatalog. Utilisez static uniquement lorsque les lignes de manifeste sont assez complètes pour permettre aux surfaces de liste et de sélecteur filtrées par fournisseur d’ignorer la découverte du registre ou de l’exécution. Utilisez refreshable lorsque les lignes de manifeste sont des amorces ou des compléments listables utiles, mais qu’une actualisation ou un cache peut ajouter davantage de lignes plus tard ; les lignes actualisables ne font pas autorité à elles seules. Utilisez runtime lorsque OpenClaw doit charger l’exécution du fournisseur pour connaître la liste.

Référence modelIdNormalization

Utilisez modelIdNormalization pour un nettoyage peu coûteux des identifiants de modèle contrôlé par le fournisseur, qui doit se produire avant le chargement de l’exécution du fournisseur. Cela conserve les alias tels que les noms de modèle courts, 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 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 du fournisseur :

Champ Type Signification
aliases Record<string,string> Alias exacts d’identifiants de modèle, insensibles à la casse. Les valeurs sont renvoyées telles qu’écrites.
stripPrefixes string[] Préfixes à retirer avant la recherche d’alias, utile pour les duplications héritées fournisseur/modèle.
prefixWhenBare string Préfixe à ajouter lorsque l’identifiant de modèle normalisé ne contient pas déjà /.
prefixWhenBareAfterAliasStartsWith object[] Règles conditionnelles de préfixe d’identifiant nu après la recherche d’alias, indexées par modelPrefix et prefix.

Référence providerEndpoints

Utilisez providerEndpoints pour la classification des points de terminaison que la politique de requête générique doit connaître avant le chargement de l’exécution du fournisseur. Le cœur reste propriétaire de la signification de chaque endpointClass ; les manifestes de Plugin possèdent les métadonnées d’hôte et d’URL de base.

Champs de point de terminaison :

Champ Type Signification
endpointClass string Classe de point de terminaison connue du cœur, comme openrouter, moonshot-native ou google-vertex.
hosts string[] Noms d’hôte exacts qui correspondent à la classe de point de terminaison.
hostSuffixes string[] Suffixes d’hôte qui correspondent à la classe de point de terminaison. Préfixez avec . pour une correspondance limitée aux suffixes de domaine.
baseUrls string[] URL de base HTTP(S) normalisées exactes qui correspondent à la classe de point de terminaison.
googleVertexRegion string Région Google Vertex statique pour les hôtes globaux exacts.
googleVertexRegionHostSuffix string Suffixe à retirer des hôtes correspondants pour exposer le préfixe de région Google Vertex.

Référence providerRequest

Utilisez providerRequest pour des métadonnées peu coûteuses de compatibilité des requêtes dont la politique de requête générique a besoin sans charger l’exécution du fournisseur. Conservez la réécriture de charge utile propre à un comportement dans les hooks d’exécution du fournisseur ou les assistants partagés de famille de fournisseurs.

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

Champs du fournisseur :

Champ Type Signification
family string Libellé de famille de fournisseurs utilisé par les décisions génériques de compatibilité des requêtes et les diagnostics.
compatibilityFamily "moonshot" Groupe facultatif de compatibilité de famille de fournisseurs pour les assistants de requête partagés.
openAICompletions object Indicateurs de requête de complétions compatibles OpenAI, actuellement supportsStreamingUsage.

Référence modelPricing

Utilisez modelPricing lorsqu’un fournisseur doit contrôler le comportement de tarification du plan de contrôle avant le chargement de l’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 :

Champ Type Signification
external boolean Définissez false pour les fournisseurs locaux/auto-hébergés qui ne doivent jamais récupérer les tarifs OpenRouter ou LiteLLM.
openRouter false | object Correspondance de recherche de tarifs OpenRouter. false désactive la recherche OpenRouter pour ce fournisseur.
liteLLM false | object Correspondance de recherche de tarifs LiteLLM. false désactive la recherche LiteLLM pour ce fournisseur.

Champs source :

Champ Type Signification
provider string Identifiant de fournisseur du catalogue externe lorsqu’il diffère de l’identifiant de fournisseur OpenClaw, par exemple z-ai pour un fournisseur zai.
passthroughProviderModel boolean Traite les identifiants de modèle contenant une barre oblique comme des références imbriquées fournisseur/modèle, utile pour les fournisseurs proxy comme OpenRouter.
modelIdTransforms "version-dots"[] Variantes supplémentaires d’identifiant de modèle du catalogue externe. version-dots essaie les identifiants de version avec points comme claude-opus-4.6.

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 Plugin restent l’autorité pour les plugins installés. L’Index des fournisseurs est le contrat de secours interne que les futures surfaces de fournisseurs installables et de sélecteur de modèles avant installation 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’une actualisation 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 d’exécution ni de données de modèles dynamiques propres à un compte. Ses catalogues d’aperçu utilisent la même forme de ligne fournisseur modelCatalog que les manifestes de Plugin, mais doivent rester limités aux métadonnées d’affichage stables, sauf si des champs d’adaptateur d’exécution 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 dynamique /models doivent écrire les lignes actualisées via le chemin explicite du cache de catalogue de modèles au lieu de faire appeler les API du fournisseur par la liste normale ou l’intégration initiale.

Les entrées de l’Index des fournisseurs peuvent aussi contenir des métadonnées de Plugin installable pour les fournisseurs dont le Plugin a quitté le cœur ou n’est pas encore installé pour une autre raison. Ces métadonnées reprennent le modèle du catalogue de canaux : le nom de package, la spécification d’installation npm, l’intégrité attendue et des libellés peu coûteux de choix d’authentification suffisent pour 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é héritées au niveau supérieur sont obsolètes. Utilisez openclaw doctor --fix pour déplacer speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders et webSearchProviders sous contracts ; le chargement normal des manifestes ne traite plus ces champs de niveau supérieur comme propriété de capacité.

Manifeste et package.json

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

Fichier À utiliser pour
openclaw.plugin.json Découverte, validation de configuration, métadonnées de choix d’authentification et indications d’interface utilisateur qui doivent exister avant l’exécution du code du Plugin
package.json Métadonnées npm, installation des dépendances et bloc openclaw utilisé pour les points d’entrée, les garde-fous d’installation, la configuration ou les métadonnées de catalogue

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

Champs package.json qui influencent la découverte

Certaines métadonnées de Plugin avant exécution vivent 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 ainsi que les champs package.json#openclaw pris en charge ci-dessous.

Exemples importants :

Champ Signification
openclaw.extensions Déclare les points d’entrée des plugins natifs. Doit rester dans le répertoire du package du plugin.
openclaw.runtimeExtensions Déclare les points d’entrée runtime JavaScript compilés pour les packages installés. Doit rester dans le répertoire du package du plugin.
openclaw.setupEntry Point d’entrée léger réservé à la configuration initiale, utilisé pendant l’onboarding, le démarrage différé du canal et la découverte en lecture seule de l’état du canal/des SecretRef. Doit rester dans le répertoire du package du plugin.
openclaw.runtimeSetupEntry Déclare le point d’entrée de configuration JavaScript compilé pour les packages installés. Nécessite setupEntry, doit exister et doit rester dans le répertoire du package du plugin.
openclaw.channel Métadonnées peu coûteuses du catalogue de canaux, comme les libellés, chemins de documentation, alias et texte de sélection.
openclaw.channel.commands Métadonnées statiques de commandes natives et de valeurs par défaut automatiques de skills natives utilisées par la configuration, l’audit et les surfaces de liste de commandes avant le chargement du runtime du canal.
openclaw.channel.configuredState Métadonnées légères du vérificateur d’état configuré pouvant répondre à « une configuration seulement par env existe-t-elle déjà ? » sans charger tout le runtime du canal.
openclaw.channel.persistedAuthState Métadonnées légères du vérificateur d’authentification persistée pouvant répondre à « quelque chose est-il déjà connecté ? » sans charger tout le runtime du canal.
openclaw.install.clawhubSpec / openclaw.install.npmSpec / openclaw.install.localPath Indications d’installation/mise à jour pour les plugins groupés et publiés en externe.
openclaw.install.defaultChoice Chemin d’installation préféré lorsque plusieurs sources d’installation sont disponibles.
openclaw.install.minHostVersion Version minimale prise en charge de l’hôte OpenClaw, avec un plancher semver comme >=2026.3.22 ou >=2026.5.1-beta.1.
openclaw.install.expectedIntegrity Chaîne d’intégrité npm dist attendue, comme sha512-... ; les flux d’installation et de mise à jour vérifient l’artéfact récupéré avec celle-ci.
openclaw.install.allowInvalidConfigRecovery Autorise un chemin étroit de récupération par réinstallation de plugin groupé lorsque la configuration est invalide.
openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen Permet aux surfaces de canal réservées à la configuration de se charger avant le plugin de canal complet pendant le démarrage.

Les métadonnées de manifeste décident des choix de fournisseur/canal/configuration qui apparaissent dans l’onboarding avant le chargement du runtime. package.json#openclaw.install indique à l’onboarding comment récupérer ou activer ce plugin lorsque l’utilisateur choisit l’une de ces options. 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ées. 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 l’extraction de l’hôte.

Les métadonnées officielles d’installation à la demande doivent utiliser clawhubSpec lorsque le plugin est publié sur ClawHub ; l’onboarding considère cela comme la source distante préférée et enregistre les faits d’artéfact ClawHub après l’installation. npmSpec reste la solution de repli de compatibilité pour les packages qui n’ont pas encore migré vers ClawHub.

L’épinglage exact de version npm se trouve déjà dans npmSpec, par exemple "npmSpec": "@wecom/[email protected]". Les entrées officielles du catalogue externe doivent associer des spécifications exactes à expectedIntegrity afin que les flux de mise à jour échouent de façon fermée si l’artéfact npm récupéré ne correspond plus à la version épinglée. L’onboarding interactif propose toujours les spécifications npm de registre approuvé, y compris les noms de package 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’aucune source npm valide ne peut être épinglée par celui-ci. 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 les analyses d’état, de liste de canaux ou de SecretRef doivent identifier les comptes configurés sans charger tout le runtime. Le point d’entrée de configuration doit exposer les métadonnées de canal ainsi que des adaptateurs de configuration, d’état et de secrets compatibles avec 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 runtime ne remplacent pas les vérifications 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 permet seulement aux flux d’installation de récupérer depuis des échecs spécifiques de mise à niveau de plugin groupé obsolète, 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 très petit 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 ont besoin d’une sonde d’authentification oui/non peu coûteuse avant le chargement du plugin de canal complet. L’état d’authentification persisté n’est pas l’état configuré du canal : n’utilisez pas ces métadonnées pour activer automatiquement des plugins, réparer des dépendances runtime ou décider si un runtime de canal doit se charger. L’export cible doit être une petite fonction qui lit uniquement l’état persisté ; ne l’acheminez pas via le barrel complet du runtime de canal.

openclaw.channel.configuredState suit la même forme pour les vérifications configurées peu coûteuses fondées uniquement sur l’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 entrées minuscules non runtime. Si la vérification nécessite une résolution complète de configuration ou le vrai runtime du canal, gardez cette logique dans le hook config.hasConfiguredState du plugin.

Priorité de découverte (identifiants de plugin en double)

OpenClaw découvre les plugins depuis plusieurs racines (groupés, installation globale, espace de travail, chemins explicitement sélectionnés par la configuration). Si deux découvertes partagent le même id, seul le manifeste de plus haute priorité est conservé ; les doublons de priorité inférieure sont supprimés au lieu d’être chargés à côté.

Priorité, 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 de plugins OpenClaw
  4. Espace de travail — plugins découverts relativement à l’espace de travail courant

Implications :

  • Une copie forkée ou obsolète d’un plugin groupé présente dans l’espace de travail ne masquera pas la compilation groupée.
  • Pour remplacer réellement un plugin groupé par un plugin local, épinglez-le via plugins.entries.<id> afin qu’il l’emporte par priorité plutôt que de dépendre de la découverte de l’espace de travail.
  • 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 de schéma JSON

  • Chaque plugin doit livrer 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 au runtime.
  • Lorsque vous étendez ou forkez un plugin groupé avec de nouvelles clés de configuration, mettez à jour en même temps le configSchema openclaw.plugin.json de ce plugin. Les schémas des plugins groupés sont stricts, donc ajouter 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’identifiant 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 identifiants de plugins découvrables. Les identifiants 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 plugins.* complet.

Notes

  • Le manifeste est obligatoire pour les plugins OpenClaw natifs, y compris les chargements depuis le système de fichiers local. L’exécution 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 ; les commentaires, les virgules finales et les clés sans guillemets sont donc 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.
  • providerDiscoveryEntry doit rester léger et ne doit pas importer de code d’exécution é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 d’exécution est obsolète et reste uniquement comme solution 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 confiance du plugin et la politique d’activation effective 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 hooks d’exécution des fournisseurs.
  • Si votre plugin dépend de modules natifs, documentez les étapes de build et toutes les exigences de liste d’autorisation du gestionnaire de paquets (par exemple, pnpm allow-build-scripts + pnpm rebuild <package>).

Associé

Créer des plugins

Premiers pas avec les plugins.
Architecture des plugins

Architecture interne et modèle de capacités.
Vue d’ensemble du SDK

Référence du SDK de plugin et importations de sous-chemins.