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èle, un backend CLI local, un outil d’agent, un hook, un fournisseur de média ou une autre capacité détenue par un plugin.

Vous n’avez pas besoin d’ajouter un plugin externe au référentiel OpenClaw. Publiez le package sur ClawHub et les utilisateurs l’installent avec :

openclaw plugins install clawhub:<package-name>

Les spécifications de package nues s’installent toujours depuis npm pendant la bascule de lancement. Utilisez le préfixe npmclawhub:ClawHub lorsque vous souhaitez la résolution ClawHub.

Prérequis

Utilisez Node 22.19 ou plus récent et un gestionnaire de packages tel que npm ou pnpm.
Soyez familiarisé avec les modules ESM TypeScript.
Pour le travail sur les plugins groupés dans le dépôt, clonez le référentiel et exécutez pnpm installOpenClaw. Le développement de plugins avec extraction du code source est réservé à pnpm car OpenClaw charge les plugins groupés depuis les packages de l’espace de travail extensions/*.

Choisir la forme du plugin

Plugin de canal

Connectez OpenClaw à une plateforme de messagerie.

Plugin de fournisseur

Ajoutez un fournisseur de modèle, de média, de recherche, de récupération, de synthèse vocale ou en temps réel.

CLIPlugin backend CLI

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

Tool plugin

Enregistrer les outils d’agent.

Démarrage rapide

Créez un plugin d’outil minimal en enregistrant un outil d’agent requis. C’est la forme de plugin utile la plus courte et présente le package, le manifeste, le point d’entrée et la preuve locale.

Créer les métadonnées du package

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "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"
    }
  }
}

{
  "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 les entrées d’exécution vers des fichiers JavaScript construits. Consultez Points d’entrée du SDK pour le contrat complet du point d’entrée.

Chaque plugin a besoin d’un manifeste, même lorsqu’il n’a pas de configuration. Les outils d’exécution doivent apparaître dans contracts.tools pour qu’OpenClaw puisse découvrir la propriété sans charger impatiemment chaque runtime de plugin. Définissez activation.onStartup intentionnellement. Cet exemple démarre au démarrage du Gateway.

Pour chaque champ de manifeste, consultez Manifeste du plugin.

Enregistrer l'outil

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 qui ne sont pas des channels. Les plugins de channel utilisent defineChannelPluginEntry.

Tester le runtime
Pour un plugin installé ou externe, inspectez le runtime chargé :
Fenêtre de terminal
```
openclaw plugins inspect my-plugin --runtime --json
```
Si le plugin enregistre une commande CLI, exécutez également cette commande. Par exemple, une commande de démonstration doit avoir une preuve d’exécution telle que openclaw demo-plugin ping.

Pour un plugin groupé dans ce dépôt, OpenClaw découvre les packages de plugins à partir de l’espace de travail extensions/*. Exécutez le test ciblé le plus proche :
Fenêtre de terminal
```
pnpm test -- extensions/my-plugin/
pnpm check
```
Publier
Validez le package avant publication :
Fenêtre de terminal
```
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
```
Les extraits canoniques du ClawHub se trouvent dans docs/snippets/plugin-publish/.
Install
Installez le package publié via ClawHub :
Fenêtre de terminal
```
openclaw plugins install clawhub:your-org/your-plugin
```

Enregistrement des outils

Les outils peuvent être requis ou facultatifs. Les outils requis sont toujours disponibles lorsque le plugin est activé. Les outils facultatifs nécessitent une acceptation par l’utilisateur.

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 :

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

Les utilisateurs acceptent via tools.allow :

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

Utilisez des outils facultatifs pour les effets secondaires, les binaires inhabituels ou les capacités qui ne doivent pas être exposées par défaut. Les noms d’outils ne doivent pas entrer en conflit avec les outils principaux ; les conflits sont ignorés et signalés dans les diagnostics du plugin. Les enregistrements malformés, y compris les descripteurs d’outils sans parameters, sont ignorés et signalés de la même manière. Les outils enregistrés sont des fonctions typées que le modèle peut appeler une fois les vérifications de stratégie et de liste blanche passées.

Les fabriques d’outils reçoivent un objet de contexte fourni par le runtime. Utilisez ctx.activeModel lorsqu’un outil doit journaliser, afficher ou s’adapter au modèle actif pour le tour courant. L’objet peut inclure provider, modelId et modelRefOpenClaw. Traitez-le comme métadonnées d’exécution informationnelles, et non comme une limite de sécurité contre l’opérateur local, le code de plugin installé ou un runtime OpenClaw modifié. Les outils locaux sensibles doivent toujours exiger une acceptation explicite du plugin ou de l’opérateur et échouer en mode fermé lorsque les métadonnées du modèle actif sont manquantes ou inadaptées.

Le manifeste déclare la propriété et la découverte ; l’exécution appelle toujours l’implémentation de l’outil enregistré en direct. Gardez toolMetadata.<tool>.optional: true aligné avec api.registerTool(..., { optional: true })OpenClaw pour qu’OpenClaw puisse éviter de charger ce runtime de plugin jusqu’à ce que l’outil soit explicitement autorisé.

Conventions d’importation

Importez à partir des sous-chemins SDK ciblés :

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";

N’importez pas à partir du baril racine obsolète :

import { definePluginEntry } from "openclaw/plugin-sdk";

Dans le package de votre plugin, utilisez des fichiers barrel locaux tels que api.ts et runtime-api.ts pour les importations internes. N’importez pas votre propre plugin via un chemin SDK. Les helpers spécifiques au provider doivent rester dans le package provider, sauf si la jointure est véritablement générique.

Les méthodes RPC de GatewayRPC personnalisées sont un point d’entrée avancé. Gardez-les sur un préfixe spécifique au plugin ; les espaces de noms d’administration principale tels que config.*, exec.approvals.*, operator.admin.*, wizard.* et update.* restent réservés et résolvent vers operator.admin. Le pont openclaw/plugin-sdk/gateway-method-runtime est réservé aux itinéraires HTTP des plugins qui déclarent contracts.gatewayMethodDispatch: ["authenticated-request"].

Pour la carte d’importation complète, consultez la vue d’ensemble du SDK Plugin.

Liste de contrôle avant soumission

Tester contre les versions bêta

Surveillez les tags de publication GitHub sur openclaw/openclaw et abonnez-vous via Watch > Releases. Les tags bêta ressemblent à v2026.3.N-beta.1. Vous pouvez également activer les notifications pour le compte X officiel OpenClaw @openclaw pour les annonces de publication.
Testez votre plugin par rapport au tag bêta dès son apparition. La fenêtre avant la version stable est généralement de quelques heures seulement.
Publiez dans le fil de discussion de votre plugin sur le canal Discord plugin-forumDiscord après avoir testé avec all good ou ce qui a échoué. Si vous n’avez pas encore de fil de discussion, créez-en un.
Si quelque chose échoue, ouvrez ou mettez à jour un problème intitulé Beta blocker: <plugin-name> - <summary> et appliquez l’étiquette beta-blocker. Mettez le lien du problème dans votre fil de discussion.
Ouvrez une PR vers main intitulée fix(<plugin-id>): beta blocker - <summary>Discord et liez le problème à la fois dans la PR et votre fil de discussion Discord. Les contributeurs ne peuvent pas étiqueter les PR, donc le titre est le signal côté PR pour les mainteneurs et l’automatisation. Les bloquants avec une PR sont fusionnés ; les bloquants sans PR pourraient tout de même être livrés. Les mainteneurs surveillent ces fils de discussion pendant les tests bêta.
Le silence signifie que tout va bien. Si vous manquez la fenêtre, votre correctif sera probablement inclus dans le prochain cycle.