Internal Plugin

Ini adalah referensi arsitektur mendalam untuk sistem plugin OpenClaw. Untuk panduan praktis, mulailah dengan salah satu halaman yang berfokus pada topik tertentu di bawah ini.

Model kapabilitas publik

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

Sikap terhadap kompatibilitas eksternal

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

Pendaftaran kapabilitas adalah arah yang dituju. Hook lama tetap menjadi jalur teraman tanpa kerusakan bagi plugin eksternal selama transisi. Tidak semua subjalur pembantu yang diekspor setara — utamakan kontrak sempit yang terdokumentasi 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.

Sinyal kompatibilitas

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

Tidak satu pun sinyal anjuran/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 root dibagi menjadi dua fase:

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

Hal itu mempertahankan kode CLI milik plugin di dalam plugin sambil tetap memungkinkan OpenClaw mencadangkan nama perintah root sebelum penguraian.

Batas desain yang penting:

• validasi manifes/konfigurasi harus berfungsi dari metadata manifes/skema tanpa mengeksekusi kode plugin
• penemuan kapabilitas native dapat memuat kode entri plugin tepercaya untuk membangun snapshot registri yang tidak mengaktifkan
• 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, serta membangun petunjuk UI/skema sebelum runtime lengkap aktif.

Snapshot metadata plugin dan tabel pencarian

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

Validasi konfigurasi yang memahami plugin, pengaktifan otomatis saat mulai, dan bootstrap plugin Gateway menggunakan snapshot tersebut, alih-alih 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 alih-alih merekonstruksi indeks yang terinstal dan registri manifes untuk setiap lintasan katalog penyedia. Snapshot dihapus atau diganti saat Gateway dimatikan, ketika konfigurasi/inventaris plugin berubah, dan ketika indeks yang terinstal ditulis; pemanggil kembali ke jalur manifes/indeks dingin jika tidak ada snapshot saat ini yang kompatibel. Pemeriksaan kompatibilitas harus mencakup root 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 berulang pada jalur cepat:

• kepemilikan saluran
• permulaan saluran yang ditangguhkan
• 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 saluran
• keputusan pengaktifan otomatis saat mulai

Batas keamanannya adalah penggantian snapshot, bukan mutasi. Bangun ulang snapshot ketika konfigurasi, inventaris plugin, catatan 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 status runtime yang kedaluwarsa tidak dapat disembunyikan di balik cache metadata.

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

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

Perencanaan aktivasi

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

Perencana mempertahankan kompatibilitas perilaku manifes saat ini:

• bidang activation.* adalah petunjuk perencana eksplisit
• providers, channels, commandAliases, setup.providers, contracts.tools, dan hook tetap menjadi fallback kepemilikan manifes
• API perencana khusus id tetap tersedia bagi pemanggil yang 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 biasa. OpenClaw mempertahankan satu alat message bersama di inti, sedangkan 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 diwariskan dari percakapan induk
• plugin saluran mengeksekusi tindakan akhir melalui adaptor tindakannya

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

Nama tindakan pesan menggunakan kosakata tertutup yang sengaja dimiliki inti agar setiap transportasi dapat merender setiap tindakan. Plugin menambahkan nama tindakan melalui PR inti; pendaftaran saat runtime sengaja tidak didukung.

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 mengodekan nama parameter milik plugin secara permanen. Utamakan peta yang dicakup 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 tepercaya

Hal tersebut penting bagi plugin yang peka terhadap konteks. Sebuah saluran dapat menyembunyikan atau menampilkan tindakan pesan berdasarkan akun aktif, ruang/utas/pesan saat ini, atau identitas pemohon tepercaya tanpa mengodekan cabang khusus saluran secara permanen 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 terbundel harus menyimpan runtime eksekusi di dalam modul pluginnya sendiri. Inti tidak lagi memiliki runtime tindakan pesan Discord, Slack, Telegram, atau WhatsApp di bawah src/agents/tools. Kami tidak memublikasikan subjalur plugin-sdk/*-action-runtime terpisah, dan plugin terbundel harus mengimpor kode runtime lokalnya sendiri secara langsung dari modul milik plugin tersebut.

Batas yang sama berlaku bagi seam SDK bernama penyedia secara umum: inti tidak boleh mengimpor barrel praktis khusus saluran untuk Discord, Signal, Slack, WhatsApp, atau plugin serupa. Jika inti memerlukan suatu perilaku, gunakan barrel api.ts / runtime-api.ts milik plugin terbundel itu sendiri atau promosikan kebutuhan tersebut menjadi kapabilitas generik sempit dalam SDK bersama.

Plugin terbundel mengikuti aturan yang sama. runtime-api.ts milik plugin terbundel tidak boleh mengekspor ulang fasad openclaw/plugin-sdk/<plugin-id> bermereknya sendiri. Fasad bermerek tersebut tetap menjadi shim kompatibilitas bagi plugin eksternal dan konsumen lama, tetapi plugin terbundel harus menggunakan ekspor lokal ditambah subjalur SDK generik 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 memerlukannya.

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 pengendali 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 native sebagai batas kepemilikan bagi sebuah perusahaan atau fitur, bukan sebagai kumpulan integrasi yang tidak saling terkait.

Artinya:

• plugin perusahaan biasanya harus memiliki seluruh permukaan perusahaan tersebut yang menghadap 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

Kondisi akhir yang dimaksud adalah:

• permukaan vendor yang menghadap OpenClaw berada dalam satu plugin meskipun mencakup model teks, ujaran, gambar, dan video
• vendor lain dapat melakukan hal yang sama untuk area permukaannya sendiri
• saluran tidak memedulikan 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 mengodekan penanganan video secara permanen?" 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 tempat kode seharusnya berada:

Sebagai contoh, TTS mengikuti bentuk ini:

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

Pola yang sama harus diutamakan untuk kapabilitas mendatang.

Contoh plugin perusahaan multi-kapabilitas

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

  export default definePluginEntry({  id: "exampleai",  name: "ExampleAI",  description: "Model dan kapabilitas media ExampleAI.",  register(api) {    api.registerProvider({      id: "exampleai",      // hook autentikasi/katalog model/runtime    });     api.registerSpeechProvider({      id: "exampleai",      // konfigurasi ujaran vendor — implementasikan antarmuka SpeechProviderPlugin secara langsung    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      describeImage: (req) => exampleAiMedia.describeImage(req),      transcribeAudio: (req) => exampleAiMedia.transcribeAudio(req),      describeVideo: (req) => exampleAiMedia.describeVideo(req),    });     api.registerWebSearchProvider({      id: "exampleai-search",      createTool() {        // Kembalikan alat pencarian web milik vendor.      },    });  },});

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

• satu plugin memiliki permukaan vendor
• inti tetap memiliki kontrak kapabilitas
• penerjemahan permintaan penyedia dan pembantu HTTP tetap berada di plugin vendor
• saluran dan plugin fitur menggunakan pembantu api.runtime.*, bukan kode vendor
• pengujian kontrak dapat memastikan bahwa plugin mendaftarkan kapabilitas yang diklaim dimilikinya

Contoh kapabilitas: pemahaman video

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

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

Pembuatan video sudah menggunakan urutan yang sama: core memiliki kontrak kapabilitas bertipe dan pembantu runtime, sementara plugin vendor mendaftarkan implementasi api.registerVideoGenerationProvider(...) terhadap kontrak tersebut.

Memerlukan daftar periksa peluncuran yang konkret? Lihat Buku Panduan 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 hal ini penting:

• penulis plugin mendapatkan satu standar internal yang stabil
• core dapat menolak kepemilikan duplikat, 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 tanpa peringatan

Terdapat dua lapisan penegakan:

Dampak praktisnya adalah OpenClaw mengetahui sejak awal plugin mana yang memiliki setiap permukaan. Hal ini memungkinkan core dan kanal berintegrasi dengan lancar karena kepemilikan dideklarasikan, bertipe, dan dapat diuji, bukan tersirat.

Apa yang termasuk dalam kontrak

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

Model eksekusi

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

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 yang tidak dibundel. Perlakukan plugin ruang kerja sebagai kode untuk masa pengembangan, bukan sebagai nilai default produksi.

Untuk nama paket ruang kerja bawaan, pertahankan id plugin agar tetap berakar pada nama npm: @openclaw/<id> secara default, 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 kontrak:

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

Subjalur pembantu plugin bawaan yang dicadangkan telah dihentikan dari peta ekspor SDK yang dihasilkan. Simpan 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 kapabilitas API plugin yang diinjeksi.

Internal dan referensi

Untuk pipeline 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