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: [
  "Global command hint.",
  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },
];

​

Infrastructure

​

Hooks hôte pour les plugins de workflow

• 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 détenir 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 normaux.
• Les politiques d’outils approuvés s’exécutent avant les hooks ordinaires before_tool_call et sont approuvées par l’hôte. Les politiques intégrées s’exécutent en premier ; les politiques des plugins installés nécessitent une activation explicite plus leurs identifiants locaux dans contracts.trustedToolPolicies, puis s’exécutent ensuite 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 réservée aux modules intégrés. Les plugins externes doivent utiliser leurs propres noms de commande ou alias.
• allowPromptInjection=false désactive les hooks qui modifient le prompt, notamment agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, les champs de prompt de l’ancien before_agent_start, et enqueueNextTurnInjection.

​

Enregistrement de découverte 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 CLI

• commands : noms de commandes explicites détenus par le registraire
• descriptors : descripteurs de commandes au moment de l’analyse utilisés pour l’aide CLI, le routage et l’enregistrement paresseux de CLI de Plugin
• parentPath : chemin de commande parent facultatif pour les groupes de commandes imbriqués, comme ["nodes"]

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Manage Matrix accounts, verification, devices, and profile state",
        hasSubcommands: true,
      },
    ],
  },
);

api.registerCli(
  async ({ program }) => {
    const { registerNodesCanvasCommands } = await import("./src/cli.js");
    registerNodesCanvasCommands(program);
  },
  {
    parentPath: ["nodes"],
    descriptors: [
      {
        name: "canvas",
        description: "Capture or render canvas content from a paired node",
        hasSubcommands: true,
      },
    ],
  },
);

​

Enregistrement du backend CLI

• Le id du backend devient le préfixe de fournisseur dans les références de modèle comme my-cli/gpt-5.
• La config du backend utilise la même forme que agents.defaults.cliBackends.<id>.
• La configuration 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 a besoin de réécritures de compatibilité après fusion (par exemple pour normaliser d’anciennes formes d’indicateurs).
• Utilisez resolveExecutionArgs pour les réécritures argv limitées à la requête qui relèvent du dialecte CLI, comme le mappage des niveaux de réflexion OpenClaw vers un indicateur d’effort natif. Le hook reçoit ctx.executionMode; utilisez "side-question" pour ajouter des indicateurs d’isolation natifs au backend pour les appels /btw éphémères. Si ces indicateurs désactivent de façon fiable les outils natifs pour une CLI autrement toujours active, déclarez aussi sideQuestionToolMode: "disabled".

​

Emplacements exclusifs

​

Adaptateurs d’embedding mémoire obsolètes

• registerMemoryCapability est l’API exclusive de Plugin mémoire recommandée.
• registerMemoryCapability peut également exposer publicArtifacts.listArtifacts(...) afin que les Plugins compagnons puissent consommer les artefacts mémoire exportés via openclaw/plugin-sdk/memory-host-core au lieu d’accéder à la structure privée d’un Plugin mémoire spécifique.
• registerMemoryPromptSection, registerMemoryFlushPlan et registerMemoryRuntime sont des API exclusives de Plugin mémoire compatibles avec l’existant.
• MemoryFlushPlan.model peut épingler le tour de vidage à une référence provider/model exacte, comme ollama/qwen3:8b, sans hériter de la chaîne de repli active.
• registerMemoryEmbeddingProvider est obsolète. Les nouveaux fournisseurs d’embeddings doivent utiliser api.registerEmbeddingProvider(...) et contracts.embeddingProviders.
• Les fournisseurs propres à la mémoire existants continuent de fonctionner pendant la fenêtre de migration, mais l’inspection du Plugin signale cela comme une dette de compatibilité pour les Plugins non groupés.

​

Événements et cycle de vie

​

Sémantique de décision des hooks

• before_tool_call : renvoyer { block: true } est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
• before_tool_call : renvoyer { block: false } est traité comme une absence de décision (comme si block était omis), et non comme une substitution.
• before_install : renvoyer { block: true } est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
• before_install : renvoyer { block: false } est traité comme une absence de décision (comme si block était omis), et non comme une substitution.
• reply_dispatch : renvoyer { handled: true, ... } est terminal. Dès qu’un gestionnaire revendique l’envoi, les gestionnaires de priorité inférieure et le chemin d’envoi de modèle par défaut sont ignorés.
• message_sending : renvoyer { cancel: true } est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
• message_sending : renvoyer { cancel: false } est traité comme une absence de décision (comme si cancel était omis), et non comme une substitution.
• message_received : utilisez le champ typé threadId lorsque vous avez besoin du routage entrant par fil/sujet. Conservez metadata pour les compléments propres au canal.
• message_sending : utilisez les champs de routage 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 détenu par le Gateway au lieu de dépendre des hooks internes gateway:startup.
• cron_changed : observez les changements de cycle de vie Cron détenus par le Gateway. Utilisez event.job?.state?.nextRunAtMs et ctx.getCron?.() lors de la synchronisation de planificateurs de réveil externes, et conservez OpenClaw comme source de vérité pour les vérifications d’échéance et l’exécution.

​

Champs de l’objet API

​

Convention de module interne

my-plugin/
  api.ts            # Public exports for external consumers
  runtime-api.ts    # Internal-only runtime exports
  index.ts          # Plugin entry point
  setup-entry.ts    # Lightweight setup-only entry (optional)

• Anthropic : surface publique api.ts / contract-api.ts pour les assistants de flux d’en-tête bêta Claude et service_tier.
• @openclaw/openai-provider : api.ts exporte les constructeurs de fournisseur, les assistants de modèle par défaut et les constructeurs de fournisseur temps réel.
• @openclaw/openrouter-provider : api.ts exporte le constructeur de fournisseur ainsi que les assistants d’onboarding/configuration.

​

Connexe