Migrasi SDK Plugin

OpenClaw telah beralih dari lapisan kompatibilitas mundur yang luas ke arsitektur plugin modern dengan impor yang terfokus dan terdokumentasi. Jika plugin Anda dibuat 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 perlukan dari satu titik masuk:

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

Permukaan impor yang luas kini deprecated. Permukaan ini masih berjalan saat runtime, tetapi plugin baru tidak boleh menggunakannya, dan plugin yang ada sebaiknya bermigrasi sebelum rilis mayor berikutnya menghapusnya. API pendaftaran extension factory khusus embedded-runner telah dihapus; gunakan middleware tool-result sebagai gantinya.

OpenClaw tidak menghapus atau menafsirkan ulang perilaku plugin yang terdokumentasi dalam perubahan yang sama yang memperkenalkan pengganti. Perubahan kontrak yang breaking harus terlebih dahulu melalui adapter kompatibilitas, diagnostik, dokumentasi, dan jendela deprecation. Ini 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 melingkar - re-export yang luas memudahkan terciptanya siklus impor
• Permukaan API tidak jelas - tidak ada cara untuk mengetahui ekspor mana yang stabil vs internal

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

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

Contoh provider bundled 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

Rencana migrasi Talk dan suara realtime

Kode suara realtime, telephony, meeting, dan Talk 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 output-audio, riwayat event terbaru, dan penolakan stale-turn. Plugin provider harus tetap memiliki sesi realtime khusus vendor; plugin permukaan harus tetap memiliki kekhasan capture, playback, telephony, dan meeting.

Migrasi Talk ini sengaja breaking-clean:

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

Kode baru tidak boleh memanggil createTalkEventSequencer(...) secara langsung kecuali sedang mengimplementasikan adapter tingkat rendah atau fixture test. Utamakan controller bersama agar event yang dibatasi turn tidak dapat dipancarkan tanpa turn id, panggilan stale turnEnd / turnCancel tidak dapat menghapus turn aktif yang lebih baru, dan event lifecycle output-audio tetap konsisten di telephony, meeting, browser relay, managed-room handoff, dan native Talk client.

Bentuk API publik target 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 });await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });

Sesi WebRTC/provider-websocket yang dimiliki 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 gateway-relay realtime, gateway-relay transcription, dan sesi STT/TTS native managed-room.

Config legacy yang menempatkan selector realtime di sebelah 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 memperkenalkan kasus khusus penyedia atau platform di core agar ini berfungsi. Core memiliki semantik sesi Talk. Plugin penyedia memiliki penyiapan sesi vendor. Voice-call dan Google Meet memiliki adaptor telepon/meeting. Browser dan aplikasi native memiliki UX capture/playback perangkat.

Kebijakan kompatibilitas

Untuk plugin eksternal, pekerjaan kompatibilitas mengikuti urutan ini:

1. tambahkan kontrak baru
2. pertahankan perilaku lama yang disambungkan melalui adaptor kompatibilitas
3. keluarkan diagnostik atau peringatan yang menyebutkan jalur lama dan penggantinya
4. cakup kedua jalur dalam pengujian
5. dokumentasikan deprekasi 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 jumlah ringkas, --owner <id> untuk satu plugin atau pemilik kompatibilitas, dan pnpm plugins:boundary-report:ci ketika gate CI harus gagal pada catatan kompatibilitas yang jatuh tempo, impor SDK cadangan lintas pemilik, atau subpath SDK cadangan yang tidak digunakan. Laporan mengelompokkan catatan kompatibilitas yang dideprekasi berdasarkan tanggal penghapusan, menghitung referensi kode/dokumen lokal, menampilkan impor SDK cadangan lintas pemilik, dan merangkum bridge SDK memory-host privat agar pembersihan kompatibilitas tetap eksplisit alih-alih mengandalkan pencarian ad hoc. Subpath SDK cadangan harus memiliki penggunaan pemilik yang dilacak; ekspor helper cadangan yang tidak digunakan harus dihapus dari SDK publik.

Jika field manifest masih diterima, penulis plugin dapat tetap menggunakannya sampai dokumen dan diagnostik menyatakan sebaliknya. Kode baru sebaiknya memilih pengganti yang terdokumentasi, tetapi plugin yang sudah ada tidak boleh rusak selama rilis minor biasa.

Cara bermigrasi

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

// OpenClaw and Codex runtime dynamic toolsapi.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "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 { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

Referensi path 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 helper plugin bundel yang dicadangkan telah dihentikan dari peta ekspor SDK publik kecuali fasad kompatibilitas yang didokumentasikan secara eksplisit seperti shim plugin-sdk/discord yang sudah usang dan dipertahankan untuk paket @openclaw/discord@2026.3.13 yang telah dipublikasikan. Helper khusus owner 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 tugas. Jika Anda tidak dapat menemukan ekspor, periksa sumber di src/plugin-sdk/ atau tanyakan kepada maintainer kontrak generik mana yang seharusnya memilikinya.

Penghentian aktif

Penghentian yang lebih sempit yang berlaku di seluruh SDK Plugin, kontrak provider, permukaan runtime, dan manifest. Masing-masing masih berfungsi saat 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";

// Beforeapi.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // Afterapi.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

// Beforeapi.on("subagent_spawning", async () => ({  status: "ok",  threadBindingReady: true,  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },})); // Afterapi.on("subagent_spawned", async (event) => {  await observeSubagentLaunch(event);});

{  "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 untuk 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 jalan keluar sementara, bukan solusi permanen.

Terkait

• Memulai - bangun Plugin pertama Anda
• Ikhtisar SDK - referensi lengkap impor subpath
• Plugin Channel - membangun Plugin channel
• Plugin Provider - membangun Plugin provider
• Internal Plugin - pendalaman arsitektur
• Manifest Plugin - referensi skema manifest