Vue d’ensemble du SDK Plugin

Le SDK de Plugin est le contrat typé entre les Plugins et le noyau. Cette page est la référence pour ce qu’il faut importer et ce que vous pouvez enregistrer.

Convention d’importation

Importez toujours depuis un sous-chemin spécifique :

Chaque sous-chemin est un petit module autonome. Cela accélère le démarrage et évite les problèmes de dépendances circulaires. Pour les helpers d’entrée/de construction propres aux canaux, préférez openclaw/plugin-sdk/channel-core; réservez openclaw/plugin-sdk/core à la surface générale plus large et aux helpers partagés comme buildChannelConfigSchema.

Pour la configuration de canal, publiez le schéma JSON détenu par le canal via openclaw.plugin.json#channelConfigs. Le sous-chemin plugin-sdk/channel-config-schema sert aux primitives de schéma partagées et au générateur générique. Les Plugins intégrés d’OpenClaw utilisent plugin-sdk/bundled-channel-config-schema pour conserver les schémas de canaux intégrés. Les exports de compatibilité obsolètes restent sur plugin-sdk/channel-config-schema-legacy; aucun des sous-chemins de schéma intégrés n’est un modèle pour les nouveaux Plugins.

Référence des sous-chemins

Le SDK de Plugin est exposé sous forme d’un ensemble de sous-chemins étroits regroupés par domaine (entrée de Plugin, canal, fournisseur, authentification, runtime, capacité, mémoire et helpers réservés aux Plugins intégrés). Pour le catalogue complet, regroupé et lié, consultez Sous-chemins du SDK de Plugin.

L’inventaire des points d’entrée du compilateur se trouve dans scripts/lib/plugin-sdk-entrypoints.json ; les exports de package sont générés à partir du sous-ensemble public après soustraction des sous-chemins de test/internes locaux au dépôt listés dans scripts/lib/plugin-sdk-private-local-only-subpaths.json. Exécutez pnpm plugin-sdk:surface pour auditer le nombre d’exports publics. Les sous-chemins publics obsolètes suffisamment anciens et inutilisés par le code de production des extensions intégrées sont suivis dans scripts/lib/plugin-sdk-deprecated-public-subpaths.json ; les barrels larges de réexport obsolètes sont suivis dans scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json.

API d’enregistrement

Le callback register(api) reçoit un objet OpenClawPluginApi avec ces méthodes :

Enregistrement des capacités

Outils et commandes

Les commandes de Plugin peuvent définir agentPromptGuidance lorsque l’agent a besoin d’un bref indice de routage détenu par la commande. Gardez ce texte centré sur la commande elle-même ; n’ajoutez pas de politique propre à un fournisseur ou à un Plugin aux constructeurs de prompts du noyau.

Infrastructure

Hooks hôte pour les Plugins de workflow

Les hooks hôte sont les interfaces SDK pour les Plugins qui doivent participer au cycle de vie de l’hôte plutôt que seulement ajouter un fournisseur, un canal ou un outil. Ce sont des contrats génériques ; le Mode Plan peut les utiliser, mais aussi les workflows d’approbation, les barrières de politique d’espace de travail, les moniteurs d’arrière-plan, les assistants de configuration et les Plugins compagnons d’interface.

Utilisez les espaces de noms groupés pour le nouveau code de Plugin :

• 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 méthodes plates équivalentes restent disponibles comme alias de compatibilité obsolètes pour les Plugins existants. N’ajoutez pas de nouveau code de Plugin qui appelle directement api.registerSessionExtension, api.enqueueNextTurnInjection, api.registerControlUiDescriptor, api.registerRuntimeLifecycle, api.registerAgentEventSubscription, api.emitAgentEvent, api.setRunContext, api.getRunContext, api.clearRunContext, api.registerSessionSchedulerJob, api.registerSessionAction, api.sendSessionAttachment, api.scheduleSessionTurn ou api.unscheduleSessionTurnsByTag.

scheduleSessionTurn(...) est un raccourci limité à la session par-dessus le planificateur Gateway Cron. Cron possède la temporisation et crée l’enregistrement de tâche en arrière-plan lorsque le tour s’exécute ; le Plugin SDK ne contraint que la session cible, les noms appartenant au plugin et le nettoyage. Utilisez api.runtime.tasks.managedFlows dans le tour planifié lorsque le travail lui-même nécessite un état durable de flux de tâches en plusieurs étapes.

Les contrats séparent volontairement les responsabilités :

• Les plugins externes peuvent posséder les extensions de session, les descripteurs d’UI, les commandes, les métadonnées d’outils, les injections au tour suivant et les hooks normaux.
• Les politiques d’outils approuvées s’exécutent avant les hooks before_tool_call ordinaires et sont réservées aux éléments groupés, car elles participent à la politique de sécurité de l’hôte.
• La propriété des commandes réservées est réservée aux éléments groupés. Les plugins externes doivent utiliser leurs propres noms de commandes 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.

Exemples de consommateurs non-Plan :

Enregistrement de découverte Gateway

api.registerGatewayDiscoveryService(...) permet à un plugin d’annoncer le Gateway actif sur un transport de découverte local comme mDNS/Bonjour. OpenClaw appelle le service au démarrage du Gateway lorsque la découverte locale est activée, transmet les ports Gateway actuels et les données d’indice TXT non secrètes, puis appelle le gestionnaire stop retourné lors de l’arrêt 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() };  },});

Les plugins de découverte Gateway ne doivent pas traiter les valeurs TXT annoncées comme des secrets ou une authentification. La découverte est un indice de routage ; l’authentification Gateway et l’épinglage TLS restent responsables de la confiance.

Métadonnées d’enregistrement CLI

api.registerCli(registrar, opts?) accepte deux types de métadonnées de commande :

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

Pour les fonctionnalités de nœuds appairés, préférez api.registerNodeCliFeature(registrar, opts?). C’est un petit wrapper autour de api.registerCli(..., { parentPath: ["nodes"] }) qui rend les commandes comme openclaw nodes canvas explicites en tant que fonctionnalités de nœud appartenant au plugin.

Si vous voulez qu’une commande de plugin reste chargée paresseusement dans le chemin CLI racine normal, fournissez des descriptors couvrant chaque racine de commande de premier niveau exposée par ce registrar.

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

Les commandes imbriquées reçoivent la commande parent résolue comme program :

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

Utilisez commands seul uniquement lorsque vous n’avez pas besoin d’un enregistrement CLI racine paresseux. Ce chemin de compatibilité anticipé reste pris en charge, mais il n’installe pas d’espaces réservés adossés à des descripteurs pour le chargement paresseux au moment de l’analyse.

Enregistrement du backend CLI

api.registerCliBackend(...) permet à un plugin de posséder la configuration par défaut d’un backend CLI d’IA local comme codex-cli.

• Le id du backend devient le préfixe du fournisseur dans les références de modèle comme codex-cli/gpt-5.
• La config du backend utilise la même forme que agents.defaults.cliBackends.<id>.
• La configuration utilisateur prévaut toujours. OpenClaw fusionne agents.defaults.cliBackends.<id> par-dessus la valeur par défaut du plugin avant d’exécuter le CLI.
• Utilisez normalizeConfig lorsqu’un backend a besoin de réécritures de compatibilité après la fusion (par exemple pour normaliser d’anciennes formes de flags).
• Utilisez resolveExecutionArgs pour les réécritures d’argv limitées à la requête qui appartiennent au dialecte CLI, comme le mappage des niveaux de réflexion OpenClaw vers un flag d’effort natif.

Pour un guide de création de bout en bout, consultez plugins de backend CLI.

Emplacements exclusifs

Adaptateurs d’embedding de mémoire

• registerMemoryCapability est l’API exclusive de plugin de mémoire préférée.
• registerMemoryCapability peut aussi exposer publicArtifacts.listArtifacts(...) afin que les plugins compagnons puissent consommer les artefacts de mémoire exportés via openclaw/plugin-sdk/memory-host-core au lieu d’accéder à la disposition privée d’un plugin de mémoire spécifique.
• registerMemoryPromptSection, registerMemoryFlushPlan et registerMemoryRuntime sont des API exclusives de plugin de mémoire compatibles avec l’ancien comportement.
• 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 permet au plugin de mémoire actif d’enregistrer un ou plusieurs ids d’adaptateur d’embedding (par exemple openai, gemini ou un id personnalisé défini par un plugin).
• La configuration utilisateur comme agents.defaults.memorySearch.provider et agents.defaults.memorySearch.fallback se résout par rapport à ces ids d’adaptateur enregistrés.

Événements et cycle de vie

Voir Hooks de plugin pour des exemples, des noms de hooks courants et la sémantique des gardes.

Sémantique de décision des hooks

• before_tool_call : retourner { block: true } est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
• before_tool_call : retourner { block: false } est traité comme une absence de décision (identique à l’omission de block), pas comme une surcharge.
• before_install : retourner { block: true } est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
• before_install : retourner { block: false } est traité comme une absence de décision (identique à l’omission de block), pas comme une surcharge.
• reply_dispatch : retourner { handled: true, ... } est terminal. Dès qu’un gestionnaire revendique l’envoi, les gestionnaires de priorité inférieure et le chemin d’envoi au modèle par défaut sont ignorés.
• message_sending : retourner { cancel: true } est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
• message_sending : retourner { cancel: false } est traité comme une absence de décision (identique à l’omission de cancel), pas comme une surcharge.
• message_received : utilisez le champ typé threadId lorsque vous avez besoin du routage de thread/sujet entrant. Gardez metadata pour les compléments propres au canal.
• message_sending : utilisez les champs de routage typés replyToId / threadId avant de revenir à metadata propre au canal.
• gateway_start : utilisez ctx.config, ctx.workspaceDir et ctx.getCron?.() pour l’état de démarrage appartenant au gateway au lieu de vous appuyer sur les hooks internes gateway:startup.
• cron_changed : observez les changements de cycle de vie de cron appartenant au gateway. Utilisez event.job?.state?.nextRunAtMs et ctx.getCron?.() lors de la synchronisation de planificateurs de réveil externes, et gardez 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

Dans votre Plugin, utilisez des fichiers barrel locaux pour les imports internes :

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)

Les surfaces publiques des Plugins groupés chargées via façade (api.ts, runtime-api.ts, index.ts, setup-entry.ts, et les fichiers d’entrée publics similaires) préfèrent l’instantané de configuration d’exécution actif lorsque OpenClaw est déjà en cours d’exécution. Si aucun instantané d’exécution n’existe encore, elles se rabattent sur le fichier de configuration résolu sur le disque. Les façades des Plugins groupés empaquetés doivent être chargées via les chargeurs de façades de Plugins d’OpenClaw ; les imports directs depuis dist/extensions/... contournent les vérifications du manifeste et du sidecar d’exécution que les installations empaquetées utilisent pour le code détenu par le Plugin.

Les Plugins fournisseurs peuvent exposer un barrel de contrat étroit et local au Plugin lorsqu’un assistant est volontairement propre au fournisseur et n’a pas encore sa place dans un sous-chemin SDK générique. Exemples groupés :

• Anthropic : jointure publique api.ts / contract-api.ts pour Claude beta-header et les assistants de flux 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 en temps réel.
• @openclaw/openrouter-provider : api.ts exporte le constructeur de fournisseur ainsi que les assistants d’intégration/configuration.

Connexe