Migrasi SDK Plugin

OpenClaw telah berpindah dari lapisan kompatibilitas mundur yang luas ke arsitektur plugin modern dengan impor yang terfokus dan terdokumentasi. Jika plugin Anda dibuat sebelum arsitektur baru, panduan ini membantu Anda melakukan migrasi.

Apa yang berubah

Sistem plugin lama menyediakan dua permukaan yang sangat terbuka yang memungkinkan plugin mengimpor apa pun yang dibutuhkan dari satu titik masuk:

• openclaw/plugin-sdk/compat - satu impor yang mengekspor ulang puluhan helper. Ini diperkenalkan untuk menjaga plugin lama berbasis hook tetap berfungsi saat arsitektur plugin baru sedang dibangun.
• openclaw/plugin-sdk/infra-runtime - barrel helper runtime luas yang mencampur event sistem, status Heartbeat, antrean pengiriman, helper fetch/proxy, helper file, tipe persetujuan, dan utilitas yang tidak terkait.
• openclaw/plugin-sdk/config-runtime - barrel kompatibilitas config luas yang masih membawa helper load/write langsung yang sudah deprecated selama jendela migrasi.
• openclaw/extension-api - bridge yang memberi plugin akses langsung ke helper sisi host seperti runner agen tertanam.
• api.registerEmbeddedExtensionFactory(...) - hook ekstensi bundel khusus Pi yang telah dihapus yang dapat mengamati event embedded-runner seperti tool_result.

Permukaan impor yang luas kini deprecated. Permukaan itu masih berfungsi saat runtime, tetapi plugin baru tidak boleh menggunakannya, dan plugin yang ada sebaiknya bermigrasi sebelum rilis mayor berikutnya menghapusnya. API pendaftaran factory ekstensi tertanam khusus Pi telah dihapus; gunakan middleware hasil tool sebagai gantinya.

OpenClaw tidak menghapus atau menafsirkan ulang perilaku plugin terdokumentasi dalam perubahan yang sama yang memperkenalkan penggantinya. Perubahan kontrak yang breaking harus terlebih dahulu melalui adapter kompatibilitas, diagnostik, docs, dan jendela deprecation. Itu berlaku untuk impor SDK, field manifest, API setup, hook, dan perilaku pendaftaran runtime.

Mengapa ini berubah

Pendekatan lama menyebabkan masalah:

• Startup lambat - mengimpor satu helper memuat puluhan modul yang tidak terkait
• Dependensi sirkular - re-export luas memudahkan pembuatan siklus impor
• Permukaan API tidak jelas - tidak ada cara untuk mengetahui ekspor mana yang stabil vs internal

SDK plugin modern memperbaiki ini: setiap path impor (openclaw/plugin-sdk/\<subpath\>) adalah modul kecil dan mandiri dengan tujuan yang jelas dan kontrak terdokumentasi.

Seam kemudahan provider legacy untuk channel bundel juga sudah hilang. Seam helper bermerek channel adalah shortcut privat mono-repo, bukan kontrak plugin yang stabil. Gunakan subpath SDK generik yang sempit sebagai gantinya. Di dalam workspace plugin bundel, simpan helper milik provider di api.ts atau runtime-api.ts milik plugin itu sendiri.

Contoh provider bundel saat ini:

• Anthropic menyimpan helper stream khusus Claude di seam api.ts / contract-api.ts miliknya sendiri
• OpenAI menyimpan builder provider, helper model default, dan builder provider realtime di api.ts miliknya sendiri
• OpenRouter menyimpan builder provider dan helper onboarding/config di api.ts miliknya sendiri

Rencana migrasi Talk dan suara realtime

Kode Talk untuk suara realtime, telephony, meeting, dan browser sedang dipindahkan dari pencatatan turn lokal permukaan ke controller sesi Talk bersama yang diekspor oleh openclaw/plugin-sdk/realtime-voice. Controller baru memiliki envelope event Talk umum, status turn aktif, status capture, status audio output, riwayat event terbaru, dan penolakan turn usang. Plugin provider harus tetap memiliki sesi realtime spesifik vendor; plugin permukaan harus tetap memiliki capture, playback, telephony, dan kekhasan meeting.

Migrasi Talk ini sengaja dibuat bersih meski breaking:

1. Simpan primitive controller/runtime bersama di plugin-sdk/realtime-voice.
2. Pindahkan permukaan bundel ke controller bersama: relay browser, handoff managed-room, realtime voice-call, STT streaming voice-call, Google Meet realtime, dan native push-to-talk.
3. Ganti keluarga RPC Talk lama dengan API final talk.session.* dan talk.client.*.
4. Iklankan satu channel event Talk live di Gateway hello-ok.features.events: talk.event.
5. Hapus endpoint HTTP realtime lama dan semua path override instruksi saat request.

Kode baru sebaiknya tidak memanggil createTalkEventSequencer(...) langsung kecuali jika mengimplementasikan adapter level rendah atau fixture test. Pilih controller bersama agar event yang ber-scope turn tidak dapat dipancarkan tanpa id turn, panggilan turnEnd / turnCancel yang usang tidak dapat menghapus turn aktif yang lebih baru, dan event lifecycle audio output tetap konsisten di telephony, meeting, relay browser, handoff managed-room, dan klien Talk native.

Bentuk target API publik adalah:

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

Sesi WebRTC/provider-websocket milik browser menggunakan talk.client.create, karena browser memiliki negosiasi provider dan transport media sementara Gateway memiliki kredensial, instruksi, dan kebijakan tool. talk.session.* adalah permukaan umum yang dikelola Gateway untuk realtime gateway-relay, transcription gateway-relay, dan sesi STT/TTS native managed-room.

Config legacy yang menempatkan selector realtime di samping talk.provider / talk.providers harus diperbaiki dengan openclaw doctor --fix; runtime Talk tidak menafsirkan ulang config provider speech/TTS sebagai config provider realtime.

Kombinasi talk.session.create yang didukung sengaja dibuat kecil:

Peta metode yang dihapus:

Kosakata kontrol terpadu juga sengaja dibuat sempit:

Jangan tambahkan kasus khusus penyedia atau platform di core untuk membuat ini berfungsi. Core memiliki semantik sesi Talk. Plugin penyedia memiliki penyiapan sesi vendor. Panggilan suara dan Google Meet memiliki adapter telepon/rapat. Browser dan aplikasi native memiliki UX penangkapan/pemutaran perangkat.

Kebijakan kompatibilitas

Untuk plugin eksternal, pekerjaan kompatibilitas mengikuti urutan ini:

1. tambahkan kontrak baru
2. pertahankan perilaku lama yang disambungkan melalui adapter kompatibilitas
3. keluarkan diagnostik atau peringatan yang menyebutkan jalur lama dan penggantinya
4. cakup kedua jalur dalam pengujian
5. dokumentasikan penghentian dan jalur migrasi
6. hapus hanya setelah jendela migrasi yang diumumkan, biasanya dalam rilis mayor

Maintainer dapat mengaudit antrean migrasi saat ini dengan pnpm plugins:boundary-report. Gunakan pnpm plugins:boundary-report:summary untuk hitungan ringkas, --owner <id> untuk satu plugin atau pemilik kompatibilitas, dan pnpm plugins:boundary-report:ci saat gate CI harus gagal pada catatan kompatibilitas yang jatuh tempo, impor SDK reserved lintas pemilik, atau subpath SDK reserved yang tidak digunakan. Laporan mengelompokkan catatan kompatibilitas yang dihentikan berdasarkan tanggal penghapusan, menghitung referensi kode/dokumen lokal, memunculkan impor SDK reserved lintas pemilik, dan meringkas bridge SDK host memori privat sehingga pembersihan kompatibilitas tetap eksplisit, bukan bergantung pada pencarian ad hoc. Subpath SDK reserved harus memiliki penggunaan pemilik yang terlacak; ekspor helper reserved yang tidak digunakan harus dihapus dari SDK publik.

Jika sebuah field manifes masih diterima, penulis plugin dapat terus menggunakannya sampai dokumentasi dan diagnostik mengatakan sebaliknya. Kode baru sebaiknya memilih pengganti yang terdokumentasi, tetapi plugin yang ada tidak boleh rusak selama rilis minor biasa.

Cara bermigrasi

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/

Referensi jalur impor

Tabel ini sengaja merupakan subset migrasi umum, bukan seluruh permukaan SDK. Inventaris entrypoint compiler berada di scripts/lib/plugin-sdk-entrypoints.json; ekspor paket dibuat dari subset publik.

Seam pembantu Plugin bundel yang dicadangkan telah dipensiunkan dari peta ekspor SDK publik kecuali facade kompatibilitas yang didokumentasikan secara eksplisit seperti shim plugin-sdk/discord yang sudah deprecated dan dipertahankan untuk paket @openclaw/[email protected] yang telah dipublikasikan. Pembantu khusus pemilik berada di dalam paket plugin pemiliknya; perilaku host bersama harus bergerak melalui kontrak SDK generik seperti plugin-sdk/gateway-runtime, plugin-sdk/security-runtime, dan plugin-sdk/plugin-config-runtime.

Gunakan impor paling sempit yang sesuai dengan tugasnya. Jika Anda tidak dapat menemukan ekspor, periksa sumber di src/plugin-sdk/ atau tanyakan kepada maintainer kontrak generik mana yang harus memilikinya.

Deprecation aktif

Deprecation yang lebih sempit yang berlaku di seluruh SDK plugin, kontrak provider, permukaan runtime, dan manifes. Masing-masing masih berfungsi hari ini tetapi akan dihapus dalam rilis mayor mendatang. Entri di bawah setiap item memetakan API lama ke pengganti kanonisnya.

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

Linimasa penghapusan

Semua plugin inti sudah dimigrasikan. Plugin eksternal harus bermigrasi sebelum rilis mayor berikutnya.

Menekan peringatan sementara

Tetapkan variabel lingkungan ini saat Anda mengerjakan migrasi:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

Ini adalah pintu keluar sementara, bukan solusi permanen.

Terkait

• Memulai - bangun plugin pertama Anda
• Ikhtisar SDK - referensi impor subpath lengkap
• Plugin Channel - membangun plugin channel
• Plugin Provider - membangun plugin provider
• Internal Plugin - pembahasan mendalam arsitektur
• Manifes Plugin - referensi skema manifes