Présentation du SDK de 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 garde le démarrage rapide 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 d’ensemble plus large et aux helpers partagés tels que 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 constructeur générique. Les plugins intégrés d’OpenClaw utilisent plugin-sdk/bundled-channel-config-schema pour les schémas de canaux intégrés conservés. Les exports de compatibilité obsolètes restent sur plugin-sdk/channel-config-schema-legacy ; aucun des sous-chemins de schéma intégré n’est un modèle pour les nouveaux plugins.

Référence des sous-chemins

Le SDK de plugin est exposé comme un ensemble de sous-chemins étroits regroupés par domaine (entrée de plugin, canal, fournisseur, auth, 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 depuis le sous-ensemble public après soustraction des sous-chemins de test/internes propres 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 assez 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

Les fournisseurs d’embeddings enregistrés avec api.registerEmbeddingProvider(...) doivent également être listés dans contracts.embeddingProviders dans le manifeste du plugin. C’est la surface d’embeddings générique pour la génération vectorielle réutilisable. La recherche mémoire peut consommer cette surface de fournisseur générique. L’ancienne couture api.registerMemoryEmbeddingProvider(...) et contracts.memoryEmbeddingProviders est une compatibilité obsolète pendant la migration des fournisseurs existants propres à la mémoire.

Les fournisseurs propres à la mémoire qui exposent encore un runtime batchEmbed(...) restent sur le contrat existant de traitement par lots par fichier, sauf si leur runtime définit explicitement sourceWideBatchEmbed: true. Cette option permet à l’hôte mémoire de soumettre des fragments provenant de plusieurs fichiers mémoire modifiés et sources activées dans un seul appel batchEmbed(...) jusqu’aux limites de lot de l’hôte. Les adaptateurs de lot qui téléversent des fichiers de requêtes JSONL doivent diviser les tâches fournisseur avant leur plafond de taille de téléversement ainsi que leur plafond de nombre de requêtes. Le fournisseur doit renvoyer un embedding par fragment d’entrée dans le même ordre que batch.chunks ; omettez l’indicateur lorsque le fournisseur attend des lots locaux au fichier ou ne peut pas préserver l’ordre des entrées dans une tâche plus large à l’échelle de la source.

Outils et commandes

Utilisez defineToolPlugin pour les plugins simples uniquement composés d’outils avec des noms d’outils fixes. Utilisez directement api.registerTool(...) pour les plugins mixtes ou l’enregistrement d’outils entièrement dynamique.

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

Les entrées de guidage peuvent être des chaînes héritées, qui s’appliquent à toutes les surfaces de prompt, ou des entrées structurées :

agentPromptGuidance: [  "Global command hint.",  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },];

Les surfaces structurées peuvent inclure openclaw_main, codex_app_server, cli_backend, acp_backend ou subagent. pi_main reste un alias obsolète de openclaw_main. Omettez surfaces pour un guidage volontairement valable sur toutes les surfaces. Ne passez pas de tableau surfaces vide ; il est rejeté afin qu’une perte accidentelle de portée ne devienne pas du texte de prompt global.

Les instructions développeur natives du serveur d’application Codex sont plus strictes que les autres surfaces de prompt : seul le guidage explicitement limité à codex_app_server est promu dans cette voie à priorité plus élevée. Le guidage hérité sous forme de chaîne et le guidage structuré sans portée restent disponibles pour les surfaces de prompt non Codex par compatibilité.

Infrastructure

Hooks hôte pour les plugins de workflow

Les hooks hôte sont les coutures 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 garde-fous de politique d’espace de travail, les moniteurs d’arrière-plan, les assistants de configuration et les plugins compagnons d’interface utilisateur.

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

scheduleSessionTurn(...) est un raccourci limité à une session au-dessus du planificateur Cron du Gateway. Cron possède la temporalité et crée l’enregistrement de tâche en arrière-plan lorsque le tour s’exécute ; le SDK Plugin limite uniquement la session cible, la nomination détenue par le 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 Task Flow en plusieurs étapes.

Les contrats séparent volontairement les autorités :

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

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 tel que mDNS/Bonjour. OpenClaw appelle le service pendant le démarrage du Gateway lorsque la découverte locale est activée, transmet les ports Gateway actuels et des données d’indication TXT non secrètes, et appelle le gestionnaire stop renvoyé pendant 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 de l’authentification. La découverte est une indication de routage ; l’authentification Gateway et l’épinglage TLS restent propriétaires 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 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"]

Pour les fonctionnalités de nœud appairé, 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 explicitement des fonctionnalités de nœud détenues par le Plugin.

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

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 parente 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 de l’enregistrement paresseux de CLI racine. Ce chemin de compatibilité avide 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 détenir la configuration par défaut pour un backend CLI d’IA local tel que claude-cli ou my-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".

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

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

Consultez Hooks de Plugin pour des exemples, les noms de hooks courants et la sémantique des gardes.

Sémantique de décision des hooks

before_install est un hook de cycle de vie de l’exécution du Plugin, pas la surface de politique d’installation de l’opérateur. Utilisez security.installPolicy lorsqu’une décision d’autorisation/blocage doit couvrir les chemins d’installation ou de mise à jour adossés à la CLI et au Gateway.

• 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

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és par façade (api.ts, runtime-api.ts, index.ts, setup-entry.ts et 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 disque. Les façades de Plugins groupés empaquetés doivent être chargées via les chargeurs de façade de Plugin d’OpenClaw ; les imports directs depuis dist/extensions/... contournent le manifeste et les vérifications sidecar d’exécution que les installations empaquetées utilisent pour le code détenu par le Plugin.

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

• 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