Skip to main content
Ini adalah panduan kontributor bagi pengembang inti OpenClaw. Jika Anda sedang membuat plugin eksternal, lihat Membuat plugin sebagai gantinya. Untuk referensi arsitektur mendalam (model kapabilitas, kepemilikan, alur pemuatan, pembantu runtime), lihat Internal Plugin.
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

​
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