Internal Plugin

Ini adalah referensi arsitektur mendalam untuk sistem Plugin OpenClaw. Untuk panduan praktis, mulailah dengan salah satu halaman khusus di bawah ini.

Model kapabilitas publik

Kapabilitas adalah model Plugin native publik di dalam OpenClaw. Setiap Plugin OpenClaw native didaftarkan pada satu atau beberapa jenis kapabilitas:

Sikap terhadap kompatibilitas eksternal

Model kapabilitas telah tersedia di inti dan saat ini digunakan oleh Plugin bawaan/native, tetapi kompatibilitas Plugin eksternal masih memerlukan standar yang lebih ketat daripada "karena diekspor, maka sudah dibekukan."

Pendaftaran kapabilitas adalah arah yang dituju. Hook lama tetap menjadi jalur paling aman tanpa kerusakan bagi Plugin eksternal selama transisi. Tidak semua subjalur pembantu yang diekspor memiliki kedudukan yang sama — utamakan kontrak terdokumentasi yang sempit daripada ekspor pembantu insidental.

Bentuk Plugin

OpenClaw mengklasifikasikan setiap Plugin yang dimuat ke dalam suatu bentuk berdasarkan perilaku pendaftaran aktualnya (bukan hanya metadata statis):

Gunakan openclaw plugins inspect <id> untuk melihat bentuk dan perincian kapabilitas suatu Plugin. Lihat referensi CLI untuk detailnya.

Hook lama

Hook before_agent_start tetap didukung sebagai jalur kompatibilitas bagi Plugin khusus hook. Plugin lama di dunia nyata masih bergantung padanya.

Arah:

• pertahankan agar tetap berfungsi
• dokumentasikan sebagai fitur lama
• utamakan before_model_resolve untuk pekerjaan penggantian model/penyedia
• utamakan before_prompt_build untuk pekerjaan perubahan prompt
• hapus hanya setelah penggunaan nyata menurun dan cakupan fixture membuktikan keamanan migrasi

Sinyal kompatibilitas

openclaw doctor, openclaw plugins inspect <id>, openclaw status --all, dan openclaw plugins doctor menampilkan pemberitahuan kompatibilitas berikut:

Tidak satu pun sinyal saran/peringatan tersebut merusak Plugin Anda saat ini. Sinyal ini juga muncul di openclaw status --all dan openclaw plugins doctor.

Ikhtisar arsitektur

Sistem Plugin OpenClaw memiliki empat lapisan:

Khusus untuk CLI Plugin, penemuan perintah akar dibagi menjadi dua fase:

• metadata saat penguraian berasal dari registerCli(..., { descriptors: [...] })
• modul CLI Plugin yang sebenarnya dapat tetap dimuat secara lambat dan didaftarkan saat pemanggilan pertama

Hal tersebut mempertahankan kode CLI milik Plugin di dalam Plugin, sekaligus tetap memungkinkan OpenClaw mencadangkan nama perintah akar sebelum penguraian.

Batas desain yang penting:

• validasi manifes/konfigurasi harus bekerja berdasarkan metadata manifes/skema tanpa menjalankan kode Plugin
• penemuan kapabilitas native dapat memuat kode entri Plugin tepercaya untuk membangun snapshot registri yang tidak mengaktifkan apa pun
• perilaku runtime native berasal dari jalur register(api) modul Plugin dengan api.registrationMode === "full"

Pemisahan tersebut memungkinkan OpenClaw memvalidasi konfigurasi, menjelaskan Plugin yang hilang/dinonaktifkan, dan membangun petunjuk UI/skema sebelum runtime penuh aktif.

Snapshot metadata Plugin dan tabel pencarian

Saat dimulai, Gateway membangun satu PluginMetadataSnapshot untuk snapshot konfigurasi saat ini. Snapshot ini hanya berisi metadata: menyimpan indeks Plugin yang terinstal, registri manifes, diagnostik manifes, peta pemilik, penormal ID Plugin, dan rekaman manifes. Snapshot ini tidak menyimpan modul Plugin yang dimuat, SDK penyedia, isi paket, atau ekspor runtime.

Validasi konfigurasi yang memahami Plugin, pengaktifan otomatis saat dimulai, dan bootstrap Plugin Gateway menggunakan snapshot tersebut daripada membangun ulang metadata manifes/indeks secara terpisah. PluginLookUpTable diturunkan dari snapshot yang sama dan menambahkan rencana Plugin awal untuk konfigurasi runtime saat ini.

Setelah dimulai, Gateway mempertahankan snapshot metadata saat ini sebagai produk runtime yang dapat diganti. Penemuan penyedia runtime berulang dapat meminjam snapshot tersebut daripada merekonstruksi indeks yang terinstal dan registri manifes untuk setiap proses katalog penyedia. Snapshot dihapus atau diganti saat Gateway dimatikan, ketika konfigurasi/inventaris Plugin berubah, dan ketika indeks yang terinstal ditulis; pemanggil kembali menggunakan jalur manifes/indeks dingin ketika tidak ada snapshot saat ini yang kompatibel. Pemeriksaan kompatibilitas harus mencakup akar penemuan Plugin seperti plugins.load.paths dan ruang kerja agen default, karena Plugin ruang kerja merupakan bagian dari cakupan metadata.

Snapshot dan tabel pencarian mempertahankan keputusan awal yang berulang pada jalur cepat:

• kepemilikan kanal
• penundaan dimulainya kanal
• ID Plugin awal
• kepemilikan penyedia dan backend CLI
• kepemilikan penyedia penyiapan, alias perintah, penyedia katalog model, dan kontrak manifes
• validasi skema konfigurasi Plugin dan skema konfigurasi kanal
• keputusan pengaktifan otomatis saat dimulai

Batas keamanannya adalah penggantian snapshot, bukan mutasi. Bangun ulang snapshot ketika konfigurasi, inventaris Plugin, rekaman instalasi, atau kebijakan indeks persisten berubah. Jangan memperlakukannya sebagai registri global luas yang dapat dimutasi, dan jangan menyimpan snapshot historis tanpa batas. Pemuatan Plugin runtime tetap terpisah dari snapshot metadata agar keadaan runtime yang sudah usang tidak dapat disembunyikan di balik cache metadata.

Aturan cache didokumentasikan dalam Internal arsitektur Plugin: metadata manifes dan penemuan selalu mutakhir kecuali pemanggil menyimpan snapshot, tabel pencarian, atau registri manifes eksplisit untuk alur saat ini. Cache metadata tersembunyi dan TTL berdasarkan waktu dinding bukan bagian dari pemuatan Plugin. Hanya cache pemuat runtime, modul, dan artefak dependensi yang boleh bertahan setelah kode atau artefak yang terinstal benar-benar dimuat.

Beberapa pemanggil jalur dingin masih merekonstruksi registri manifes secara langsung dari indeks Plugin terinstal yang dipersistenkan, alih-alih menerima PluginLookUpTable Gateway. Jalur tersebut kini merekonstruksi registri sesuai permintaan; utamakan meneruskan tabel pencarian saat ini atau registri manifes eksplisit melalui alur runtime ketika pemanggil sudah memilikinya.

Perencanaan aktivasi

Perencanaan aktivasi merupakan bagian dari bidang kontrol. Pemanggil dapat menanyakan Plugin mana yang relevan dengan perintah, penyedia, saluran, rute, kerangka agen, atau kapabilitas tertentu sebelum memuat registri runtime yang lebih luas.

Perencana menjaga kompatibilitas perilaku manifes saat ini:

• bidang activation.* adalah petunjuk eksplisit bagi perencana
• providers, channels, commandAliases, setup.providers, contracts.tools, dan hook tetap menjadi fallback kepemilikan manifes
• API perencana khusus ID tetap tersedia bagi pemanggil yang sudah ada
• API rencana melaporkan label alasan agar diagnostik dapat membedakan petunjuk eksplisit dari fallback kepemilikan

Plugin saluran dan alat pesan bersama

Plugin saluran tidak perlu mendaftarkan alat kirim/edit/reaksi terpisah untuk tindakan obrolan normal. OpenClaw mempertahankan satu alat message bersama di inti, sementara Plugin saluran memiliki penemuan dan eksekusi khusus saluran di baliknya.

Batas saat ini adalah:

• inti memiliki host alat message bersama, pengawatan prompt, pencatatan sesi/utas, dan pengiriman eksekusi
• Plugin saluran memiliki penemuan tindakan terbatas, penemuan kapabilitas, dan setiap fragmen skema khusus saluran
• Plugin saluran memiliki tata bahasa percakapan sesi khusus penyedia, seperti cara ID percakapan mengodekan ID utas atau mewarisinya dari percakapan induk
• Plugin saluran menjalankan tindakan akhir melalui adaptor tindakannya

Untuk Plugin saluran, permukaan SDK-nya adalah ChannelMessageActionAdapter.describeMessageTool(...). Panggilan penemuan terpadu tersebut memungkinkan Plugin mengembalikan tindakan yang terlihat, kapabilitas, dan kontribusi skemanya secara bersamaan agar bagian-bagian tersebut tidak menyimpang satu sama lain.

Saat parameter alat pesan khusus saluran membawa sumber media seperti jalur lokal atau URL media jarak jauh, Plugin juga harus mengembalikan mediaSourceParams dari describeMessageTool(...). Inti menggunakan daftar eksplisit tersebut untuk menerapkan normalisasi jalur sandbox dan petunjuk akses media keluar tanpa menanamkan nama parameter milik Plugin secara langsung. Utamakan peta yang dibatasi per tindakan di sana, bukan satu daftar datar untuk seluruh saluran, agar parameter media khusus profil tidak dinormalisasi pada tindakan yang tidak terkait seperti send.

Inti meneruskan cakupan runtime ke langkah penemuan tersebut. Bidang penting meliputi:

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• requesterSenderId masuk yang tepercaya

Hal ini penting bagi Plugin yang peka terhadap konteks. Saluran dapat menyembunyikan atau menampilkan tindakan pesan berdasarkan akun aktif, ruang/utas/pesan saat ini, atau identitas peminta tepercaya tanpa menanamkan percabangan khusus saluran secara langsung dalam alat message inti.

Inilah alasan perubahan perutean runner tertanam tetap merupakan pekerjaan Plugin: runner bertanggung jawab meneruskan identitas obrolan/sesi saat ini ke batas penemuan Plugin agar alat message bersama menampilkan permukaan milik saluran yang tepat untuk giliran saat ini.

Untuk pembantu eksekusi milik saluran, Plugin bawaan harus mempertahankan runtime eksekusi di dalam modul Plugin-nya sendiri. Inti tidak lagi memiliki runtime tindakan pesan Discord, Slack, Telegram, atau WhatsApp di bawah src/agents/tools. Kami tidak menerbitkan subjalur plugin-sdk/*-action-runtime terpisah, dan Plugin bawaan harus mengimpor kode runtime lokalnya sendiri secara langsung dari modul milik Plugin-nya.

Batas yang sama berlaku untuk celah SDK bernama penyedia secara umum: inti tidak boleh mengimpor barrel kemudahan khusus saluran untuk Discord, Signal, Slack, WhatsApp, atau Plugin serupa. Jika inti memerlukan suatu perilaku, gunakan barrel api.ts / runtime-api.ts milik Plugin bawaan itu sendiri atau tingkatkan kebutuhan tersebut menjadi kapabilitas generik yang sempit di SDK bersama.

Plugin bawaan mengikuti aturan yang sama. runtime-api.ts milik Plugin bawaan tidak boleh mengekspor ulang fasad bermereknya sendiri, yaitu openclaw/plugin-sdk/<plugin-id>. Fasad bermerek tersebut tetap menjadi shim kompatibilitas bagi Plugin eksternal dan konsumen lama, tetapi Plugin bawaan harus menggunakan ekspor lokal beserta subjalur SDK generik yang sempit seperti openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/runtime-store, atau openclaw/plugin-sdk/webhook-ingress. Kode baru tidak boleh menambahkan fasad SDK khusus ID Plugin kecuali batas kompatibilitas untuk ekosistem eksternal yang sudah ada mengharuskannya.

Khusus untuk jajak pendapat, terdapat dua jalur eksekusi:

• outbound.sendPoll adalah dasar bersama bagi saluran yang sesuai dengan model jajak pendapat umum
• actions.handleAction("poll") adalah jalur yang diutamakan untuk semantik jajak pendapat khusus saluran atau parameter jajak pendapat tambahan

Inti kini menunda penguraian jajak pendapat bersama hingga setelah pengiriman jajak pendapat Plugin menolak tindakan tersebut, sehingga penangan jajak pendapat milik Plugin dapat menerima bidang jajak pendapat khusus saluran tanpa terlebih dahulu diblokir oleh pengurai jajak pendapat generik.

Lihat Internal arsitektur Plugin untuk urutan startup lengkap.

Model kepemilikan kapabilitas

OpenClaw memperlakukan Plugin natif sebagai batas kepemilikan untuk sebuah perusahaan atau fitur, bukan sebagai kumpulan integrasi yang tidak berkaitan.

Artinya:

• Plugin perusahaan biasanya harus memiliki semua permukaan perusahaan tersebut yang berhadapan dengan OpenClaw
• Plugin fitur biasanya harus memiliki seluruh permukaan fitur yang diperkenalkannya
• saluran harus menggunakan kapabilitas inti bersama alih-alih mengimplementasikan ulang perilaku penyedia secara ad hoc

Keadaan akhir yang dituju adalah:

• permukaan vendor yang berhadapan dengan OpenClaw berada dalam satu Plugin meskipun mencakup model teks, ucapan, gambar, dan video
• vendor lain dapat melakukan hal yang sama untuk area permukaan mereka sendiri
• saluran tidak perlu mengetahui Plugin vendor mana yang memiliki penyedia; saluran menggunakan kontrak kapabilitas bersama yang diekspos oleh inti

Inilah perbedaan utamanya:

• Plugin = batas kepemilikan
• kapabilitas = kontrak inti yang dapat diimplementasikan atau digunakan oleh beberapa Plugin

Jadi, jika OpenClaw menambahkan domain baru seperti video, pertanyaan pertama bukanlah "penyedia mana yang harus menanamkan penanganan video secara langsung?" Pertanyaan pertama adalah "apa kontrak kapabilitas video inti?" Setelah kontrak tersebut tersedia, Plugin vendor dapat mendaftar terhadapnya dan Plugin saluran/fitur dapat menggunakannya.

Jika kapabilitas tersebut belum tersedia, langkah yang tepat biasanya adalah:

Hal ini menjaga kepemilikan tetap eksplisit sekaligus menghindari perilaku inti yang bergantung pada satu vendor atau jalur kode khusus Plugin sekali pakai.

Pelapisan kapabilitas

Gunakan model mental ini saat menentukan lokasi kode:

Sebagai contoh, TTS mengikuti bentuk ini:

• inti memiliki kebijakan TTS pada waktu balasan, urutan fallback, preferensi, dan pengiriman saluran
• elevenlabs, google, microsoft, dan openai memiliki implementasi sintesis
• voice-call menggunakan pembantu runtime TTS telepon

Pola yang sama harus diutamakan untuk kapabilitas mendatang.

Contoh Plugin perusahaan multikapabilitas

Plugin perusahaan harus terasa kohesif dari luar. Jika OpenClaw memiliki kontrak bersama untuk model, ucapan, transkripsi waktu nyata, suara waktu nyata, pemahaman media, pembuatan gambar, pembuatan video, pengambilan web, dan pencarian web, vendor dapat memiliki semua permukaannya di satu tempat:

    describeImageWithModel,  transcribeOpenAiCompatibleAudio,} from "openclaw/plugin-sdk/media-understanding"; const plugin: OpenClawPluginDefinition = {  id: "exampleai",  name: "ExampleAI",  register(api) {    api.registerProvider({      id: "exampleai",      // auth/model catalog/runtime hooks    });     api.registerSpeechProvider({      id: "exampleai",      // vendor speech config — implement the SpeechProviderPlugin interface directly    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      async describeImage(req) {        return describeImageWithModel({          ...req,          provider: "exampleai",        });      },      async transcribeAudio(req) {        return transcribeOpenAiCompatibleAudio({          ...req,          provider: "exampleai",        });      },    });     api.registerWebSearchProvider(      createPluginBackedWebSearchProvider({        id: "exampleai-search",        // credential + fetch logic      }),    );  },}; export default plugin;

Yang penting bukanlah nama pembantu yang persis. Bentuknya yang penting:

• satu Plugin memiliki permukaan vendor
• inti tetap memiliki kontrak kapabilitas
• saluran dan Plugin fitur menggunakan pembantu api.runtime.*, bukan kode vendor
• pengujian kontrak dapat menegaskan bahwa Plugin mendaftarkan kapabilitas yang diklaim sebagai miliknya

Contoh kapabilitas: pemahaman video

OpenClaw sudah memperlakukan pemahaman gambar/audio/video sebagai satu kapabilitas bersama. Model kepemilikan yang sama berlaku di sana:

Hal ini menghindari penanaman asumsi video milik satu penyedia ke dalam inti. Plugin memiliki permukaan vendor; inti memiliki kontrak kapabilitas dan perilaku fallback.

Pembuatan video sudah menggunakan urutan yang sama: inti memiliki kontrak kapabilitas bertipe dan pembantu runtime, sementara Plugin vendor mendaftarkan implementasi api.registerVideoGenerationProvider(...) terhadapnya.

Memerlukan daftar periksa peluncuran yang konkret? Lihat Panduan Praktis Kapabilitas.

Kontrak dan penegakan

Permukaan API plugin sengaja dibuat bertipe dan dipusatkan di OpenClawPluginApi. Kontrak tersebut menentukan titik pendaftaran yang didukung dan pembantu runtime yang dapat diandalkan oleh plugin.

Mengapa ini penting:

• pembuat plugin mendapatkan satu standar internal yang stabil
• inti dapat menolak kepemilikan ganda, seperti dua plugin yang mendaftarkan id penyedia yang sama
• proses awal dapat menampilkan diagnostik yang dapat ditindaklanjuti untuk pendaftaran yang tidak valid
• pengujian kontrak dapat menegakkan kepemilikan plugin bawaan dan mencegah penyimpangan tersembunyi

Ada dua lapisan penegakan:

Dampak praktisnya adalah OpenClaw mengetahui sejak awal plugin mana yang memiliki permukaan tertentu. Hal ini memungkinkan inti dan kanal berpadu dengan lancar karena kepemilikan dideklarasikan, diberi tipe, dan dapat diuji, bukan tersirat.

Hal yang termasuk dalam kontrak

Jika ragu, naikkan tingkat abstraksinya: tentukan kapabilitas terlebih dahulu, lalu biarkan plugin terhubung dengannya.

Model eksekusi

Plugin native OpenClaw berjalan dalam proses bersama Gateway. Plugin tersebut tidak berada dalam sandbox. Plugin native yang dimuat memiliki batas kepercayaan tingkat proses yang sama dengan kode inti.

Bundel yang kompatibel secara default lebih aman karena OpenClaw saat ini memperlakukannya sebagai paket metadata/konten. Dalam rilis saat ini, hal tersebut terutama berarti Skills yang dibundel.

Gunakan daftar izin dan jalur instalasi/pemuatan eksplisit untuk plugin nonbawaan. Perlakukan plugin ruang kerja sebagai kode untuk masa pengembangan, bukan sebagai nilai default produksi.

Untuk nama paket ruang kerja bawaan, pertahankan id plugin agar berpatokan pada nama npm: secara default @openclaw/<id>, atau akhiran bertipe yang disetujui seperti -provider, -plugin, -speech, -sandbox, atau -media-understanding ketika paket tersebut sengaja mengekspos peran plugin yang lebih sempit.

Batas ekspor

OpenClaw mengekspor kapabilitas, bukan kemudahan implementasi.

Pertahankan pendaftaran kapabilitas sebagai API publik. Pangkas ekspor pembantu yang bukan bagian dari kontrak:

• subjalur pembantu khusus plugin bawaan
• subjalur pengaturan runtime yang tidak ditujukan sebagai API publik
• pembantu kemudahan khusus vendor
• pembantu penyiapan/orientasi awal yang merupakan detail implementasi

Subjalur pembantu khusus plugin bawaan yang dicadangkan telah dihentikan dari peta ekspor SDK yang dihasilkan. Pertahankan pembantu khusus pemilik di dalam paket plugin pemiliknya; promosikan hanya perilaku host yang dapat digunakan kembali ke kontrak SDK generik seperti plugin-sdk/gateway-runtime, plugin-sdk/security-runtime, dan plugin-sdk/plugin-config-runtime.

Internal dan referensi

Untuk alur pemuatan, model registri, hook runtime penyedia, rute HTTP Gateway, skema alat pesan, resolusi target kanal, katalog penyedia, plugin mesin konteks, dan panduan menambahkan kapabilitas baru, lihat Internal arsitektur plugin.

Terkait

• Membangun plugin
• Manifes plugin
• Penyiapan SDK plugin