Migration du SDK Plugin

​

Ce qui change

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

​

Pourquoi cela a changé

• 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

• 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

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.

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

​

Politique de compatibilité

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

​

Comment migrer

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

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

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

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

// After
const 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 build
pnpm test -- my-plugin/

​

Référence des chemins d’importation

​

Dépréciations actives

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

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

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

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

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

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

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

​

Suppression temporaire des avertissements

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

​

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