15 KiB
| read_when | summary | title | x-i18n | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Référence CLI pour `openclaw plugins` (liste, installation, marketplace, désinstallation, activation/désactivation, doctor) | plugins |
|
openclaw plugins
Gérez les plugins/extensions de la passerelle, les packs de hooks et les bundles compatibles.
Lié :
- Système de plugins : Plugins
- Compatibilité des bundles : Bundles de plugins
- Manifeste + schéma de plugin : Manifeste de plugin
- Durcissement de la sécurité : Security
Commandes
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
openclaw plugins inspect --all
openclaw plugins info <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins uninstall <id>
openclaw plugins doctor
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
Les plugins groupés sont livrés avec OpenClaw. Certains sont activés par défaut (par exemple les fournisseurs de modèles groupés, les fournisseurs vocaux groupés et le plugin navigateur groupé) ; d’autres nécessitent plugins enable.
Les plugins OpenClaw natifs doivent fournir openclaw.plugin.json avec un schéma JSON inline (configSchema, même s’il est vide). Les bundles compatibles utilisent à la place leurs propres manifestes de bundle.
plugins list affiche Format: openclaw ou Format: bundle. La sortie détaillée de list/info affiche aussi le sous-type de bundle (codex, claude ou cursor) ainsi que les capacités de bundle détectées.
Installation
openclaw plugins install <package> # ClawHub d’abord, puis npm
openclaw plugins install clawhub:<package> # ClawHub uniquement
openclaw plugins install <package> --force # écraser une installation existante
openclaw plugins install <package> --pin # épingler la version
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path> # chemin local
openclaw plugins install <plugin>@<marketplace> # marketplace
openclaw plugins install <plugin> --marketplace <name> # marketplace (explicite)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
Les noms de package nus sont d’abord vérifiés dans ClawHub, puis dans npm. Remarque de sécurité : traitez les installations de plugin comme l’exécution de code. Préférez les versions épinglées.
Si la configuration est invalide, plugins install échoue normalement en mode fail-closed et vous indique d’exécuter d’abord openclaw doctor --fix. La seule exception documentée est un chemin étroit de récupération de plugin groupé pour les plugins qui activent explicitement openclaw.install.allowInvalidConfigRecovery.
--force réutilise la cible d’installation existante et écrase sur place un plugin ou pack de hooks déjà installé. Utilisez-le lorsque vous réinstallez intentionnellement le même identifiant à partir d’un nouveau chemin local, d’une archive, d’un package ClawHub ou d’un artefact npm.
--pin s’applique uniquement aux installations npm. Il n’est pas pris en charge avec --marketplace, car les installations depuis un marketplace conservent des métadonnées de source de marketplace au lieu d’une spécification npm.
--dangerously-force-unsafe-install est une option de dernier recours pour les faux positifs dans l’analyseur intégré de code dangereux. Elle permet à l’installation de continuer même lorsque l’analyseur intégré signale des constats critical, mais elle ne contourne pas les blocages de politique des hooks before_install du plugin et ne contourne pas les échecs d’analyse.
Cette option CLI s’applique aux flux d’installation/mise à jour de plugins. Les installations de dépendances de Skills adossées à la passerelle utilisent la surcharge de requête correspondante dangerouslyForceUnsafeInstall, tandis que openclaw skills install reste un flux distinct de téléchargement/installation de Skills ClawHub.
plugins install est également la surface d’installation pour les packs de hooks qui exposent openclaw.hooks dans package.json. Utilisez openclaw hooks pour la visibilité filtrée des hooks et l’activation par hook, et non pour l’installation des packages.
Les spécifications npm sont réservées au registre (nom du package + version exacte ou dist-tag facultatif). Les spécifications git/URL/fichier et les plages semver sont rejetées. Les installations de dépendances s’exécutent avec --ignore-scripts pour des raisons de sécurité.
Les spécifications nues et @latest restent sur la piste stable. Si npm résout l’un ou l’autre vers une préversion, OpenClaw s’arrête et vous demande d’opter explicitement pour une balise de préversion telle que @beta/@rc ou une version de préversion exacte telle que @1.2.3-beta.4.
Si une spécification d’installation nue correspond à un identifiant de plugin groupé (par exemple diffs), OpenClaw installe directement le plugin groupé. Pour installer un package npm portant le même nom, utilisez une spécification explicitement préfixée par un scope (par exemple @scope/diffs).
Archives prises en charge : .zip, .tgz, .tar.gz, .tar.
Les installations depuis le marketplace Claude sont également prises en charge.
Les installations ClawHub utilisent un localisateur explicite clawhub:<package> :
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
OpenClaw préfère désormais aussi ClawHub pour les spécifications de plugin nues compatibles npm. Il ne revient à npm que si ClawHub ne possède pas ce package ou cette version :
openclaw plugins install openclaw-codex-app-server
OpenClaw télécharge l’archive du package depuis ClawHub, vérifie la compatibilité annoncée avec l’API du plugin / la version minimale de la passerelle, puis l’installe via le chemin normal d’archive. Les installations enregistrées conservent leurs métadonnées de source ClawHub pour les mises à jour ultérieures.
Utilisez la forme abrégée plugin@marketplace lorsque le nom du marketplace existe dans le cache local de registre Claude à ~/.claude/plugins/known_marketplaces.json :
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
Utilisez --marketplace lorsque vous souhaitez transmettre explicitement la source du marketplace :
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
Les sources de marketplace peuvent être :
- un nom de marketplace connu de Claude provenant de
~/.claude/plugins/known_marketplaces.json - une racine de marketplace locale ou un chemin
marketplace.json - une forme abrégée de dépôt GitHub telle que
owner/repo - une URL de dépôt GitHub telle que
https://github.com/owner/repo - une URL git
Pour les marketplaces distants chargés depuis GitHub ou git, les entrées de plugin doivent rester à l’intérieur du dépôt de marketplace cloné. OpenClaw accepte les sources de chemin relatif depuis ce dépôt et rejette les sources de plugin HTTP(S), de chemin absolu, git, GitHub et autres sources non basées sur des chemins provenant de manifestes distants.
Pour les chemins locaux et les archives, OpenClaw détecte automatiquement :
- les plugins OpenClaw natifs (
openclaw.plugin.json) - les bundles compatibles Codex (
.codex-plugin/plugin.json) - les bundles compatibles Claude (
.claude-plugin/plugin.jsonou la disposition de composants Claude par défaut) - les bundles compatibles Cursor (
.cursor-plugin/plugin.json)
Les bundles compatibles sont installés dans la racine normale des extensions et participent au même flux list/info/enable/disable. Aujourd’hui, les Skills de bundle, les command-skills Claude, les valeurs par défaut settings.json de Claude, les valeurs par défaut Claude .lsp.json / lspServers déclarées dans le manifeste, les command-skills Cursor et les répertoires de hooks Codex compatibles sont pris en charge ; les autres capacités de bundle détectées sont affichées dans les diagnostics/info mais ne sont pas encore raccordées à l’exécution runtime.
Liste
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
Utilisez --enabled pour n’afficher que les plugins chargés. Utilisez --verbose pour passer de la vue tableau à des lignes de détail par plugin avec les métadonnées de source/origine/version/activation. Utilisez --json pour un inventaire lisible par machine ainsi que les diagnostics du registre.
Utilisez --link pour éviter de copier un répertoire local (ajoute à plugins.load.paths) :
openclaw plugins install -l ./my-plugin
--force n’est pas pris en charge avec --link car les installations liées réutilisent le chemin source au lieu de copier vers une cible d’installation gérée.
Utilisez --pin sur les installations npm pour enregistrer la spécification exacte résolue (name@version) dans plugins.installs tout en conservant le comportement non épinglé par défaut.
Désinstallation
openclaw plugins uninstall <id>
openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
uninstall supprime les enregistrements de plugin de plugins.entries, plugins.installs, de la liste d’autorisation des plugins et des entrées liées plugins.load.paths lorsqu’elles s’appliquent.
Pour les plugins de mémoire actifs, le slot mémoire revient à memory-core.
Par défaut, la désinstallation supprime aussi le répertoire d’installation du plugin sous la racine de plugins du répertoire d’état actif. Utilisez
--keep-files pour conserver les fichiers sur disque.
--keep-config est pris en charge comme alias obsolète de --keep-files.
Mise à jour
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins update <id-or-npm-spec> --dry-run
openclaw plugins update @openclaw/voice-call@beta
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
Les mises à jour s’appliquent aux installations suivies dans plugins.installs et aux installations suivies de packs de hooks dans hooks.internal.installs.
Lorsque vous transmettez un identifiant de plugin, OpenClaw réutilise la spécification d’installation enregistrée pour ce plugin. Cela signifie que les dist-tags précédemment stockés tels que @beta et les versions exactes épinglées continuent d’être utilisés lors des exécutions ultérieures de update <id>.
Pour les installations npm, vous pouvez aussi transmettre une spécification explicite de package npm avec un dist-tag ou une version exacte. OpenClaw résout alors ce nom de package vers l’enregistrement de plugin suivi, met à jour ce plugin installé et enregistre la nouvelle spécification npm pour les futures mises à jour basées sur l’identifiant.
Lorsqu’un hachage d’intégrité stocké existe et que le hachage de l’artefact récupéré change, OpenClaw affiche un avertissement et demande une confirmation avant de continuer. Utilisez le --yes global pour contourner les invites dans les exécutions CI/non interactives.
--dangerously-force-unsafe-install est également disponible sur plugins update comme surcharge de dernier recours pour les faux positifs de l’analyse intégrée de code dangereux lors des mises à jour de plugin. Il ne contourne toujours pas les blocages de politique before_install du plugin ni le blocage en cas d’échec d’analyse, et il s’applique uniquement aux mises à jour de plugins, pas aux mises à jour de packs de hooks.
Inspection
openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
Inspection approfondie d’un plugin unique. Affiche l’identité, l’état de chargement, la source, les capacités enregistrées, les hooks, les outils, les commandes, les services, les méthodes de passerelle, les routes HTTP, les indicateurs de politique, les diagnostics, les métadonnées d’installation, les capacités de bundle et tout support MCP ou LSP détecté.
Chaque plugin est classé selon ce qu’il enregistre réellement à l’exécution :
- plain-capability — un seul type de capacité (par ex. un plugin uniquement fournisseur)
- hybrid-capability — plusieurs types de capacités (par ex. texte + voix + images)
- hook-only — uniquement des hooks, sans capacités ni surfaces
- non-capability — outils/commandes/services mais sans capacités
Consultez Formes de plugins pour en savoir plus sur le modèle de capacités.
L’option --json produit un rapport lisible par machine adapté aux scripts et aux audits.
inspect --all affiche un tableau à l’échelle de la flotte avec les colonnes forme, types de capacités, remarques de compatibilité, capacités de bundle et résumé des hooks.
info est un alias de inspect.
Doctor
openclaw plugins doctor
doctor signale les erreurs de chargement des plugins, les diagnostics de manifeste/découverte et les remarques de compatibilité. Lorsque tout est propre, il affiche No plugin issues detected.
Marketplace
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
La liste du marketplace accepte un chemin de marketplace local, un chemin marketplace.json, une forme abrégée GitHub comme owner/repo, une URL de dépôt GitHub ou une URL git. --json affiche le libellé de source résolu ainsi que le manifeste de marketplace analysé et les entrées de plugin.