Migrazione del Plugin SDK

OpenClaw è passato da un ampio livello di compatibilità all’indietro a una moderna architettura a Plugin con import mirati e documentati. Se il tuo Plugin è stato creato prima della nuova architettura, questa guida ti aiuta a migrare.

Cosa cambia

Il vecchio sistema di Plugin forniva due superfici molto aperte che permettevano ai Plugin di importare qualsiasi cosa servisse da un singolo punto di ingresso:

• openclaw/plugin-sdk/compat - un singolo import che riesportava decine di helper. È stato introdotto per mantenere funzionanti i Plugin più vecchi basati su hook mentre veniva costruita la nuova architettura a Plugin.
• openclaw/plugin-sdk/infra-runtime - un ampio barrel di helper runtime che combinava eventi di sistema, stato Heartbeat, code di consegna, helper fetch/proxy, helper per file, tipi di approvazione e utilità non correlate.
• openclaw/plugin-sdk/config-runtime - un ampio barrel di compatibilità per la configurazione che durante la finestra di migrazione contiene ancora helper diretti deprecati per caricamento/scrittura.
• openclaw/extension-api - un bridge che dava ai Plugin accesso diretto a helper lato host come il runner agente incorporato.
• api.registerEmbeddedExtensionFactory(...) - un hook per estensioni in bundle rimosso e riservato all’embedded runner che poteva osservare eventi dell’embedded runner come tool_result.

Le ampie superfici di import sono ora deprecate. Continuano a funzionare a runtime, ma i nuovi Plugin non devono usarle, e i Plugin esistenti dovrebbero migrare prima che la prossima release maggiore le rimuova. L’API di registrazione della factory di estensioni riservata all’embedded runner è stata rimossa; usa invece il middleware per i risultati degli strumenti.

OpenClaw non rimuove né reinterpreta un comportamento documentato dei Plugin nello stesso cambiamento che introduce una sostituzione. Le modifiche che rompono un contratto devono prima passare attraverso un adattatore di compatibilità, diagnostica, documentazione e una finestra di deprecazione. Questo vale per import dell’SDK, campi del manifest, API di setup, hook e comportamento di registrazione runtime.

Perché è cambiato

Il vecchio approccio causava problemi:

• Avvio lento - importare un helper caricava decine di moduli non correlati
• Dipendenze circolari - le ampie riesportazioni rendevano facile creare cicli di import
• Superficie API poco chiara - non c’era modo di distinguere quali export fossero stabili rispetto a quelli interni

Il moderno SDK per Plugin risolve questo problema: ogni percorso di import (openclaw/plugin-sdk/\<subpath\>) è un modulo piccolo e autonomo con uno scopo chiaro e un contratto documentato.

Sono sparite anche le vecchie cuciture di comodità per provider per i canali in bundle. Le cuciture helper brandizzate per canale erano scorciatoie private del monorepo, non contratti stabili per Plugin. Usa invece sottopercorsi SDK generici e ristretti. All’interno del workspace dei Plugin in bundle, mantieni gli helper di proprietà del provider nel suo api.ts o runtime-api.ts.

Esempi attuali di provider in bundle:

• Anthropic mantiene gli helper di stream specifici per Claude nella propria cucitura api.ts / contract-api.ts
• OpenAI mantiene provider builder, helper per modello predefinito e builder per provider realtime nel proprio api.ts
• OpenRouter mantiene provider builder e helper di onboarding/configurazione nel proprio api.ts

Piano di migrazione per Talk e voce realtime

Il codice Talk per voce realtime, telefonia, riunioni e browser sta passando dalla contabilità dei turni locale alla superficie a un controller di sessione Talk condiviso esportato da openclaw/plugin-sdk/realtime-voice. Il nuovo controller possiede l’envelope comune degli eventi Talk, lo stato del turno attivo, lo stato di cattura, lo stato dell’audio in uscita, la cronologia recente degli eventi e il rifiuto dei turni obsoleti. I Plugin provider dovrebbero continuare a possedere le sessioni realtime specifiche del vendor; i Plugin di superficie dovrebbero continuare a possedere cattura, riproduzione, telefonia e particolarità delle riunioni.

Questa migrazione di Talk è intenzionalmente breaking-clean:

1. Mantieni le primitive condivise di controller/runtime in plugin-sdk/realtime-voice.
2. Sposta le superfici in bundle sul controller condiviso: relay browser, handoff managed-room, realtime voice-call, STT streaming voice-call, realtime Google Meet e push-to-talk nativo.
3. Sostituisci le vecchie famiglie RPC Talk con l’API finale talk.session.* e talk.client.*.
4. Pubblicizza un solo canale di eventi Talk live in Gateway hello-ok.features.events: talk.event.
5. Elimina il vecchio endpoint HTTP realtime e qualsiasi percorso di override delle istruzioni al momento della richiesta.

Il nuovo codice non dovrebbe chiamare direttamente createTalkEventSequencer(...) a meno che stia implementando un adapter di basso livello o una fixture di test. Preferisci il controller condiviso così gli eventi con scope di turno non possono essere emessi senza un id di turno, le chiamate obsolete turnEnd / turnCancel non possono cancellare un turno attivo più recente, e gli eventi del ciclo di vita dell’audio in uscita restano coerenti tra telefonia, riunioni, relay browser, handoff managed-room e client Talk nativi.

La forma dell’API pubblica target è:

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

Le sessioni WebRTC/provider-websocket di proprietà del browser usano talk.client.create, perché il browser possiede la negoziazione del provider e il trasporto dei media mentre il Gateway possiede credenziali, istruzioni e policy degli strumenti. talk.session.* è la superficie comune gestita dal Gateway per realtime gateway-relay, trascrizione gateway-relay e sessioni STT/TTS native managed-room.

Le configurazioni legacy che collocavano i selettori realtime accanto a talk.provider / talk.providers dovrebbero essere riparate con openclaw doctor --fix; a runtime Talk non reinterpreta la configurazione provider speech/TTS come configurazione provider realtime.

Le combinazioni supportate di talk.session.create sono intenzionalmente poche:

Mappa dei metodi rimossi:

Anche il vocabolario di controllo unificato è deliberatamente ristretto:

Non introdurre casi speciali per provider o piattaforma nel core per farlo funzionare. Il core possiede la semantica delle sessioni Talk. I Plugin provider possiedono la configurazione delle sessioni vendor. Le chiamate vocali e Google Meet possiedono gli adattatori di telefonia/riunione. Browser e app native possiedono l'UX di acquisizione/riproduzione del dispositivo.

Criterio di compatibilità

Per i Plugin esterni, il lavoro di compatibilità segue questo ordine:

1. aggiungere il nuovo contratto
2. mantenere il vecchio comportamento collegato tramite un adattatore di compatibilità
3. emettere una diagnostica o un avviso che nomini il vecchio percorso e il sostituto
4. coprire entrambi i percorsi nei test
5. documentare la deprecazione e il percorso di migrazione
6. rimuovere solo dopo la finestra di migrazione annunciata, di solito in una release principale

I manutentori possono verificare la coda di migrazione corrente con pnpm plugins:boundary-report. Usa pnpm plugins:boundary-report:summary per conteggi compatti, --owner <id> per un Plugin o proprietario della compatibilità, e pnpm plugins:boundary-report:ci quando un gate CI deve fallire su record di compatibilità scaduti, import SDK riservati tra proprietari o sottopercorsi SDK riservati non usati. Il report raggruppa i record di compatibilità deprecati per data di rimozione, conta i riferimenti locali di codice/documentazione, espone gli import SDK riservati tra proprietari e riepiloga il bridge SDK privato memory-host, così la pulizia della compatibilità rimane esplicita invece di dipendere da ricerche ad hoc. I sottopercorsi SDK riservati devono avere utilizzo del proprietario tracciato; gli export helper riservati inutilizzati devono essere rimossi dall'SDK pubblico.

Se un campo del manifest è ancora accettato, gli autori di Plugin possono continuare a usarlo finché documentazione e diagnostica non indicano diversamente. Il nuovo codice dovrebbe preferire il sostituto documentato, ma i Plugin esistenti non dovrebbero rompersi durante le normali release minori.

Come migrare

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

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

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

pnpm buildpnpm test -- my-plugin/

Riferimento dei percorsi di importazione

Questa tabella è intenzionalmente il sottoinsieme comune per la migrazione, non l'intera superficie dell'SDK. L'inventario degli entrypoint del compilatore si trova in scripts/lib/plugin-sdk-entrypoints.json; gli export dei pacchetti vengono generati dal sottoinsieme pubblico.

Le seam helper riservate dei plugin in bundle sono state ritirate dalla mappa degli export dell'SDK pubblico, tranne le facade di compatibilità documentate esplicitamente come lo shim deprecato plugin-sdk/discord mantenuto per il pacchetto pubblicato @openclaw/discord@2026.3.13. Gli helper specifici del proprietario risiedono nel pacchetto del plugin proprietario; il comportamento host condiviso dovrebbe passare attraverso contratti SDK generici come plugin-sdk/gateway-runtime, plugin-sdk/security-runtime e plugin-sdk/plugin-config-runtime.

Usa l'import più ristretto adatto al compito. Se non riesci a trovare un export, controlla il sorgente in src/plugin-sdk/ o chiedi ai maintainer quale contratto generico dovrebbe possederlo.

Deprecazioni attive

Deprecazioni più ristrette che si applicano a tutto l'SDK dei plugin, al contratto dei provider, alla superficie runtime e al manifest. Ognuna funziona ancora oggi, ma sarà rimossa in una futura release major. La voce sotto ogni elemento mappa la vecchia API alla sua sostituzione canonica.

// Beforeimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Afterimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// Beforeapi.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // Afterapi.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

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

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

Tempistica di rimozione

Tutti i plugin core sono già stati migrati. I plugin esterni devono migrare prima della prossima major release.

Sopprimere temporaneamente gli avvisi

Imposta queste variabili d'ambiente mentre lavori alla migrazione:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

Questo è un meccanismo temporaneo di uscita, non una soluzione permanente.

Correlati

• Per iniziare - crea il tuo primo plugin
• Panoramica dell'SDK - riferimento completo agli import dei sottopercorsi
• Plugin di canale - creare plugin di canale
• Plugin provider - creare plugin provider
• Internals dei Plugin - approfondimento sull'architettura
• Manifest del Plugin - riferimento dello schema del manifest