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é appartenant au Plugin.

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

openclaw plugins install clawhub:<package-name>

Les spécifications de paquet sans préfixe sont toujours 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.22.3+, Node 24.15+ ou Node 25.9+, et npm ou pnpm.
• Modules ESM TypeScript.
• 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 à partir du code source utilise uniquement pnpm, car OpenClaw détecte les Plugins intégrés à partir des paquets de l’espace de travail extensions/*.

Choisir la forme du Plugin

Démarrage rapide

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

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

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

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}` }],        };      },    });  },});

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

pnpm test extensions/my-plugin/pnpm check

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

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

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’adhésion explicite de l’utilisateur avant qu’OpenClaw ne 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 sur la plateforme lorsqu’elle est disponible, et requesterSenderId.

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 donnent leur accord avec tools.allow :

{  tools: { allow: ["workflow_tool"] }, // ou ["my-plugin"] pour tous les outils d’un même 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 les noms d’outils du cœur ; les conflits sont ignorés et signalés dans les diagnostics des Plugins. Les enregistrements incorrects sont ignorés et signalés de la même manière : un name non vide manquant, un execute qui n’est pas une fonction ou un descripteur d’outil sans 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 s’adapter au modèle actif pour le tour en cours ; il peut inclure provider, modelId et modelRef. Considérez-le comme des métadonnées d’exécution informatives, et non comme une frontière de sécurité vis-à-vis de l’opérateur local, du code des Plugins installés ou d’un environnement d’exécution OpenClaw modifié. Les outils locaux sensibles doivent toujours exiger l’adhésion explicite du Plugin ou de l’opérateur et échouer de manière fermée lorsque les métadonnées du modèle actif sont absentes ou inadaptées.

Le manifeste déclare la propriété et la détection ; l’exécution appelle toujours l’implémentation active de l’outil enregistré. Maintenez toolMetadata.<tool>.optional: true aligné sur 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 :

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

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

Les méthodes RPC personnalisées du Gateway constituent un point d’entrée avancé. Conservez-les sous 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 se résolvent en operator.admin. Le pont openclaw/plugin-sdk/gateway-method-runtime est réservé aux routes HTTP des Plugins qui déclarent contracts.gatewayMethodDispatch: ["authenticated-request"].

Pour la carte complète des imports, consultez Vue d’ensemble du SDK des Plugins.

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 Tous les imports utilisent des chemins plugin-sdk/<subpath> ciblés OPENCLAW_DOCS_MARKER:calloutClose: