Skip to main content
Referensi untuk pengemasan plugin (metadata package.json), manifes (openclaw.plugin.json), entri penyiapan, dan skema konfigurasi.
Mencari panduan langkah demi langkah? Panduan praktis membahas pengemasan dalam konteksnya: Plugin kanal dan Plugin penyedia.

Metadata paket

package.json Anda memerlukan bidang openclaw yang memberi tahu sistem plugin tentang apa yang disediakan plugin Anda:
Publikasi secara eksternal di ClawHub memerlukan compat dan build. Cuplikan publikasi kanonis tersedia di docs/snippets/plugin-publish/.

Bidang openclaw

string[]
File titik masuk (relatif terhadap akar paket). Entri sumber yang valid untuk pengembangan ruang kerja dan checkout git.
string[]
Padanan JavaScript hasil build untuk extensions, yang diutamakan saat OpenClaw memuat paket npm terinstal. Lihat Titik masuk SDK untuk urutan resolusi sumber/hasil build.
string
Entri ringan khusus penyiapan (opsional).
string
Padanan JavaScript hasil build untuk setupEntry. Mengharuskan setupEntry juga ditetapkan.
object
Identitas plugin cadangan { id, label }, digunakan ketika plugin tidak memiliki metadata kanal/penyedia untuk memperoleh id atau label.
object
Metadata katalog kanal untuk permukaan penyiapan, pemilih, mulai cepat, dan status.
object
Petunjuk instalasi: npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery, requiredPlatformPackages.
object
Flag perilaku saat dimulai.
object
Rentang versi pluginApi yang didukung plugin ini. Wajib untuk publikasi eksternal di ClawHub.
Id penyedia (providers: string[]) merupakan metadata manifes, bukan metadata paket. Deklarasikan dalam openclaw.plugin.json, bukan di sini — lihat Manifes plugin.

openclaw.channel

openclaw.channel adalah metadata paket ringan untuk penemuan kanal dan permukaan penyiapan sebelum runtime dimuat. Contoh:
exposure mendukung:
  • configured: sertakan kanal dalam permukaan daftar bergaya konfigurasi/status
  • setup: sertakan kanal dalam pemilih penyiapan/konfigurasi interaktif
  • docs: tandai kanal sebagai ditujukan untuk publik dalam permukaan dokumentasi/navigasi

openclaw.install

openclaw.install adalah metadata paket, bukan metadata manifes.
Orientasi interaktif menggunakan openclaw.install untuk permukaan instalasi sesuai permintaan: jika plugin Anda mengekspos pilihan autentikasi penyedia atau metadata penyiapan/katalog kanal sebelum runtime dimuat, orientasi dapat meminta instalasi melalui ClawHub, npm, atau lokal, menginstal atau mengaktifkan plugin, lalu melanjutkan alur yang dipilih. Pilihan ClawHub menggunakan clawhubSpec dan diutamakan jika tersedia; pilihan npm memerlukan metadata katalog tepercaya dengan npmSpec registri (versi persis dan expectedIntegrity merupakan patokan opsional, yang diberlakukan saat instalasi/pembaruan jika ditetapkan). Simpan “apa yang ditampilkan” dalam openclaw.plugin.json dan “cara menginstalnya” dalam package.json.
Jika minHostVersion ditetapkan, instalasi dan pemuatan registri manifes nonbawaan sama-sama memberlakukannya. Host lama melewati plugin eksternal; string versi yang tidak valid ditolak. Plugin sumber bawaan diasumsikan memiliki versi yang sama dengan checkout host.
Untuk instalasi npm yang dipatok, simpan versi persis dalam npmSpec dan tambahkan integritas artefak yang diharapkan:
allowInvalidConfigRecovery bukan mekanisme umum untuk melewati konfigurasi yang rusak. Ini hanya untuk pemulihan sempit plugin bawaan, yang memungkinkan instalasi ulang/penyiapan memperbaiki sisa peningkatan yang diketahui seperti jalur plugin bawaan yang hilang atau entri channels.<id> usang untuk plugin yang sama. Jika konfigurasi rusak karena alasan lain, instalasi tetap gagal secara tertutup dan meminta operator menjalankan openclaw doctor --fix.

Penundaan pemuatan penuh

Plugin kanal dapat memilih pemuatan tertunda dengan:
Jika diaktifkan, OpenClaw hanya memuat setupEntry selama fase awal sebelum mulai mendengarkan, bahkan untuk kanal yang sudah dikonfigurasi. Entri lengkap dimuat setelah Gateway mulai mendengarkan.
Hanya aktifkan pemuatan tertunda ketika setupEntry Anda mendaftarkan semua yang dibutuhkan gateway sebelum mulai mendengarkan (pendaftaran kanal, rute HTTP, metode gateway). Jika entri lengkap memiliki kapabilitas startup yang diperlukan, pertahankan perilaku default.
Jika entri penyiapan/lengkap Anda mendaftarkan metode RPC gateway, pertahankan metode tersebut pada prefiks khusus plugin. Namespace admin inti yang dicadangkan (config.*, exec.approvals.*, wizard.*, update.*) tetap dimiliki inti dan selalu dinormalisasi menjadi operator.admin.

Manifes plugin

Setiap plugin native harus menyertakan openclaw.plugin.json di root paket. OpenClaw menggunakannya untuk memvalidasi konfigurasi tanpa mengeksekusi kode plugin.
Untuk plugin kanal, tambahkan channels (dan plugin penyedia menambahkan providers):
Bahkan plugin tanpa konfigurasi harus menyertakan skema. Skema kosong tetap valid:
Lihat Manifes plugin untuk referensi skema lengkap.

Publikasi ClawHub

Paket Skills dan plugin menggunakan perintah publikasi ClawHub yang terpisah. Untuk paket plugin, gunakan perintah khusus paket:
clawhub skill publish <path> adalah perintah yang berbeda untuk memublikasikan folder skill, bukan paket plugin. Lihat Publikasi di ClawHub.

Entri penyiapan

setup-entry.ts adalah alternatif ringan untuk index.ts yang dimuat OpenClaw ketika hanya memerlukan permukaan penyiapan (orientasi awal, perbaikan konfigurasi, pemeriksaan kanal yang dinonaktifkan):
Ini menghindari pemuatan kode runtime yang berat (pustaka kriptografi, pendaftaran CLI, layanan latar belakang) selama alur penyiapan. Kanal ruang kerja yang dibundel dan mempertahankan ekspor yang aman untuk penyiapan dalam modul pendamping dapat menggunakan defineBundledChannelSetupEntry(...) dari openclaw/plugin-sdk/channel-entry-contract, alih-alih defineSetupPluginEntry(...). Kontrak yang dibundel tersebut juga mendukung ekspor opsional runtime agar pengawatan runtime saat penyiapan tetap ringan dan eksplisit.
  • Kanal dinonaktifkan tetapi memerlukan permukaan penyiapan/orientasi awal.
  • Kanal diaktifkan tetapi belum dikonfigurasi.
  • Pemuatan tertunda diaktifkan (deferConfiguredChannelFullLoadUntilAfterListen).
  • Objek plugin kanal (melalui defineSetupPluginEntry).
  • Rute HTTP apa pun yang diperlukan sebelum gateway mulai mendengarkan.
  • Metode gateway apa pun yang diperlukan selama startup.
Metode gateway startup tersebut tetap harus menghindari namespace admin inti yang dicadangkan seperti config.* atau update.*.
  • Pendaftaran CLI.
  • Layanan latar belakang.
  • Impor runtime yang berat (kriptografi, SDK).
  • Metode Gateway yang hanya diperlukan setelah startup.

Impor helper penyiapan yang sempit

Untuk jalur khusus penyiapan yang sering digunakan, pilih seam helper penyiapan yang sempit daripada payung plugin-sdk/setup yang lebih luas ketika Anda hanya memerlukan sebagian permukaan penyiapan: Gunakan seam plugin-sdk/setup yang lebih luas ketika Anda menginginkan kotak alat penyiapan bersama secara lengkap, termasuk helper patch konfigurasi seperti moveSingleAccountChannelSectionToDefaultAccount(...). Gunakan createSetupTranslator(...) untuk teks tetap wizard penyiapan. Ini menggunakan nilai tidak kosong pertama dari OPENCLAW_LOCALE, LC_ALL, LC_MESSAGES, dan LANG, dalam urutan tersebut, lalu kembali ke bahasa Inggris. Atur OPENCLAW_LOCALE=en untuk penggantian bahasa Inggris yang eksplisit. Pertahankan teks penyiapan khusus plugin dalam kode milik plugin dan gunakan kunci katalog bersama hanya untuk label penyiapan umum, teks status, serta teks penyiapan plugin resmi yang dibundel. Adaptor patch penyiapan tetap aman untuk jalur yang sering digunakan saat diimpor. Pencarian permukaan kontrak promosi akun tunggal yang dibundel bersifat malas, sehingga mengimpor plugin-sdk/setup-runtime tidak segera memuat penemuan permukaan kontrak yang dibundel sebelum adaptor benar-benar digunakan.

Promosi akun tunggal milik kanal

Ketika kanal meningkatkan konfigurasi tingkat atas akun tunggal menjadi channels.<id>.accounts.*, perilaku bersama default memindahkan nilai cakupan akun yang dipromosikan ke accounts.default. Kanal yang dibundel dapat mempersempit atau mengganti promosi tersebut melalui permukaan kontrak penyiapannya:
  • singleAccountKeysToMove: kunci tingkat atas tambahan yang harus dipindahkan ke akun yang dipromosikan
  • namedAccountPromotionKeys: ketika akun bernama sudah ada, hanya kunci-kunci ini yang dipindahkan ke akun yang dipromosikan; kunci kebijakan/pengiriman bersama tetap berada di root kanal
  • resolveSingleAccountPromotionTarget(...): memilih akun yang sudah ada untuk menerima nilai yang dipromosikan
Matrix adalah contoh yang dibundel saat ini. Jika tepat satu akun Matrix bernama sudah ada, atau jika defaultAccount menunjuk ke kunci nonkanonis yang sudah ada seperti Ops, promosi mempertahankan akun tersebut alih-alih membuat entri accounts.default baru.

Skema konfigurasi

Konfigurasi plugin divalidasi terhadap JSON Schema dalam manifes Anda. Pengguna mengonfigurasi plugin melalui:
Plugin Anda menerima konfigurasi ini sebagai api.pluginConfig selama pendaftaran. Untuk konfigurasi khusus kanal, gunakan bagian konfigurasi kanal sebagai gantinya:

Membuat skema konfigurasi kanal

Gunakan buildChannelConfigSchema untuk mengonversi skema Zod menjadi pembungkus ChannelConfigSchema yang digunakan oleh artefak konfigurasi milik plugin:
Jika Anda sudah menulis kontrak sebagai JSON Schema atau TypeBox, gunakan helper langsung agar OpenClaw dapat melewati konversi Zod-ke-JSON-Schema pada jalur metadata:
Untuk plugin pihak ketiga, kontrak jalur dingin tetap berupa manifes plugin: cerminkan JSON Schema yang dihasilkan ke openclaw.plugin.json#channelConfigs agar permukaan skema konfigurasi, penyiapan, dan UI dapat memeriksa channels.<id> tanpa memuat kode runtime.

Wizard penyiapan

Plugin kanal dapat menyediakan wizard penyiapan interaktif untuk openclaw onboard. Wizard tersebut adalah objek ChannelSetupWizard pada ChannelPlugin:
ChannelSetupWizard juga mendukung textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize, dan lainnya. Lihat src/setup-core.ts milik plugin Discord untuk contoh lengkap yang dibundel.
Untuk prompt daftar yang diizinkan DM yang hanya memerlukan alur standar note -> prompt -> parse -> merge -> patch, pilih helper penyiapan bersama dari openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...), dan createNestedChannelParsedAllowFromPrompt(...).
Untuk blok status penyiapan kanal yang hanya berbeda dalam label, skor, dan baris tambahan opsional, pilih createStandardChannelSetupStatus(...) dari openclaw/plugin-sdk/setup, alih-alih membuat sendiri objek status yang sama di setiap plugin.
Untuk permukaan penyiapan opsional yang hanya boleh muncul dalam konteks tertentu, gunakan createOptionalChannelSetupSurface dari openclaw/plugin-sdk/channel-setup:
plugin-sdk/channel-setup juga mengekspos builder tingkat rendah createOptionalChannelSetupAdapter(...) dan createOptionalChannelSetupWizard(...) ketika Anda hanya memerlukan separuh dari permukaan instalasi opsional tersebut.Adaptor/wizard opsional yang dihasilkan menolak secara aman pada penulisan konfigurasi nyata. Keduanya menggunakan kembali satu pesan wajib-instalasi untuk validateInput, applyAccountConfig, dan finalize, serta menambahkan tautan dokumentasi saat docsPath ditetapkan.
Untuk UI penyiapan berbasis biner, utamakan helper delegasi bersama daripada menyalin logika penghubung biner/status yang sama ke setiap kanal:
  • createDetectedBinaryStatus(...) untuk blok status yang hanya berbeda dalam label, petunjuk, skor, dan deteksi biner
  • createCliPathTextInput(...) untuk input teks berbasis jalur
  • createDelegatedSetupWizardStatusResolvers(...), createDelegatedPrepare(...), createDelegatedFinalize(...), dan createDelegatedResolveConfigured(...) saat setupEntry perlu meneruskan secara tunda ke wizard lengkap yang lebih berat
  • createDelegatedTextInputShouldPrompt(...) saat setupEntry hanya perlu mendelegasikan keputusan textInputs[*].shouldPrompt

Memublikasikan dan menginstal

Plugin eksternal: publikasikan ke ClawHub, lalu instal:
Spesifikasi paket polos diinstal dari npm selama peralihan peluncuran, kecuali namanya cocok dengan id plugin bawaan atau resmi. Dalam hal ini, OpenClaw menggunakan salinan lokal/resmi tersebut sebagai gantinya. Gunakan clawhub:, npm:, git:, atau npm-pack: untuk pemilihan sumber yang deterministik — lihat Kelola plugin.
Plugin dalam repositori: tempatkan di bawah pohon ruang kerja plugin bawaan; plugin tersebut ditemukan secara otomatis selama build.
Untuk instalasi yang bersumber dari npm, openclaw plugins install menginstal paket ke proyek per-plugin di bawah ~/.openclaw/npm/projects dengan skrip siklus hidup dinonaktifkan (--ignore-scripts). Pastikan pohon dependensi plugin sepenuhnya menggunakan JS/TS dan hindari paket yang memerlukan build postinstall.
Proses awal Gateway tidak menginstal dependensi plugin. Alur instalasi npm/git/ClawHub menangani konvergensi dependensi; plugin lokal harus sudah memiliki dependensi yang terinstal.
Metadata paket bawaan bersifat eksplisit, bukan disimpulkan dari JavaScript hasil build saat Gateway dimulai. Dependensi runtime harus berada dalam paket plugin yang memilikinya; proses awal OpenClaw terpaket tidak pernah memperbaiki atau mencerminkan dependensi plugin.

Terkait