Créer des plugins

Les Plugins étendent OpenClaw sans modifier le noyau. 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édias ou une autre capacité appartenant au Plugin.

Vous n’avez pas besoin d’ajouter un Plugin externe au dépôt 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 encore depuis npm pendant la transition du lancement. Utilisez le préfixe clawhub: lorsque vous voulez la résolution ClawHub.

Exigences

• Utilisez Node 22.19+, Node 23.11+ ou Node 24+, ainsi qu’un gestionnaire de package comme npm ou pnpm.
• Soyez à l’aise avec les modules TypeScript ESM.
• Pour travailler sur un Plugin groupé dans le dépôt, clonez le dépôt et exécutez pnpm install. Le développement de Plugins depuis une extraction source est réservé à pnpm, car OpenClaw charge les Plugins groupés depuis les packages d’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. C’est la forme de Plugin utile la plus courte et elle montre le package, le manifeste, le point d’entrée et la preuve 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’activation explicite 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 aussi être déclaré dans le manifeste du Plugin :

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

Les utilisateurs l’activent avec tools.allow :

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

Les outils facultatifs contrôlent 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 que le modèle l’a sélectionné et avant l’exécution de l’action.

Utilisez les outils facultatifs pour les effets de bord, 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 du noyau ; les conflits sont ignorés et signalés dans les diagnostics de Plugin. Les enregistrements mal formés, y compris les descripteurs d’outils sans parameters, sont ignorés et signalés de la même façon. Les outils enregistrés sont des fonctions typées que le modèle peut appeler après validation des politiques et de la liste d’autorisation.

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 actuel. L’objet peut inclure provider, modelId et modelRef. Traitez-le comme des métadonnées d’exécution informatives, et non comme une frontière 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 activation explicite du Plugin ou de l’opérateur, et échouer fermement lorsque les métadonnées de modèle actif sont absentes ou inadaptées.

Le manifeste déclare la propriété et la découverte ; l’exécution appelle tout de même l’implémentation d’outil enregistrée en direct. Gardez toolMetadata.<tool>.optional: true aligné avec api.registerTool(..., { optional: true }) afin qu’OpenClaw puisse éviter de charger ce runtime de Plugin tant que l’outil n’est pas explicitement autorisé.

Conventions d’import

Importez depuis des sous-chemins SDK ciblés :

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

Dans votre package de Plugin, utilisez des fichiers barrel locaux comme api.ts et runtime-api.ts pour les imports internes. N’importez pas votre propre Plugin via un chemin SDK. Les assistants propres à un fournisseur doivent rester dans le package du fournisseur, sauf si le point d’extension est réellement générique.

Les méthodes RPC Gateway personnalisées sont un point d’entrée avancé. Gardez-les sur un préfixe propre au Plugin ; les espaces de noms d’administration du noyau comme config.*, exec.approvals.*, operator.admin.*, wizard.* et update.* restent réservés et se résolvent vers operator.admin. Le pont openclaw/plugin-sdk/gateway-method-runtime est réservé aux routes HTTP de Plugin qui déclarent contracts.gatewayMethodDispatch: ["authenticated-request"].

Pour la carte complète des imports, consultez Présentation du SDK de Plugin.

Liste de vérification 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: