Migration du SDK de Plugin

OpenClaw a remplacé une vaste couche de rétrocompatibilité par une architecture de plugins moderne fondée sur de petits imports ciblés. Si votre plugin est antérieur à ce changement, ce guide vous aide à adopter les contrats actuels.

Ce qui a changé

Deux surfaces d’import très permissives permettaient auparavant aux plugins d’accéder à presque tout depuis un point d’entrée unique :

• openclaw/plugin-sdk/compat - réexportait des dizaines d’utilitaires pour maintenir le fonctionnement des anciens plugins fondés sur des hooks pendant la construction de la nouvelle architecture.
• openclaw/plugin-sdk/infra-runtime - un vaste module d’agrégation mêlant événements système, état Heartbeat, files d’attente de livraison, utilitaires de récupération/proxy, utilitaires de fichiers, types d’approbation et utilitaires sans rapport entre eux.
• openclaw/plugin-sdk/config-runtime - un vaste module d’agrégation de configuration qui contenait encore des utilitaires directs obsolètes de chargement/écriture pendant la période de migration.
• openclaw/extension-api - une passerelle donnant aux plugins un accès direct aux utilitaires côté hôte, comme l’exécuteur d’agent intégré.
• api.registerEmbeddedExtensionFactory(...) - un hook supprimé, propre à l’exécuteur intégré, qui observait ses événements tels que tool_result. Utilisez plutôt l’intergiciel de résultats d’outils d’agent (voir Migrer les extensions de résultats d’outils intégrées vers l’intergiciel).

Ces surfaces sont obsolètes : elles fonctionnent encore, mais les nouveaux plugins ne doivent pas les utiliser et les plugins existants doivent migrer avant leur suppression dans la prochaine version majeure. registerEmbeddedExtensionFactory a déjà été supprimé ; les anciens enregistrements ne sont plus chargés.

OpenClaw ne supprime ni ne réinterprète un comportement de plugin documenté dans le même changement que celui qui introduit son remplacement. Les modifications de contrat incompatibles passent d’abord par un adaptateur de compatibilité, des diagnostics, de la documentation et une période d’obsolescence. Cela s’applique aux imports du SDK, aux champs du manifeste, aux API de configuration, aux hooks et au comportement d’enregistrement à l’exécution.

Pourquoi

• Démarrage lent - l’import d’un seul utilitaire chargeait des dizaines de modules sans rapport.
• Dépendances circulaires - les vastes réexportations facilitaient la création de cycles d’import.
• Surface d’API peu claire - rien ne permettait de distinguer les exports stables des exports internes.

Chaque openclaw/plugin-sdk/<subpath> est désormais un petit module autonome doté d’un contrat documenté.

Les anciennes interfaces pratiques de fournisseurs pour les canaux intégrés ont également disparu : les raccourcis d’utilitaires propres aux canaux étaient des commodités privées du monorepo, et non des contrats de plugin stables. Utilisez plutôt des sous-chemins génériques et ciblés du SDK. Dans l’espace de travail des plugins intégrés, conservez les utilitaires appartenant au fournisseur dans le fichier api.ts ou runtime-api.ts de ce plugin :

• Anthropic conserve les utilitaires de flux propres à Claude dans son interface api.ts / contract-api.ts.
• OpenAI conserve les constructeurs de fournisseurs, les utilitaires de modèle par défaut et les constructeurs de fournisseurs en temps réel dans son fichier api.ts.
• OpenRouter conserve le constructeur de fournisseur et les utilitaires d’intégration/configuration dans son fichier api.ts.

Politique de compatibilité

Les travaux de compatibilité des plugins externes suivent cet ordre :

1. Ajouter le nouveau contrat.
2. Maintenir l’ancien comportement au moyen d’un adaptateur de compatibilité.
3. Émettre un diagnostic ou un avertissement indiquant l’ancien chemin et son remplacement.
4. Couvrir les deux chemins dans les tests.
5. Documenter l’obsolescence et la procédure de migration.
6. Ne supprimer qu’après la période de migration annoncée, généralement dans une version majeure.

Si un champ de manifeste est encore accepté, continuez à l’utiliser jusqu’à ce que la documentation et les diagnostics indiquent le contraire. Le nouveau code doit privilégier le remplacement documenté ; les plugins existants ne doivent pas cesser de fonctionner lors de versions mineures ordinaires.

Auditez la file de migration actuelle avec pnpm plugins:boundary-report :

pnpm plugins:boundary-report:ci s’exécute avec les trois options d’échec. Chaque enregistrement de compatibilité possède une date removeAfter explicite (et non une vague « prochaine version majeure ») : le rapport regroupe les enregistrements obsolètes selon cette date, compte les références locales dans le code et la documentation, signale les imports SDK réservés entre propriétaires et résume la passerelle SDK privée de l’hôte de mémoire. Les sous-chemins SDK réservés doivent être associés à un usage suivi par leur propriétaire ; les exports réservés inutilisés doivent être supprimés du SDK public.

Procédure de migration

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

// Outils dynamiques des environnements d’exécution OpenClaw et Codexapi.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

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

// Avantconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Aprèsconst program = applyWindowsSpawnProgramPolicy({  candidate,  // Définissez ceci uniquement pour les appelants de compatibilité de  // confiance qui acceptent intentionnellement un repli via le shell.  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/

// Avant (couche de rétrocompatibilité obsolète)import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // Après (imports modernes et ciblés)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";

// Avant (pont extension-api obsolète)import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // Après (environnement d’exécution injecté)const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test my-plugin/

Référence des chemins d’importation

Ce tableau présente le sous-ensemble commun pour la migration, et non l’intégralité de la surface du SDK. L’inventaire des points d’entrée du compilateur se trouve dans scripts/lib/plugin-sdk-entrypoints.json ; les exportations de paquet sont générées à partir du sous-ensemble public.

Les interfaces d’assistance réservées aux plugins intégrés ont été retirées de la carte d’exportation du SDK public, à l’exception des façades de compatibilité explicitement documentées, telles que le shim plugin-sdk/discord obsolète, conservé pour les plugins externes qui importent encore directement le paquet publié @openclaw/discord. Les assistants propres à un propriétaire résident dans le paquet du plugin concerné ; le comportement partagé de l’hôte passe par des contrats SDK génériques tels que plugin-sdk/gateway-runtime, plugin-sdk/security-runtime et plugin-sdk/plugin-config-runtime.

Utilisez l’importation la plus ciblée correspondant à la tâche. Si vous ne trouvez pas une exportation, consultez le code source dans src/plugin-sdk/ ou demandez aux responsables quel contrat générique doit en être propriétaire.

Dépréciations actives

Dépréciations plus ciblées dans le SDK des plugins, le contrat des fournisseurs, la surface d’exécution et le manifeste. Chacune fonctionne encore actuellement, mais sera supprimée dans une prochaine version majeure. Chaque entrée associe l’ancienne API à son remplacement canonique.

// Avantimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Aprèsimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// Avantapi.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // Aprèsapi.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

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

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

// Avantconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Aprèsconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Avantimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Aprèsimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

Migration de Talk et de la voix en temps réel

Le code de voix en temps réel, de téléphonie, de réunion et de Talk dans le navigateur partage un contrôleur de session Talk exporté par openclaw/plugin-sdk/realtime-voice. Le contrôleur possède l’enveloppe commune des événements Talk, l’état du tour actif, l’état de capture, l’état de la sortie audio, l’historique récent des événements et le rejet des tours obsolètes. Les plugins fournisseurs possèdent les sessions en temps réel propres à chaque fournisseur ; les plugins de surface possèdent les particularités de la capture, de la lecture, de la téléphonie et des réunions.

Toutes les surfaces intégrées s’exécutent sur le contrôleur partagé : relais du navigateur, transfert vers une salle gérée, appel vocal en temps réel, reconnaissance vocale en continu pour les appels vocaux, Google Meet en temps réel et mode natif « appuyer pour parler ». Le Gateway annonce un seul canal d’événements Talk en direct dans hello-ok.features.events : talk.event.

Le nouveau code ne doit pas appeler directement createTalkEventSequencer(...), sauf pour implémenter un adaptateur de bas niveau ou un dispositif de test. Utilisez 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 du cycle de vie de la sortie audio restent cohérents entre la téléphonie, les réunions, le relais du navigateur, le transfert vers une salle gérée et les clients Talk natifs.

Forme de l’API publique :

// API de session Talk détenue par le Gateway.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 }); // API de session fournisseur détenue par le client.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/WebSocket fournisseur détenues par le navigateur utilisent talk.client.create, car le navigateur prend en charge la négociation avec le fournisseur et le transport des médias, tandis que le Gateway possède les identifiants, les instructions et la politique des outils. talk.session.* est la surface commune gérée par le Gateway pour le temps réel via relais du Gateway, la transcription via relais du Gateway et les sessions STT/TTS natives en salle gérée.

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

Les combinaisons prises en charge par talk.session.create sont intentionnellement peu nombreuses :

Correspondance des méthodes pour les lecteurs migrant depuis les anciennes familles talk.realtime.* / talk.transcription.* / talk.handoff.* (toutes supprimées) :

Le vocabulaire de contrôle unifié est lui aussi volontairement restreint :

N’introduisez pas de cas particuliers propres à un fournisseur ou à une plateforme dans le cœur pour assurer ce fonctionnement. Le cœur gère la sémantique des sessions Talk. Les plugins de fournisseur gèrent la configuration des sessions propres aux fournisseurs. Voice-call et Google Meet gèrent les adaptateurs de téléphonie et de réunion. Le navigateur et les applications natives gèrent l’expérience utilisateur de capture et de lecture sur l’appareil.

Calendrier de suppression

Tous les plugins du cœur ont déjà été migrés. Les plugins externes doivent migrer avant la prochaine version majeure. Exécutez pnpm plugins:boundary-report pour savoir quelles entrées de compatibilité arriveront le plus tôt à échéance pour les surfaces utilisées par votre plugin.

Suppression temporaire des avertissements

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, et non d’une solution permanente.

Ressources connexes

• Bien démarrer - créez votre premier plugin
• Présentation du SDK - référence complète des importations de sous-chemins
• Plugins de canal - création de plugins de canal
• Plugins de fournisseur - création de plugins de fournisseur
• Fonctionnement interne des plugins - présentation approfondie de l’architecture
• Manifeste de plugin - référence du schéma du manifeste