Migrasi SDK Plugin

OpenClaw mengganti lapisan kompatibilitas mundur yang luas dengan arsitektur plugin modern yang dibangun dari impor kecil dan terfokus. Jika plugin Anda dibuat sebelum perubahan tersebut, panduan ini membantu memigrasikannya ke kontrak saat ini.

Yang berubah

Beberapa permukaan impor yang sangat terbuka sebelumnya memungkinkan plugin mengakses hampir semua hal dari satu titik masuk:

• openclaw/plugin-sdk dan openclaw/plugin-sdk/compat - mengekspor ulang puluhan helper selama SDK terfokus sedang dibangun. Kedua root tersebut kini telah dihapus; gunakan subpath terdokumentasi sebagai gantinya.
• openclaw/plugin-sdk/infra-runtime - barrel luas yang mencampurkan event sistem, status heartbeat, antrean pengiriman, helper fetch/proxy, helper file, tipe persetujuan, dan utilitas yang tidak terkait.
• openclaw/plugin-sdk/config-runtime - barrel konfigurasi luas yang dipertahankan hanya untuk jendela kompatibilitas berikutnya; helper langsung untuk memuat/menulis saat runtime telah dihapus.
• openclaw/extension-api - bridge yang telah dihapus dan memberi plugin akses langsung ke helper sisi host seperti runner agen tertanam.
• api.registerEmbeddedExtensionFactory(...) - hook khusus runner tertanam yang telah dihapus dan mengamati event runner tertanam seperti tool_result. Gunakan middleware hasil alat agen sebagai gantinya (lihat Migrasikan ekstensi hasil alat tertanam ke middleware).

SDK root, barrel kompatibilitas, bridge ekstensi, dan factory ekstensi tertanam telah dihapus. infra-runtime dan config-runtime tetap tersedia hanya untuk jendela berikutnya yang dicatat secara terpisah; plugin baru harus menggunakan subpath terfokus.

OpenClaw tidak menghapus atau menafsirkan ulang perilaku plugin terdokumentasi dalam perubahan yang sama dengan diperkenalkannya pengganti. Perubahan kontrak yang merusak kompatibilitas terlebih dahulu melalui adaptor kompatibilitas, diagnostik, dokumentasi, dan jendela penghentian. Hal tersebut berlaku untuk impor SDK, field manifes, API penyiapan, hook, dan perilaku pendaftaran runtime.

Alasannya

• Startup lambat - mengimpor satu helper memuat puluhan modul yang tidak terkait.
• Dependensi melingkar - ekspor ulang yang luas memudahkan terbentuknya siklus impor.
• Permukaan API yang tidak jelas - tidak ada cara untuk membedakan ekspor stabil dari ekspor internal.

Setiap openclaw/plugin-sdk/<subpath> kini merupakan modul kecil dan mandiri dengan kontrak terdokumentasi.

Seam kemudahan provider lama untuk channel bawaan juga telah dihapus - pintasan helper bermerek channel merupakan kemudahan privat mono-repo, 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 tersebut:

• 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 serta helper onboarding/konfigurasi di api.ts miliknya sendiri.

Kebijakan kompatibilitas

Pekerjaan kompatibilitas plugin eksternal mengikuti urutan ini:

1. Tambahkan kontrak baru.
2. Pertahankan perilaku lama yang terhubung melalui adaptor kompatibilitas.
3. Keluarkan diagnostik atau peringatan yang menyebutkan path lama dan penggantinya.
4. Cakup kedua path dalam pengujian.
5. Dokumentasikan penghentian dan jalur migrasinya.
6. Hapus hanya setelah jendela migrasi yang diumumkan, biasanya dalam rilis mayor.

Jika sebuah field manifes masih diterima, terus gunakan field tersebut hingga dokumentasi dan diagnostik menyatakan sebaliknya. Kode baru sebaiknya mengutamakan pengganti yang terdokumentasi; plugin yang sudah ada tidak boleh rusak selama rilis minor biasa.

Audit antrean migrasi saat ini dengan pnpm plugins:boundary-report:

pnpm plugins:boundary-report:ci berjalan dengan ketiga flag kegagalan. Setiap catatan kompatibilitas memiliki tanggal removeAfter yang eksplisit (bukan "rilis mayor berikutnya" yang samar) - laporan mengelompokkan catatan yang dihentikan berdasarkan tanggal tersebut, menghitung referensi kode/dokumentasi lokal, menampilkan impor SDK khusus pemilik lain yang dicadangkan, dan merangkum bridge SDK host memori privat. Subpath SDK yang dicadangkan harus memiliki penggunaan pemilik yang dilacak; ekspor cadangan yang tidak digunakan harus dihapus dari SDK publik.

Cara melakukan migrasi

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

// Alat runtime OpenClaw dan alat dinamis runtime Codex (hasil dapat// ditransformasi). Hasil alat native Codex juga diteruskan untuk pengamatan,// tetapi output yang ditransformasi tidak pernah mencapai model: kontrak hook// PostToolUse Codex tidak dapat menggantikan respons alat native.api.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"]  }}

// Sebelumconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Sesudahconst program = applyWindowsSpawnProgramPolicy({  candidate,  // Tetapkan ini hanya untuk pemanggil kompatibilitas tepercaya yang secara sengaja  // menerima fallback yang dimediasi shell.  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/

// Sebelum (lapisan kompatibilitas mundur yang tidak digunakan lagi)import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // Setelah (impor terfokus modern)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";

// Sebelum (jembatan extension-api yang tidak digunakan lagi)import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // Setelah (runtime yang diinjeksi)const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test my-plugin/

Referensi jalur impor

Peta ekspor paket publik adalah sumber kebenaran untuk subjalur SDK yang dapat diimpor. Gunakan panduan SDK berdasarkan topik yang ditautkan dari ikhtisar SDK dan utamakan subjalur publik terdokumentasi yang paling sempit. Inventaris compiler dalam scripts/lib/plugin-sdk-entrypoints.json juga memuat entri lokal privat yang digunakan untuk membangun plugin bawaan; keberadaannya di sana tidak menjadikannya ekspor paket publik.

Tabel ini adalah subset migrasi umum, bukan keseluruhan permukaan SDK. Inventaris titik masuk compiler berada di scripts/lib/plugin-sdk-entrypoints.json; ekspor paket dihasilkan dari subset publik.

Jalur pembantu khusus plugin bawaan telah dihentikan dari peta ekspor SDK publik, kecuali fasad kompatibilitas yang didokumentasikan secara eksplisit seperti shim plugin-sdk/discord yang tidak digunakan lagi dan dipertahankan untuk plugin eksternal yang masih mengimpor paket @openclaw/discord yang dipublikasikan secara langsung. Pembantu khusus pemilik berada di dalam paket plugin pemiliknya; perilaku host bersama dipindahkan melalui kontrak SDK generik seperti plugin-sdk/gateway-runtime, plugin-sdk/security-runtime, dan API plugin yang diinjeksi.

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.

Permukaan kompatibilitas yang dihapus

Penyisiran Juli 2026 menghapus barrel SDK root dan compat, jembatan API ekstensi, alias subjalur SDK yang kedaluwarsa, subjalur SDK yang tidak digunakan, serta ekspor publik untuk modul SDK khusus bawaan. Modul khusus bawaan tetap tersedia bagi pemiliknya di repositori melalui pemetaan build lokal privat; modul tersebut tidak dapat diimpor dari paket yang dipublikasikan.

Publikasi penyedia API global proses

registerApiProvider(...) dan unregisterApiProviders(...) dihapus dari openclaw/plugin-sdk/llm. Keduanya memublikasikan transportasi API ke state global proses, yang kemudian harus disalin oleh runtime model milik siklus hidup ke setiap registry yang telah disiapkan.

Plugin penyedia harus mendaftarkan penyedia inferensi teks melalui api.registerProvider(...). Kode dan pengujian milik host yang membuat ApiRegistry harus mendaftar langsung pada registry tersebut agar kepemilikan penyedia dan pembongkaran tetap terbatas pada runtime yang telah disiapkan.

Barrel pengujian privat

openclaw/plugin-sdk/testing bersifat lokal repo dan dikecualikan dari artefak paket yang dirilis, sehingga dihapus sebelum tanggal removeAfter 2026-07-28. Pengujian repositori menggunakan subjalur terfokus seperti plugin-sdk/plugin-test-runtime, plugin-sdk/channel-test-helpers, plugin-sdk/channel-target-testing, plugin-sdk/test-env, dan plugin-sdk/test-fixtures.

Referensi migrasi

Pemetaan ini mencakup permukaan yang dihapus pada Juli 2026 serta penghentian aktif dengan jangka waktu yang lebih panjang. Pemetaan merupakan panduan migrasi, bukan bukti bahwa permukaan lama masih tersedia; lihat registry kompatibilitas dan linimasa penghapusan untuk status terkini.

// Sebelumimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Setelahimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

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

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

{  "contracts": {    "externalAuthProviders": ["anthropic", "openai"]  }}

// Sebelumnyaconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Sesudahnyaconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Sebelumnyaimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Sesudahnyaimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";

Migrasi Talk dan suara waktu nyata

Kode suara waktu nyata, telefoni, rapat, dan Talk peramban berbagi satu pengontrol sesi Talk yang diekspor oleh openclaw/plugin-sdk/realtime-voice. Pengontrol tersebut memiliki amplop peristiwa Talk umum, status giliran aktif, status pengambilan, status audio keluaran, riwayat peristiwa terbaru, dan penolakan giliran usang. Plugin penyedia memiliki sesi waktu nyata khusus vendor. Plugin rapat-peramban menggunakan openclaw/plugin-sdk/meeting-runtime untuk mekanisme sesi, peramban, audio, host-node, konsultasi-agen, dan panggilan suara, lalu mengimplementasikan MeetingPlatformAdapter untuk aturan URL, skrip DOM, pemetaan tindakan manual, takarir, pembuatan, dan rencana akses masuk. API REST platform, OAuth, artefak, pemilih, dan nama wire tetap berada dalam plugin. Rencana izin peramban menerima URL rapat yang diminta agar setiap platform hanya dapat memberikan izin untuk origin yang didukungnya secara tepat. Runtime sesi juga harus menormalkan kesehatan langsung khusus platform setelah kepergian dari peramban dikonfirmasi; bidang transkrip historis dapat tetap ada, tetapi kesiapan takarir dan audio tidak boleh tetap aktif setelah keluar.

Semua permukaan bawaan berjalan pada pengontrol bersama: relay peramban, serah-terima ruang terkelola, waktu nyata panggilan suara, STT streaming panggilan suara, waktu nyata Google Meet, dan tekan-untuk-bicara native. Gateway mengiklankan satu kanal peristiwa Talk langsung dalam hello-ok.features.events: talk.event.

Kode baru tidak boleh memanggil createTalkEventSequencer(...) secara langsung kecuali mengimplementasikan adaptor tingkat rendah atau fixture pengujian. Gunakan pengontrol bersama agar peristiwa dengan cakupan giliran tidak dapat dipancarkan tanpa id giliran, panggilan turnEnd / turnCancel yang usang tidak dapat menghapus giliran aktif yang lebih baru, dan peristiwa siklus hidup audio keluaran tetap konsisten di seluruh telefoni, rapat, relay peramban, serah-terima ruang terkelola, dan klien Talk native.

Bentuk API publik:

// API sesi Talk milik Gateway.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 }); // API sesi penyedia milik klien.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/websocket-penyedia milik peramban menggunakan talk.client.create, karena peramban memiliki negosiasi penyedia dan transportasi media, sedangkan Gateway memiliki kredensial, instruksi, dan kebijakan alat. talk.session.* adalah permukaan umum yang dikelola Gateway untuk waktu nyata gateway-relay, transkripsi gateway-relay, dan sesi STT/TTS native ruang terkelola.

Konfigurasi lama yang menempatkan pemilih waktu nyata di samping talk.provider / talk.providers harus diperbaiki dengan openclaw doctor --fix; Talk runtime tidak menafsirkan ulang konfigurasi penyedia ucapan/TTS sebagai konfigurasi penyedia waktu nyata.

Kombinasi talk.session.create yang didukung sengaja dibatasi:

Peta metode untuk pembaca yang bermigrasi dari keluarga talk.realtime.* / talk.transcription.* / talk.handoff.* lama (semuanya telah dihapus):

Kosakata kontrol terpadu juga sengaja dibuat terbatas:

Jangan memperkenalkan kasus khusus penyedia atau platform di inti agar ini berfungsi. Inti mengelola semantik sesi Talk. Plugin penyedia mengelola penyiapan sesi vendor. Voice-call dan Google Meet mengelola adaptor telepon/pertemuan. Browser dan aplikasi native mengelola UX perekaman/pemutaran perangkat.

Linimasa penghapusan

Subpath SDK publik yang tersisa di bawah ini memiliki jangka waktu penghapusan yang didukung registri. Baris 30 Juli dihapus setelah penyisiran awal yang diotorisasi pengelola: subpath yang tidak digunakan dihapus, alias kompatibilitas sebelumnya dihapus, dan modul khusus bawaan diturunkan menjadi pemetaan build lokal privat.

Semua Plugin inti telah dimigrasikan. Plugin eksternal harus bermigrasi sebelum rilis mayor berikutnya. Jalankan pnpm plugins:boundary-report untuk melihat catatan kompatibilitas yang tenggatnya paling dekat bagi permukaan yang digunakan Plugin Anda.

Menonaktifkan peringatan untuk sementara

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 - buat Plugin pertama Anda
• Ikhtisar SDK - referensi lengkap impor subpath
• Plugin Saluran - membuat Plugin saluran
• Plugin Penyedia - membuat Plugin penyedia
• Internal Plugin - pembahasan mendalam tentang arsitektur
• Manifes Plugin - referensi skema manifes