Migrasi Plugin SDK

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, 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 Plugin lama berbasis hook tetap berfungsi sementara 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 - bridge yang memberi Plugin akses langsung ke helper sisi host seperti runner agent tertanam.
• api.registerEmbeddedExtensionFactory(...) - hook ekstensi bundled khusus Pi yang sudah dihapus yang dapat mengamati event embedded-runner seperti tool_result.

Permukaan impor yang luas sekarang deprecated. Permukaan tersebut masih berfungsi saat runtime, tetapi Plugin baru tidak boleh menggunakannya, dan Plugin yang sudah ada sebaiknya bermigrasi sebelum rilis major berikutnya menghapusnya. API pendaftaran embedded extension factory khusus Pi telah dihapus; gunakan middleware hasil-tool sebagai gantinya.

OpenClaw tidak menghapus atau menafsirkan ulang perilaku Plugin yang terdokumentasi dalam perubahan yang sama saat pengganti diperkenalkan. Perubahan kontrak yang breaking harus terlebih dahulu melalui adapter kompatibilitas, diagnostik, docs, 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 sirkular - re-export yang luas memudahkan pembuatan siklus impor
• Permukaan API tidak jelas - tidak ada cara untuk mengetahui export mana yang stabil vs internal

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

Seam kemudahan provider legacy untuk channel bundled juga sudah dihapus. Seam helper bermerek channel adalah shortcut 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 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 suara realtime, telephony, meeting, dan Talk browser berpindah dari pembukuan 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 capture, playback, telephony, dan kekhususan meeting.

Migrasi Talk ini sengaja breaking-clean:

1. Simpan primitive controller/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. Iklankan 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 sebaiknya tidak memanggil createTalkEventSequencer(...) secara langsung kecuali sedang mengimplementasikan adapter level rendah atau fixture test. Pilih controller bersama agar event dengan cakupan turn tidak dapat dipancarkan tanpa turn id, panggilan turnEnd / turnCancel yang stale tidak dapat menghapus turn aktif yang lebih baru, dan event lifecycle output-audio tetap konsisten di telephony, meeting, browser relay, managed-room handoff, dan client 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 });
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, transkripsi gateway-relay, dan sesi native STT/TTS managed-room.

Config legacy yang menempatkan selector realtime di samping talk.provider / talk.providers sebaiknya 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 kecil:

Peta method yang dihapus:

Kosakata kontrol terpadu juga sengaja sempit:

Jangan memperkenalkan kasus khusus provider atau platform di core untuk membuat ini berfungsi. Core memiliki semantik sesi Talk. Plugin provider memiliki setup sesi vendor. Voice-call dan Google Meet memiliki adapter telephony/meeting. Aplikasi browser dan 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 dihubungkan melalui adapter kompatibilitas
3. pancarkan diagnostik atau warning yang menyebutkan jalur lama dan penggantinya
4. cakup kedua jalur dalam test
5. dokumentasikan deprecation dan jalur migrasi
6. hapus hanya setelah jendela migrasi yang diumumkan, biasanya dalam rilis major

Pengelola dapat mengaudit antrean migrasi saat ini dengan pnpm plugins:boundary-report. Gunakan pnpm plugins:boundary-report:summary untuk jumlah yang ringkas, --owner <id> untuk satu plugin atau pemilik kompatibilitas, dan pnpm plugins:boundary-report:ci ketika gerbang CI harus gagal pada catatan kompatibilitas yang jatuh tempo, impor SDK tercadangkan lintas-pemilik, atau subjalur SDK tercadangkan yang tidak digunakan. Laporan mengelompokkan catatan kompatibilitas yang tidak digunakan lagi berdasarkan tanggal penghapusan, menghitung referensi kode/dokumen lokal, menampilkan impor SDK tercadangkan lintas-pemilik, dan merangkum jembatan SDK host memori privat agar pembersihan kompatibilitas tetap eksplisit alih-alih bergantung pada pencarian ad hoc. Subjalur SDK tercadangkan harus memiliki penggunaan pemilik yang terlacak; ekspor helper tercadangkan yang tidak digunakan harus dihapus dari SDK publik.

Jika sebuah bidang manifes masih diterima, penulis plugin dapat terus menggunakannya hingga dokumentasi dan diagnostik menyatakan sebaliknya. Kode baru sebaiknya mengutamakan 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 ??= {};
  },
});

// Pi and Codex runtime dynamic tools
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["pi", "codex"],
});

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

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

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 build
pnpm test -- my-plugin/

# Referensi jalur impor

Tabel ini sengaja merupakan subset migrasi umum, bukan seluruh permukaan SDK. Daftar lengkap 200+ titik masuk berada di scripts/lib/plugin-sdk-entrypoints.json.

Seam pembantu bundled-plugin yang dicadangkan telah dipensiunkan dari peta ekspor SDK publik kecuali facade kompatibilitas yang didokumentasikan secara eksplisit seperti shim plugin-sdk/discord yang tidak digunakan lagi tetapi 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 pekerjaan. 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 penyedia, 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.

// Before
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// After
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

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

// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

# Linimasa penghapusan

Semua plugin inti sudah dimigrasikan. Plugin eksternal sebaiknya 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 run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

Ini adalah jalan keluar sementara, bukan solusi permanen.

# Terkait

• Mulai Cepat - bangun plugin pertama Anda
• Ringkasan SDK - referensi impor subpath lengkap
• Plugin Saluran - membangun plugin saluran
• Plugin Penyedia - membangun plugin penyedia
• Internal Plugin - pendalaman arsitektur
• Manifest Plugin - referensi skema manifest