Présentation du SDK de Plugin

​

Convention d’importation

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

​

Référence des sous-chemins

​

API d’enregistrement

​

Enregistrement des capacités

​

Outils et commandes

agentPromptGuidance: [
  "Indication globale sur la commande.",
  { text: "Afficher ceci uniquement dans l’invite principale d’OpenClaw.", surfaces: ["openclaw_main"] },
];

​

Infrastructure

​

Hooks de l’hôte pour les Plugins de flux de travail

api.session.controls.registerControlUiDescriptor({
  surface: "tab",
  id: "logbook",
  label: "Logbook",
  description: "Your day as a timeline, built from screen snapshots.",
  icon: "sun",
  group: "control",
  requiredScopes: ["operator.write"],
});

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

• Les Plugins externes peuvent régir les extensions de session, les descripteurs d’interface utilisateur, les commandes, les métadonnées d’outils, les injections au tour suivant et les hooks ordinaires.
• Les politiques d’outils de confiance s’exécutent avant les hooks before_tool_call ordinaires et bénéficient de la confiance de l’hôte. Les politiques intégrées s’exécutent en premier ; les politiques des Plugins installés nécessitent une activation explicite ainsi que leurs identifiants locaux dans contracts.trustedToolPolicies, puis s’exécutent dans l’ordre de chargement des Plugins. Les identifiants de politique sont limités au Plugin qui les enregistre.
• La propriété des commandes réservées est limitée aux Plugins intégrés. Les Plugins externes doivent utiliser leurs propres noms de commande ou alias.
• allowPromptInjection=false désactive les hooks qui modifient l’invite, notamment agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, les champs d’invite issus de l’ancien before_agent_start et enqueueNextTurnInjection.

​

Enregistrement de la découverte du Gateway

api.registerGatewayDiscoveryService({
  id: "my-discovery",
  async advertise(ctx) {
    const handle = await startMyAdvertiser({
      gatewayPort: ctx.gatewayPort,
      tls: ctx.gatewayTlsEnabled,
      displayName: ctx.machineDisplayName,
    });
    return { stop: () => handle.stop() };
  },
});

​

Métadonnées d’enregistrement de la CLI

• commands : noms de commandes explicites appartenant au gestionnaire d’enregistrement
• descriptors : descripteurs de commande utilisés lors de l’analyse pour l’aide de la CLI, le routage et l’enregistrement différé de la CLI du Plugin
• parentPath : chemin facultatif de la commande parente pour les groupes de commandes imbriqués, tels que ["nodes"]

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Gérer les comptes Matrix, la vérification, les appareils et l’état du profil",
        hasSubcommands: true,
      },
    ],
  },
);

api.registerCli(
  async ({ program }) => {
    const { registerNodesCanvasCommands } = await import("./src/cli.js");
    registerNodesCanvasCommands(program);
  },
  {
    parentPath: ["nodes"],
    descriptors: [
      {
        name: "canvas",
        description: "Capturer ou restituer le contenu d’un canevas depuis un nœud appairé",
        hasSubcommands: true,
      },
    ],
  },
);

​

Enregistrement d’un backend de CLI

• L’id du backend devient le préfixe du fournisseur dans les références de modèle telles que my-cli/gpt-5.
• La config du backend utilise la même structure que agents.defaults.cliBackends.<id>.
• La configuration de l’utilisateur reste prioritaire. OpenClaw fusionne agents.defaults.cliBackends.<id> par-dessus la valeur par défaut du Plugin avant d’exécuter la CLI.
• Utilisez normalizeConfig lorsqu’un backend nécessite des réécritures de compatibilité après la fusion, par exemple pour normaliser d’anciennes formes d’options.
• Utilisez resolveExecutionArgs pour les réécritures d’arguments propres à la requête qui relèvent du dialecte de la CLI, comme la conversion des niveaux de réflexion d’OpenClaw en une option d’effort native. Le hook reçoit ctx.executionMode ; utilisez "side-question" pour ajouter des options d’isolation natives du backend aux appels éphémères /btw. Si ces options désactivent de manière fiable les outils natifs pour une CLI où ils seraient autrement toujours actifs, déclarez également sideQuestionToolMode: "disabled".
• Les backends capables de désactiver tous les outils natifs pour une exécution précise peuvent déclarer nativeToolMode: "selectable". Les appels restreints transmettent un tuple ctx.toolAvailability.native vide ainsi qu’une liste d’autorisation MCP exacte et isolée de l’hôte ; resolveExecutionArgs doit appliquer les deux aux arguments finaux d’une nouvelle exécution ou d’une reprise. OpenClaw applique un refus par défaut si le backend ne peut pas le faire.

​

Emplacements exclusifs

​

Adaptateurs d’intégration vectorielle de mémoire obsolètes

• registerMemoryCapability est l’API exclusive privilégiée pour les Plugins de mémoire.
• registerMemoryCapability peut également exposer publicArtifacts.listArtifacts(...) afin que les Plugins complémentaires puissent utiliser les artefacts de mémoire exportés via openclaw/plugin-sdk/memory-host-core au lieu d’accéder à l’organisation privée d’un Plugin de mémoire particulier.
• registerMemoryPromptSection, registerMemoryFlushPlan et registerMemoryRuntime sont des API exclusives de Plugin de mémoire compatibles avec l’ancien système.
• MemoryFlushPlan.model peut fixer le tour de vidage à une référence provider/model exacte, telle que ollama/qwen3:8b, sans hériter de la chaîne de repli active.
• registerMemoryEmbeddingProvider est obsolète. Les nouveaux fournisseurs d’intégration vectorielle doivent utiliser api.registerEmbeddingProvider(...) et contracts.embeddingProviders.
• Les fournisseurs existants propres à la mémoire continuent de fonctionner pendant la période de migration, mais l’inspection des Plugins signale cela comme une dette de compatibilité pour les Plugins non intégrés.

​

Événements et cycle de vie

​

Sémantique des décisions des hooks

• before_tool_call : le renvoi de { block: true } est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
• before_tool_call : le renvoi de { block: false } est considéré comme une absence de décision (comme si block était omis), et non comme un remplacement.
• before_install : le renvoi de { block: true } est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
• before_install : le renvoi de { block: false } est considéré comme une absence de décision (comme si block était omis), et non comme un remplacement.
• reply_dispatch : le renvoi de { handled: true, ... } est terminal. Dès qu’un gestionnaire prend en charge la distribution, les gestionnaires de priorité inférieure et le chemin de distribution par défaut du modèle sont ignorés.
• message_sending : le renvoi de { cancel: true } est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
• message_sending : le renvoi de { cancel: false } est considéré comme une absence de décision (comme si cancel était omis), et non comme un remplacement.
• message_received : utilisez le champ typé threadId lorsque vous devez acheminer un fil ou un sujet entrant. Réservez metadata aux données supplémentaires propres au canal.
• message_sending : utilisez les champs d’acheminement typés replyToId / threadId avant de vous rabattre sur les metadata propres au canal.
• gateway_start : utilisez ctx.config, ctx.workspaceDir et ctx.getCron?.() pour l’état de démarrage appartenant au Gateway au lieu de dépendre des hooks internes gateway:startup. Cron peut encore être en cours de chargement à ce stade.
• cron_reconciled : reconstruisez une projection Cron externe complète après le démarrage ou le rechargement du planificateur. Elle inclut reason et l’état enabled effectif, y compris enabled: false, tandis que ctx.getCron?.() renvoie le planificateur réconcilié exact. Transmettez ctx.abortSignal aux travaux de projection durable ; il est interrompu lorsque cet instantané du planificateur est remplacé ou que le Gateway se ferme.
• cron_changed : observez les changements du cycle de vie de Cron appartenant au Gateway. Les événements scheduled et removed sont des indications de réconciliation postérieures à la validation, et non un journal ordonné des différences. Le champ event.nextRunAtMs d’un événement planifié est absent lorsque la tâche n’a pas de prochain réveil ; un événement de suppression contient toujours l’instantané de la tâche supprimée.

​

Champs de l’objet API

​

Convention relative aux modules internes

my-plugin/
  api.ts            # Exportations publiques destinées aux consommateurs externes
  runtime-api.ts    # Exportations d’exécution réservées à l’usage interne
  index.ts          # Point d’entrée du Plugin
  setup-entry.ts    # Point d’entrée léger réservé à la configuration (facultatif)

• Anthropic : interface publique api.ts / contract-api.ts pour les assistants d’en-tête bêta de Claude et de flux service_tier.
• @openclaw/openai-provider : api.ts exporte les générateurs de fournisseurs, les assistants de modèle par défaut et les générateurs de fournisseurs en temps réel.
• @openclaw/openrouter-provider : api.ts exporte le générateur de fournisseur ainsi que les assistants d’intégration et de configuration.

​

Voir aussi