Passer au contenu principal
Les Plugins étendent OpenClaw avec des canaux, des fournisseurs de modèles, des harnais d’agent, des outils, des Skills, la parole, la transcription en temps réel, la voix, la compréhension des médias, la génération, la récupération web, la recherche web et d’autres capacités d’exécution. Utilisez cette page lorsque vous voulez installer un plugin, redémarrer le Gateway, vérifier que le runtime l’a chargé et résoudre les échecs de configuration courants. Pour des exemples uniquement sous forme de commandes, consultez Gérer les plugins. Pour l’inventaire généré complet des plugins groupés, externes officiels et disponibles uniquement dans le source, consultez Inventaire des Plugin.

​
Prérequis

Avant d’installer un plugin, assurez-vous de disposer de :
  • un checkout ou une installation OpenClaw avec la CLI openclaw disponible
  • un accès réseau à la source sélectionnée, comme ClawHub, npm ou un hôte git
  • tous les identifiants, clés de configuration ou outils de système d’exploitation propres au plugin indiqués par la documentation de configuration de ce plugin
  • l’autorisation pour le Gateway qui dessert vos canaux de se recharger ou de redémarrer

​
Démarrage rapide

1

Trouver le plugin

Recherchez des paquets de plugins publics dans ClawHub :
openclaw plugins search "calendar"
ClawHub est la principale surface de découverte pour les plugins communautaires. Pendant la bascule de lancement, les spécifications de paquet ordinaires sans préfixe s’installent toujours depuis npm sauf si elles correspondent à un id de plugin officiel. Les spécifications de paquet @openclaw/* brutes qui correspondent à des plugins groupés utilisent la copie groupée de la version actuelle d’OpenClaw. Utilisez un préfixe explicite lorsque vous avez besoin d’une source précise.
2

Installer le plugin

# Depuis ClawHub.
openclaw plugins install clawhub:<package>

# Depuis npm.
openclaw plugins install npm:<package>

# Depuis git.
openclaw plugins install git:github.com/<owner>/<repo>@<ref>

# Depuis un checkout de développement local.
openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin
Traitez les installations de plugins comme l’exécution de code. Préférez les versions épinglées lorsque vous avez besoin d’installations de production reproductibles.
3

Le configurer et l’activer

Configurez les paramètres propres au plugin sous plugins.entries.<id>.config. Activez le plugin lorsqu’il ne l’est pas déjà :
openclaw plugins enable <plugin-id>
Si votre configuration utilise une liste restrictive plugins.allow, l’id du plugin installé doit y être présent avant que le plugin puisse se charger. openclaw plugins install ajoute l’id installé à une liste plugins.allow existante et supprime le même id de plugins.deny afin que l’installation explicite puisse se charger après redémarrage.
4

Laisser le Gateway se recharger

L’installation, la mise à jour ou la désinstallation du code d’un plugin nécessite un redémarrage du Gateway. Lorsqu’un Gateway géré est déjà en cours d’exécution avec le rechargement de configuration activé, OpenClaw détecte l’enregistrement d’installation de plugin modifié et redémarre le Gateway automatiquement. Si le Gateway n’est pas géré ou si le rechargement est désactivé, redémarrez-le vous-même :
openclaw gateway restart
Les opérations d’activation et de désactivation mettent à jour la configuration et rafraîchissent le registre à froid. Une inspection du runtime reste le chemin de vérification le plus clair pour les surfaces d’exécution actives.
5

Vérifier l’enregistrement dans le runtime

openclaw plugins inspect <plugin-id> --runtime --json
Utilisez --runtime lorsque vous devez prouver les outils, hooks, services, méthodes Gateway ou commandes CLI appartenant au plugin qui sont enregistrés. Un simple inspect est une vérification à froid du manifeste et du registre.

​
Configuration

​
Choisir une source d’installation

SourceÀ utiliser lorsqueExemple
ClawHubVous voulez une découverte native OpenClaw, des analyses, des métadonnées de version et des indications d’installationopenclaw plugins install clawhub:<package>
npmVous avez besoin de workflows directs de registre npm ou de dist-tagopenclaw plugins install npm:<package>
gitVous avez besoin d’une branche, d’un tag ou d’un commit depuis un dépôtopenclaw plugins install git:github.com/<owner>/<repo>@<ref>
chemin localVous développez ou testez un plugin sur la même machineopenclaw plugins install --link ./my-plugin
marketplaceVous installez un plugin de marketplace compatible avec Claudeopenclaw plugins install <plugin> --marketplace <source>
Les spécifications de paquet sans préfixe ont un comportement de compatibilité spécial. Si le nom sans préfixe correspond à un id de plugin groupé, OpenClaw utilise cette source groupée. S’il correspond à un id de plugin externe officiel, OpenClaw utilise le catalogue de paquets officiel. Les autres spécifications de paquet ordinaires sans préfixe s’installent via npm pendant la bascule de lancement. Les spécifications de paquet @openclaw/* brutes qui correspondent à des plugins groupés se résolvent aussi vers la copie groupée avant le repli npm. Utilisez npm:@openclaw/<plugin>@<version> lorsque vous voulez délibérément le paquet npm externe plutôt que la copie groupée détenue par l’image. Utilisez clawhub:, npm:, git: ou npm-pack: lorsque vous avez besoin d’une sélection de source déterministe. Consultez openclaw plugins pour le contrat de commande complet. Pour les installations npm, les spécifications de paquet non épinglées et @latest choisissent le paquet stable le plus récent qui annonce sa compatibilité avec cette version d’OpenClaw. Si la version latest actuelle de npm déclare un openclaw.compat.pluginApi ou un openclaw.install.minHostVersion plus récent, OpenClaw analyse les anciennes versions stables du paquet et installe la plus récente qui convient. Les versions exactes et les tags de canal explicites comme @beta restent épinglés au paquet sélectionné et échouent en cas d’incompatibilité.

​
Politique d’installation de l’opérateur

Configurez security.installPolicy pour exécuter une commande de politique locale de confiance avant que l’installation ou la mise à jour d’un plugin ne se poursuive. La politique reçoit les métadonnées ainsi que le chemin source préparé et peut autoriser ou bloquer l’installation. Elle couvre les chemins d’installation/mise à jour de plugins adossés à la CLI et au Gateway. Les hooks before_install de plugin s’exécutent plus tard uniquement dans les processus OpenClaw où les hooks de plugin sont chargés, donc utilisez security.installPolicy pour les décisions d’installation détenues par l’opérateur. L’option obsolète --dangerously-force-unsafe-install est acceptée pour compatibilité mais ne contourne pas la politique d’installation ni la denylist intégrée d’OpenClaw pour les dépendances de plugins. Consultez Configuration des Skills pour le schéma exec partagé security.installPolicy utilisé à la fois par les Skills et les plugins.

​
Configurer la politique des plugins

La forme de configuration commune des plugins est : 
{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-plugin"] },
    slots: { memory: "memory-core" },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}
Règles de politique clés :
  • plugins.enabled: false désactive tous les plugins et ignore le travail de découverte/chargement des plugins. Les références de plugins obsolètes sont inertes tant que cela est actif ; réactivez les plugins avant d’exécuter le nettoyage doctor lorsque vous voulez supprimer les ids obsolètes.
  • plugins.deny l’emporte sur l’autorisation et l’activation par plugin.
  • plugins.allow est une allowlist exclusive. Les outils appartenant aux plugins en dehors de l’allowlist restent indisponibles, même lorsque tools.allow inclut "*".
  • plugins.entries.<id>.enabled: false désactive un plugin tout en conservant sa configuration.
  • plugins.load.paths ajoute des fichiers ou répertoires de plugin locaux explicites. Les chemins locaux plugins install gérés doivent être des répertoires ou archives de plugin ; utilisez plugins.load.paths pour les fichiers de plugin autonomes.
  • Les plugins issus du workspace sont désactivés par défaut ; activez-les explicitement ou ajoutez-les à l’allowlist avant d’utiliser du code de workspace local.
  • Les plugins groupés suivent leurs métadonnées intégrées default-on/default-off sauf si la configuration les remplace explicitement.
  • plugins.slots.<slot> choisit un plugin pour des catégories exclusives comme les moteurs de mémoire et de contexte. La sélection d’un slot force l’activation du plugin sélectionné pour ce slot en comptant comme activation explicite ; il peut se charger même lorsqu’il serait sinon opt-in. plugins.deny et plugins.entries.<id>.enabled: false le bloquent toujours.
  • Les plugins groupés opt-in peuvent s’auto-activer lorsque la configuration nomme l’une de leurs surfaces détenues, comme une référence fournisseur/modèle, une configuration de canal, un backend CLI ou un runtime de harnais d’agent.
  • Le routage Codex de la famille OpenAI garde les frontières du fournisseur et du plugin de runtime séparées : les anciennes références de modèles Codex sont une configuration legacy réparée par doctor, tandis que le plugin groupé codex possède le runtime serveur d’application Codex pour les références d’agent canoniques openai/*, agentRuntime.id: "codex" explicite et les références legacy codex/*.
Lorsque plugins.allow n’est pas défini et que des plugins non groupés sont auto-découverts depuis le workspace ou les racines de plugins globales, les journaux de démarrage indiquent plugins.allow is empty; discovered non-bundled plugins may auto-load: .... L’avertissement inclut les ids de plugins découverts et, pour les listes courtes, un extrait minimal plugins.allow. Exécutez openclaw plugins list --enabled --verbose ou openclaw plugins inspect <id> avec l’id de plugin indiqué avant de copier des plugins de confiance dans openclaw.json. Les mêmes recommandations d’épinglage de confiance s’appliquent lorsque les diagnostics indiquent qu’un plugin s’est chargé without install/load-path provenance : inspectez cet id de plugin, puis épinglez l’id de confiance dans plugins.allow ou réinstallez depuis une source de confiance afin qu’OpenClaw enregistre la provenance d’installation. Exécutez openclaw doctor ou openclaw doctor --fix lorsque la validation de configuration signale des ids de plugins obsolètes, des incohérences allowlist/outils ou des chemins de plugins groupés legacy.

​
Comprendre les formats de plugins

OpenClaw reconnaît deux formats de plugins :
FormatComment il se chargeÀ utiliser lorsque
Plugin OpenClaw natifopenclaw.plugin.json plus un module de runtime chargé dans le processusVous installez ou construisez des capacités de runtime propres à OpenClaw
Bundle compatibleAgencement de plugin Codex, Claude ou Cursor mappé dans l’inventaire des plugins OpenClawVous réutilisez des Skills, commandes, hooks ou métadonnées de bundle compatibles
Les deux formats apparaissent dans openclaw plugins list, openclaw plugins inspect, openclaw plugins enable et openclaw plugins disable. Consultez Bundles de plugins pour la frontière de compatibilité des bundles et Construire des plugins pour la création de plugins natifs.

​
Hooks de plugin

Les plugins peuvent enregistrer des hooks au runtime, mais il existe deux API différentes avec des rôles différents.
  • Utilisez les hooks typés via api.on(...) pour les hooks de cycle de vie du runtime. C’est la surface privilégiée pour les middlewares, les politiques, la réécriture de messages, la mise en forme des prompts et le contrôle des outils.
  • Utilisez api.registerHook(...) uniquement lorsque vous voulez participer au système de hooks interne décrit dans Hooks. C’est principalement destiné aux effets de bord grossiers de commande/cycle de vie et à la compatibilité avec l’automatisation existante de style HOOK.
Règle rapide :
  • Si le gestionnaire a besoin d’une priorité, d’une sémantique de fusion ou d’un comportement de blocage/annulation, utilisez les hooks de plugin typés.
  • Si le gestionnaire réagit simplement à command:new, command:reset, message:sent ou à des événements grossiers similaires, api.registerHook(...) convient.
Les hooks internes gérés par des plugins apparaissent dans openclaw hooks list avec plugin:<id>. Vous ne pouvez pas les activer ni les désactiver via openclaw hooks ; activez ou désactivez plutôt le plugin.

​
Vérifier le Gateway actif

openclaw plugins list et openclaw plugins inspect simple lisent l’état à froid de la config, du manifeste et du registre. Ils ne prouvent pas qu’un Gateway déjà en cours d’exécution a importé le même code de Plugin. Lorsqu’un Plugin semble installé mais que le trafic de discussion en direct ne l’utilise pas : 
openclaw gateway status --deep --require-rpc
openclaw plugins inspect <plugin-id> --runtime --json
openclaw gateway restart
Les Gateways gérés redémarrent automatiquement après les changements d’installation, de mise à jour et de désinstallation de Plugins qui modifient la source du Plugin. Sur les installations VPS ou en conteneur, assurez-vous que tout redémarrage manuel cible le véritable processus enfant openclaw gateway run qui sert vos canaux, et pas seulement un wrapper ou un superviseur.

​
Dépannage

SymptômeVérificationCorrectif
Le Plugin apparaît dans plugins list, mais les hooks runtime ne s’exécutent pasUtilisez openclaw plugins inspect <id> --runtime --json et confirmez le Gateway actif avec gateway status --deep --require-rpcRedémarrez le Gateway en direct après des changements d’installation, de mise à jour, de config ou de source
Des diagnostics de propriété de canal ou d’outil en double apparaissentExécutez openclaw plugins list --enabled --verbose, inspectez chaque Plugin suspect avec --runtime --json, et comparez la propriété des canaux/outilsDésactivez un propriétaire, supprimez les installations obsolètes, ou utilisez le manifeste preferOver pour un remplacement intentionnel
La config indique qu’un Plugin est manquantConsultez Inventaire des Plugins pour savoir s’il est groupé, externe officiel ou uniquement sourceInstallez le package externe, activez le Plugin groupé, ou supprimez la config obsolète
La config est invalide pendant l’installationLisez le message de validation et exécutez openclaw doctor --fix lorsqu’il pointe vers un état de Plugin obsolèteDoctor peut mettre en quarantaine une config de Plugin invalide en désactivant l’entrée et en supprimant le payload invalide
Le chemin du Plugin est bloqué pour cause de propriété ou de permissions suspectesInspectez le diagnostic avant l’erreur de configCorrigez la propriété/les permissions du système de fichiers, puis exécutez openclaw plugins registry --refresh
OPENCLAW_NIX_MODE=1 bloque les commandes de cycle de vieConfirmez que l’installation est gérée par NixModifiez la sélection de Plugins dans la source Nix au lieu d’utiliser les commandes de mutation de Plugins
L’importation d’une dépendance échoue au runtimeVérifiez si le Plugin a été installé via npm/git/ClawHub ou chargé depuis un chemin localExécutez openclaw plugins update <id>, réinstallez la source, ou installez vous-même les dépendances locales du Plugin
Lorsqu’une config de Plugin obsolète nomme encore un Plugin de canal qui n’est plus découvrable, le démarrage du Gateway ignore ce canal fourni par Plugin au lieu de bloquer tous les autres canaux. Exécutez openclaw doctor --fix pour supprimer les entrées de Plugin et de canal obsolètes. Les clés de canal inconnues sans preuve de Plugin obsolète échouent toujours à la validation afin que les fautes de frappe restent visibles. Pour un remplacement intentionnel de canal, le Plugin préféré doit déclarer channelConfigs.<channel-id>.preferOver avec l’id de Plugin hérité ou de priorité inférieure. Si les deux Plugins sont explicitement activés, OpenClaw conserve cette demande et signale des diagnostics de canal ou d’outil en double au lieu de choisir silencieusement un propriétaire. Si un package installé signale qu’il requires compiled runtime output for TypeScript entry ..., le package a été publié sans les fichiers JavaScript dont OpenClaw a besoin au runtime. Mettez à jour ou réinstallez après que l’éditeur a livré le JavaScript compilé, ou désactivez/désinstallez le Plugin jusque-là.

​
Propriété bloquée du chemin de Plugin

Si les diagnostics de Plugin indiquent blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) et que la validation de config suit avec plugin present but blocked, OpenClaw a trouvé des fichiers de Plugin appartenant à un utilisateur Unix différent de celui du processus qui les charge. Gardez la config de Plugin en place ; corrigez la propriété du système de fichiers ou exécutez OpenClaw avec le même utilisateur que celui qui possède le répertoire d’état. Pour les installations Docker, l’image officielle s’exécute en tant que node (uid 1000), donc les répertoires de config OpenClaw et d’espace de travail montés depuis l’hôte doivent normalement appartenir à l’uid 1000 : 
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
Si vous exécutez intentionnellement OpenClaw en tant que root, réparez plutôt la racine de Plugins gérée pour qu’elle appartienne à root : 
sudo chown -R root:root /path/to/openclaw-config/npm
Après avoir corrigé la propriété, relancez openclaw doctor --fix ou openclaw plugins registry --refresh afin que le registre de Plugins persistant corresponde aux fichiers réparés.

​
Configuration lente des outils de Plugin

Si les tours d’agent semblent se bloquer pendant la préparation des outils, activez la journalisation de trace et recherchez les lignes de chronométrage des fabriques d’outils de Plugin : 
openclaw config set logging.level trace
openclaw logs --follow
Recherchez : 
[trace:plugin-tools] factory timings ...
Le résumé liste le temps total des fabriques et les fabriques d’outils de Plugin les plus lentes, y compris l’id du Plugin, les noms d’outils déclarés, la forme du résultat, et si l’outil est optionnel. Les lignes lentes sont promues en avertissements lorsqu’une seule fabrique prend au moins 1 s ou que la préparation totale des fabriques d’outils de Plugin prend au moins 5 s. OpenClaw met en cache les résultats réussis des fabriques d’outils de Plugin pour les résolutions répétées avec le même contexte de requête effectif. La clé de cache inclut la config runtime effective, l’espace de travail, les ids d’agent/session, la politique de sandbox, les paramètres du navigateur, le contexte de livraison, l’identité du demandeur et l’état de propriété, de sorte que les fabriques qui dépendent de ces champs fiables sont réexécutées lorsque le contexte change. Si les temps restent élevés, le Plugin effectue peut-être un travail coûteux avant de renvoyer ses définitions d’outils. Si un Plugin domine le chronométrage, inspectez ses enregistrements runtime : 
openclaw plugins inspect <plugin-id> --runtime --json
Ensuite, mettez à jour, réinstallez ou désactivez ce Plugin. Les auteurs de Plugins doivent déplacer le chargement coûteux des dépendances derrière le chemin d’exécution de l’outil au lieu de le faire dans la fabrique d’outils. Pour les racines de dépendances, la validation des métadonnées de package, les enregistrements de registre, le comportement de rechargement au démarrage et le nettoyage hérité, consultez Résolution des dépendances de Plugins.

​
Liens associés