Migrazione del Plugin SDK

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

# Cosa cambia

Il vecchio sistema 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 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 utility non correlate.
• openclaw/plugin-sdk/config-runtime - un ampio barrel di compatibilità della configurazione che conserva 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 dell'agente incorporato.
• api.registerEmbeddedExtensionFactory(...) - un hook rimosso di estensione in bundle solo per Pi che poteva osservare eventi del runner incorporato 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 major release le rimuova. L'API di registrazione della factory di estensioni incorporate solo per Pi è stata rimossa; usa invece il middleware per i risultati degli strumenti.

OpenClaw non rimuove né reinterpreta un comportamento Plugin documentato nella stessa modifica che introduce un sostituto. Le modifiche che interrompono il contratto devono prima passare attraverso un adattatore di compatibilità, diagnostica, documentazione e una finestra di deprecazione. Questo vale per gli import SDK, i campi del manifest, le API di configurazione, gli hook e il 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 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 state rimosse anche le seam legacy di praticità dei provider per i canali in bundle. Le seam helper con marchio del canale erano scorciatoie private del mono-repo, non contratti Plugin stabili. Usa invece sottopercorsi SDK generici e mirati. 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 conserva gli helper di streaming specifici di Claude nella propria seam api.ts / contract-api.ts
• OpenAI conserva builder di provider, helper per il modello predefinito e builder di provider realtime nel proprio api.ts
• OpenRouter conserva il builder di provider e gli helper di onboarding/configurazione nel proprio api.ts

# Piano di migrazione per Talk e voce realtime

Il codice realtime voice, telefonia, riunioni e browser Talk si sta spostando dalla contabilità dei turni locale alla superficie a un controller condiviso delle sessioni 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 devono continuare a possedere le sessioni realtime specifiche del vendor; i plugin di superficie devono continuare a possedere acquisizione, riproduzione, telefonia e particolarità delle riunioni.

Questa migrazione di Talk è intenzionalmente una rottura pulita:

1. Mantieni le primitive condivise controller/runtime in plugin-sdk/realtime-voice.
2. Sposta le superfici in bundle sul controller condiviso: relay del browser, handoff della stanza gestita, realtime per chiamate vocali, STT in streaming per chiamate vocali, 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 solo canale live di eventi Talk 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 non stia implementando un adattatore di basso livello o una fixture di test. Preferisci il controller condiviso così gli eventi con ambito di turno non possono essere emessi senza un id di turno, le chiamate turnEnd / turnCancel obsolete 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 del browser, handoff della stanza gestita e client Talk nativi.

La forma target dell'API pubblica è:

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

Le sessioni WebRTC/provider-websocket possedute dal browser usano talk.client.create, perché il browser possiede la negoziazione del provider e il trasporto multimediale 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 posizionavano i selettori realtime accanto a talk.provider / talk.providers devono essere riparate con openclaw doctor --fix; il runtime Talk non reinterpreta la configurazione dei provider speech/TTS come configurazione dei provider realtime.

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

Mappa dei metodi rimossi:

Anche il vocabolario di controllo unificato è deliberatamente ristretto:

Non introdurre casi speciali di provider o piattaforma nel core per far funzionare tutto questo. Il core possiede la semantica delle sessioni Talk. I plugin provider possiedono la configurazione delle sessioni vendor. Voice-call e Google Meet possiedono gli adattatori di telefonia/riunione. Browser e app native possiedono l'UX di acquisizione/riproduzione del dispositivo.

# Policy 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 major release

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 singolo plugin o proprietario di compatibilità, e pnpm plugins:boundary-report:ci quando un gate CI deve fallire per 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/documentazione, evidenzia gli import SDK riservati tra proprietari e riepiloga il bridge SDK privato del memory-host, così la pulizia della compatibilità resta esplicita invece di basarsi su 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 del manifest è ancora accettato, gli autori di plugin possono continuare a usarlo finché la documentazione e la diagnostica non indicano diversamente. Il nuovo codice dovrebbe preferire il sostituto documentato, ma i plugin esistenti non dovrebbero rompersi durante normali rilasci minor.

# Come migrare

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

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

{
  "contracts": {
    "agentToolResultMiddleware": ["pi", "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 { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });

// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });

pnpm build
pnpm test -- my-plugin/

# Riferimento dei percorsi di importazione

Questa tabella è intenzionalmente il sottoinsieme comune per la migrazione, non l'intera superficie dell'SDK. L'elenco completo di oltre 200 entrypoint si trova in scripts/lib/plugin-sdk-entrypoints.json.

Le seam helper riservate dei Plugin in bundle sono state ritirate dalla mappa degli export dell'SDK pubblico, fatta eccezione per le facade di compatibilità documentate esplicitamente, 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 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 lavoro. 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'intero SDK dei Plugin, al contratto 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 al suo sostituto canonico.

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

# Timeline di rimozione

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

# Sopprimere temporaneamente gli avvisi

Imposta queste variabili d'ambiente mentre lavori alla migrazione:

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

Questa è una via di fuga temporanea, non una soluzione permanente.

# Correlati

• Introduzione - crea il tuo primo Plugin
• Panoramica dell'SDK - riferimento completo degli import da sottopercorsi
• Plugin di canale - creazione di Plugin di canale
• Plugin provider - creazione di Plugin provider
• Interni dei Plugin - approfondimento sull'architettura
• Manifest dei Plugin - riferimento dello schema manifest