Points d’entrée du Plugin

Chaque Plugin exporte un objet d’entrée par défaut. Le SDK fournit trois helpers pour les créer.

Pour les Plugins installés, package.json doit pointer le chargement d’exécution vers le JavaScript compilé lorsqu’il est disponible :

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

extensions et setupEntry restent des entrées sources valides pour le développement dans un workspace et un checkout git. runtimeExtensions et runtimeSetupEntry sont préférés quand OpenClaw charge un package installé et permettent aux packages npm d’éviter la compilation TypeScript à l’exécution. Des entrées d’exécution explicites sont requises : runtimeSetupEntry requiert setupEntry, et les artefacts runtimeExtensions ou runtimeSetupEntry manquants font échouer l’installation/la découverte au lieu de revenir silencieusement à la source. Si un package installé ne déclare qu’une entrée source TypeScript, OpenClaw utilisera un pair dist/*.js compilé correspondant lorsqu’il existe, puis reviendra à la source TypeScript.

Tous les chemins d’entrée doivent rester dans le répertoire du package du Plugin. Les entrées d’exécution et les pairs JavaScript compilés déduits ne rendent pas valide un chemin source extensions ou setupEntry qui s’échappe.

definePluginEntry

Import : openclaw/plugin-sdk/plugin-entry

Pour les Plugins de fournisseur, les Plugins d’outils, les Plugins de hook 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.
• kind sert aux emplacements exclusifs : "memory" ou "context-engine".
• configSchema peut être une fonction pour une évaluation paresseuse.
• OpenClaw résout et mémorise ce schéma au premier accès, donc les constructeurs de schéma coûteux ne s’exécutent qu’une seule fois.

defineChannelPluginEntry

Import : openclaw/plugin-sdk/channel-core

Enveloppe definePluginEntry avec un câblage propre aux canaux. Appelle automatiquement api.registerChannel({ plugin }), expose une couture optionnelle de métadonnées CLI pour l’aide racine et protège registerFull selon le 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(/* ... */);  },});

• setRuntime est appelé pendant l’enregistrement afin que vous puissiez stocker la référence d’exécution (généralement via createPluginRuntimeStore). Il est ignoré pendant la capture des métadonnées CLI.
• registerCliMetadata s’exécute pendant api.registrationMode === "cli-metadata", api.registrationMode === "discovery" et api.registrationMode === "full". Utilisez-le comme emplacement canonique pour les 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 de commandes statiques et que l’enregistrement normal des commandes CLI reste compatible avec les chargements complets de Plugin.
• L’enregistrement de découverte est non activant, pas sans import. OpenClaw peut évaluer l’entrée de Plugin fiable et le module de Plugin de canal pour construire l’instantané ; gardez donc les imports de premier niveau sans effet de bord et placez les sockets, clients, workers et services derrière des chemins réservés à "full".
• registerFull ne s’exécute que lorsque api.registrationMode === "full". Il est ignoré pendant le chargement uniquement de configuration.
• Comme definePluginEntry, configSchema peut être une fabrique paresseuse et OpenClaw mémorise le schéma résolu au premier accès.
• Pour les commandes CLI racine appartenant au Plugin, préférez api.registerCli(..., { descriptors: [...] }) lorsque vous voulez que la commande reste chargée paresseusement sans disparaître de l’arbre d’analyse CLI racine. Pour les commandes de fonctionnalité de nœud appairé, préférez api.registerNodeCliFeature(...) afin que la commande arrive sous openclaw nodes. Pour les autres commandes de Plugin imbriquées, ajoutez parentPath et enregistrez les commandes sur l’objet program passé au registraire ; OpenClaw le résout vers la commande parente avant d’appeler le Plugin. Pour les Plugins de canal, préférez enregistrer ces descripteurs depuis registerCliMetadata(...) et gardez registerFull(...) concentré sur le travail réservé à l’exécution.
• Si registerFull(...) enregistre aussi des méthodes RPC Gateway, gardez-les sur un préfixe propre au Plugin. Les espaces de noms d’administration du noyau réservés (config.*, exec.approvals.*, wizard.*, update.*) sont toujours forcés en operator.admin.

defineSetupPluginEntry

Import : openclaw/plugin-sdk/channel-core

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

 export default defineSetupPluginEntry(myChannelPlugin);

OpenClaw charge ceci au lieu 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 importe.

En pratique, associez defineSetupPluginEntry(...) aux familles étroites de helpers de configuration :

• openclaw/plugin-sdk/setup-runtime pour les helpers de configuration sûrs à l’exécution, comme les adaptateurs de patch de configuration sûrs à importer, la sortie de note de recherche, promptResolvedAllowFrom, splitSetupEntries et les proxys de configuration délégués
• openclaw/plugin-sdk/channel-setup pour les surfaces de configuration d’installation optionnelle
• openclaw/plugin-sdk/setup-tools pour les helpers CLI/archive/docs de configuration/installation

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

Les canaux de workspace groupés qui séparent les surfaces de configuration et d’exécution peuvent utiliser defineBundledChannelSetupEntry(...) depuis openclaw/plugin-sdk/channel-entry-contract à la place. Ce contrat permet à l’entrée de configuration de conserver des exports Plugin/secrets sûrs pour la configuration tout en exposant un setter d’exécution :

 export default defineBundledChannelSetupEntry({  importMetaUrl: import.meta.url,  plugin: {    specifier: "./channel-plugin-api.js",    exportName: "myChannelPlugin",  },  runtime: {    specifier: "./runtime-api.js",    exportName: "setMyChannelRuntime",  },});

Utilisez ce contrat groupé seulement lorsque les flux de configuration ont réellement besoin d’un setter d’exécution léger avant le chargement de l’entrée complète du canal.

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 :

register(api) {  if (    api.registrationMode === "cli-metadata" ||    api.registrationMode === "discovery" ||    api.registrationMode === "full"  ) {    api.registerCli(/* ... */);    if (api.registrationMode === "cli-metadata") return;  }   api.registerChannel({ plugin: myPlugin });  if (api.registrationMode !== "full") return;   // Heavy runtime-only registrations  api.registerService(/* ... */);}

Le mode découverte construit un instantané de registre non activant. Il peut tout de même évaluer l’entrée de Plugin et l’objet Plugin de canal afin qu’OpenClaw puisse enregistrer les capacités du canal et les descripteurs CLI statiques. Traitez l’évaluation de module en mode découverte comme fiable mais légère : aucun client réseau, sous-processus, écouteur, connexion à une base de données, worker d’arrière-plan, lecture d’identifiants ni autre effet de bord d’exécution réel au premier niveau.

Traitez "setup-runtime" comme la fenêtre où les surfaces de démarrage uniquement de configuration doivent exister sans réentrer dans l’exécution complète du canal groupé. Les bons cas d’usage sont l’enregistrement du canal, les routes HTTP sûres pour la configuration, les méthodes Gateway sûres pour la configuration et les helpers de configuration délégués. Les services d’arrière-plan lourds, les registraires CLI et les amorçages de SDK fournisseur/client restent réservés à "full".

Pour les registraires CLI en particulier :

• utilisez descriptors lorsque le registraire possède une ou plusieurs commandes racines et que vous voulez qu’OpenClaw charge de manière différée le module CLI réel à la première invocation
• assurez-vous que ces descripteurs couvrent chaque racine de commande de premier niveau exposée par le registraire
• limitez les noms de commande des descripteurs aux lettres, chiffres, traits d’union et traits de soulignement, en commençant par une lettre ou un chiffre ; OpenClaw rejette les noms de descripteur qui ne respectent pas cette forme et supprime les séquences de contrôle du terminal des descriptions avant d’afficher l’aide
• utilisez commands seul uniquement pour les chemins de compatibilité à chargement immédiat

Formes de Plugin

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

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

Connexe

• Vue d’ensemble 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, point d’entrée de configuration, chargement différé
• Plugins de canal - création de l’objet ChannelPlugin
• Plugins de fournisseur - enregistrement du fournisseur et hooks