OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Building plugins

Menambahkan kemampuan (panduan kontributor)

Gunakan panduan ini saat OpenClaw memerlukan domain bersama baru seperti embedding, pembuatan gambar, pembuatan video, atau area fitur masa depan yang didukung vendor.

Aturannya:

  • plugin = batas kepemilikan
  • kapabilitas = kontrak inti bersama

Jangan hubungkan vendor secara langsung ke kanal atau alat. Definisikan kapabilitasnya terlebih dahulu.

Kapan harus membuat kapabilitas

Buat kapabilitas baru hanya jika semua hal berikut terpenuhi:

  1. Lebih dari satu vendor secara masuk akal dapat mengimplementasikannya.
  2. Kanal, alat, atau plugin fitur harus dapat menggunakannya tanpa perlu mengetahui vendornya.
  3. Inti perlu memiliki perilaku fallback, kebijakan, konfigurasi, atau pengiriman.

Jika pekerjaan hanya khusus untuk vendor dan belum ada kontrak bersama, definisikan kontraknya terlebih dahulu.

Urutan standar

  1. Definisikan kontrak inti bertipe.
  2. Tambahkan pendaftaran plugin untuk kontrak tersebut.
  3. Tambahkan pembantu runtime bersama.
  4. Hubungkan satu plugin vendor nyata sebagai bukti.
  5. Pindahkan konsumen fitur/kanal ke pembantu runtime.
  6. Tambahkan pengujian kontrak.
  7. Dokumentasikan konfigurasi yang ditujukan bagi operator dan model kepemilikannya.

Penempatan komponen

Lapisan Memiliki
Inti Tipe permintaan/respons; registri dan resolusi penyedia; perilaku fallback; skema konfigurasi dengan metadata dokumentasi title/description yang diteruskan pada simpul objek bertingkat, wildcard, item larik, dan komposisi; permukaan pembantu runtime.
Plugin vendor Panggilan API vendor, penanganan autentikasi vendor, normalisasi permintaan khusus vendor, dan pendaftaran implementasi kapabilitas.
Plugin fitur/kanal Memanggil api.runtime.* atau pembantu plugin-sdk/*-runtime yang sesuai. Tidak pernah memanggil implementasi vendor secara langsung.

Titik integrasi penyedia dan harness

Gunakan hook penyedia ketika perilaku merupakan bagian dari kontrak penyedia model, bukan loop agen generik. Contohnya mencakup parameter permintaan khusus penyedia setelah pemilihan transportasi, preferensi profil autentikasi, overlay prompt, dan perutean fallback lanjutan setelah failover model/profil.

Gunakan hook harness agen ketika perilaku merupakan bagian dari runtime yang menjalankan suatu giliran. Harness dapat mengklasifikasikan hasil protokol eksplisit seperti keluaran kosong, penalaran tanpa keluaran yang terlihat, atau rencana terstruktur tanpa jawaban akhir agar kebijakan fallback model luar dapat menentukan keputusan percobaan ulang.

Jaga agar kedua titik integrasi tetap sempit:

  • Inti memiliki kebijakan percobaan ulang/fallback.
  • Plugin penyedia memiliki petunjuk permintaan/autentikasi/perutean khusus penyedia.
  • Plugin harness memiliki klasifikasi percobaan khusus runtime.
  • Plugin pihak ketiga mengembalikan petunjuk, bukan mutasi langsung terhadap status inti.

Daftar periksa berkas

Untuk kapabilitas baru, bersiaplah menyentuh area berikut:

  • src/<capability>/types.ts
  • src/<capability>/...registry/runtime.ts
  • src/plugins/types.ts
  • src/plugins/registry.ts
  • src/plugins/captured-registration.ts
  • src/plugins/contracts/registry.ts
  • src/plugins/runtime/types-core.ts
  • src/plugins/runtime/index.ts
  • src/plugin-sdk/<capability>.ts
  • src/plugin-sdk/<capability>-runtime.ts
  • Satu atau beberapa paket plugin bawaan.
  • Konfigurasi, dokumentasi, pengujian.

Contoh lengkap: pembuatan gambar

Pembuatan gambar mengikuti struktur standar:

  1. Inti mendefinisikan ImageGenerationProvider.
  2. Inti mengekspos registerImageGenerationProvider(...).
  3. Inti mengekspos api.runtime.imageGeneration.generate(...) dan .listProviders(...).
  4. Plugin vendor (comfy, deepinfra, fal, google, litellm, microsoft-foundry, minimax, openai, openrouter, vydra, xai) mendaftarkan implementasi yang didukung vendor.
  5. Vendor mendatang mendaftarkan kontrak yang sama tanpa mengubah kanal/alat.

Kunci konfigurasi sengaja dipisahkan dari perutean analisis penglihatan:

  • agents.defaults.imageModel menganalisis gambar.
  • agents.defaults.imageGenerationModel menghasilkan gambar.

Pertahankan keduanya secara terpisah agar fallback dan kebijakan tetap eksplisit.

Penyedia embedding

Gunakan registerEmbeddingProvider(...) / kontrak embeddingProviders untuk penyedia embedding vektor yang dapat digunakan kembali. Kontrak ini sengaja lebih luas daripada memori: alat, pencarian, pengambilan, pengimpor, atau plugin fitur masa depan dapat menggunakan embedding tanpa bergantung pada mesin memori. Pencarian memori juga menggunakan embeddingProviders generik.

API pendaftaran lama yang khusus untuk memori dan kontrak memoryEmbeddingProviders sudah tidak digunakan lagi. Gunakan registerEmbeddingProvider dan embeddingProviders untuk semua penyedia embedding baru.

Daftar periksa peninjauan

Sebelum merilis kapabilitas baru, verifikasi:

  • Tidak ada kanal/alat yang mengimpor kode vendor secara langsung.
  • Pembantu runtime menjadi jalur bersama.
  • Setidaknya satu pengujian kontrak memverifikasi kepemilikan bawaan.
  • Dokumentasi konfigurasi menyebutkan model/kunci konfigurasi baru.
  • Dokumentasi plugin menjelaskan batas kepemilikan.

Jika sebuah PR melewati lapisan kapabilitas dan menanamkan perilaku vendor langsung ke kanal/alat, kembalikan PR tersebut dan definisikan kontraknya terlebih dahulu.

Terkait

Was this useful?
On this page

On this page