package.json), les manifestes (openclaw.plugin.json), les points d’entrée de configuration et les schémas de configuration.
Métadonnées du paquet
Votre fichierpackage.json doit comporter un champ openclaw qui indique au système de plugins ce que fournit votre plugin :
- Plugin de canal
- Plugin de fournisseur / configuration de référence ClawHub
La publication externe sur ClawHub requiert
compat et build. Les extraits de référence pour la publication se trouvent dans docs/snippets/plugin-publish/.Champs openclaw
string[]
Fichiers de point d’entrée (relatifs à la racine du paquet). Entrées source valides pour le développement dans un espace de travail ou une extraction Git.
string[]
Équivalents JavaScript compilés de
extensions, privilégiés lorsqu’OpenClaw charge un paquet npm installé. Consultez Points d’entrée du SDK pour connaître l’ordre de résolution entre la source et les fichiers compilés.string
Point d’entrée léger réservé à la configuration (facultatif).
string
Équivalent JavaScript compilé de
setupEntry. Nécessite que setupEntry soit également défini.object
Identité de plugin de secours
{ id, label }, utilisée lorsqu’un plugin ne comporte aucune métadonnée de canal ou de fournisseur permettant d’en déduire un identifiant ou un libellé.object
Métadonnées du catalogue de canaux pour les interfaces de configuration, de sélection, de démarrage rapide et d’état.
object
Indications d’installation :
npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery, requiredPlatformPackages.object
Indicateurs de comportement au démarrage.
object
Plage de versions de
pluginApi prise en charge par ce plugin. Requise pour les publications externes sur ClawHub.Les identifiants de fournisseurs (
providers: string[]) sont des métadonnées du manifeste, et non du paquet. Déclarez-les dans openclaw.plugin.json, pas ici — consultez Manifeste du plugin.openclaw.channel
openclaw.channel fournit des métadonnées de paquet légères pour la découverte des canaux et les interfaces de configuration avant le chargement de l’environnement d’exécution.
Exemple :
exposure prend en charge :
configured: inclut le canal dans les interfaces de liste des canaux configurés et d’étatsetup: inclut le canal dans les sélecteurs interactifs de configurationdocs: indique que le canal est public dans les interfaces de documentation et de navigation
showConfigured et showInSetup restent pris en charge en tant qu’alias hérités. Privilégiez exposure.openclaw.install
openclaw.install constitue une métadonnée du paquet, et non du manifeste.
Comportement de la prise en main
Comportement de la prise en main
La prise en main interactive utilise
openclaw.install pour les interfaces d’installation à la demande : si votre plugin expose des choix d’authentification de fournisseur ou des métadonnées de configuration/catalogue de canal avant le chargement de l’environnement d’exécution, la prise en main peut proposer une installation depuis ClawHub, npm ou une source locale, installer ou activer le plugin, puis poursuivre le flux sélectionné. Les choix ClawHub utilisent clawhubSpec et sont privilégiés lorsqu’ils sont présents ; les choix npm nécessitent des métadonnées de catalogue fiables avec une valeur npmSpec provenant du registre (les versions exactes et expectedIntegrity sont des épinglages facultatifs, appliqués lors de l’installation ou de la mise à jour lorsqu’ils sont définis). Conservez « ce qu’il faut afficher » dans openclaw.plugin.json et « comment l’installer » dans package.json.Application de minHostVersion
Application de minHostVersion
Si
minHostVersion est défini, cette contrainte s’applique à la fois à l’installation et au chargement des plugins non intégrés depuis le registre de manifestes. Les hôtes plus anciens ignorent les plugins externes ; les chaînes de version non valides sont rejetées. Les plugins source intégrés sont supposés avoir la même version que l’extraction de l’hôte.Installations npm épinglées
Installations npm épinglées
Pour les installations npm épinglées, conservez la version exacte dans
npmSpec et ajoutez l’intégrité attendue de l’artefact :Portée de allowInvalidConfigRecovery
Portée de allowInvalidConfigRecovery
allowInvalidConfigRecovery ne constitue pas un contournement général des configurations défectueuses. Il s’agit uniquement d’un mécanisme de récupération limité aux plugins intégrés, qui permet à la réinstallation ou à la configuration de réparer les résidus connus d’une mise à niveau, comme l’absence du chemin d’un plugin intégré ou une entrée channels.<id> obsolète pour ce même plugin. Si la configuration est défectueuse pour d’autres raisons, l’installation échoue toujours de manière sécurisée et indique à l’opérateur d’exécuter openclaw doctor --fix.Chargement complet différé
Les plugins de canal peuvent activer le chargement différé avec :setupEntry pendant la phase de démarrage précédant la mise en écoute, même pour les canaux déjà configurés. Le point d’entrée complet est chargé une fois que le Gateway commence à écouter.
Si vos points d’entrée de configuration ou complet enregistrent des méthodes RPC du Gateway, utilisez un préfixe propre au plugin. Les espaces de noms d’administration réservés au cœur (config.*, exec.approvals.*, wizard.*, update.*) restent la propriété du cœur et sont toujours normalisés en operator.admin.
Manifeste du plugin
Chaque Plugin natif doit inclure un fichieropenclaw.plugin.json à la racine du paquet. OpenClaw l’utilise pour valider la configuration sans exécuter le code du Plugin.
channels (et, pour les Plugins de fournisseur, ajoutez providers) :
Publication sur ClawHub
Les Skills et les paquets de Plugins utilisent des commandes de publication ClawHub distinctes. Pour les paquets de Plugins, utilisez la commande propre aux paquets :clawhub skill publish <path> est une autre commande, destinée à publier un dossier de Skill et non un paquet de Plugin. Consultez Publication sur ClawHub.Point d’entrée de configuration
setup-entry.ts est une alternative légère à index.ts qu’OpenClaw charge lorsqu’il n’a besoin que des surfaces de configuration (intégration initiale, réparation de la configuration, inspection des canaux désactivés) :
defineBundledChannelSetupEntry(...) depuis openclaw/plugin-sdk/channel-entry-contract au lieu de defineSetupPluginEntry(...). Ce contrat intégré prend également en charge un export facultatif runtime, afin que le câblage de l’environnement d’exécution pendant la configuration reste léger et explicite.
Quand OpenClaw utilise setupEntry au lieu du point d’entrée complet
Quand OpenClaw utilise setupEntry au lieu du point d’entrée complet
- Le canal est désactivé, mais nécessite des surfaces de configuration ou d’intégration initiale.
- Le canal est activé, mais n’est pas configuré.
- Le chargement différé est activé (
deferConfiguredChannelFullLoadUntilAfterListen).
Ce que setupEntry doit enregistrer
Ce que setupEntry doit enregistrer
- L’objet du Plugin de canal (via
defineSetupPluginEntry). - Toute route HTTP requise avant la mise en écoute du Gateway.
- Toute méthode du Gateway nécessaire au démarrage.
config.* ou update.*.Ce que setupEntry ne doit PAS inclure
Ce que setupEntry ne doit PAS inclure
- Les enregistrements CLI.
- Les services en arrière-plan.
- Les imports lourds de l’environnement d’exécution (cryptographie, SDK).
- Les méthodes du Gateway nécessaires uniquement après le démarrage.
Imports ciblés des assistants de configuration
Pour les chemins critiques réservés à la configuration, préférez les interfaces ciblées d’assistance à la configuration à l’interface globaleplugin-sdk/setup lorsque vous n’avez besoin que d’une partie de la surface de configuration :
Utilisez l’interface plus générale
plugin-sdk/setup lorsque vous souhaitez disposer de la boîte à outils partagée complète pour la configuration, y compris des assistants de modification de configuration tels que moveSingleAccountChannelSectionToDefaultAccount(...).
Utilisez createSetupTranslator(...) pour les textes fixes de l’assistant de configuration. Il suit les paramètres régionaux de l’assistant CLI (OPENCLAW_LOCALE, puis les variables de paramètres régionaux du système) et utilise l’anglais comme solution de repli. Conservez le texte de configuration propre au Plugin dans le code appartenant à celui-ci et utilisez les clés du catalogue partagé uniquement pour les libellés de configuration communs, les textes d’état et les textes de configuration des Plugins officiels intégrés.
Les adaptateurs de modification de configuration restent sûrs à importer dans les chemins critiques. Leur recherche de la surface contractuelle de promotion d’un compte unique intégré est différée ; ainsi, l’importation de plugin-sdk/setup-runtime ne charge pas immédiatement la découverte des surfaces contractuelles intégrées avant l’utilisation effective de l’adaptateur.
Promotion d’un compte unique détenue par le canal
Lorsqu’un canal passe d’une configuration de compte unique au niveau supérieur àchannels.<id>.accounts.*, le comportement partagé par défaut déplace les valeurs promues propres au compte vers accounts.default.
Les canaux intégrés peuvent restreindre ou remplacer cette promotion au moyen de leur surface contractuelle de configuration :
singleAccountKeysToMove: clés supplémentaires de niveau supérieur à déplacer dans le compte promunamedAccountPromotionKeys: lorsque des comptes nommés existent déjà, seules ces clés sont déplacées dans le compte promu ; les clés partagées de stratégie et de distribution restent à la racine du canalresolveSingleAccountPromotionTarget(...): choisit le compte existant qui reçoit les valeurs promues
Matrix est l’exemple intégré actuel. S’il existe déjà exactement un compte Matrix nommé, ou si
defaultAccount pointe vers une clé non canonique existante telle que Ops, la promotion conserve ce compte au lieu de créer une nouvelle entrée accounts.default.Schéma de configuration
La configuration du Plugin est validée par rapport au schéma JSON de votre manifeste. Les utilisateurs configurent les Plugins comme suit :api.pluginConfig lors de l’enregistrement.
Pour une configuration propre à un canal, utilisez plutôt la section de configuration du canal :
Création de schémas de configuration de canal
UtilisezbuildChannelConfigSchema pour convertir un schéma Zod dans l’enveloppe ChannelConfigSchema utilisée par les artefacts de configuration appartenant au Plugin :
openclaw.plugin.json#channelConfigs afin que le schéma de configuration, la configuration et les surfaces d’interface utilisateur puissent inspecter channels.<id> sans charger le code d’exécution.
Assistants de configuration
Les Plugins de canal peuvent fournir des assistants de configuration interactifs pouropenclaw onboard. L’assistant est un objet ChannelSetupWizard dans le ChannelPlugin :
ChannelSetupWizard prend également en charge textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize, entre autres. Consultez le fichier src/setup-core.ts du Plugin Discord pour obtenir un exemple intégré complet.
Invites allowFrom partagées
Invites allowFrom partagées
Pour les invites de liste d’autorisation des messages privés qui n’ont besoin que du flux standard
note -> prompt -> parse -> merge -> patch, préférez les assistants de configuration partagés fournis par openclaw/plugin-sdk/setup : createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) et createNestedChannelParsedAllowFromPrompt(...).État standard de configuration du canal
État standard de configuration du canal
Pour les blocs d’état de configuration du canal qui ne varient que par leurs libellés, scores et lignes supplémentaires facultatives, préférez
createStandardChannelSetupStatus(...) depuis openclaw/plugin-sdk/setup plutôt que de recréer manuellement le même objet status dans chaque Plugin.Surface facultative de configuration du canal
Surface facultative de configuration du canal
Pour les surfaces de configuration facultatives qui ne doivent apparaître que dans certains contextes, utilisez
createOptionalChannelSetupSurface depuis openclaw/plugin-sdk/channel-setup :plugin-sdk/channel-setup expose également les constructeurs de plus bas niveau createOptionalChannelSetupAdapter(...) et createOptionalChannelSetupWizard(...) lorsque vous n’avez besoin que d’une moitié de cette surface d’installation facultative.L’adaptateur/l’assistant facultatif généré échoue de manière sécurisée lors des écritures réelles de configuration. Il réutilise un même message indiquant qu’une installation est requise dans validateInput, applyAccountConfig et finalize, et ajoute un lien vers la documentation lorsque docsPath est défini.Assistants de configuration reposant sur un binaire
Assistants de configuration reposant sur un binaire
Pour les interfaces de configuration reposant sur un binaire, privilégiez les assistants partagés délégués plutôt que de recopier la même logique de gestion du binaire et de l’état dans chaque canal :
createDetectedBinaryStatus(...)pour les blocs d’état qui ne varient que par les libellés, les indications, les scores et la détection du binairecreateCliPathTextInput(...)pour les champs de saisie de texte associés à un chemincreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...)etcreateDelegatedResolveConfigured(...)lorsquesetupEntrydoit transférer paresseusement le traitement à un assistant complet plus conséquentcreateDelegatedTextInputShouldPrompt(...)lorsquesetupEntrydoit uniquement déléguer une décisiontextInputs[*].shouldPrompt
Publication et installation
Plugins externes : publiez-les sur ClawHub, puis installez-les :- npm
- ClawHub uniquement
- Spécification de paquet npm
clawhub:, npm:, git: ou npm-pack: pour sélectionner la source de manière déterministe — consultez Gérer les Plugins.Pour les installations provenant de npm,
openclaw plugins install installe le paquet dans un projet propre à chaque Plugin sous ~/.openclaw/npm/projects, avec les scripts de cycle de vie désactivés (--ignore-scripts). Veillez à ce que les arborescences de dépendances des Plugins soient exclusivement en JS/TS et évitez les paquets qui nécessitent des compilations postinstall.Le démarrage du Gateway n’installe pas les dépendances des Plugins. Les processus d’installation npm/git/ClawHub assurent la convergence des dépendances ; les dépendances des Plugins locaux doivent déjà être installées.
Pages connexes
- Créer des Plugins — guide de démarrage pas à pas
- Manifeste de Plugin — référence complète du schéma du manifeste
- Points d’entrée du SDK —
definePluginEntryetdefineChannelPluginEntry