Migrazione del Plugin SDK

OpenClaw è passato da un ampio livello di compatibilità retroattiva a una moderna architettura a plugin con import focalizzati e documentati. Se il tuo plugin è stato creato prima della nuova architettura, questa guida ti aiuta a migrarlo.

Cosa cambia

Il vecchio sistema di plugin forniva due superfici molto aperte che consentivano ai plugin di importare tutto ciò di cui avevano bisogno da un unico 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 mescolava eventi di sistema, stato Heartbeat, code di consegna, helper fetch/proxy, helper per file, tipi di approvazione e utility non correlate.
• openclaw/plugin-sdk/config-runtime - un ampio barrel di compatibilità della configurazione che contiene ancora helper diretti di caricamento/scrittura deprecati durante la finestra di migrazione.
• openclaw/extension-api - un bridge che forniva ai plugin accesso diretto agli helper lato host, come il runner agente incorporato.
• api.registerEmbeddedExtensionFactory(...) - un hook di estensione in bundle solo per Pi rimosso che poteva osservare eventi dell'embedded-runner come tool_result.

Le ampie superfici di import sono ora deprecate. Funzionano ancora a runtime, ma i nuovi plugin non devono usarle, e i plugin esistenti dovrebbero migrare prima che la prossima release major le rimuova. L'API di registrazione dell'embedded extension factory solo per Pi è stata rimossa; usa invece il middleware dei risultati degli strumenti.

OpenClaw non rimuove né reinterpreta il comportamento documentato dei plugin nello stesso cambiamento che introduce un sostituto. Le modifiche incompatibili al contratto devono prima passare attraverso un adapter di compatibilità, diagnostica, documentazione e una finestra di deprecazione. Questo vale per import 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 capire quali export fossero stabili e quali interni

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

Anche le seam legacy di comodità dei provider per i canali in bundle sono state rimosse. Le seam helper brandizzate per canale erano scorciatoie private del mono-repo, 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 api.ts o runtime-api.ts del plugin stesso.

Esempi attuali di provider in bundle:

• Anthropic mantiene gli helper di stream specifici per Claude nella propria seam api.ts / contract-api.ts
• OpenAI mantiene provider builder, helper per modelli predefiniti e builder di 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 si sta spostando dalla contabilità dei turni locale alla superficie a un controller condiviso di sessione Talk 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 acquisizione, 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 acquisizione, riproduzione, telefonia e particolarità delle riunioni.

Questa migrazione di Talk è intenzionalmente incompatibile e pulita:

1. Mantieni le primitive condivise di controller/runtime in plugin-sdk/realtime-voice.
2. Sposta le superfici in bundle sul controller condiviso: browser relay, handoff managed-room, voice-call realtime, voice-call streaming STT, Google Meet realtime e push-to-talk nativo.
3. Sostituisci le vecchie famiglie RPC di Talk con l'API finale talk.session.* e talk.client.*.
4. Pubblicizza un unico 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(...), salvo 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, browser relay, 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 });

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

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

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

Mappa dei metodi rimossi:

Anche il vocabolario di controllo unificato è deliberatamente ristretto:

Non introdurre casi speciali per provider o piattaforme nel core per far funzionare questo. Il core possiede la semantica delle sessioni Talk. I Plugin provider possiedono la configurazione delle sessioni dei vendor. Le chiamate vocali e Google Meet possiedono gli adattatori di telefonia/riunione. Browser e app native possiedono l'esperienza utente 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 indichi 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 major

I maintainer 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 un proprietario di 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 inutilizzati. Il report raggruppa i record di compatibilità deprecati per data di rimozione, conta i riferimenti locali in codice/docs, evidenzia gli import SDK riservati tra proprietari e riassume il bridge SDK privato dell'host di memoria, così la pulizia della compatibilità resta esplicita invece di affidarsi a ricerche ad hoc. I sottopercorsi SDK riservati devono avere un uso del proprietario tracciato; gli export di helper riservati inutilizzati devono essere rimossi dall'SDK pubblico.

Se un campo manifest è ancora accettato, gli autori di Plugin possono continuare a usarlo finché la documentazione e le diagnostiche non dicono altrimenti. Il nuovo codice dovrebbe preferire il sostituto documentato, ma i Plugin esistenti non dovrebbero rompersi durante le normali release minor.

Come migrare

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/

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 sono generati dal sottoinsieme pubblico.

I seam helper riservati dei plugin in bundle sono stati rimossi dalla mappa degli export dell'SDK pubblico, tranne per le facade di compatibilità esplicitamente documentate come lo shim deprecato plugin-sdk/discord mantenuto per il pacchetto pubblicato @openclaw/[email protected]. Gli helper specifici del proprietario vivono all'interno del 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 che corrisponde al compito. Se non riesci a trovare un export, controlla il sorgente in src/plugin-sdk/ oppure chiedi ai maintainer quale contratto generico dovrebbe possederlo.

Deprecazioni attive

Deprecazioni più ristrette che si applicano all'SDK dei plugin, al contratto provider, alla superficie runtime e al manifesto. 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";

{  "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 dovrebbero migrare prima della prossima release major.

Soppressione temporanea degli 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

Questa è una via d'uscita temporanea, non una soluzione permanente.

Correlati

• Per iniziare - crea il tuo primo plugin
• Panoramica dell'SDK - riferimento completo agli import da subpath
• Plugin di canale - creazione di plugin di canale
• Plugin provider - creazione di plugin provider
• Interni dei plugin - approfondimento sull'architettura
• Manifesto del plugin - riferimento dello schema del manifesto