Plugins

Gérez les plugins du Gateway, les packs de hooks et les bundles compatibles.

Commandes

openclaw plugins list [--enabled] [--verbose] [--json]openclaw plugins search <query> [--limit <n>] [--json]openclaw plugins install <path-or-spec> [--link] [--force] [--pin] [--marketplace <source>]openclaw plugins inspect <id> [--runtime] [--json]openclaw plugins inspect --all [--runtime] [--json]openclaw plugins info <id>                    # alias d’inspectopenclaw plugins enable <id>openclaw plugins disable <id>openclaw plugins uninstall <id> [--dry-run] [--keep-files] [--force]openclaw plugins update <id-or-npm-spec> | --all [--dry-run]openclaw plugins registry [--refresh] [--json]openclaw plugins doctoropenclaw plugins init <id> [--name <name>] [--type tool|provider] [--directory <path>]openclaw plugins build [--entry <path>] [--check]openclaw plugins validate [--entry <path>]openclaw plugins marketplace entries [--offline] [--feed-profile <name>] [--json]openclaw plugins marketplace list <source> [--json]openclaw plugins marketplace refresh [--feed-profile <name>] [--expected-sha256 <sha256>] [--json]

Pour analyser une installation, une inspection, une désinstallation ou une actualisation du registre lente, exécutez la commande avec OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1. La trace écrit la durée des phases dans stderr et conserve une sortie JSON analysable. Consultez Débogage.

Création

openclaw plugins init stock-quotes --name "Stock Quotes"cd stock-quotesnpm run plugin:buildnpm run plugin:validate

plugins init crée par défaut un plugin d’outil TypeScript minimal. Le premier argument est l’identifiant du plugin ; --name définit le nom d’affichage. OpenClaw utilise l’identifiant pour le répertoire de sortie par défaut et le nommage du paquet. Les structures d’outil utilisent defineToolPlugin et génèrent les scripts package.json plugin:build et plugin:validate, qui effectuent la compilation puis appellent openclaw plugins build/validate.

plugins build importe le point d’entrée compilé, lit les métadonnées statiques de son outil, écrit openclaw.plugin.json et maintient le champ openclaw.extensions de package.json synchronisé. plugins validate vérifie que le manifeste généré, les métadonnées du paquet et l’exportation actuelle du point d’entrée concordent toujours. Consultez Plugins d’outils pour le processus de création complet.

La structure écrit le code source TypeScript, mais génère les métadonnées à partir du point d’entrée ./dist/index.js compilé, de sorte que le processus fonctionne également avec la CLI publiée. Utilisez --entry <path> lorsque le point d’entrée n’est pas celui par défaut du paquet. Utilisez plugins build --check dans la CI pour échouer lorsque les métadonnées générées sont obsolètes, sans réécrire les fichiers.

Structure de fournisseur

openclaw plugins init acme-models --name "Acme Models" --type providercd acme-modelsnpm installnpm run buildnpm testnpm run validate

Les structures de fournisseur créent un plugin générique de fournisseur de modèles compatible avec OpenAI, avec la gestion de l’authentification par clé API, un script npm run validate qui exécute clawhub package validate, les métadonnées de paquet ClawHub et un workflow GitHub Actions déclenché manuellement pour permettre ultérieurement une publication fiable via GitHub OIDC. Les structures de fournisseur ne génèrent pas de Skills et n’utilisent pas openclaw plugins build/validate ; ces commandes sont destinées au chemin de métadonnées générées de la structure d’outil.

Avant la publication, remplacez l’URL de base d’API fictive, le catalogue de modèles, la route de documentation, le texte relatif aux identifiants et le contenu du README par les informations réelles du fournisseur. Utilisez le README généré pour la première publication sur ClawHub et la configuration d’un éditeur de confiance.

Installation

openclaw plugins search "calendar"                      # rechercher des plugins ClawHubopenclaw plugins install @openclaw/<package>            # catalogue officiel de confianceopenclaw plugins install <package>                       # paquet npm arbitraireopenclaw plugins install clawhub:<package>                # ClawHub uniquementopenclaw plugins install npm:<package>                    # npm uniquementopenclaw plugins install npm-pack:<path.tgz>               # archive npm-pack localeopenclaw plugins install git:github.com/<owner>/<repo>     # dépôt gitopenclaw plugins install git:github.com/<owner>/<repo>@<ref>openclaw plugins install <path>                            # chemin local ou archiveopenclaw plugins install -l <path>                         # lier au lieu de copieropenclaw plugins install <plugin>@<marketplace>             # forme abrégée de marketplaceopenclaw plugins install <plugin> --marketplace <name>      # marketplace (explicite)openclaw plugins install <package> --force                  # confirmer la source / écraser l’existantopenclaw plugins install <package> --pin                    # épingler la version npm résolueopenclaw plugins install clawhub:<package> --acknowledge-clawhub-riskopenclaw plugins install <package> --dangerously-force-unsafe-install

Les mainteneurs qui testent les installations pendant la configuration peuvent remplacer les sources d’installation automatique des plugins à l’aide de variables d’environnement protégées. Consultez Remplacements des sources d’installation de plugins.

plugins search interroge ClawHub pour obtenir les paquets code-plugin et bundle-plugin installables (pas les Skills ; utilisez openclaw skills search pour ceux-ci). La valeur par défaut de --limit est 20, avec un maximum de 100. Cette commande lit uniquement le catalogue distant : aucune inspection de l’état local, modification de la configuration, installation de paquet ni chargement de l’environnement d’exécution du plugin. Les résultats comprennent le nom du paquet ClawHub, la famille, le canal, la version, le résumé et une indication d’installation telle que openclaw plugins install clawhub:<package>.

Les installations ClawHub utilisent un localisateur clawhub:<package> explicite :

openclaw plugins install clawhub:openclaw-codex-app-serveropenclaw plugins install clawhub:openclaw-codex-app-server@1.2.3

Pendant la transition de lancement, les spécifications de Plugin sans préfixe compatibles avec les noms npm s’installent par défaut depuis npm, sauf si elles correspondent à l’identifiant d’un Plugin officiel :

openclaw plugins install openclaw-codex-app-server

Utilisez npm: pour rendre explicite une résolution exclusivement via npm :

openclaw plugins install npm:openclaw-codex-app-serveropenclaw plugins install npm:@openclaw/discord@2026.5.20openclaw plugins install npm:@scope/plugin-name@1.0.1

OpenClaw vérifie avant l’installation la compatibilité annoncée avec l’API de Plugin et la version minimale du Gateway. Lorsque la version ClawHub sélectionnée publie un artefact ClawPack, OpenClaw télécharge le .tgz npm-pack versionné, vérifie l’en-tête d’empreinte de ClawHub et l’empreinte de l’artefact, puis l’installe par le chemin d’archive habituel. Les anciennes versions ClawHub sans métadonnées ClawPack s’installent toujours par le chemin historique de vérification des archives de paquet. Les installations enregistrées conservent les métadonnées de leur source ClawHub, le type d’artefact, l’intégrité npm, la somme SHA npm, le nom de l’archive tar et les informations d’empreinte ClawPack en vue des mises à jour ultérieures. Les installations ClawHub sans version conservent une spécification enregistrée sans version afin que openclaw plugins update puisse suivre les nouvelles versions ClawHub ; les sélecteurs explicites de version ou d’étiquette tels que clawhub:pkg@1.2.3 et clawhub:pkg@beta restent épinglés à ce sélecteur.

Forme abrégée de la place de marché

Utilisez la forme abrégée plugin@marketplace lorsque le nom de la place de marché existe dans le cache local du registre Claude à l’emplacement ~/.claude/plugins/known_marketplaces.json :

openclaw plugins marketplace list <marketplace-name>openclaw plugins install <plugin-name>@<marketplace-name>

Utilisez --marketplace pour transmettre explicitement la source de la place de marché :

openclaw plugins install <plugin-name> --marketplace <marketplace-name>openclaw plugins install <plugin-name> --marketplace <owner/repo>openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>openclaw plugins install <plugin-name> --marketplace ./my-marketplace

Pour les chemins locaux et les archives, OpenClaw détecte automatiquement :

• les Plugins OpenClaw natifs (openclaw.plugin.json)
• les ensembles compatibles avec Codex (.codex-plugin/plugin.json)
• les ensembles compatibles avec Claude (.claude-plugin/plugin.json, ou la disposition par défaut des composants Claude lorsque ce fichier manifeste est absent)
• les ensembles compatibles avec Cursor (.cursor-plugin/plugin.json)

Les installations locales gérées doivent être des répertoires ou des archives de Plugin. Les fichiers de Plugin autonomes .js, .mjs, .cjs et .ts ne sont pas copiés dans la racine gérée des Plugins par plugins install, ni chargés lorsqu’ils sont placés directement dans ~/.openclaw/extensions ou <workspace>/.openclaw/extensions ; ces racines de détection automatique chargent des répertoires de paquet ou d’ensemble de Plugin et ignorent les fichiers de script de premier niveau en tant qu’utilitaires locaux. Répertoriez plutôt explicitement les fichiers autonomes dans plugins.load.paths.

Utilisez -l/--link pour référencer un répertoire local de Plugin sans le copier (l’ajoute à plugins.load.paths) :

openclaw plugins install -l ./my-plugin

--link n’est pas pris en charge avec les installations --marketplace ou git:, et nécessite un chemin local qui existe déjà. Pour créer un lien local sans interaction, transmettez --force après avoir examiné la source ; cette option confirme la provenance, mais ne copie ni ne remplace le répertoire lié.

Liste

openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --json

Si le démarrage journalise plugins.allow is empty; discovered non-bundled plugins may auto-load: ..., exécutez openclaw plugins list --enabled --verbose ou openclaw plugins inspect <id> avec l’identifiant d’un plugin répertorié pour confirmer les identifiants des plugins et copier les identifiants fiables dans plugins.allow dans openclaw.json. Lorsque l’avertissement peut répertorier tous les plugins découverts, il affiche un extrait plugins.allow prêt à coller qui inclut déjà ces identifiants. Si un plugin se charge sans provenance d’installation ou de chemin de chargement, inspectez cet identifiant de plugin, puis épinglez l’identifiant fiable dans plugins.allow ou réinstallez le plugin depuis une source fiable afin qu’OpenClaw enregistre la provenance de l’installation.

Pour travailler sur un plugin intégré dans une image Docker empaquetée, montez par liaison le répertoire source du plugin sur le chemin source empaqueté correspondant, par exemple /app/extensions/synology-chat. OpenClaw découvre cette superposition de sources montée avant /app/dist/extensions/synology-chat ; un simple répertoire source copié reste inactif, de sorte que les installations empaquetées normales continuent d’utiliser la distribution compilée.

Pour déboguer les hooks d’exécution :

• openclaw plugins inspect <id> --runtime --json affiche les hooks enregistrés et les diagnostics issus d’une passe d’inspection avec chargement du module. L’inspection d’exécution n’installe jamais de dépendances ; utilisez openclaw doctor --fix pour nettoyer l’état hérité des dépendances ou récupérer les plugins téléchargeables manquants qui sont référencés par la configuration.
• openclaw gateway status --deep --require-rpc confirme l’URL et le profil Gateway accessibles, les indications relatives au service et au processus, le chemin de configuration et l’état RPC.
• Les hooks de conversation non intégrés (llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize, agent_end) nécessitent plugins.entries.<id>.hooks.allowConversationAccess=true.

Index des plugins

Les métadonnées d’installation des plugins constituent un état géré par la machine, et non une configuration utilisateur. Les installations et les mises à jour les écrivent dans la base de données d’état SQLite partagée, sous le répertoire d’état OpenClaw actif. La ligne installed_plugin_index stocke des métadonnées installRecords durables, notamment des enregistrements pour les manifestes de plugins endommagés ou manquants, ainsi qu’un cache de registre à froid dérivé des manifestes utilisé par openclaw plugins update, la désinstallation, les diagnostics et le registre de plugins à froid.

Lorsqu’OpenClaw détecte dans la configuration des enregistrements hérités plugins.installs provenant d’une version publiée, les lectures à l’exécution les traitent comme des données de compatibilité sans réécrire openclaw.json. Les écritures explicites de plugins et openclaw doctor --fix déplacent ces enregistrements vers l’index des plugins et suppriment la clé de configuration lorsque les écritures de configuration sont autorisées ; si l’une ou l’autre écriture échoue, les enregistrements de configuration sont conservés afin de ne pas perdre les métadonnées d’installation.

Désinstallation

openclaw plugins uninstall <id>openclaw plugins uninstall <id> --dry-runopenclaw plugins uninstall <id> --keep-filesopenclaw plugins uninstall <id> --force

uninstall supprime les enregistrements du plugin de plugins.entries, de l’index persistant des plugins, des entrées des listes d’autorisation et de refus des plugins, ainsi que des entrées plugins.load.paths liées, le cas échéant. Sauf si --keep-files est défini, la désinstallation supprime également le répertoire d’installation géré suivi, mais uniquement si son chemin résolu se trouve dans la racine des extensions de plugins d’OpenClaw. Si le plugin occupe actuellement l’emplacement memory ou contextEngine, cet emplacement est réinitialisé à sa valeur par défaut (memory-core pour la mémoire, legacy pour le moteur de contexte).

uninstall affiche un aperçu de ce qui sera supprimé, puis demande Uninstall plugin "<id>"? avant d’appliquer les modifications. Passez --force pour ignorer la demande de confirmation, ce qui est utile pour les scripts et les exécutions non interactives ; sans cette option, la désinstallation nécessite un TTY interactif. --dry-run affiche le même aperçu et se termine sans demander de confirmation ni modifier quoi que ce soit.

Mise à jour

openclaw plugins update <id-or-npm-spec>openclaw plugins update --allopenclaw plugins update <id-or-npm-spec> --dry-runopenclaw plugins update @openclaw/voice-callopenclaw plugins update @acme/demoopenclaw plugins update openclaw-codex-app-server --acknowledge-clawhub-riskopenclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install

Les mises à jour s’appliquent aux installations de plugins suivies dans l’index géré des plugins et aux installations de paquets de hooks suivies dans hooks.internal.installs. Elles réutilisent la source déjà choisie par l’utilisateur lors de l’installation du plugin et ne nécessitent donc pas une seconde acceptation de la source.

Inspection

openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --jsonopenclaw plugins inspect --all

Par défaut, l’inspection affiche l’identité, l’état de chargement, la source, les capacités du manifeste, les indicateurs de politique, les diagnostics, les métadonnées d’installation, les capacités du paquet et toute prise en charge détectée de serveurs MCP ou LSP, sans importer le code d’exécution du plugin. La sortie JSON inclut les contrats du manifeste du plugin, tels que contracts.agentToolResultMiddleware et contracts.trustedToolPolicies, afin que les opérateurs puissent auditer les déclarations des surfaces fiables avant d’activer ou de redémarrer un plugin. Ajoutez --runtime pour charger le module du plugin et inclure les hooks, outils, commandes, services, méthodes du Gateway et routes HTTP enregistrés. L’inspection d’exécution signale directement les dépendances de plugin manquantes ; les installations et réparations restent assurées par openclaw plugins install, openclaw plugins update et openclaw doctor --fix.

Les commandes CLI appartenant aux plugins sont généralement installées sous forme de groupes de commandes openclaw à la racine, mais les plugins peuvent également enregistrer des commandes imbriquées sous un parent du cœur tel que openclaw nodes. Une fois que inspect --runtime affiche une commande sous cliCommands, exécutez-la au chemin indiqué ; par exemple, un plugin qui enregistre demo-git peut être vérifié avec openclaw demo-git ping.

Chaque plugin est classé selon ce qu’il enregistre réellement à l’exécution :

Consultez Formes de plugins pour en savoir plus sur le modèle de capacités.

Doctor

openclaw plugins doctor

doctor signale les erreurs de chargement des plugins, les diagnostics de manifeste/découverte, les avis de compatibilité et les références obsolètes de configuration de plugins, telles que des emplacements de plugins manquants. Lorsque l’arborescence d’installation et la configuration des plugins sont propres, il affiche No plugin issues detected. Si une configuration obsolète subsiste, mais que l’arborescence d’installation est par ailleurs saine, le résumé l’indique au lieu de laisser entendre que tous les plugins sont sains.

Si un plugin configuré est présent sur le disque, mais bloqué par les contrôles de sécurité des chemins du chargeur, la validation de la configuration conserve l’entrée du plugin et la signale comme present but blocked. Corrigez le diagnostic précédent concernant le plugin bloqué, par exemple la propriété du chemin ou les autorisations d’écriture pour tous, au lieu de supprimer la configuration plugins.entries.<id> ou plugins.allow.

Pour les échecs liés à la structure du module, tels que des exports register/activate manquants, relancez avec OPENCLAW_PLUGIN_LOAD_DEBUG=1 afin d’inclure un résumé compact de la structure des exports dans la sortie de diagnostic.

Registre

openclaw plugins registryopenclaw plugins registry --refreshopenclaw plugins registry --json

Le registre local des plugins est le modèle de lecture à froid persistant d’OpenClaw pour l’identité des plugins installés, leur activation, les métadonnées de leur source et la propriété de leurs contributions. Le démarrage normal, la recherche du propriétaire d’un fournisseur, la classification de la configuration des canaux et l’inventaire des plugins peuvent le consulter sans importer les modules d’exécution des plugins.

Utilisez plugins registry pour vérifier si le registre persistant est présent, à jour ou obsolète. Utilisez --refresh pour le reconstruire à partir de l’index persistant des plugins, de la politique de configuration et des métadonnées des manifestes/paquets. Il s’agit d’une procédure de réparation, et non d’une procédure d’activation à l’exécution.

openclaw doctor --fix répare également les dérives npm gérées adjacentes au registre : si un paquet @openclaw/* orphelin ou récupéré, situé dans un projet npm de plugin géré ou dans l’ancienne racine npm gérée à plat, masque un plugin intégré, doctor supprime ce paquet obsolète et reconstruit le registre afin que le démarrage effectue la validation par rapport au manifeste intégré. Doctor recrée également le lien vers le paquet hôte openclaw dans les plugins npm gérés qui déclarent peerDependencies.openclaw, afin que les imports d’exécution locaux au paquet, tels que openclaw/plugin-sdk/*, soient résolus après des mises à jour ou des réparations npm.

Place de marché

openclaw plugins marketplace entriesopenclaw plugins marketplace entries --offlineopenclaw plugins marketplace entries --jsonopenclaw plugins marketplace entries --feed-profile <name>openclaw plugins marketplace entries --feed-url <url>openclaw plugins marketplace list <source>openclaw plugins marketplace list <source> --jsonopenclaw plugins marketplace refreshopenclaw plugins marketplace refresh --feed-profile <name>openclaw plugins marketplace refresh --feed-url <url>openclaw plugins marketplace refresh --expected-sha256 <sha256> --json

plugins marketplace entries répertorie les entrées du flux de place de marché OpenClaw configuré. Par défaut, il tente d’utiliser le flux hébergé et se rabat sur le dernier instantané accepté ou les données intégrées. Utilisez --feed-profile <name> pour lire un profil configuré spécifique, --feed-url <url> pour lire une URL explicite de flux hébergé et --offline pour lire le dernier instantané accepté sans récupérer le flux.

plugins marketplace refresh actualise l’instantané du flux hébergé configuré et indique si OpenClaw a accepté les données hébergées, un instantané hébergé ou les données intégrées de repli. Utilisez --expected-sha256 lorsqu’un appelant exige que la commande échoue à moins qu’une charge utile hébergée récente corresponde à une somme de contrôle épinglée.

La commande list de la place de marché accepte un chemin local de place de marché, un chemin marketplace.json, un raccourci GitHub tel que owner/repo, une URL de dépôt GitHub ou une URL git. --json affiche le libellé de la source résolue, ainsi que le manifeste analysé de la place de marché et les entrées de plugins.

L’actualisation de la place de marché charge un flux hébergé de la place de marché OpenClaw et conserve la réponse validée en tant qu’instantané local du flux hébergé. Sans option, elle utilise le profil de flux par défaut configuré. Utilisez --feed-profile <name> pour actualiser un profil configuré spécifique, --feed-url <url> pour actualiser une URL explicite de flux hébergé, --expected-sha256 <sha256> pour exiger une somme de contrôle de charge utile correspondante (sha256:<hex> ou un condensé hexadécimal brut de 64 caractères), et --json pour une sortie lisible par une machine. Les URL explicites de flux hébergés ne doivent pas contenir d’identifiants, de chaînes de requête ni de fragments. Les actualisations non épinglées peuvent signaler un instantané hébergé ou un résultat de repli sur les données intégrées sans faire échouer la commande. Les actualisations épinglées échouent sauf si elles acceptent une nouvelle charge utile hébergée, et les actualisations hébergées réussies échouent si OpenClaw ne peut pas conserver l’instantané validé.

Voir aussi

• Création de plugins
• Référence de la CLI
• ClawHub