Points d’entrée des Plugins

​

Entrées de paquet

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

import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

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

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

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

import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

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 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.

• 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

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);

import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";

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 */
      },
    });
  },
});

​

Mode d’enregistrement

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(/* ... */);
}

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

​

Formes de plugins

​

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