Migration du SDK Plugin

OpenClaw est passé d’une large couche de rétrocompatibilité à une architecture de Plugin moderne avec des imports ciblés et documentés. Si votre Plugin a été créé avant la nouvelle architecture, ce guide vous aide à le migrer.

Ce qui change

L’ancien système de Plugin fournissait deux surfaces très ouvertes qui permettaient aux Plugins d’importer tout ce dont ils avaient besoin depuis un point d’entrée unique :

• openclaw/plugin-sdk/compat - un import unique qui réexportait des dizaines d’assistants. Il a été introduit pour maintenir le fonctionnement des anciens Plugins basés sur des hooks pendant la construction de la nouvelle architecture de Plugin.
• openclaw/plugin-sdk/infra-runtime - un large barrel d’assistants d’exécution qui mélangeait événements système, état Heartbeat, files de livraison, assistants fetch/proxy, assistants de fichiers, types d’approbation et utilitaires sans rapport.
• openclaw/plugin-sdk/config-runtime - un large barrel de compatibilité de configuration qui conserve encore des assistants directs de chargement/écriture dépréciés pendant la fenêtre de migration.
• openclaw/extension-api - un pont qui donnait aux Plugins un accès direct aux assistants côté hôte, comme l’exécuteur d’agent intégré.
• api.registerEmbeddedExtensionFactory(...) - un hook d’extension groupée réservé à l’exécuteur intégré, désormais supprimé, qui pouvait observer les événements de l’exécuteur intégré tels que tool_result.

Les larges surfaces d’import sont maintenant dépréciées. Elles fonctionnent encore à l’exécution, mais les nouveaux Plugins ne doivent pas les utiliser, et les Plugins existants devraient migrer avant que la prochaine version majeure ne les supprime. L’API d’enregistrement de fabrique d’extension réservée à l’exécuteur intégré a été supprimée ; utilisez plutôt un middleware de résultat d’outil.

OpenClaw ne supprime ni ne réinterprète un comportement de Plugin documenté dans le même changement qui introduit un remplacement. Les changements de contrat incompatibles doivent d’abord passer par un adaptateur de compatibilité, des diagnostics, de la documentation et une fenêtre de dépréciation. Cela s’applique aux imports SDK, champs de manifeste, API de configuration, hooks et comportements d’enregistrement à l’exécution.

Pourquoi cela a changé

L’ancienne approche posait des problèmes :

• Démarrage lent - importer un assistant chargeait des dizaines de modules sans rapport
• Dépendances circulaires - les réexports larges facilitaient la création de cycles d’import
• Surface d’API peu claire - aucun moyen de distinguer les exports stables des exports internes

Le SDK de Plugin moderne corrige cela : chaque chemin d’import (openclaw/plugin-sdk/\<subpath\>) est un petit module autonome, doté d’un objectif clair et d’un contrat documenté.

Les coutures de commodité des anciens fournisseurs pour les canaux groupés ont également disparu. Les coutures d’assistants de marque de canal étaient des raccourcis privés du monorepo, pas des contrats de Plugin stables. Utilisez plutôt des sous-chemins SDK génériques et étroits. Dans l’espace de travail du Plugin groupé, gardez les assistants appartenant au fournisseur dans le propre api.ts ou runtime-api.ts de ce Plugin.

Exemples actuels de fournisseurs groupés :

• Anthropic garde les assistants de flux propres à Claude dans sa propre couture api.ts / contract-api.ts
• OpenAI garde les constructeurs de fournisseur, les assistants de modèle par défaut et les constructeurs de fournisseur temps réel dans son propre api.ts
• OpenRouter garde le constructeur de fournisseur et les assistants d’onboarding/configuration dans son propre api.ts

Plan de migration de Talk et de la voix en temps réel

Le code Talk pour la voix en temps réel, la téléphonie, les réunions et le navigateur passe d’une comptabilité des tours locale à chaque surface à un contrôleur de session Talk partagé exporté par openclaw/plugin-sdk/realtime-voice. Le nouveau contrôleur possède l’enveloppe commune des événements Talk, l’état de tour actif, l’état de capture, l’état de sortie audio, l’historique récent des événements et le rejet des tours obsolètes. Les Plugins fournisseurs doivent continuer à posséder les sessions temps réel propres au fournisseur ; les Plugins de surface doivent continuer à posséder la capture, la lecture, la téléphonie et les particularités de réunion.

Cette migration Talk est volontairement nette et incompatible :

1. Garder les primitives partagées de contrôleur/exécution dans plugin-sdk/realtime-voice.
2. Migrer les surfaces groupées vers le contrôleur partagé : relais navigateur, transfert de salle gérée, temps réel d’appel vocal, STT en streaming d’appel vocal, temps réel Google Meet et push-to-talk natif.
3. Remplacer les anciennes familles RPC Talk par l’API finale talk.session.* et talk.client.*.
4. Annoncer un seul canal d’événements Talk actif dans hello-ok.features.events du Gateway : talk.event.
5. Supprimer l’ancien endpoint HTTP temps réel et tout chemin de remplacement des instructions au moment de la requête.

Le nouveau code ne devrait pas appeler createTalkEventSequencer(...) directement, sauf s’il implémente un adaptateur bas niveau ou un fixture de test. Préférez le contrôleur partagé afin que les événements limités à un tour ne puissent pas être émis sans identifiant de tour, que les appels turnEnd / turnCancel obsolètes ne puissent pas effacer un tour actif plus récent, et que les événements de cycle de vie de sortie audio restent cohérents entre la téléphonie, les réunions, le relais navigateur, le transfert de salle gérée et les clients Talk natifs.

La forme cible de l’API publique est :

// Gateway-owned Talk session API.await gateway.request("talk.session.create", {  mode: "realtime",  transport: "gateway-relay",  brain: "agent-consult",  sessionKey: "main",});await gateway.request("talk.session.appendAudio", { sessionId, audioBase64 });await gateway.request("talk.session.cancelOutput", { sessionId, reason: "barge-in" });await gateway.request("talk.session.submitToolResult", {  sessionId,  callId,  result: { status: "working" },  options: { willContinue: true },});await gateway.request("talk.session.submitToolResult", {  sessionId,  callId,  result: { status: "already_delivered" },  options: { suppressResponse: true },});await gateway.request("talk.session.submitToolResult", { sessionId, callId, result });await gateway.request("talk.session.close", { sessionId }); // Client-owned provider session API.await gateway.request("talk.client.create", {  mode: "realtime",  transport: "webrtc",  brain: "agent-consult",  sessionKey: "main",});await gateway.request("talk.client.toolCall", { sessionKey, callId, name, args });await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });

Les sessions WebRTC/provider-websocket appartenant au navigateur utilisent talk.client.create, car le navigateur possède la négociation fournisseur et le transport média tandis que le Gateway possède les identifiants, les instructions et la politique d’outils. talk.session.* est la surface commune gérée par le Gateway pour le temps réel gateway-relay, la transcription gateway-relay et les sessions STT/TTS natives managed-room.

Les anciennes configurations qui plaçaient les sélecteurs temps réel à côté de talk.provider / talk.providers doivent être réparées avec openclaw doctor --fix ; l’exécution Talk ne réinterprète pas la configuration de fournisseur speech/TTS comme configuration de fournisseur temps réel.

Les combinaisons prises en charge par talk.session.create sont volontairement limitées :

Carte des méthodes supprimées :

Le vocabulaire de contrôle unifié est également volontairement étroit :

N’introduisez pas de cas particuliers de fournisseur ou de plateforme dans le cœur pour que cela fonctionne. Le cœur possède la sémantique des sessions Talk. Les Plugins fournisseurs possèdent la configuration des sessions fournisseur. Les appels vocaux et Google Meet possèdent les adaptateurs de téléphonie/réunion. Les navigateurs et les applications natives possèdent l’expérience utilisateur de capture/lecture des appareils.

Politique de compatibilité

Pour les Plugins externes, le travail de compatibilité suit cet ordre :

1. ajouter le nouveau contrat
2. conserver l’ancien comportement câblé via un adaptateur de compatibilité
3. émettre un diagnostic ou un avertissement qui nomme l’ancien chemin et son remplacement
4. couvrir les deux chemins dans les tests
5. documenter l’obsolescence et le chemin de migration
6. supprimer uniquement après la fenêtre de migration annoncée, généralement dans une version majeure

Les mainteneurs peuvent auditer la file de migration actuelle avec pnpm plugins:boundary-report. Utilisez pnpm plugins:boundary-report:summary pour des nombres compacts, --owner <id> pour un Plugin ou propriétaire de compatibilité, et pnpm plugins:boundary-report:ci lorsqu’une barrière CI doit échouer sur des enregistrements de compatibilité arrivés à échéance, des imports SDK réservés entre propriétaires ou des sous-chemins SDK réservés inutilisés. Le rapport groupe les enregistrements de compatibilité obsolètes par date de suppression, compte les références locales de code/docs, met en évidence les imports SDK réservés entre propriétaires et résume le pont SDK privé de l’hôte mémoire afin que le nettoyage de compatibilité reste explicite au lieu de s’appuyer sur des recherches ponctuelles. Les sous-chemins SDK réservés doivent avoir une utilisation propriétaire suivie ; les exports d’aides réservées inutilisés doivent être retirés du SDK public.

Si un champ de manifeste est toujours accepté, les auteurs de Plugins peuvent continuer à l’utiliser jusqu’à ce que les docs et diagnostics indiquent le contraire. Le nouveau code doit préférer le remplacement documenté, mais les Plugins existants ne doivent pas casser pendant les versions mineures ordinaires.

Comment migrer

await api.runtime.config.mutateConfigFile({  afterWrite: { mode: "auto" },  mutate(draft) {    draft.plugins ??= {};  },});

// OpenClaw and Codex runtime dynamic toolsapi.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"]  }}

// Beforeconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Afterconst program = applyWindowsSpawnProgramPolicy({  candidate,  // Only set this for trusted compatibility callers that intentionally  // accept shell-mediated fallback.  allowShellFallback: true,});

grep -r "plugin-sdk/compat" my-plugin/grep -r "plugin-sdk/infra-runtime" my-plugin/grep -r "plugin-sdk/config-runtime" my-plugin/grep -r "openclaw/extension-api" my-plugin/

// Before (deprecated backwards-compatibility layer)import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // After (modern focused imports)import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";

// Before (deprecated extension-api bridge)import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

Référence des chemins d’importation

Ce tableau est volontairement le sous-ensemble commun de migration, et non la surface complète du SDK. L’inventaire des points d’entrée du compilateur se trouve dans scripts/lib/plugin-sdk-entrypoints.json ; les exports de paquet sont générés à partir du sous-ensemble public.

Les points de jonction d’assistance réservés aux plugins groupés ont été retirés de la carte d’export public du SDK, sauf pour les façades de compatibilité explicitement documentées, comme le shim déprécié plugin-sdk/discord conservé pour le paquet publié @openclaw/discord@2026.3.13. Les assistants propres à un propriétaire résident dans le paquet du plugin propriétaire ; le comportement partagé de l’hôte doit passer par des contrats SDK génériques comme plugin-sdk/gateway-runtime, plugin-sdk/security-runtime et plugin-sdk/plugin-config-runtime.

Utilisez l’import le plus étroit qui correspond à la tâche. Si vous ne trouvez pas d’export, vérifiez la source dans src/plugin-sdk/ ou demandez aux mainteneurs quel contrat générique doit en être propriétaire.

Dépréciations actives

Dépréciations plus ciblées qui s’appliquent au SDK de plugin, au contrat de fournisseur, à la surface d’exécution et au manifeste. Chacune fonctionne encore aujourd’hui, mais sera supprimée dans une future version majeure. L’entrée sous chaque élément associe l’ancienne API à son remplacement canonique.

// Beforeimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Afterimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// Beforeapi.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // Afterapi.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

// Beforeapi.on("subagent_spawning", async () => ({  status: "ok",  threadBindingReady: true,  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },})); // Afterapi.on("subagent_spawned", async (event) => {  await observeSubagentLaunch(event);});

{  "contracts": {    "externalAuthProviders": ["anthropic", "openai"]  }}

// Beforeconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Afterconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Beforeimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Afterimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

Calendrier de suppression

Tous les plugins principaux ont déjà été migrés. Les plugins externes doivent migrer avant la prochaine version majeure.

Suppression temporaire des avertissements

Définissez ces variables d’environnement pendant que vous travaillez sur la migration :

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

Il s’agit d’une solution de contournement temporaire, pas d’une solution permanente.

Associé

• Bien démarrer - créez votre premier plugin
• Vue d’ensemble du SDK - référence complète des importations de sous-chemins
• Plugins de canaux - création de plugins de canaux
• Plugins de fournisseurs - création de plugins de fournisseurs
• Internes des plugins - analyse approfondie de l’architecture
• Manifeste de plugin - référence du schéma de manifeste