Plugins

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

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 un checkout de développement local.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 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 :

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-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw 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

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 traceopenclaw 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

• Gérer les Plugins - exemples de commandes pour lister, installer, mettre à jour, désinstaller et publier
• openclaw plugins - référence CLI complète
• Inventaire des Plugins - liste générée des Plugins groupés et externes
• Référence des Plugins - pages de référence générées par Plugin
• Plugins communautaires - découverte ClawHub et politique de PR de docs
• Résolution des dépendances de Plugins - racines d’installation, enregistrements de registre et frontières runtime
• Créer des Plugins - guide de création de Plugins natifs
• Vue d’ensemble du SDK de Plugin - enregistrement runtime, hooks et champs d’API
• Manifeste de Plugin - métadonnées de manifeste et de package