Migrazione al Plugin SDK

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

Cosa sta cambiando

Il vecchio sistema dei plugin forniva due superfici molto ampie che permettevano 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 vecchi plugin basati su hook mentre veniva sviluppata la nuova architettura dei plugin.
openclaw/extension-api — un bridge che forniva ai plugin accesso diretto agli helper lato host, come l’embedded agent runner.

Entrambe le superfici sono ora deprecate. Continuano a funzionare in fase di runtime, ma i nuovi plugin non devono usarle e i plugin esistenti dovrebbero migrare prima che la prossima major release le rimuova.

Il livello di retrocompatibilità verrà rimosso in una futura major release. I plugin che importano ancora da queste superfici smetteranno di funzionare quando ciò accadrà.

Perché è cambiato

Il vecchio approccio causava problemi:

Avvio lento — importare un helper caricava decine di moduli non correlati
Dipendenze circolari — le riesportazioni ampie 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 Plugin SDK risolve questo problema: ogni percorso di import (openclaw/plugin-sdk/\<subpath\>) è un modulo piccolo e autonomo con uno scopo chiaro e un contratto documentato. Anche i legacy provider convenience seams per i canali bundled non esistono più. Import come openclaw/plugin-sdk/slack, openclaw/plugin-sdk/discord, openclaw/plugin-sdk/signal, openclaw/plugin-sdk/whatsapp, i channel-branded helper seams e openclaw/plugin-sdk/telegram-core erano scorciatoie private del mono-repo, non contratti stabili per i plugin. Usa invece subpath generici e mirati del SDK. All’interno del workspace dei plugin bundled, mantieni gli helper del provider nel file api.ts o runtime-api.ts di quel plugin. Esempi attuali di provider bundled:

Anthropic mantiene gli helper di stream specifici per Claude nel proprio seam api.ts / contract-api.ts
OpenAI mantiene i builder del provider, gli helper per il modello predefinito e i builder del provider realtime nel proprio api.ts
OpenRouter mantiene il builder del provider e gli helper di onboarding/config nel proprio api.ts

Come effettuare la migrazione

Migra gli handler approval-native ai capability facts

I plugin di canale con capacità di approvazione ora espongono il comportamento di approvazione nativo tramite approvalCapability.nativeRuntime insieme al registro condiviso del contesto runtime.Modifiche principali:

Sostituisci approvalCapability.handler.loadRuntime(...) con approvalCapability.nativeRuntime
Sposta auth/delivery specifici per l’approvazione dal legacy wiring plugin.auth / plugin.approvals a approvalCapability
ChannelPlugin.approvals è stato rimosso dal contratto pubblico del channel-plugin; sposta i campi delivery/native/render su approvalCapability
plugin.auth rimane solo per i flussi di login/logout del canale; gli hook di auth per l’approvazione presenti lì non vengono più letti dal core
Registra gli oggetti runtime posseduti dal canale, come client, token o app Bolt, tramite openclaw/plugin-sdk/channel-runtime-context
Non inviare avvisi di reindirizzamento posseduti dal plugin dagli handler di approvazione nativi; il core ora gestisce gli avvisi instradati altrove a partire dai risultati di delivery reali
Quando passi channelRuntime a createChannelManager(...), fornisci una vera superficie createPluginRuntime().channel. Gli stub parziali vengono rifiutati.

Vedi /plugins/sdk-channel-plugins per il layout corrente della capability di approvazione.

Verifica il comportamento di fallback del wrapper Windows

Se il tuo plugin usa openclaw/plugin-sdk/windows-spawn, i wrapper Windows .cmd/.bat non risolti ora falliscono in modo chiuso a meno che tu non passi esplicitamente allowShellFallback: true.

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

Se il tuo chiamante non dipende intenzionalmente dal fallback della shell, non impostare allowShellFallback e gestisci invece l’errore generato.

Trova gli import deprecati

Cerca nel tuo plugin gli import da una delle due superfici deprecate:

grep -r "plugin-sdk/compat" my-plugin/
grep -r "openclaw/extension-api" my-plugin/

Sostituisci con import focalizzati

Ogni export della vecchia superficie corrisponde a uno specifico percorso di import moderno:

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

Per gli helper lato host, usa invece il runtime del plugin iniettato invece di importare direttamente:

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

Lo stesso schema si applica agli altri helper legacy del bridge:

Vecchio import	Equivalente moderno
`resolveAgentDir`	`api.runtime.agent.resolveAgentDir`
`resolveAgentWorkspaceDir`	`api.runtime.agent.resolveAgentWorkspaceDir`
`resolveAgentIdentity`	`api.runtime.agent.resolveAgentIdentity`
`resolveThinkingDefault`	`api.runtime.agent.resolveThinkingDefault`
`resolveAgentTimeoutMs`	`api.runtime.agent.resolveAgentTimeoutMs`
`ensureAgentWorkspace`	`api.runtime.agent.ensureAgentWorkspace`
helper del session store	`api.runtime.agent.session.*`

Compila ed esegui i test

pnpm build
pnpm test -- my-plugin/

Riferimento ai percorsi di import

Tabella comune dei percorsi di import

Percorso di import	Scopo	Export principali
`plugin-sdk/plugin-entry`	Helper canonico per l’entry del plugin	`definePluginEntry`
`plugin-sdk/core`	Riesportazione legacy ombrello per definizioni/builder di entry dei canali	`defineChannelPluginEntry`, `createChatChannelPlugin`
`plugin-sdk/config-schema`	Export dello schema di configurazione root	`OpenClawSchema`
`plugin-sdk/provider-entry`	Helper per entry con provider singolo	`defineSingleProviderPluginEntry`
`plugin-sdk/channel-core`	Definizioni e builder focalizzati per le entry dei canali	`defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`
`plugin-sdk/setup`	Helper condivisi per la procedura guidata di setup	Prompt di allowlist, builder dello stato di setup
`plugin-sdk/setup-runtime`	Helper runtime per il setup	Adapter di patch setup import-safe, helper per note di lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, proxy di setup delegati
`plugin-sdk/setup-adapter-runtime`	Helper per adapter di setup	`createEnvPatchedAccountSetupAdapter`
`plugin-sdk/setup-tools`	Helper per gli strumenti di setup	`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`
`plugin-sdk/account-core`	Helper multi-account	Helper per elenco/configurazione/gate delle azioni degli account
`plugin-sdk/account-id`	Helper per account-id	`DEFAULT_ACCOUNT_ID`, normalizzazione di account-id
`plugin-sdk/account-resolution`	Helper per la ricerca degli account	Helper per la ricerca degli account + fallback predefinito
`plugin-sdk/account-helpers`	Helper mirati per account	Helper per elenco account/azioni sugli account
`plugin-sdk/channel-setup`	Adapter per la procedura guidata di setup	`createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, più `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries`
`plugin-sdk/channel-pairing`	Primitive di pairing DM	`createChannelPairingController`
`plugin-sdk/channel-reply-pipeline`	Wiring per prefisso della risposta + digitazione	`createChannelReplyPipeline`
`plugin-sdk/channel-config-helpers`	Factory per adapter di configurazione	`createHybridChannelConfigAdapter`
`plugin-sdk/channel-config-schema`	Builder dello schema di configurazione	Tipi dello schema di configurazione del canale
`plugin-sdk/telegram-command-config`	Helper per la configurazione dei comandi Telegram	Normalizzazione del nome del comando, trimming della descrizione, validazione di duplicati/conflitti
`plugin-sdk/channel-policy`	Risoluzione delle policy per gruppi/DM	`resolveChannelGroupRequireMention`
`plugin-sdk/channel-lifecycle`	Tracciamento dello stato dell’account	`createAccountStatusSink`
`plugin-sdk/inbound-envelope`	Helper per inbound envelope	Helper condivisi per route + builder di envelope
`plugin-sdk/inbound-reply-dispatch`	Helper per le risposte in ingresso	Helper condivisi per registrazione e dispatch
`plugin-sdk/messaging-targets`	Parsing dei target di messaggistica	Helper per parsing/matching dei target
`plugin-sdk/outbound-media`	Helper per media in uscita	Caricamento condiviso dei media in uscita
`plugin-sdk/outbound-runtime`	Helper runtime per l’uscita	Helper per identità in uscita/delegati di invio
`plugin-sdk/thread-bindings-runtime`	Helper per thread-binding	Helper per ciclo di vita dei thread-binding e adapter
`plugin-sdk/agent-media-payload`	Helper legacy per payload media	Builder del payload media dell’agente per layout legacy dei campi
`plugin-sdk/channel-runtime`	Shim di compatibilità deprecato	Solo utility legacy per il runtime del canale
`plugin-sdk/channel-send-result`	Tipi del risultato di invio	Tipi del risultato di risposta
`plugin-sdk/runtime-store`	Storage persistente del plugin	`createPluginRuntimeStore`
`plugin-sdk/runtime`	Helper runtime ampi	Helper per runtime/logging/backup/installazione plugin
`plugin-sdk/runtime-env`	Helper mirati per runtime env	Logger/runtime env, helper per timeout, retry e backoff
`plugin-sdk/plugin-runtime`	Helper runtime condivisi del plugin	Helper per comandi/hook/http/interattivi del plugin
`plugin-sdk/hook-runtime`	Helper per la pipeline degli hook	Helper condivisi per pipeline di webhook/hook interni
`plugin-sdk/lazy-runtime`	Helper per runtime lazy	`createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface`
`plugin-sdk/process-runtime`	Helper di processo	Helper condivisi per exec
`plugin-sdk/cli-runtime`	Helper runtime per CLI	Formattazione dei comandi, attese, helper per versione
`plugin-sdk/gateway-runtime`	Helper per Gateway	Client Gateway e helper per patch dello stato dei canali
`plugin-sdk/config-runtime`	Helper di configurazione	Helper per caricamento/scrittura della configurazione
`plugin-sdk/telegram-command-config`	Helper per comandi Telegram	Helper di validazione dei comandi Telegram stabili con fallback quando la superficie contrattuale del Telegram bundled non è disponibile
`plugin-sdk/approval-runtime`	Helper per prompt di approvazione	Payload di approvazione exec/plugin, helper per capability/profilo di approvazione, helper runtime/routing di approvazione nativa
`plugin-sdk/approval-auth-runtime`	Helper di auth per l’approvazione	Risoluzione degli approvatori, auth delle azioni nella stessa chat
`plugin-sdk/approval-client-runtime`	Helper client per l’approvazione	Helper per profili/filtri di approvazione exec nativa
`plugin-sdk/approval-delivery-runtime`	Helper di delivery per l’approvazione	Adapter per capability/delivery di approvazione nativa
`plugin-sdk/approval-gateway-runtime`	Helper Gateway per l’approvazione	Helper condiviso per la risoluzione del Gateway di approvazione
`plugin-sdk/approval-handler-adapter-runtime`	Helper per adapter di approvazione	Helper leggeri per il caricamento di adapter di approvazione nativa per entrypoint hot dei canali
`plugin-sdk/approval-handler-runtime`	Helper per handler di approvazione	Helper runtime più ampi per handler di approvazione; preferisci i seam adapter/gateway più mirati quando sono sufficienti
`plugin-sdk/approval-native-runtime`	Helper per target di approvazione	Helper per binding tra target/account di approvazione nativa
`plugin-sdk/approval-reply-runtime`	Helper per risposte di approvazione	Helper per payload di risposta di approvazione exec/plugin
`plugin-sdk/channel-runtime-context`	Helper per il contesto runtime del canale	Helper generici per register/get/watch del contesto runtime del canale
`plugin-sdk/security-runtime`	Helper di sicurezza	Helper condivisi per trust, gating DM, contenuti esterni e raccolta di secret
`plugin-sdk/ssrf-policy`	Helper per policy SSRF	Helper per allowlist degli host e policy di rete privata
`plugin-sdk/ssrf-runtime`	Helper runtime SSRF	Helper per pinned-dispatcher, fetch protetto e policy SSRF
`plugin-sdk/collection-runtime`	Helper per cache limitata	`pruneMapToMaxSize`
`plugin-sdk/diagnostic-runtime`	Helper per il gating diagnostico	`isDiagnosticFlagEnabled`, `isDiagnosticsEnabled`
`plugin-sdk/error-runtime`	Helper per la formattazione degli errori	`formatUncaughtError`, `isApprovalNotFoundError`, helper del grafo degli errori
`plugin-sdk/fetch-runtime`	Helper per fetch/proxy wrapperizzati	`resolveFetch`, helper per proxy
`plugin-sdk/host-runtime`	Helper per la normalizzazione dell’host	`normalizeHostname`, `normalizeScpRemoteHost`
`plugin-sdk/retry-runtime`	Helper per retry	`RetryConfig`, `retryAsync`, esecutori di policy
`plugin-sdk/allow-from`	Formattazione dell’allowlist	`formatAllowFromLowercase`
`plugin-sdk/allowlist-resolution`	Mappatura degli input dell’allowlist	`mapAllowlistResolutionInputs`
`plugin-sdk/command-auth`	Gating dei comandi e helper per la superficie dei comandi	`resolveControlCommandGate`, helper per l’autorizzazione del mittente, helper per il registro dei comandi
`plugin-sdk/command-status`	Renderer di stato/help dei comandi	`buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage`
`plugin-sdk/secret-input`	Parsing degli input secret	Helper per input secret
`plugin-sdk/webhook-ingress`	Helper per richieste Webhook	Utility per target Webhook
`plugin-sdk/webhook-request-guards`	Helper di guardia per i body Webhook	Helper per lettura/limite del body della richiesta
`plugin-sdk/reply-runtime`	Runtime condiviso per le risposte	Dispatch in ingresso, Heartbeat, pianificatore delle risposte, chunking
`plugin-sdk/reply-dispatch-runtime`	Helper mirati per il dispatch delle risposte	Helper per finalize + dispatch del provider
`plugin-sdk/reply-history`	Helper per reply-history	`buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled`
`plugin-sdk/reply-reference`	Pianificazione dei riferimenti di risposta	`createReplyReferencePlanner`
`plugin-sdk/reply-chunking`	Helper per chunk di risposta	Helper per chunking di testo/markdown
`plugin-sdk/session-store-runtime`	Helper per session store	Helper per percorso dello store + updated-at
`plugin-sdk/state-paths`	Helper per i percorsi di stato	Helper per directory di stato e OAuth
`plugin-sdk/routing`	Helper per instradamento/session-key	`resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helper per la normalizzazione della session-key
`plugin-sdk/status-helpers`	Helper di stato del canale	Builder di riepilogo dello stato di canale/account, valori predefiniti dello stato runtime, helper per metadati dei problemi
`plugin-sdk/target-resolver-runtime`	Helper per il risolutore dei target	Helper condivisi per il risolutore dei target
`plugin-sdk/string-normalization-runtime`	Helper per la normalizzazione delle stringhe	Helper per la normalizzazione di slug/stringhe
`plugin-sdk/request-url`	Helper per URL di richiesta	Estrae URL stringa da input simili a request
`plugin-sdk/run-command`	Helper per comandi temporizzati	Esecutore di comandi temporizzati con `stdout`/`stderr` normalizzati
`plugin-sdk/param-readers`	Lettori di parametri	Lettori comuni di parametri per tool/CLI
`plugin-sdk/tool-payload`	Estrazione del payload dei tool	Estrae payload normalizzati da oggetti risultato dei tool
`plugin-sdk/tool-send`	Estrazione di invio dei tool	Estrae campi target di invio canonici dagli argomenti del tool
`plugin-sdk/temp-path`	Helper per percorsi temporanei	Helper condivisi per percorsi temporanei di download
`plugin-sdk/logging-core`	Helper di logging	Logger di sottosistema e helper di redazione
`plugin-sdk/markdown-table-runtime`	Helper per tabelle Markdown	Helper per la modalità tabella Markdown
`plugin-sdk/reply-payload`	Tipi di risposta del messaggio	Tipi del payload di risposta
`plugin-sdk/provider-setup`	Helper curati per setup di provider locali/self-hosted	Helper per discovery/configurazione di provider self-hosted
`plugin-sdk/self-hosted-provider-setup`	Helper focalizzati per setup di provider self-hosted compatibili con OpenAI	Gli stessi helper per discovery/configurazione di provider self-hosted
`plugin-sdk/provider-auth-runtime`	Helper di auth runtime del provider	Helper runtime per la risoluzione delle API key
`plugin-sdk/provider-auth-api-key`	Helper di setup delle API key del provider	Helper per onboarding/scrittura profilo delle API key
`plugin-sdk/provider-auth-result`	Helper per auth-result del provider	Builder standard del risultato di auth OAuth
`plugin-sdk/provider-auth-login`	Helper di login interattivo del provider	Helper condivisi per login interattivo
`plugin-sdk/provider-env-vars`	Helper per env var del provider	Helper per lookup delle env var di auth del provider
`plugin-sdk/provider-model-shared`	Helper condivisi per modello/replay del provider	`ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder condivisi di replay-policy, helper per endpoint del provider e helper per la normalizzazione di model-id
`plugin-sdk/provider-catalog-shared`	Helper condivisi per il catalogo dei provider	`findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat`
`plugin-sdk/provider-onboard`	Patch di onboarding del provider	Helper di configurazione per l’onboarding
`plugin-sdk/provider-http`	Helper HTTP del provider	Helper generici per HTTP/capacità endpoint del provider
`plugin-sdk/provider-web-fetch`	Helper web-fetch del provider	Helper per registrazione/cache del provider web-fetch
`plugin-sdk/provider-web-search-config-contract`	Helper di configurazione web-search del provider	Helper mirati per configurazione/credenziali web-search per provider che non richiedono wiring di abilitazione del plugin
`plugin-sdk/provider-web-search-contract`	Helper contrattuali web-search del provider	Helper contrattuali mirati per configurazione/credenziali web-search come `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setter/getter di credenziali con scope
`plugin-sdk/provider-web-search`	Helper web-search del provider	Helper per registrazione/cache/runtime del provider web-search
`plugin-sdk/provider-tools`	Helper di compatibilità tool/schema del provider	`ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, cleanup + diagnostica dello schema Gemini e helper di compatibilità xAI come `resolveXaiModelCompatPatch` / `applyXaiModelCompat`
`plugin-sdk/provider-usage`	Helper di utilizzo del provider	`fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` e altri helper di utilizzo del provider
`plugin-sdk/provider-stream`	Helper wrapper di stream del provider	`ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipi dei wrapper di stream e helper wrapper condivisi per Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot
`plugin-sdk/provider-transport-runtime`	Helper di trasporto del provider	Helper di trasporto nativi del provider come fetch protetto, trasformazioni dei messaggi di trasporto e stream di eventi di trasporto scrivibili
`plugin-sdk/keyed-async-queue`	Coda async ordinata	`KeyedAsyncQueue`
`plugin-sdk/media-runtime`	Helper media condivisi	Helper per fetch/trasformazione/store dei media più builder del payload media
`plugin-sdk/media-generation-runtime`	Helper condivisi per la generazione di media	Helper condivisi per failover, selezione dei candidati e messaggi di modello mancante per la generazione di immagini/video/musica
`plugin-sdk/media-understanding`	Helper per media-understanding	Tipi del provider per media understanding più export di helper lato provider per immagini/audio
`plugin-sdk/text-runtime`	Helper di testo condivisi	Rimozione del testo visibile all’assistente, helper per rendering/chunking/tabelle Markdown, helper di redazione, helper per directive-tag, utility di testo sicuro e relativi helper per testo/logging
`plugin-sdk/text-chunking`	Helper per chunking del testo	Helper per chunking del testo in uscita
`plugin-sdk/speech`	Helper Speech	Tipi del provider Speech più export di helper lato provider per directive, registro e validazione
`plugin-sdk/speech-core`	Core Speech condiviso	Tipi del provider Speech, registro, directive, normalizzazione
`plugin-sdk/realtime-transcription`	Helper per trascrizione realtime	Tipi del provider e helper del registro
`plugin-sdk/realtime-voice`	Helper per voce realtime	Tipi del provider e helper del registro
`plugin-sdk/image-generation-core`	Core condiviso per la generazione di immagini	Tipi, failover, auth e helper del registro per la generazione di immagini
`plugin-sdk/music-generation`	Helper per generazione musicale	Tipi di provider/richiesta/risultato per la generazione musicale
`plugin-sdk/music-generation-core`	Core condiviso per la generazione musicale	Tipi per la generazione musicale, helper di failover, ricerca provider e parsing di model-ref
`plugin-sdk/video-generation`	Helper per generazione video	Tipi di provider/richiesta/risultato per la generazione video
`plugin-sdk/video-generation-core`	Core condiviso per la generazione video	Tipi per la generazione video, helper di failover, ricerca provider e parsing di model-ref
`plugin-sdk/interactive-runtime`	Helper per risposte interattive	Normalizzazione/riduzione del payload delle risposte interattive
`plugin-sdk/channel-config-primitives`	Primitive di configurazione del canale	Primitive mirate dello schema di configurazione del canale
`plugin-sdk/channel-config-writes`	Helper per scrittura della configurazione del canale	Helper di autorizzazione per la scrittura della configurazione del canale
`plugin-sdk/channel-plugin-common`	Prelude condiviso del canale	Export condivisi del prelude del channel plugin
`plugin-sdk/channel-status`	Helper di stato del canale	Helper condivisi per snapshot/riepilogo dello stato del canale
`plugin-sdk/allowlist-config-edit`	Helper di configurazione dell’allowlist	Helper per modifica/lettura della configurazione dell’allowlist
`plugin-sdk/group-access`	Helper per accesso ai gruppi	Helper condivisi per le decisioni di accesso ai gruppi
`plugin-sdk/direct-dm`	Helper per direct-DM	Helper condivisi di auth/guard per direct-DM
`plugin-sdk/extension-shared`	Helper condivisi dell’estensione	Primitive helper per canale/stato passivi e proxy ambient
`plugin-sdk/webhook-targets`	Helper per target Webhook	Registro dei target Webhook e helper per installazione delle route
`plugin-sdk/webhook-path`	Helper per percorsi Webhook	Helper per normalizzazione dei percorsi Webhook
`plugin-sdk/web-media`	Helper media web condivisi	Helper per caricamento di media remoti/locali
`plugin-sdk/zod`	Riesportazione di zod	`zod` riesportato per i consumer del Plugin SDK
`plugin-sdk/memory-core`	Helper bundled memory-core	Superficie helper per memory manager/config/file/CLI
`plugin-sdk/memory-core-engine-runtime`	Facciata runtime del motore di memoria	Facciata runtime per indice/ricerca della memoria
`plugin-sdk/memory-core-host-engine-foundation`	Motore foundation host della memoria	Export del motore foundation host della memoria
`plugin-sdk/memory-core-host-engine-embeddings`	Motore embeddings host della memoria	Contratti degli embedding di memoria, accesso al registro, provider locale e helper generici batch/remoti; i provider remoti concreti si trovano nei plugin che li possiedono
`plugin-sdk/memory-core-host-engine-qmd`	Motore QMD host della memoria	Export del motore QMD host della memoria
`plugin-sdk/memory-core-host-engine-storage`	Motore storage host della memoria	Export del motore storage host della memoria
`plugin-sdk/memory-core-host-multimodal`	Helper multimodali host della memoria	Helper multimodali host della memoria
`plugin-sdk/memory-core-host-query`	Helper query host della memoria	Helper query host della memoria
`plugin-sdk/memory-core-host-secret`	Helper secret host della memoria	Helper secret host della memoria
`plugin-sdk/memory-core-host-events`	Helper per event journal host della memoria	Helper per event journal host della memoria
`plugin-sdk/memory-core-host-status`	Helper di stato host della memoria	Helper di stato host della memoria
`plugin-sdk/memory-core-host-runtime-cli`	Runtime CLI host della memoria	Helper runtime CLI host della memoria
`plugin-sdk/memory-core-host-runtime-core`	Runtime core host della memoria	Helper runtime core host della memoria
`plugin-sdk/memory-core-host-runtime-files`	Helper file/runtime host della memoria	Helper file/runtime host della memoria
`plugin-sdk/memory-host-core`	Alias runtime core host della memoria	Alias neutrale rispetto al vendor per gli helper runtime core host della memoria
`plugin-sdk/memory-host-events`	Alias event journal host della memoria	Alias neutrale rispetto al vendor per gli helper event journal host della memoria
`plugin-sdk/memory-host-files`	Alias file/runtime host della memoria	Alias neutrale rispetto al vendor per gli helper file/runtime host della memoria
`plugin-sdk/memory-host-markdown`	Helper per markdown gestito	Helper condivisi per managed-markdown per plugin adiacenti alla memoria
`plugin-sdk/memory-host-search`	Facciata di ricerca Active Memory	Facciata runtime lazy del search-manager di Active Memory
`plugin-sdk/memory-host-status`	Alias stato host della memoria	Alias neutrale rispetto al vendor per gli helper di stato host della memoria
`plugin-sdk/memory-lancedb`	Helper bundled memory-lancedb	Superficie helper memory-lancedb
`plugin-sdk/testing`	Utility di test	Helper di test e mock

Questa tabella è intenzionalmente il sottoinsieme comune per la migrazione, non l’intera superficie del SDK. L’elenco completo di oltre 200 entrypoint si trova in scripts/lib/plugin-sdk-entrypoints.json. Quell’elenco include ancora alcuni helper seam dei plugin bundled come plugin-sdk/feishu, plugin-sdk/feishu-setup, plugin-sdk/zalo, plugin-sdk/zalo-setup e plugin-sdk/matrix*. Questi continuano a essere esportati per la manutenzione e la compatibilità dei plugin bundled, ma sono intenzionalmente omessi dalla tabella comune di migrazione e non sono il target consigliato per il nuovo codice dei plugin. La stessa regola si applica ad altre famiglie di helper bundled come:

helper di supporto browser: plugin-sdk/browser-cdp, plugin-sdk/browser-config-runtime, plugin-sdk/browser-config-support, plugin-sdk/browser-control-auth, plugin-sdk/browser-node-runtime, plugin-sdk/browser-profiles, plugin-sdk/browser-security-runtime, plugin-sdk/browser-setup-tools, plugin-sdk/browser-support
Matrix: plugin-sdk/matrix*
LINE: plugin-sdk/line*
IRC: plugin-sdk/irc*
superfici di helper/plugin bundled come plugin-sdk/googlechat, plugin-sdk/zalouser, plugin-sdk/bluebubbles*, plugin-sdk/mattermost*, plugin-sdk/msteams, plugin-sdk/nextcloud-talk, plugin-sdk/nostr, plugin-sdk/tlon, plugin-sdk/twitch, plugin-sdk/github-copilot-login, plugin-sdk/github-copilot-token, plugin-sdk/diagnostics-otel, plugin-sdk/diffs, plugin-sdk/llm-task, plugin-sdk/thread-ownership e plugin-sdk/voice-call

plugin-sdk/github-copilot-token espone attualmente la superficie mirata degli helper per token DEFAULT_COPILOT_API_BASE_URL, deriveCopilotApiBaseUrlFromToken e resolveCopilotApiToken. Usa l’import più mirato che corrisponde al lavoro da svolgere. Se non riesci a trovare un export, controlla il sorgente in src/plugin-sdk/ o chiedi su Discord.

Tempistiche di rimozione

Quando	Cosa succede
Ora	Le superfici deprecate emettono avvisi a runtime
Prossima major release	Le superfici deprecate verranno rimosse; i plugin che le usano ancora smetteranno di funzionare

Tutti i plugin core sono già stati migrati. I plugin esterni dovrebbero effettuare la migrazione prima della prossima major release.

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

Per iniziare — crea il tuo primo plugin
Panoramica dell’SDK — riferimento completo agli import per subpath
Plugin di canale — creare plugin di canale
Plugin provider — creare plugin provider
Interni dei plugin — approfondimento sull’architettura
Manifest del plugin — riferimento allo schema del manifest

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

Migrazione al Plugin SDK

Migrazione al Plugin SDK

Cosa sta cambiando

Perché è cambiato

Come effettuare la migrazione

Riferimento ai percorsi di import

Tempistiche di rimozione

Soppressione temporanea degli avvisi

Correlati

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

​Migrazione al Plugin SDK

​Cosa sta cambiando

​Perché è cambiato

​Come effettuare la migrazione

​Riferimento ai percorsi di import

​Tempistiche di rimozione

​Soppressione temporanea degli avvisi

​Correlati

Migrazione al Plugin SDK

Cosa sta cambiando

Perché è cambiato

Come effettuare la migrazione

Riferimento ai percorsi di import

Tempistiche di rimozione

Soppressione temporanea degli avvisi

Correlati