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é créé 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 seul point d’entrée :

• openclaw/plugin-sdk/compat - un import unique qui réexportait des dizaines de helpers. Il a été introduit pour maintenir le fonctionnement des anciens plugins basés sur des hooks pendant la construction de la nouvelle architecture de plugins.
• openclaw/plugin-sdk/infra-runtime - un large barrel de helpers d’exécution qui mélangeait événements système, état de Heartbeat, files de livraison, helpers fetch/proxy, helpers 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 helpers directs de chargement/écriture obsolètes pendant la fenêtre de migration.
• openclaw/extension-api - un pont qui donnait aux plugins un accès direct aux helpers côté hôte, comme le runner d’agent intégré.
• api.registerEmbeddedExtensionFactory(...) - un hook d’extension groupée, réservé à Pi et supprimé, qui pouvait observer les événements du runner intégré comme tool_result.

Les surfaces d’import larges sont maintenant obsolètes. 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 intégrée réservée à Pi a été supprimée ; utilisez plutôt un middleware de résultats d’outils.

OpenClaw ne supprime ni ne réinterprète un comportement de plugin documenté dans le même changement qui introduit son 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, 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 un seul helper 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 savoir quels exports étaient stables ou internes

Le SDK de plugins 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 anciens points de convenance de fournisseurs pour les canaux groupés ont également disparu. Les points de helpers marqués par canal étaient des raccourcis privés de mono-repo, pas des contrats de plugins stables. Utilisez plutôt des sous-chemins SDK génériques et ciblés. Dans l’espace de travail des plugins groupés, conservez les helpers appartenant au fournisseur dans le api.ts ou le runtime-api.ts propre à ce plugin.

Exemples actuels de fournisseurs groupés :

• Anthropic conserve les helpers de flux propres à Claude dans son propre point api.ts / contract-api.ts
• OpenAI conserve les builders de fournisseur, les helpers de modèle par défaut et les builders de fournisseur realtime dans son propre api.ts
• OpenRouter conserve le builder de fournisseur et les helpers d’onboarding/configuration dans son propre api.ts

# Plan de migration Talk et voix realtime

Le code Talk pour la voix realtime, la téléphonie, les réunions et le navigateur passe d’un suivi des tours local à 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 d’événement Talk, l’état du tour actif, l’état de capture, l’état de sortie audio, l’historique récent des événements et le rejet des tours périmés. Les plugins de fournisseurs doivent continuer à posséder les sessions realtime propres aux vendeurs ; 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 incompatible de façon nette :

1. Conserver les primitives partagées de contrôleur/runtime dans plugin-sdk/realtime-voice.
2. Déplacer les surfaces groupées vers le contrôleur partagé : relais navigateur, transfert de salle gérée, realtime d’appel vocal, STT en streaming d’appel vocal, Google Meet realtime 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 live dans hello-ok.features.events du Gateway : talk.event.
5. Supprimer l’ancien endpoint HTTP realtime et tout chemin de surcharge d’instructions au moment de la requête.

Le nouveau code ne doit pas appeler directement createTalkEventSequencer(...), 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 périmés 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 téléphonie, réunions, relais navigateur, transfert de salle gérée et 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 });
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 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 les sessions realtime gateway-relay, de transcription gateway-relay, et STT/TTS natives en salle gérée.

Les configurations héritées qui plaçaient les sélecteurs realtime à 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 configuration de fournisseur realtime.

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

Table de correspondance des méthodes supprimées :

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

N’introduisez pas de cas particuliers de fournisseur ou de plateforme dans le noyau pour faire fonctionner cela. Le noyau possède la sémantique des sessions Talk. Les plugins de fournisseurs possèdent la configuration des sessions vendeur. Voice-call et Google Meet possèdent les adaptateurs téléphonie/réunion. Les applications navigateur et natives possèdent l’UX 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 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 la dépréciation 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 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 regroupe les enregistrements de compatibilité obsolètes par date de suppression, compte les références locales dans le code et la documentation, expose 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 reposer sur des recherches ad hoc. 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 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 préférer le remplacement documenté, mais les plugins existants ne doivent pas casser lors des versions mineures ordinaires.

# Comment migrer

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

// Pi et outils dynamiques de l’exécution Codex
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["pi", "codex"],
});

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

// Avant
const program = applyWindowsSpawnProgramPolicy({ candidate });

// Après
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // Ne définissez ceci que pour les appelants de compatibilité fiables qui acceptent
  // intentionnellement un fallback médié par 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 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 { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });

// Après (exécution injectée)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });

pnpm build
pnpm test -- my-plugin/

# Référence des chemins d’importation

Ce tableau constitue intentionnellement le sous-ensemble commun de migration, pas la surface complète du SDK. La liste complète des plus de 200 points d’entrée se trouve dans scripts/lib/plugin-sdk-entrypoints.json.

Les points d’extension d’aide réservés aux plugins intégrés ont été retirés de la carte d’export du SDK public, à l’exception des façades de compatibilité explicitement documentées, comme le shim obsolète plugin-sdk/discord conservé pour le paquet publié @openclaw/[email protected]. 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 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 propriétaire.

# Dépréciations actives

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

// Before
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// After
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

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

// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import 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 à la migration :

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

Il s’agit d’une échappatoire temporaire, pas d’une solution permanente.

# Connexe

• Bien démarrer - créez votre premier Plugin
• Vue d’ensemble du SDK - référence complète des imports de sous-chemins
• Plugins de canal - créer des plugins de canal
• Plugins fournisseurs - créer des plugins fournisseurs
• Internes des plugins - plongée approfondie dans l’architecture
• Manifeste de Plugin - référence du schéma de manifeste