Migration du SDK de Plugin

​

Ce qui a changé

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

​

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.

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

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.

​

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 Codex
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["openclaw", "codex"],
});

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

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

// Après
const 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 build
pnpm test my-plugin/

​

Référence des chemins d’importation

​

Dépréciations actives

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

// Après
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// Avant
api.on("deactivate", async (event, ctx) => {
  await stopPluginService(ctx);
});

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

// Avant
api.on("subagent_spawning", async () => ({
  status: "ok",
  threadBindingReady: true,
  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },
}));

// Après
api.on("subagent_spawned", async (event) => {
  await observeSubagentLaunch(event);
});

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

// Avant
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// Après
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Avant
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// Après
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

​

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

// 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" });

​

Calendrier de suppression

​

Suppression temporaire des avertissements

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

​

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