Plugins

Les Plugins étendent OpenClaw avec des canaux, des fournisseurs de modèles, des environnements d’agents, 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 fonctionnalités d’exécution.

Utilisez cette page pour installer un Plugin, redémarrer le Gateway, vérifier que l’environnement d’exécution l’a chargé et résoudre les échecs de configuration courants. Pour des exemples portant uniquement sur les commandes, consultez Gérer les Plugins. Pour l’inventaire généré des Plugins intégrés, externes officiels et disponibles uniquement sous forme de code source, consultez Inventaire des Plugins.

Prérequis

• une copie de travail ou une installation d’OpenClaw avec la CLI openclaw disponible
• un accès réseau à la source sélectionnée (ClawHub, npm ou un hébergeur git)
• les identifiants, clés de configuration ou outils du système d’exploitation propres au Plugin indiqués dans la documentation de configuration de ce Plugin
• l’autorisation de recharger ou redémarrer le Gateway qui dessert vos canaux

Démarrage rapide

openclaw plugins search "calendar"

# 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 une copie de travail de développement locale.openclaw plugins install ./my-pluginopenclaw plugins install --link ./my-plugin

openclaw plugins enable <plugin-id>

openclaw gateway restart

openclaw plugins inspect <plugin-id> --runtime --json

Configuration

Choisir une source d’installation

Les spécifications de paquet simples ont un comportement de compatibilité particulier : un nom simple qui correspond à l’identifiant d’un Plugin intégré utilise cette source intégrée ; un nom simple qui correspond à l’identifiant d’un Plugin externe officiel utilise le catalogue officiel de paquets ; toute autre spécification simple est installée par npm pendant la transition de lancement. Les spécifications @openclaw/* brutes qui correspondent à des Plugins intégrés sont également résolues vers la copie intégrée avant le repli vers npm. Utilisez npm:@openclaw/<plugin>@<version> pour installer délibérément le paquet npm externe plutôt que la copie intégrée. Utilisez clawhub:, npm:, git: ou npm-pack: pour sélectionner la source de manière déterministe. Consultez openclaw plugins pour connaître le contrat complet de la commande.

Pour les installations npm, les spécifications non épinglées et @latest sélectionnent le paquet stable le plus récent qui annonce sa compatibilité avec cette version d’OpenClaw. Si la dernière version actuellement publiée sur npm déclare une version de openclaw.compat.pluginApi ou openclaw.install.minHostVersion plus récente que celle prise en charge par cette version, OpenClaw analyse les anciennes versions stables et installe la plus récente qui convient. Les versions exactes et les balises de canal explicites telles que @beta restent épinglées au paquet sélectionné et échouent en cas d’incompatibilité.

Politique d’installation de l’opérateur

Configurez security.installPolicy afin d’exécuter une commande de politique locale fiable avant qu’une installation ou une mise à jour de Plugin ne se poursuive. La politique reçoit des métadonnées ainsi que le chemin de la source préparée et peut autoriser ou bloquer l’installation. Elle couvre à la fois les chemins d’installation et de mise à jour de la CLI et ceux gérés par le Gateway. Les hooks before_install du Plugin s’exécutent plus tard, et uniquement dans les processus OpenClaw où les hooks de Plugins sont chargés ; utilisez donc plutôt security.installPolicy pour les décisions d’installation appartenant à l’opérateur. L’option obsolète --dangerously-force-unsafe-install est acceptée à des fins de compatibilité, mais n’a aucun effet : elle ne contourne ni la politique d’installation ni la liste de refus intégrée des dépendances de Plugins d’OpenClaw.

Consultez la configuration des Skills pour connaître le schéma d’exécution security.installPolicy partagé par les Skills et les Plugins.

Configurer la politique des Plugins

La structure de configuration commune des Plugins est la suivante :

{  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" } },    },  },}

Principales règles de politique :

• plugins.enabled: false désactive tous les Plugins et ignore les opérations de découverte et de chargement. Les références obsolètes à des Plugins restent inertes tant que cette option est active ; réactivez les Plugins avant d’exécuter le nettoyage par doctor si vous souhaitez supprimer les identifiants obsolètes.
• plugins.deny prévaut sur la liste d’autorisation et sur l’activation individuelle des Plugins.
• plugins.allow est une liste d’autorisation exclusive. Les outils appartenant à des Plugins qui ne figurent pas dans la liste d’autorisation restent indisponibles même lorsque tools.allow contient "*".
• plugins.entries.<id>.enabled: false désactive un Plugin tout en conservant sa configuration.
• plugins.load.paths ajoute explicitement des fichiers ou répertoires de Plugins locaux. Les chemins locaux plugins install gérés doivent être des répertoires ou des archives de Plugins ; utilisez plugins.load.paths pour les fichiers de Plugin autonomes.
• Les Plugins provenant de l’espace de travail sont désactivés par défaut ; activez-les explicitement ou ajoutez-les à la liste d’autorisation avant d’utiliser du code local de l’espace de travail.
• Les Plugins intégrés suivent leurs métadonnées internes d’activation ou de désactivation par défaut, sauf si la configuration les remplace explicitement.
• plugins.slots.<slot> (memory ou contextEngine) sélectionne un Plugin pour une catégorie exclusive. La sélection d’un emplacement compte comme une activation explicite et force l’activation du Plugin sélectionné pour cet emplacement, même s’il devrait autrement être optionnel. plugins.deny et plugins.entries.<id>.enabled: false le bloquent toujours.
• Les Plugins intégrés optionnels peuvent s’activer automatiquement lorsque la configuration nomme l’une de leurs interfaces, comme une référence de fournisseur/modèle, une configuration de canal, un moteur de CLI ou un environnement d’exécution d’agent.
• Le routage Codex de la famille OpenAI maintient séparées les limites entre le fournisseur et le Plugin d’exécution : les anciennes références de modèles Codex constituent une configuration héritée que doctor répare, tandis que le Plugin intégré codex possède l’environnement d’exécution du serveur d’application Codex pour les références d’agents openai/* canoniques, les références agentRuntime.id: "codex" explicites et les anciennes références codex/*.

Lorsque plugins.allow n’est pas défini et que des Plugins non intégrés sont découverts automatiquement depuis l’espace de travail ou les racines globales des Plugins, le démarrage consigne plugins.allow is empty; discovered non-bundled plugins may auto-load: ... avec les identifiants des Plugins découverts et, pour les listes courtes, un extrait plugins.allow minimal. Exécutez openclaw plugins list --enabled --verbose ou openclaw plugins inspect <id> avec l’identifiant du Plugin indiqué avant de copier les Plugins fiables dans openclaw.json. Le même épinglage de confiance s’applique lorsque les diagnostics indiquent qu’un Plugin a été chargé without install/load-path provenance : inspectez cet identifiant de Plugin, puis épinglez-le dans plugins.allow ou réinstallez-le depuis une source fiable afin qu’OpenClaw enregistre la provenance de l’installation.

Exécutez openclaw doctor ou openclaw doctor --fix lorsque la validation de la configuration signale des identifiants de Plugins obsolètes, des incohérences de liste d’autorisation ou d’outils, ou d’anciens chemins de Plugins intégrés.

Comprendre les formats de Plugins

OpenClaw reconnaît deux formats de Plugins :

Les deux formats apparaissent dans openclaw plugins list, openclaw plugins inspect, openclaw plugins enable et openclaw plugins disable. Consultez Bundles de Plugins pour connaître la limite de compatibilité des bundles et Créer des Plugins pour la création de Plugins natifs.

Hooks de Plugins

Les Plugins peuvent enregistrer des hooks à l’exécution au moyen de deux API différentes :

• Les hooks typés api.on(...) pour les événements du cycle de vie de l’environnement d’exécution. Il s’agit de l’interface privilégiée pour les intergiciels, les politiques, la réécriture des messages, la mise en forme des prompts et le contrôle des outils.
• api.registerHook(...) pour le système de hooks interne décrit dans Hooks. Il sert principalement aux effets secondaires généraux liés aux commandes ou au cycle de vie et à la compatibilité avec les automatisations existantes de style HOOK.

Règle simple : si le gestionnaire nécessite une priorité, une sémantique de fusion ou un comportement de blocage/annulation, utilisez les hooks typés. S’il réagit simplement à command:new, command:reset, message:sent ou à des événements généraux similaires, api.registerHook convient.

Les hooks internes gérés par les Plugins apparaissent dans openclaw hooks list avec plugin:<id>. Vous ne pouvez pas les activer ou les désactiver au moyen de openclaw hooks ; activez ou désactivez plutôt le Plugin.

Vérifier le Gateway actif

openclaw plugins list et la commande simple openclaw plugins inspect lisent l’état à froid de la configuration, du manifeste et du registre. Elles 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-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw gateway restart

Les Gateways gérés redémarrent automatiquement après les modifications d’installation, de mise à jour et de désinstallation qui changent la source du plugin. Sur les installations VPS ou en conteneur, assurez-vous que tout redémarrage manuel cible bien le processus enfant openclaw gateway run qui dessert vos canaux, et pas seulement un encapsuleur ou un superviseur.

Résolution des problèmes

Lorsque la configuration obsolète d’un plugin mentionne encore un plugin de canal qui n’est plus détectable, la validation de la configuration rétrograde la clé de ce canal en avertissement au lieu d’émettre une erreur bloquante, afin que le démarrage du Gateway puisse toujours desservir tous les autres canaux. Exécutez openclaw doctor --fix pour supprimer les entrées obsolètes du plugin et du canal. Les clés de canal inconnues sans preuve de plugin obsolète font toujours échouer la validation afin que les fautes de frappe restent visibles.

Pour remplacer intentionnellement un canal, le plugin à privilégier doit déclarer channelConfigs.<channel-id>.preferOver avec l’identifiant du plugin hérité ou de priorité inférieure. Si les deux plugins sont explicitement activés, OpenClaw respecte cette demande et signale des diagnostics de propriété de canal ou d’outil en double au lieu de choisir silencieusement un propriétaire.

Si un paquet installé indique qu’il requires compiled runtime output for TypeScript entry ..., le paquet a été publié sans les fichiers JavaScript dont OpenClaw a besoin à l’exécution. Mettez-le à jour ou réinstallez-le après que l’éditeur a fourni le JavaScript compilé, ou désactivez/désinstallez le plugin en attendant.

Propriété bloquée du chemin du plugin

Si les diagnostics indiquent blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) et que la validation affiche ensuite plugin present but blocked, OpenClaw a trouvé des fichiers de plugin appartenant à un utilisateur Unix différent de celui du processus qui les charge. Conservez la configuration du plugin ; corrigez le propriétaire dans le 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 sous l’identité node (uid 1000) ; les répertoires de configuration et d’espace de travail OpenClaw montés depuis l’hôte doivent donc 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, attribuez plutôt à root la propriété de la racine des plugins gérés :

sudo chown -R root:root /path/to/openclaw-config/npm

Après avoir corrigé le propriétaire, réexécutez openclaw doctor --fix ou openclaw plugins registry --refresh afin que le registre persistant des plugins corresponde aux fichiers réparés.

Configuration lente des outils de plugin

Si les tours de l’agent semblent se bloquer pendant la préparation des outils, activez la journalisation de trace et recherchez les lignes de durée des fabriques d’outils de plugin :

openclaw config set logging.level traceopenclaw logs --follow

Recherchez :

[trace:plugin-tools] durées des fabriques ...

Le récapitulatif indique la durée totale des fabriques et les fabriques d’outils de plugin les plus lentes, notamment l’identifiant du plugin, les noms d’outils déclarés, la forme du résultat et le caractère facultatif ou non de l’outil. Les lignes lentes deviennent des avertissements lorsqu’une seule fabrique prend au moins 1s ou que la préparation totale des fabriques d’outils de plugin prend au moins 5s.

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é du cache comprend la configuration d’exécution effective, l’espace de travail et l’identifiant de l’agent, la politique de bac à sable, les paramètres du navigateur, le contexte de livraison, l’identité du demandeur et l’état de propriété, de sorte que les fabriques dépendant de ces champs fiables se réexécutent lorsque le contexte change. Si les durées restent élevées, il est possible que le plugin effectue un travail coûteux avant de renvoyer les définitions de ses outils.

Si un plugin domine les mesures de durée, examinez ses enregistrements d’exécution :

openclaw plugins inspect <plugin-id> --runtime --json

Mettez ensuite à jour, réinstallez ou désactivez ce plugin. Les auteurs de plugins doivent déplacer le chargement coûteux des dépendances vers le chemin d’exécution de l’outil plutôt que de l’effectuer dans la fabrique d’outils.

Pour les racines des dépendances, la validation des métadonnées de paquet, les enregistrements du registre, le comportement de rechargement au démarrage et le nettoyage des éléments hérités, consultez Résolution des dépendances des plugins.

Pages connexes

• Gérer les plugins - exemples de commandes pour répertorier, installer, mettre à jour, désinstaller et publier
• openclaw plugins - référence complète de la CLI
• Inventaire des plugins - liste générée des plugins intégrés et externes
• Référence des plugins - pages de référence générées pour chaque plugin
• Plugins communautaires - découverte sur ClawHub et politique relative aux PR de documentation
• Résolution des dépendances des plugins - racines d’installation, enregistrements du registre et limites d’exécution
• Création de plugins - guide de création de plugins natifs
• Présentation du SDK des plugins - enregistrement à l’exécution, hooks et champs de l’API
• Manifeste de plugin - manifeste et métadonnées de paquet