Migration du SDK Plugin

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

Ce qui change

L’ancien système de plugins 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’aides. Il a été introduit pour maintenir le fonctionnement des anciens plugins basés sur des hooks pendant que la nouvelle architecture de plugins était en cours de construction.
• openclaw/plugin-sdk/infra-runtime - un large barrel d’aides d’exécution qui mélangeait événements système, état Heartbeat, files de livraison, aides fetch/proxy, aides 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 aides directes de chargement/écriture dépréciées pendant la fenêtre de migration.
• openclaw/extension-api - une passerelle qui donnait aux plugins un accès direct à des aides côté hôte comme le runner d’agent intégré.
• api.registerEmbeddedExtensionFactory(...) - un hook d’extension intégrée réservé à Pi et supprimé qui pouvait observer les événements du runner intégré tels que tool_result.

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

OpenClaw ne supprime pas et ne réinterprète pas un comportement de plugin documenté dans le même changement qui introduit un remplacement. Les changements de contrat cassants 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, aux champs de manifeste, aux API de configuration, aux hooks et au comportement d’enregistrement à l’exécution.

Pourquoi ce changement

L’ancienne approche posait des problèmes :

• Démarrage lent - importer une aide chargeait des dizaines de modules sans rapport
• Dépendances circulaires - les réexportations 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 avec un objectif clair et un contrat documenté.

Les anciennes interfaces de commodité fournisseur pour les canaux inclus ont également disparu. Les interfaces d’aide marquées par canal étaient des raccourcis privés de mono-repo, pas des contrats de plugin stables. Utilisez plutôt des sous-chemins SDK génériques étroits. Dans l’espace de travail des plugins inclus, conservez les aides appartenant au fournisseur dans le api.ts ou runtime-api.ts propre à ce plugin.

Exemples actuels de fournisseurs inclus :

• Anthropic conserve les aides de flux spécifiques à Claude dans sa propre interface api.ts / contract-api.ts
• OpenAI conserve les builders de fournisseur, les aides de modèle par défaut et les builders de fournisseur temps réel dans son propre api.ts
• OpenRouter conserve les aides de builder de fournisseur et d’onboarding/configuration dans son propre api.ts

Plan de migration Talk et voix temps réel

Le code de voix temps réel, téléphonie, réunion et Talk dans le navigateur passe d’une tenue de comptabilité des tours locale à la surface vers un contrôleur de session Talk partagé exporté par openclaw/plugin-sdk/realtime-voice. Le nouveau contrôleur possède l’enveloppe d’événements Talk commune, l’état de tour actif, l’état de capture, l’état d’audio de sortie, 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 vendeur ; 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 cassante et propre :

1. Conserver les primitives partagées de contrôleur/runtime dans plugin-sdk/realtime-voice.
2. Migrer les surfaces incluses vers le contrôleur partagé : relais navigateur, handoff 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 canal d’événements Talk en direct unique dans hello-ok.features.events du Gateway : talk.event.
5. Supprimer l’ancien endpoint HTTP temps réel et tout chemin de surcharge d’instructions au moment de la requête.

Le nouveau code ne doit pas appeler createTalkEventSequencer(...) directement sauf s’il implémente un adaptateur de bas niveau ou une fixture de test. Préférez le contrôleur partagé afin que les événements bornés au tour ne puissent pas être émis sans id 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 d’audio de sortie restent cohérents entre la téléphonie, les réunions, le relais navigateur, le handoff 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 });

Les sessions WebRTC/websocket fournisseur possédées par le 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 les sessions temps réel gateway-relay, de transcription gateway-relay et STT/TTS natives de salle gérée.

Les configurations héritées 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 ; Talk à l’exécution ne réinterprète pas la configuration de fournisseur speech/TTS comme une configuration de fournisseur temps réel.

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

Carte des méthodes supprimées :

Le vocabulaire de contrôle unifié est également délibérément étroit :

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

Politique de compatibilité

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

1. ajouter le nouveau contrat
2. conserver l’ancien comportement raccordé 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 décomptes compacts, --owner <id> pour un plugin ou un 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 inter-propriétaires, ou des sous-chemins SDK réservés inutilisés. Le rapport regroupe les enregistrements de compatibilité obsolètes par date de suppression, compte les références locales dans le code/la documentation, fait remonter les imports SDK réservés inter-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 ad hoc. Les sous-chemins SDK réservés doivent avoir une utilisation propriétaire suivie ; les exports d’assistants réservés inutilisés doivent être supprimés du SDK public.

Si un champ de manifeste est encore accepté, les auteurs de plugins peuvent continuer à l’utiliser jusqu’à ce que la documentation et les diagnostics indiquent le contraire. Le nouveau code doit privilégier 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 ??= {};  },});

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

{  "contracts": {    "agentToolResultMiddleware": ["pi", "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 { runEmbeddedPiAgent } from "openclaw/extension-api";const result = await runEmbeddedPiAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

Référence des chemins d’importation

Ce tableau correspond volontairement au 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’aide réservés aux plugins groupés ont été retirés de la carte d’exports du SDK public, à l’exception des façades de compatibilité explicitement documentées, comme le shim déprécié plugin-sdk/discord conservé pour le paquet publié @openclaw/[email protected]. Les aides 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 tels que plugin-sdk/gateway-runtime, plugin-sdk/security-runtime et plugin-sdk/plugin-config-runtime.

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

Dépréciations actives

Dépréciations plus ciblées qui s’appliquent au SDK de plugins, 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";

{  "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.

Supprimer temporairement les avertissements

Définissez ces variables d’environnement pendant que vous travaillez à 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 échappatoire temporaire, pas d’une solution permanente.

Liens connexes

• Bien démarrer - créer votre premier plugin
• Vue d’ensemble du SDK - référence complète des imports par sous-chemin
• Plugins de canaux - créer des plugins de canaux
• Plugins fournisseurs - créer des plugins fournisseurs
• Internes des plugins - exploration approfondie de l’architecture
• Manifeste de plugin - référence du schéma de manifeste