Points d’entrée des Plugins

Chaque plugin exporte un objet d’entrée par défaut. Le SDK fournit une fonction utilitaire pour chaque forme d’entrée : defineToolPlugin, definePluginEntry, defineChannelPluginEntry, defineSetupPluginEntry.

Entrées de paquet

Les plugins installés font pointer les champs package.json openclaw à la fois vers les entrées sources et compilées :

{  "openclaw": {    "extensions": ["./src/index.ts"],    "runtimeExtensions": ["./dist/index.js"],    "setupEntry": "./src/setup-entry.ts",    "runtimeSetupEntry": "./dist/setup-entry.js"  }}

• extensions et setupEntry sont des entrées sources, utilisées pour le développement dans l’espace de travail et depuis une copie de travail git.
• runtimeExtensions et runtimeSetupEntry sont préférées pour les paquets installés : elles permettent aux paquets npm d’éviter la compilation TypeScript à l’exécution.
• runtimeExtensions, lorsqu’il est présent, doit correspondre à extensions en longueur de tableau (les entrées sont associées selon leur position). runtimeSetupEntry nécessite setupEntry.
• Si un artefact runtimeExtensions/runtimeSetupEntry est déclaré mais absent, l’installation ou la découverte échoue avec une erreur de paquetage ; OpenClaw ne revient pas silencieusement au code source. Le repli vers le code source (ci-dessous) s’applique uniquement lorsqu’aucune entrée d’exécution n’est déclarée.
• Si un paquet installé déclare uniquement une entrée source TypeScript, OpenClaw recherche une entrée homologue compilée dist/*.js (ou .mjs/.cjs) correspondante et l’utilise ; sinon, il revient à la source TypeScript.
• Tous les chemins d’entrée doivent rester dans le répertoire du paquet du plugin. Les entrées d’exécution et les entrées homologues JavaScript compilées déduites ne rendent pas valide un chemin source extensions ou setupEntry qui sort de ce répertoire.

defineToolPlugin

Importation : openclaw/plugin-sdk/tool-plugin

Pour les plugins qui ajoutent uniquement des outils d’agent. Cette fonction conserve un code source réduit, déduit les types de configuration et de paramètres d’outil à partir des schémas TypeBox, enveloppe les valeurs de retour simples dans le format de résultat d’outil d’OpenClaw et expose les métadonnées statiques que openclaw plugins build écrit dans le manifeste du plugin (contracts.tools, configSchema).

  export default defineToolPlugin({  id: "stock-quotes",  name: "Stock Quotes",  description: "Fetch stock quotes.",  configSchema: Type.Object({    apiKey: Type.Optional(Type.String({ description: "API key." })),  }),  tools: (tool) => [    tool({      name: "quote",      label: "Quote",      description: "Fetch a quote.",      parameters: Type.Object({        symbol: Type.String({ description: "Ticker symbol." }),      }),      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),    }),  ],});

• configSchema est facultatif ; son omission utilise un schéma strict d’objet vide (le manifeste généré inclut toujours configSchema).
• execute renvoie une chaîne simple ou une valeur sérialisable en JSON ; la fonction utilitaire l’enveloppe dans un résultat d’outil textuel, avec details défini sur la valeur de retour d’origine (non convertie en chaîne).
• Pour les résultats d’outil personnalisés, openclaw/plugin-sdk/tool-results exporte textResult et jsonResult.
• Les noms d’outils sont statiques ; openclaw plugins build déduit donc contracts.tools à partir des outils déclarés, sans duplication manuelle des noms.
• Le chargement à l’exécution reste strict : les plugins installés nécessitent toujours openclaw.plugin.json et package.json openclaw.extensions. OpenClaw n’exécute jamais le code du plugin pour déduire les données manquantes du manifeste.

definePluginEntry

Importation : openclaw/plugin-sdk/plugin-entry

Pour les plugins de fournisseurs, les plugins d’outils avancés, les plugins de hooks et tout ce qui n’est pas un canal de messagerie.

 export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Short summary",  register(api) {    api.registerProvider({/* ... */});    api.registerTool({/* ... */});  },});

• id doit correspondre à votre manifeste openclaw.plugin.json.
• Les catalogues de sessions externes utilisent openclaw/plugin-sdk/session-catalog et api.registerSessionCatalog({ id, label, list, read, continueSession?, archive? }). Le cœur possède les méthodes Gateway sessions.catalog.* ; les fournisseurs renvoient des projections d’hôte, de session et de transcription normalisée sans enregistrer de RPC.
• kind est obsolète : déclarez un emplacement exclusif ("memory" ou "context-engine") dans le champ kind du manifeste openclaw.plugin.json à la place. L’entrée d’exécution kind reste uniquement comme solution de compatibilité pour les anciens plugins.
• configSchema peut être une fonction pour une évaluation différée. OpenClaw résout et mémorise le schéma lors du premier accès, afin que les générateurs de schémas coûteux ne s’exécutent qu’une seule fois.
• Un descripteur nodeHostCommands peut définir isAvailable({ config, env }). Le renvoi de false omet cette commande et sa capacité de la déclaration Gateway du nœud sans interface graphique. OpenClaw l’évalue par rapport à la configuration de démarrage locale du nœud ; les gestionnaires de commandes doivent néanmoins valider la disponibilité lorsqu’ils sont invoqués.

defineChannelPluginEntry

Importation : openclaw/plugin-sdk/channel-core

Enveloppe definePluginEntry avec un câblage propre au canal : appelle automatiquement api.registerChannel({ plugin }), expose une interface de métadonnées CLI facultative pour l’aide racine et conditionne registerFull au mode d’enregistrement.

 export default defineChannelPluginEntry({  id: "my-channel",  name: "My Channel",  description: "Short summary",  plugin: myChannelPlugin,  setRuntime: setMyRuntime,  registerCliMetadata(api) {    api.registerCli(/* ... */);  },  registerFull(api) {    api.registerGatewayMethod(/* ... */);  },});

Les fonctions de rappel s’exécutent selon le mode d’enregistrement (tableau complet dans Mode d’enregistrement) :

• setRuntime s’exécute dans tous les modes sauf "cli-metadata" et "tool-discovery". Stockez ici la référence d’exécution, généralement via createPluginRuntimeStore.
• registerCliMetadata s’exécute pour "cli-metadata", "discovery" et "full". Utilisez-le comme emplacement canonique des descripteurs CLI appartenant au canal, afin que l’aide racine reste non activante, que les instantanés de découverte incluent les métadonnées statiques des commandes et que l’enregistrement CLI normal reste compatible avec les chargements complets de plugins.
• registerFull s’exécute uniquement pour "full" et "tool-discovery". Pour "tool-discovery", il s’exécute à la place de l’enregistrement du canal : OpenClaw ignore entièrement registerChannel/setRuntime et appelle uniquement registerFull. Tout enregistrement de fournisseur ou d’outil dont votre canal a besoin pour la découverte ou l’exécution autonome des outils doit donc se trouver à cet endroit, et non derrière la configuration normale du canal.
• L’enregistrement de découverte est non activant, mais pas exempt d’importation : OpenClaw peut évaluer l’entrée du plugin de confiance et le module du plugin de canal pour créer l’instantané. Les importations de premier niveau doivent être dépourvues d’effets secondaires ; placez les sockets, clients, workers et services derrière des chemins réservés à "full".
• Comme definePluginEntry, configSchema peut être une fabrique différée ; OpenClaw mémorise le schéma résolu lors du premier accès.

Enregistrement CLI :

• Utilisez api.registerCli(..., { descriptors: [...] }) pour les commandes CLI racines appartenant au plugin que vous souhaitez charger de manière différée sans les faire disparaître de l’arbre d’analyse de la CLI racine. Les noms des descripteurs doivent contenir des lettres, des chiffres, des traits d’union et des traits de soulignement, et commencer par une lettre ou un chiffre ; OpenClaw rejette les autres formes et supprime les séquences de contrôle du terminal des descriptions avant d’afficher l’aide. Couvrez chaque racine de commande de premier niveau exposée par la fonction d’enregistrement. commands seul reste sur le chemin de compatibilité à chargement immédiat.
• Utilisez api.registerNodeCliFeature(...) pour les commandes de fonctionnalités des nœuds appairés afin qu’elles soient placées sous openclaw nodes (équivalent à registerCli(registrar, { parentPath: ["nodes"], ... })).
• Pour les autres commandes de plugin imbriquées, ajoutez parentPath et enregistrez les commandes sur l’objet program transmis à la fonction d’enregistrement ; OpenClaw le résout en commande parente avant d’appeler le plugin.
• Pour les plugins de canaux, enregistrez les descripteurs CLI depuis registerCliMetadata et limitez registerFull aux opérations d’exécution.
• Si registerFull enregistre également des méthodes RPC du Gateway, conservez-les sous un préfixe propre au plugin. Les espaces de noms d’administration réservés du cœur (config.*, exec.approvals.*, wizard.*, update.*) sont toujours contraints à operator.admin.

defineSetupPluginEntry

Importation : openclaw/plugin-sdk/channel-core

Pour le fichier léger setup-entry.ts. Renvoie uniquement { plugin }, sans câblage d’exécution ni de CLI.

 export default defineSetupPluginEntry(myChannelPlugin);

OpenClaw charge ceci à la place de l’entrée complète lorsqu’un canal est désactivé, non configuré ou lorsque le chargement différé est activé. Consultez Configuration et paramétrage pour savoir quand cela est important.

Associez defineSetupPluginEntry(...) aux familles restreintes d’assistants de configuration :

Conservez les SDK lourds, l’enregistrement de la CLI et les services d’exécution de longue durée dans l’entrée complète.

Les canaux intégrés à l’espace de travail qui séparent les surfaces de configuration et d’exécution peuvent utiliser defineBundledChannelSetupEntry(...) depuis openclaw/plugin-sdk/channel-entry-contract à la place. Cela permet à l’entrée de configuration de conserver les exports de plugin et de secrets sûrs pour la configuration, tout en exposant un mécanisme de définition de l’exécution :

 export default defineBundledChannelSetupEntry({  importMetaUrl: import.meta.url,  plugin: {    specifier: "./channel-plugin-api.js",    exportName: "myChannelPlugin",  },  runtime: {    specifier: "./runtime-api.js",    exportName: "setMyChannelRuntime",  },  registerSetupRuntime(api) {    api.registerHttpRoute({      path: "/my-channel/events",      auth: "plugin",      handler: async (req, res) => {        /* route sûre pour la configuration */      },    });  },});

Utilisez ceci uniquement lorsqu’un flux de configuration nécessite réellement un mécanisme léger de définition de l’exécution ou une surface Gateway sûre pour la configuration avant le chargement de l’entrée complète du canal. registerSetupRuntime s’exécute uniquement pour les chargements "setup-runtime" ; limitez-le aux routes ou méthodes de configuration uniquement qui doivent exister avant l’activation complète différée.

Mode d’enregistrement

api.registrationMode indique à votre plugin comment il a été chargé :

defineChannelPluginEntry gère automatiquement cette séparation. Si vous utilisez definePluginEntry directement pour un canal, vérifiez vous-même le mode et n’oubliez pas que "tool-discovery" ignore l’enregistrement du canal :

register(api) {  if (    api.registrationMode === "cli-metadata" ||    api.registrationMode === "discovery" ||    api.registrationMode === "full"  ) {    api.registerCli(/* ... */);    if (api.registrationMode === "cli-metadata") return;  }   if (api.registrationMode === "tool-discovery") {    // Enregistrer uniquement les surfaces de fonctionnalités (fournisseurs/outils), sans canal.    return;  }   api.registerChannel({ plugin: myPlugin });  if (api.registrationMode !== "full") return;   // Enregistrements lourds réservés à l’exécution  api.registerService(/* ... */);}

Les services de longue durée peuvent émettre de petits événements d’invalidation ou de cycle de vie au moyen de leur contexte de service :

api.registerService({  id: "index-events",  start(ctx) {    ctx.gatewayEvents?.emit("changed", { revision: 1 }, { scope: "operator.read" });  },});

OpenClaw lui attribue l’espace de noms plugin.<plugin-id>.changed. Les noms d’événements comportent un seul segment en minuscules, les charges utiles doivent être du JSON de taille limitée et la portée doit être operator.read, operator.write ou operator.admin. L’émetteur existe uniquement pendant la durée de vie du service et est révoqué après son arrêt ou l’échec de son démarrage. Préférez des charges utiles de version ou d’invalidation aux enregistrements complets afin que les clients autorisés relisent l’état canonique au moyen des méthodes Gateway ciblées du plugin.

Le mode de découverte crée un instantané de registre sans activation. Il peut néanmoins évaluer l’entrée du plugin et l’objet du plugin de canal afin qu’OpenClaw puisse enregistrer les fonctionnalités du canal et les descripteurs CLI statiques. Considérez l’évaluation du module en mode de découverte comme fiable, mais légère : aucun client réseau, sous-processus, écouteur, connexion à une base de données, worker en arrière-plan, lecture d’identifiants ni aucun autre effet secondaire d’exécution active au niveau supérieur.

Considérez "setup-runtime" comme la fenêtre durant laquelle les surfaces de démarrage réservées à la configuration doivent exister sans réexécuter l’environnement d’exécution complet du canal intégré. Les cas adaptés comprennent l’enregistrement du canal, les routes HTTP sûres pour la configuration, les méthodes Gateway sûres pour la configuration et les assistants de configuration délégués. Les services lourds en arrière-plan, les systèmes d’enregistrement de la CLI et l’initialisation des SDK de fournisseurs/clients doivent toujours rester dans "full".

Formes de plugins

OpenClaw classe les plugins chargés selon leur comportement d’enregistrement :

Utilisez openclaw plugins inspect <id> pour afficher la forme d’un plugin.

Ressources connexes

• Présentation du SDK - API d’enregistrement et référence des sous-chemins
• Assistants d’exécution - api.runtime et createPluginRuntimeStore
• Configuration et paramétrage - manifeste, entrée de configuration, chargement différé
• Plugins de canal - création de l’objet ChannelPlugin
• Plugins de fournisseur - enregistrement des fournisseurs et hooks