OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Building plugins

Création de plugins

Les Plugins étendent OpenClaw sans modifier le cœur. Un Plugin peut ajouter un canal de messagerie, un fournisseur de modèles, un backend CLI local, un outil d’agent, un hook, un fournisseur de médias ou une autre fonctionnalité propre au Plugin.

Vous n’avez pas besoin d’ajouter un Plugin externe au dépôt OpenClaw. Publiez le paquet sur ClawHub, puis les utilisateurs l’installent avec :

bash
openclaw plugins install clawhub:<package-name>

Les spécifications de paquet sans préfixe continuent d’être installées depuis npm pendant la transition de lancement. Utilisez le préfixe clawhub: lorsque vous souhaitez une résolution par ClawHub.

Prérequis

  • Node 22.19+, Node 23.11+ ou Node 24+, et npm ou pnpm.
  • Modules TypeScript ESM.
  • Pour travailler sur un Plugin intégré au dépôt, clonez le dépôt et exécutez pnpm install. Le développement de Plugins depuis une copie des sources utilise exclusivement pnpm, car OpenClaw découvre les Plugins intégrés à partir des paquets de l’espace de travail extensions/*.

Choisir la structure du Plugin

Plugin de canal

Connectez OpenClaw à une plateforme de messagerie.
Plugin de fournisseur

Ajoutez un fournisseur de modèles, de médias, de recherche, de récupération, de synthèse vocale ou de temps réel.
Plugin de backend CLI

Exécutez une CLI d’IA locale via le mécanisme de repli de modèle d’OpenClaw.
Plugin d’outil

Enregistrez des outils d’agent.

Démarrage rapide

Créez un Plugin d’outil minimal en enregistrant un outil d’agent obligatoire. Il s’agit de la structure de Plugin utile la plus simple, couvrant le paquet, le manifeste, le point d’entrée et la validation locale.

  • Créer les métadonnées du paquet

    package.json
    {"name": "@myorg/openclaw-my-plugin","version": "1.0.0","type": "module","dependencies": {"typebox": "1.1.39"},"peerDependencies": {"openclaw": ">=2026.3.24-beta.2"},"openclaw": {"extensions": ["./index.ts"],"compat": {"pluginApi": ">=2026.3.24-beta.2","minGatewayVersion": "2026.3.24-beta.2"},"build": {"openclawVersion": "2026.3.24-beta.2","pluginSdkVersion": "2026.3.24-beta.2"}}}
    openclaw.plugin.json
    {"id": "my-plugin","name": "My Plugin","description": "Adds a custom tool to OpenClaw","contracts": {"tools": ["my_tool"]},"activation": {"onStartup": true},"configSchema": {"type": "object","additionalProperties": false}}

    Les Plugins externes publiés doivent faire pointer leurs entrées d’exécution vers des fichiers JavaScript compilés. Consultez les points d’entrée du SDK pour connaître l’intégralité du contrat des points d’entrée.

    Chaque Plugin nécessite un manifeste, même sans configuration. Les outils d’exécution doivent figurer dans contracts.tools afin qu’OpenClaw puisse déterminer leur propriétaire sans charger immédiatement l’environnement d’exécution de chaque Plugin. Définissez activation.onStartup de manière intentionnelle ; cet exemple effectue le chargement au démarrage du Gateway.

    Les surfaces de Plugin approuvées par l’hôte sont également contrôlées par le manifeste et nécessitent une déclaration explicite pour les Plugins installés : api.registerAgentToolResultMiddleware(...) exige que chaque environnement d’exécution cible soit répertorié dans contracts.agentToolResultMiddleware, et api.registerTrustedToolPolicy(...) exige que chaque identifiant de politique figure dans contracts.trustedToolPolicies. Ces déclarations garantissent la cohérence entre l’inspection lors de l’installation et l’enregistrement à l’exécution.

    Pour chaque champ du manifeste, consultez le manifeste du Plugin.

  • Enregistrer l’outil

    index.ts
    import { Type } from "typebox";import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Adds a custom tool to OpenClaw",  register(api) {    api.registerTool({      name: "my_tool",      description: "Echo one input value",      parameters: Type.Object({ input: Type.String() }),      async execute(_id, params) {        return {          content: [{ type: "text", text: `Got: ${params.input}` }],        };      },    });  },});

    Utilisez definePluginEntry pour les Plugins autres que les Plugins de canal. Les Plugins de canal utilisent plutôt defineChannelPluginEntry depuis openclaw/plugin-sdk/core.

  • Tester l’environnement d’exécution

    Pour un Plugin installé ou externe, inspectez l’environnement d’exécution chargé :

    bash
    openclaw plugins inspect my-plugin --runtime --json

    Si le Plugin enregistre une commande CLI, exécutez également cette commande et vérifiez sa sortie, par exemple openclaw demo-plugin ping.

    Pour un Plugin intégré à ce dépôt, OpenClaw découvre les paquets de Plugins de la copie des sources dans l’espace de travail extensions/*. Exécutez le test ciblé le plus proche :

    bash
    pnpm test extensions/my-plugin/pnpm check

  • Tester l’installation du paquet

    Avant de publier un Plugin prêt à être distribué sous forme de paquet, testez la même méthode d’installation que celle utilisée par les utilisateurs. Ajoutez d’abord une étape de compilation, faites pointer les entrées d’exécution telles que openclaw.extensions vers du JavaScript compilé, par exemple ./dist/index.js, et assurez-vous que npm pack inclut cette sortie dist/. Les entrées de source TypeScript sont réservées aux copies des sources et aux chemins de développement local.

    Créez ensuite l’archive du Plugin et installez-la avec npm-pack: :

    bash
    npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

    npm-pack: utilise le projet npm géré par OpenClaw propre à chaque Plugin, ce qui permet de détecter les erreurs de dépendances d’exécution que les tests depuis une copie des sources peuvent masquer. Cela valide la structure du paquet et de ses dépendances, mais pas la confiance officielle associée au catalogue. Les importations d’exécution doivent figurer dans dependencies ou optionalDependencies ; les dépendances présentes uniquement dans devDependencies ne seront pas installées dans le projet d’exécution géré.

    N’utilisez pas l’installation directe d’une archive ou d’un chemin comme validation finale du comportement officiel ou privilégié d’un Plugin. Les sources brutes sont utiles pour le débogage local, mais elles ne valident pas le même chemin de dépendances que les installations depuis npm ou ClawHub. Si votre Plugin dépend du statut de Plugin officiel approuvé, ajoutez une seconde validation au moyen d’une installation officielle adossée au catalogue ou d’un chemin de paquet publié qui enregistre la confiance officielle. Consultez la résolution des dépendances des Plugins pour plus de détails sur la racine d’installation et la propriété des dépendances.

  • Publier

    Validez le paquet avant de le publier :

    bash
    clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

    Les extraits canoniques de paquets ClawHub se trouvent dans docs/snippets/plugin-publish/.

  • Installer

    Installez le paquet publié via ClawHub :

    bash
    openclaw plugins install clawhub:your-org/your-plugin

    • Enregistrer des outils

    Les outils peuvent être obligatoires ou facultatifs. Les outils obligatoires sont toujours disponibles lorsque le Plugin est activé. Les outils facultatifs nécessitent l’acceptation explicite de l’utilisateur avant qu’OpenClaw charge l’environnement d’exécution du Plugin propriétaire.

    Les fabriques d’outils reçoivent un contexte d’exécution approuvé, notamment deliveryContext, nativeChannelId pour la conversation active de la plateforme lorsqu’il est disponible, et requesterSenderId.

    typescript
    register(api) {  api.registerTool(    {      name: "workflow_tool",      description: "Run a workflow",      parameters: Type.Object({ pipeline: Type.String() }),      async execute(_id, params) {        return { content: [{ type: "text", text: params.pipeline }] };      },    },    { optional: true },  );}

    Chaque outil enregistré avec api.registerTool(...) doit également être déclaré dans le manifeste du Plugin :

    json
    {  "contracts": {    "tools": ["workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

    Les utilisateurs donnent leur accord avec tools.allow :

    json5
    {  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for every tool from one plugin}

    Les outils facultatifs déterminent si un outil est exposé au modèle. Utilisez les demandes d’autorisation de Plugin lorsqu’un outil ou un hook doit demander une approbation après sa sélection par le modèle et avant l’exécution de l’action.

    Utilisez des outils facultatifs pour les effets de bord, les binaires inhabituels ou les fonctionnalités qui ne doivent pas être exposées par défaut. Les noms d’outils ne doivent pas entrer en conflit avec ceux des outils du cœur ; les conflits sont ignorés et signalés dans les diagnostics des Plugins. Les enregistrements mal formés sont ignorés et signalés de la même manière : absence d’un name non vide, execute qui n’est pas une fonction ou descripteur d’outil dépourvu d’objet parameters.

    Les fabriques d’outils reçoivent un objet de contexte fourni par l’environnement d’exécution. Utilisez ctx.activeModel lorsqu’un outil doit journaliser, afficher ou adapter son comportement au modèle actif pour le tour en cours ; il peut inclure provider, modelId et modelRef. Considérez-le comme une métadonnée d’exécution informative, et non comme une frontière de sécurité contre l’opérateur local, le code des Plugins installés ou un environnement d’exécution OpenClaw modifié. Les outils locaux sensibles doivent toujours nécessiter l’acceptation explicite du Plugin ou de l’opérateur et refuser l’exécution lorsque les métadonnées du modèle actif sont absentes ou inadaptées.

    Le manifeste déclare la propriété et la découverte ; l’exécution appelle toujours l’implémentation active de l’outil enregistré. Maintenez toolMetadata.<tool>.optional: true cohérent avec api.registerTool(..., { optional: true }) afin qu’OpenClaw puisse éviter de charger l’environnement d’exécution de ce Plugin tant que l’outil n’a pas été explicitement ajouté à la liste d’autorisation.

    Conventions d’importation

    Importez depuis les sous-chemins ciblés du SDK :

    typescript

    N’importez pas depuis le regroupement racine obsolète :

    typescript

    Dans votre paquet de Plugin, utilisez des fichiers de regroupement locaux tels que api.ts et runtime-api.ts pour les importations internes. N’importez pas votre propre Plugin via un chemin du SDK. Les fonctions auxiliaires propres à un fournisseur doivent rester dans le paquet du fournisseur, sauf si l’interface est réellement générique.

    Les méthodes RPC personnalisées du Gateway constituent un point d’entrée avancé. Utilisez un préfixe propre au Plugin ; les espaces de noms d’administration du cœur tels que config.*, exec.approvals.*, operator.admin.*, wizard.* et update.* restent réservés et sont résolus en operator.admin. Le pont openclaw/plugin-sdk/gateway-method-runtime est réservé aux routes HTTP de Plugins qui déclarent contracts.gatewayMethodDispatch: ["authenticated-request"].

    Pour connaître la table complète des importations, consultez la présentation du SDK de Plugin.

    Liste de contrôle avant soumission

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json contient les métadonnées openclaw correctes OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Le manifeste openclaw.plugin.json est présent et valide OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Le point d’entrée utilise defineChannelPluginEntry ou definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Toutes les importations utilisent des chemins ciblés plugin-sdk/<subpath> OPENCLAW_DOCS_MARKER:calloutClose:

    Was this useful?
    On this page

    On this page