Langsung ke konten utama

​
Migrasi Plugin SDK

OpenClaw telah beralih dari lapisan kompatibilitas mundur yang luas ke arsitektur plugin modern dengan import yang terfokus dan terdokumentasi. Jika plugin Anda dibangun sebelum arsitektur baru ini, panduan ini membantu Anda bermigrasi.

​
Apa yang berubah

Sistem plugin lama menyediakan dua permukaan yang sangat terbuka yang memungkinkan plugin mengimpor apa pun yang mereka butuhkan dari satu entry point:
  • openclaw/plugin-sdk/compat — satu import yang me-re-export puluhan helper. Ini diperkenalkan untuk menjaga plugin berbasis hook yang lebih lama tetap berfungsi saat arsitektur plugin baru sedang dibangun.
  • openclaw/extension-api — bridge yang memberi plugin akses langsung ke helper sisi host seperti embedded agent runner.
Kedua permukaan ini sekarang deprecated. Keduanya masih berfungsi saat runtime, tetapi plugin baru tidak boleh menggunakannya, dan plugin yang sudah ada harus bermigrasi sebelum rilis mayor berikutnya menghapusnya.
Lapisan kompatibilitas mundur akan dihapus pada rilis mayor mendatang. Plugin yang masih mengimpor dari permukaan ini akan rusak saat itu terjadi.

​
Mengapa ini berubah

Pendekatan lama menyebabkan masalah:
  • Startup lambat — mengimpor satu helper memuat puluhan modul yang tidak terkait
  • Circular dependency — re-export yang luas memudahkan terbentuknya siklus import
  • Permukaan API tidak jelas — tidak ada cara untuk membedakan ekspor yang stabil vs internal
Plugin SDK modern memperbaiki ini: setiap jalur import (openclaw/plugin-sdk/\<subpath\>) adalah modul kecil yang berdiri sendiri dengan tujuan yang jelas dan kontrak yang terdokumentasi. Seam kemudahan provider lama untuk channel bawaan juga sudah dihapus. Import seperti openclaw/plugin-sdk/slack, openclaw/plugin-sdk/discord, openclaw/plugin-sdk/signal, openclaw/plugin-sdk/whatsapp, seam helper bermerek channel, dan openclaw/plugin-sdk/telegram-core adalah pintasan mono-repo privat, bukan kontrak plugin yang stabil. Gunakan subpath SDK generik yang sempit sebagai gantinya. Di dalam workspace plugin bawaan, simpan helper milik provider di api.ts atau runtime-api.ts milik plugin itu sendiri. Contoh provider bawaan saat ini:
  • Anthropic menyimpan helper stream khusus Claude di seam api.ts / contract-api.ts miliknya sendiri
  • OpenAI menyimpan builder provider, helper default-model, dan builder provider realtime di api.ts miliknya sendiri
  • OpenRouter menyimpan builder provider dan helper onboarding/config di api.ts miliknya sendiri

​
Cara bermigrasi

1

Audit perilaku fallback wrapper Windows

Jika plugin Anda menggunakan openclaw/plugin-sdk/windows-spawn, wrapper Windows .cmd/.bat yang tidak dapat di-resolve sekarang gagal tertutup kecuali Anda secara eksplisit meneruskan allowShellFallback: true.
// Sebelum
const program = applyWindowsSpawnProgramPolicy({ candidate });

// Sesudah
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // Setel ini hanya untuk pemanggil kompatibilitas tepercaya yang memang
  // menerima fallback yang dimediasi shell.
  allowShellFallback: true,
});
Jika pemanggil Anda tidak benar-benar bergantung pada shell fallback, jangan setel allowShellFallback dan tangani error yang dilempar sebagai gantinya.
2

Temukan import yang deprecated

Cari dalam plugin Anda import dari salah satu permukaan deprecated:
grep -r "plugin-sdk/compat" my-plugin/
grep -r "openclaw/extension-api" my-plugin/
3

Ganti dengan import yang terfokus

Setiap ekspor dari permukaan lama dipetakan ke jalur import modern tertentu:
// Sebelum (lapisan kompatibilitas mundur deprecated)
import {
  createChannelReplyPipeline,
  createPluginRuntimeStore,
  resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";

// Sesudah (import modern yang terfokus)
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";
Untuk helper sisi host, gunakan runtime plugin yang diinjeksi alih-alih mengimpor secara langsung:
// Sebelum (bridge extension-api deprecated)
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });

// Sesudah (runtime yang diinjeksi)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
Pola yang sama berlaku untuk helper bridge lama lainnya:
Import lamaPadanan modern
resolveAgentDirapi.runtime.agent.resolveAgentDir
resolveAgentWorkspaceDirapi.runtime.agent.resolveAgentWorkspaceDir
resolveAgentIdentityapi.runtime.agent.resolveAgentIdentity
resolveThinkingDefaultapi.runtime.agent.resolveThinkingDefault
resolveAgentTimeoutMsapi.runtime.agent.resolveAgentTimeoutMs
ensureAgentWorkspaceapi.runtime.agent.ensureAgentWorkspace
helper session storeapi.runtime.agent.session.*
4

Build dan uji

pnpm build
pnpm test -- my-plugin/

​
Referensi jalur import

Jalur importTujuanEkspor utama
plugin-sdk/plugin-entryHelper entri plugin kanonisdefinePluginEntry
plugin-sdk/coreRe-export payung lama untuk definisi/builder entri channeldefineChannelPluginEntry, createChatChannelPlugin
plugin-sdk/config-schemaEkspor skema config rootOpenClawSchema
plugin-sdk/provider-entryHelper entri provider tunggaldefineSingleProviderPluginEntry
plugin-sdk/channel-coreDefinisi dan builder entri channel yang terfokusdefineChannelPluginEntry, defineSetupPluginEntry, createChatChannelPlugin, createChannelPluginBase
plugin-sdk/setupHelper wizard setup bersamaPrompt allowlist, builder status setup
plugin-sdk/setup-runtimeHelper runtime saat setupAdapter patch setup yang aman diimpor, helper lookup-note, promptResolvedAllowFrom, splitSetupEntries, proxy setup yang didelegasikan
plugin-sdk/setup-adapter-runtimeHelper adapter setupcreateEnvPatchedAccountSetupAdapter
plugin-sdk/setup-toolsHelper tooling setupformatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR
plugin-sdk/account-coreHelper multi-akunHelper daftar akun/config/action-gate
plugin-sdk/account-idHelper account-idDEFAULT_ACCOUNT_ID, normalisasi account-id
plugin-sdk/account-resolutionHelper lookup akunHelper lookup akun + fallback default
plugin-sdk/account-helpersHelper akun yang sempitHelper daftar akun/tindakan akun
plugin-sdk/channel-setupAdapter wizard setupcreateOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, ditambah DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled, splitSetupEntries
plugin-sdk/channel-pairingPrimitive pairing DMcreateChannelPairingController
plugin-sdk/channel-reply-pipelinePrefix balasan + wiring typingcreateChannelReplyPipeline
plugin-sdk/channel-config-helpersFactory adapter configcreateHybridChannelConfigAdapter
plugin-sdk/channel-config-schemaBuilder skema configTipe skema config channel
plugin-sdk/telegram-command-configHelper config perintah TelegramNormalisasi nama perintah, trimming deskripsi, validasi duplikasi/konflik
plugin-sdk/channel-policyResolusi kebijakan grup/DMresolveChannelGroupRequireMention
plugin-sdk/channel-lifecyclePelacakan status akuncreateAccountStatusSink
plugin-sdk/inbound-envelopeHelper envelope inboundHelper route + builder envelope bersama
plugin-sdk/inbound-reply-dispatchHelper balasan inboundHelper record-and-dispatch bersama
plugin-sdk/messaging-targetsParsing target pesanHelper parsing/pencocokan target
plugin-sdk/outbound-mediaHelper media outboundPemuatan media outbound bersama
plugin-sdk/outbound-runtimeHelper runtime outboundHelper delegasi identitas/pengiriman outbound
plugin-sdk/thread-bindings-runtimeHelper thread-bindingSiklus hidup thread-binding dan helper adapter
plugin-sdk/agent-media-payloadHelper payload media lamaBuilder payload media agen untuk tata letak field lama
plugin-sdk/channel-runtimeShim kompatibilitas deprecatedHanya utilitas runtime channel lama
plugin-sdk/channel-send-resultTipe hasil pengirimanTipe hasil balasan
plugin-sdk/runtime-storePenyimpanan plugin persistencreatePluginRuntimeStore
plugin-sdk/runtimeHelper runtime yang luasHelper runtime/logging/backup/plugin-install
plugin-sdk/runtime-envHelper env runtime yang sempitLogger/runtime env, timeout, retry, dan helper backoff
plugin-sdk/plugin-runtimeHelper runtime plugin bersamaHelper plugin commands/hooks/http/interactive
plugin-sdk/hook-runtimeHelper pipeline hookHelper pipeline webhook/internal hook bersama
plugin-sdk/lazy-runtimeHelper runtime lazycreateLazyRuntimeModule, createLazyRuntimeMethod, createLazyRuntimeMethodBinder, createLazyRuntimeNamedExport, createLazyRuntimeSurface
plugin-sdk/process-runtimeHelper prosesHelper exec bersama
plugin-sdk/cli-runtimeHelper runtime CLIFormatting perintah, waits, helper versi
plugin-sdk/gateway-runtimeHelper gatewayKlien gateway dan helper patch channel-status
plugin-sdk/config-runtimeHelper configHelper load/write config
plugin-sdk/telegram-command-configHelper perintah TelegramHelper validasi perintah Telegram yang stabil dalam fallback saat permukaan kontrak Telegram bawaan tidak tersedia
plugin-sdk/approval-runtimeHelper prompt approvalPayload approval exec/plugin, helper capability/profile approval, helper routing/runtime approval native
plugin-sdk/approval-auth-runtimeHelper auth approvalResolusi approver, auth tindakan same-chat
plugin-sdk/approval-client-runtimeHelper klien approvalHelper profil/filter approval exec native
plugin-sdk/approval-delivery-runtimeHelper pengiriman approvalAdapter capability/pengiriman approval native
plugin-sdk/approval-native-runtimeHelper target approvalHelper target approval native/binding akun
plugin-sdk/approval-reply-runtimeHelper balasan approvalHelper payload balasan approval exec/plugin
plugin-sdk/security-runtimeHelper keamananHelper trust, gating DM, konten eksternal, dan pengumpulan rahasia bersama
plugin-sdk/ssrf-policyHelper kebijakan SSRFHost allowlist dan helper kebijakan private-network
plugin-sdk/ssrf-runtimeHelper runtime SSRFHelper pinned-dispatcher, guarded fetch, kebijakan SSRF
plugin-sdk/collection-runtimeHelper cache berbataspruneMapToMaxSize
plugin-sdk/diagnostic-runtimeHelper gating diagnostikisDiagnosticFlagEnabled, isDiagnosticsEnabled
plugin-sdk/error-runtimeHelper formatting errorformatUncaughtError, isApprovalNotFoundError, helper grafik error
plugin-sdk/fetch-runtimeHelper wrapped fetch/proxyresolveFetch, helper proxy
plugin-sdk/host-runtimeHelper normalisasi hostnormalizeHostname, normalizeScpRemoteHost
plugin-sdk/retry-runtimeHelper retryRetryConfig, retryAsync, runner kebijakan
plugin-sdk/allow-fromFormatting allowlistformatAllowFromLowercase
plugin-sdk/allowlist-resolutionPemetaan input allowlistmapAllowlistResolutionInputs
plugin-sdk/command-authGating perintah dan helper permukaan perintahresolveControlCommandGate, helper otorisasi pengirim, helper registry perintah
plugin-sdk/secret-inputParsing input rahasiaHelper input rahasia
plugin-sdk/webhook-ingressHelper permintaan webhookUtilitas target webhook
plugin-sdk/webhook-request-guardsHelper guard body webhookHelper baca/batas body permintaan
plugin-sdk/reply-runtimeRuntime balasan bersamaInbound dispatch, heartbeat, planner balasan, chunking
plugin-sdk/reply-dispatch-runtimeHelper dispatch balasan yang sempitHelper finalisasi + dispatch provider
plugin-sdk/reply-historyHelper riwayat balasanbuildHistoryContext, buildPendingHistoryContextFromMap, recordPendingHistoryEntry, clearHistoryEntriesIfEnabled
plugin-sdk/reply-referencePerencanaan referensi balasancreateReplyReferencePlanner
plugin-sdk/reply-chunkingHelper chunk balasanHelper chunking teks/markdown
plugin-sdk/session-store-runtimeHelper session storeHelper jalur store + updated-at
plugin-sdk/state-pathsHelper jalur stateHelper direktori state dan OAuth
plugin-sdk/routingHelper routing/session-keyresolveAgentRoute, buildAgentSessionKey, resolveDefaultAgentBoundAccountId, helper normalisasi session-key
plugin-sdk/status-helpersHelper status channelBuilder ringkasan status channel/akun, default state runtime, helper metadata issue
plugin-sdk/target-resolver-runtimeHelper target resolverHelper target resolver bersama
plugin-sdk/string-normalization-runtimeHelper normalisasi stringHelper normalisasi slug/string
plugin-sdk/request-urlHelper URL permintaanMengekstrak URL string dari input mirip request
plugin-sdk/run-commandHelper perintah bertimerRunner perintah bertimer dengan stdout/stderr ternormalisasi
plugin-sdk/param-readersPembaca parameterPembaca parameter tool/CLI umum
plugin-sdk/tool-sendEkstraksi pengiriman toolMengekstrak field target pengiriman kanonis dari argumen tool
plugin-sdk/temp-pathHelper jalur sementaraHelper jalur temp-download bersama
plugin-sdk/logging-coreHelper loggingLogger subsistem dan helper redaksi
plugin-sdk/markdown-table-runtimeHelper tabel markdownHelper mode tabel markdown
plugin-sdk/reply-payloadTipe balasan pesanTipe payload balasan
plugin-sdk/provider-setupHelper setup provider lokal/self-hosted yang dikurasiHelper discovery/config provider self-hosted
plugin-sdk/self-hosted-provider-setupHelper setup provider self-hosted yang kompatibel dengan OpenAI dan terfokusHelper discovery/config provider self-hosted yang sama
plugin-sdk/provider-auth-runtimeHelper auth runtime providerHelper resolusi API-key runtime
plugin-sdk/provider-auth-api-keyHelper setup API-key providerHelper onboarding/penulisan profil API-key
plugin-sdk/provider-auth-resultHelper auth-result providerBuilder auth-result OAuth standar
plugin-sdk/provider-auth-loginHelper login interaktif providerHelper login interaktif bersama
plugin-sdk/provider-env-varsHelper env-var providerHelper lookup env-var auth provider
plugin-sdk/provider-model-sharedHelper model/replay provider bersamaProviderReplayFamily, buildProviderReplayFamilyHooks, normalizeModelCompat, builder kebijakan replay bersama, helper endpoint provider, dan helper normalisasi model-id
plugin-sdk/provider-catalog-sharedHelper katalog provider bersamafindCatalogTemplate, buildSingleProviderApiKeyCatalog, supportsNativeStreamingUsageCompat, applyProviderNativeStreamingUsageCompat
plugin-sdk/provider-onboardPatch onboarding providerHelper config onboarding
plugin-sdk/provider-httpHelper HTTP providerHelper kemampuan HTTP/endpoint provider generik
plugin-sdk/provider-web-fetchHelper web-fetch providerHelper registrasi/cache provider web-fetch
plugin-sdk/provider-web-searchHelper web-search providerHelper registrasi/cache/config provider web-search
plugin-sdk/provider-toolsHelper kompat tool/skema providerProviderToolCompatFamily, buildProviderToolCompatFamilyHooks, pembersihan skema Gemini + diagnostik, dan helper kompat xAI seperti resolveXaiModelCompatPatch / applyXaiModelCompat
plugin-sdk/provider-usageHelper penggunaan providerfetchClaudeUsage, fetchGeminiUsage, fetchGithubCopilotUsage, dan helper penggunaan provider lainnya
plugin-sdk/provider-streamHelper wrapper stream providerProviderStreamFamily, buildProviderStreamFamilyHooks, composeProviderStreamWrappers, tipe wrapper stream, dan helper wrapper bersama Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot
plugin-sdk/keyed-async-queueAntrean async terurutKeyedAsyncQueue
plugin-sdk/media-runtimeHelper media bersamaHelper fetch/transform/store media ditambah builder payload media
plugin-sdk/media-understandingHelper media-understandingTipe provider media understanding ditambah ekspor helper image/audio untuk sisi provider
plugin-sdk/text-runtimeHelper teks bersamaPenghapusan teks yang terlihat oleh asisten, helper render/chunking/table markdown, helper redaksi, helper tag directive, utilitas safe-text, dan helper teks/logging terkait
plugin-sdk/text-chunkingHelper chunking teksHelper chunking teks outbound
plugin-sdk/speechHelper speechTipe provider speech ditambah helper directive, registry, dan validasi untuk sisi provider
plugin-sdk/speech-coreInti speech bersamaTipe provider speech, registry, directives, normalisasi
plugin-sdk/realtime-transcriptionHelper transcription realtimeTipe provider dan helper registry
plugin-sdk/realtime-voiceHelper voice realtimeTipe provider dan helper registry
plugin-sdk/image-generation-coreInti image-generation bersamaHelper tipe, failover, auth, dan registry image-generation
plugin-sdk/video-generationHelper video-generationTipe provider/permintaan/hasil video-generation
plugin-sdk/video-generation-coreInti video-generation bersamaTipe video-generation, helper failover, lookup provider, dan parsing model-ref
plugin-sdk/interactive-runtimeHelper balasan interaktifNormalisasi/reduksi payload balasan interaktif
plugin-sdk/channel-config-primitivesPrimitive config channelPrimitive channel config-schema yang sempit
plugin-sdk/channel-config-writesHelper penulisan config channelHelper otorisasi penulisan config channel
plugin-sdk/channel-plugin-commonPrelude channel bersamaEkspor prelude plugin channel bersama
plugin-sdk/channel-statusHelper status channelHelper snapshot/ringkasan status channel bersama
plugin-sdk/allowlist-config-editHelper config allowlistHelper edit/baca config allowlist
plugin-sdk/group-accessHelper akses grupHelper keputusan akses grup bersama
plugin-sdk/direct-dmHelper DM langsungHelper auth/guard DM langsung bersama
plugin-sdk/extension-sharedHelper extension bersamaPrimitive helper passive-channel/status
plugin-sdk/webhook-targetsHelper target webhookRegistry target webhook dan helper route-install
plugin-sdk/webhook-pathHelper jalur webhookHelper normalisasi jalur webhook
plugin-sdk/web-mediaHelper media web bersamaHelper pemuatan media remote/lokal
plugin-sdk/zodRe-export Zodzod yang di-re-export untuk konsumen plugin SDK
plugin-sdk/memory-coreHelper memory-core bawaanPermukaan helper memory manager/config/file/CLI
plugin-sdk/memory-core-engine-runtimeFasad runtime engine memoriFasad runtime index/search memori
plugin-sdk/memory-core-host-engine-foundationEngine foundation host memoriEkspor engine foundation host memori
plugin-sdk/memory-core-host-engine-embeddingsEngine embedding host memoriEkspor engine embedding host memori
plugin-sdk/memory-core-host-engine-qmdEngine QMD host memoriEkspor engine QMD host memori
plugin-sdk/memory-core-host-engine-storageEngine storage host memoriEkspor engine storage host memori
plugin-sdk/memory-core-host-multimodalHelper multimodal host memoriHelper multimodal host memori
plugin-sdk/memory-core-host-queryHelper kueri host memoriHelper kueri host memori
plugin-sdk/memory-core-host-secretHelper rahasia host memoriHelper rahasia host memori
plugin-sdk/memory-core-host-statusHelper status host memoriHelper status host memori
plugin-sdk/memory-core-host-runtime-cliRuntime CLI host memoriHelper runtime CLI host memori
plugin-sdk/memory-core-host-runtime-coreRuntime inti host memoriHelper runtime inti host memori
plugin-sdk/memory-core-host-runtime-filesHelper file/runtime host memoriHelper file/runtime host memori
plugin-sdk/memory-lancedbHelper memory-lancedb bawaanPermukaan helper memory-lancedb
plugin-sdk/testingUtilitas pengujianHelper dan mock pengujian
Tabel ini sengaja merupakan subset migrasi umum, bukan seluruh permukaan SDK. Daftar lengkap 200+ entrypoint ada di scripts/lib/plugin-sdk-entrypoints.json. Daftar itu masih mencakup beberapa seam helper bundled-plugin seperti plugin-sdk/feishu, plugin-sdk/feishu-setup, plugin-sdk/zalo, plugin-sdk/zalo-setup, dan plugin-sdk/matrix*. Semua itu tetap diekspor untuk pemeliharaan bundled-plugin dan kompatibilitas, tetapi sengaja dihilangkan dari tabel migrasi umum dan bukan target yang direkomendasikan untuk kode plugin baru. Aturan yang sama berlaku untuk keluarga helper bawaan lainnya seperti:
  • helper dukungan browser: plugin-sdk/browser-config-support, plugin-sdk/browser-support
  • Matrix: plugin-sdk/matrix*
  • LINE: plugin-sdk/line*
  • IRC: plugin-sdk/irc*
  • permukaan helper/plugin bawaan seperti 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, dan plugin-sdk/voice-call
plugin-sdk/github-copilot-token saat ini mengekspos permukaan helper token yang sempit DEFAULT_COPILOT_API_BASE_URL, deriveCopilotApiBaseUrlFromToken, dan resolveCopilotApiToken. Gunakan import tersempit yang sesuai dengan tugasnya. Jika Anda tidak dapat menemukan suatu ekspor, periksa source di src/plugin-sdk/ atau tanyakan di Discord.

​
Jadwal penghapusan

KapanYang terjadi
SekarangPermukaan deprecated mengeluarkan peringatan runtime
Rilis mayor berikutnyaPermukaan deprecated akan dihapus; plugin yang masih menggunakannya akan gagal
Semua plugin inti sudah dimigrasikan. Plugin eksternal harus bermigrasi sebelum rilis mayor berikutnya.

​
Menyembunyikan peringatan untuk sementara

Setel variabel lingkungan ini saat Anda sedang mengerjakan migrasi: 
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
Ini adalah jalan keluar sementara, bukan solusi permanen.

​
Terkait