package.json), manifes (openclaw.plugin.json), entri penyiapan, dan skema konfigurasi.
Metadata paket
package.json Anda memerlukan bidang openclaw yang memberi tahu sistem plugin tentang apa yang disediakan plugin Anda:
- Plugin kanal
- Plugin penyedia / dasar ClawHub
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/statussetup: sertakan kanal dalam pemilih penyiapan/konfigurasi interaktifdocs: tandai kanal sebagai ditujukan untuk publik dalam permukaan dokumentasi/navigasi
openclaw.install
openclaw.install adalah metadata paket, bukan metadata manifes.
Perilaku orientasi
Perilaku orientasi
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.Pemberlakuan minHostVersion
Pemberlakuan minHostVersion
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.Instalasi npm yang dipatok
Instalasi npm yang dipatok
Untuk instalasi npm yang dipatok, simpan versi persis dalam
npmSpec dan tambahkan integritas artefak yang diharapkan:Cakupan allowInvalidConfigRecovery
Cakupan allowInvalidConfigRecovery
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:setupEntry selama fase awal sebelum mulai mendengarkan, bahkan untuk kanal yang sudah dikonfigurasi. Entri lengkap dimuat setelah Gateway mulai mendengarkan.
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 menyertakanopenclaw.plugin.json di root paket. OpenClaw menggunakannya untuk memvalidasi konfigurasi tanpa mengeksekusi kode plugin.
channels (dan plugin penyedia menambahkan providers):
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):
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.
Saat OpenClaw menggunakan setupEntry alih-alih entri lengkap
Saat OpenClaw menggunakan setupEntry alih-alih entri lengkap
- Kanal dinonaktifkan tetapi memerlukan permukaan penyiapan/orientasi awal.
- Kanal diaktifkan tetapi belum dikonfigurasi.
- Pemuatan tertunda diaktifkan (
deferConfiguredChannelFullLoadUntilAfterListen).
Yang harus didaftarkan setupEntry
Yang harus didaftarkan setupEntry
- Objek plugin kanal (melalui
defineSetupPluginEntry). - Rute HTTP apa pun yang diperlukan sebelum gateway mulai mendengarkan.
- Metode gateway apa pun yang diperlukan selama startup.
config.* atau update.*.Yang TIDAK boleh disertakan setupEntry
Yang TIDAK boleh disertakan setupEntry
- 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 payungplugin-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 menjadichannels.<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 dipromosikannamedAccountPromotionKeys: ketika akun bernama sudah ada, hanya kunci-kunci ini yang dipindahkan ke akun yang dipromosikan; kunci kebijakan/pengiriman bersama tetap berada di root kanalresolveSingleAccountPromotionTarget(...): 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:api.pluginConfig selama pendaftaran.
Untuk konfigurasi khusus kanal, gunakan bagian konfigurasi kanal sebagai gantinya:
Membuat skema konfigurasi kanal
GunakanbuildChannelConfigSchema untuk mengonversi skema Zod menjadi pembungkus ChannelConfigSchema yang digunakan oleh artefak konfigurasi milik plugin:
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 untukopenclaw 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.
Prompt allowFrom bersama
Prompt allowFrom bersama
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(...).Status penyiapan kanal standar
Status penyiapan kanal standar
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.Permukaan penyiapan kanal opsional
Permukaan penyiapan kanal opsional
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.Helper penyiapan berbasis biner
Helper penyiapan berbasis biner
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 binercreateCliPathTextInput(...)untuk input teks berbasis jalurcreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...), dancreateDelegatedResolveConfigured(...)saatsetupEntryperlu meneruskan secara tunda ke wizard lengkap yang lebih beratcreateDelegatedTextInputShouldPrompt(...)saatsetupEntryhanya perlu mendelegasikan keputusantextInputs[*].shouldPrompt
Memublikasikan dan menginstal
Plugin eksternal: publikasikan ke ClawHub, lalu instal:- npm
- Hanya ClawHub
- Spesifikasi paket npm
clawhub:, npm:, git:, atau npm-pack: untuk pemilihan sumber yang deterministik — lihat Kelola plugin.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.
Terkait
- Membangun plugin — panduan memulai langkah demi langkah
- Manifes plugin — referensi skema manifes lengkap
- Titik masuk SDK —
definePluginEntrydandefineChannelPluginEntry