Plugins

Les Plugins étendent OpenClaw avec des canaux, des fournisseurs de modèles, des environnements d’exécution d’agents, des outils, des compétences, la synthèse vocale, la transcription en temps réel, la voix, la compréhension des médias, la génération, la récupération de contenu 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 dans le 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)
• tous les identifiants, clés de configuration ou outils de 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 paquets 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 des paquets ; toute autre spécification simple s’installe via 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 sur npm. Utilisez npm:@openclaw/<plugin>@<version> pour installer délibérément le paquet npm externe à la place de 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 indique être compatible avec cette version d’OpenClaw. Si la dernière version actuelle de npm déclare un openclaw.compat.pluginApi ou un openclaw.install.minHostVersion plus récent que ce que prend en charge 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 approuvée 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 les chemins d’installation et de mise à jour reposant à la fois sur la CLI et sur le Gateway. Les hooks before_install du Plugin s’exécutent plus tard, et uniquement dans les processus OpenClaw où les hooks du Plugin 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 d’OpenClaw pour les dépendances de Plugins.

Consultez Configuration des Skills pour connaître le schéma d’exécution partagé de security.installPolicy utilisé 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 la 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 ce paramètre est actif ; 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 aux Plugins qui n’y figurent pas 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 explicitement des fichiers ou répertoires locaux de Plugins. Les chemins locaux gérés par plugins install doivent être des répertoires ou des archives de Plugin ; 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 intégrées 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 activé manuellement. plugins.deny et plugins.entries.<id>.enabled: false continuent de le bloquer.
• Les Plugins intégrés à activation manuelle peuvent s’activer automatiquement lorsque la configuration nomme l’une de leurs interfaces, par exemple une référence de fournisseur ou de 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 du fournisseur et du 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 codex intégré gère l’environnement d’exécution du serveur d’application Codex pour les références d’agents canoniques openai/*, les valeurs explicites agentRuntime.id: "codex" 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 dans l’espace de travail ou les racines globales de Plugins, le démarrage journalise 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 minimal de plugins.allow. Exécutez openclaw plugins list --enabled --verbose ou openclaw plugins inspect <id> sur l’identifiant du Plugin indiqué avant de copier les Plugins approuvés 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 approuvée 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 entre la liste d’autorisation et les 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 Paquets de Plugins pour connaître la limite de compatibilité des paquets et Créer des Plugins pour la création de Plugins natifs.

Hooks de Plugins

Les Plugins peuvent enregistrer des hooks à l’exécution par l’intermédiaire 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 invites 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 l’automatisation existante de type HOOK.

Règle rapide : si le gestionnaire a besoin d’une priorité, d’une sémantique de fusion ou d’un comportement de blocage ou d’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 via 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 la configuration, le manifeste et l’état du registre à froid. 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-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw gateway restart

Les Gateways gérés redémarrent automatiquement après l’installation, la mise à jour et la désinstallation d’un plugin lorsque ces changements modifient sa source. Pour les installations sur VPS ou dans des conteneurs, assurez-vous que tout redémarrage manuel cible le véritable processus enfant openclaw gateway run qui dessert vos canaux, et pas seulement un wrapper ou un superviseur.

Dépannage

Lorsqu’une configuration de plugin obsolète désigne encore un plugin de canal qui n’est plus détectable, la validation de la configuration transforme la clé de ce canal en avertissement au lieu d’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 de plugin et de canal obsolètes. 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égié 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 conserve cette demande et signale des diagnostics de propriété en double des canaux et outils 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. Effectuez une mise à jour ou une réinstallation après que l’éditeur a fourni le JavaScript compilé, ou désactivez/désinstallez le plugin jusque-là.

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 est suivie de 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 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 sous l’utilisateur 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 la propriété root à la racine gérée des plugins :

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

Après avoir corrigé la propriété, 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] factory timings ...

Le résumé 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 de l’outil. Les lignes lentes deviennent des 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 utilisant le même contexte de requête effectif. La clé de 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é ; les fabriques qui dépendent de ces champs fiables sont donc réexécutées lorsque le contexte change. Si les durées restent élevées, le plugin effectue peut-être une opération coûteuse avant de renvoyer ses définitions d’outils.

Si un plugin représente l’essentiel de la durée, inspectez 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 reporter le chargement coûteux des dépendances dans le chemin d’exécution de l’outil au lieu de l’effectuer dans la fabrique d’outils.

Pour les racines de dépendances, la validation des métadonnées des paquets, 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 de la communauté - découverte avec 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 d’API
• Manifeste de plugin - manifeste et métadonnées du paquet