package.json), manifes (openclaw.plugin.json), entri penyiapan, dan skema konfigurasi.
Metadata paket
package.json Anda memerlukan bidang openclaw yang memberi tahu sistem plugin apa yang disediakan plugin Anda:
- Plugin channel
- Plugin provider / baseline ClawHub
Jika Anda menerbitkan plugin secara eksternal di ClawHub, bidang
compat dan build tersebut wajib. Cuplikan publikasi kanonis berada di docs/snippets/plugin-publish/.Bidang openclaw
File titik masuk (relatif terhadap root paket).
Entri ringan khusus penyiapan (opsional).
Metadata katalog channel untuk permukaan penyiapan, pemilih, mulai cepat, dan status.
ID provider yang didaftarkan oleh plugin ini.
Petunjuk pemasangan:
npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery.Flag perilaku startup.
openclaw.channel
openclaw.channel adalah metadata paket ringan untuk penemuan channel dan permukaan penyiapan sebelum runtime dimuat.
| Bidang | Tipe | Artinya |
|---|---|---|
id | string | ID channel kanonis. |
label | string | Label channel utama. |
selectionLabel | string | Label pemilih/penyiapan saat perlu berbeda dari label. |
detailLabel | string | Label detail sekunder untuk katalog channel dan permukaan status yang lebih kaya. |
docsPath | string | Jalur docs untuk tautan penyiapan dan pemilihan. |
docsLabel | string | Label pengganti yang digunakan untuk tautan docs saat perlu berbeda dari ID channel. |
blurb | string | Deskripsi singkat onboarding/katalog. |
order | number | Urutan sortir dalam katalog channel. |
aliases | string[] | Alias pencarian tambahan untuk pemilihan channel. |
preferOver | string[] | ID plugin/channel berprioritas lebih rendah yang harus dikalahkan channel ini. |
systemImage | string | Nama ikon/gambar sistem opsional untuk katalog UI channel. |
selectionDocsPrefix | string | Teks prefiks sebelum tautan docs di permukaan pemilihan. |
selectionDocsOmitLabel | boolean | Tampilkan jalur docs secara langsung alih-alih tautan docs berlabel dalam salinan pemilihan. |
selectionExtras | string[] | String pendek tambahan yang ditambahkan dalam salinan pemilihan. |
markdownCapable | boolean | Menandai channel sebagai mendukung markdown untuk keputusan pemformatan keluar. |
exposure | object | Kontrol visibilitas channel untuk permukaan penyiapan, daftar terkonfigurasi, dan docs. |
quickstartAllowFrom | boolean | Ikutkan channel ini ke alur penyiapan allowFrom mulai cepat standar. |
forceAccountBinding | boolean | Wajibkan pengikatan akun eksplisit bahkan ketika hanya ada satu akun. |
preferSessionLookupForAnnounceTarget | boolean | Prioritaskan pencarian sesi saat menyelesaikan target pengumuman untuk channel ini. |
exposure mendukung:
configured: menyertakan channel dalam permukaan daftar bergaya terkonfigurasi/statussetup: menyertakan channel dalam pemilih penyiapan/konfigurasi interaktifdocs: menandai channel sebagai menghadap publik dalam permukaan docs/navigasi
showConfigured dan showInSetup tetap didukung sebagai alias legacy. Utamakan exposure.openclaw.install
openclaw.install adalah metadata paket, bukan metadata manifes.
| Bidang | Tipe | Artinya |
|---|---|---|
clawhubSpec | string | Spesifikasi ClawHub kanonis untuk alur pemasangan/pembaruan dan pemasangan sesuai kebutuhan saat onboarding. |
npmSpec | string | Spesifikasi npm kanonis untuk alur fallback pemasangan/pembaruan. |
localPath | string | Jalur pengembangan lokal atau pemasangan bawaan. |
defaultChoice | "clawhub" | "npm" | "local" | Sumber pemasangan pilihan saat beberapa sumber tersedia. |
minHostVersion | string | Versi OpenClaw minimum yang didukung dalam bentuk >=x.y.z atau >=x.y.z-prerelease. |
expectedIntegrity | string | String integritas dist npm yang diharapkan, biasanya sha512-..., untuk pemasangan yang dipin. |
allowInvalidConfigRecovery | boolean | Memungkinkan alur pemasangan ulang plugin bawaan memulihkan kegagalan konfigurasi usang tertentu. |
requiredPlatformPackages | string[] | Alias npm khusus platform wajib yang diverifikasi selama pemasangan npm. |
Perilaku onboarding
Perilaku onboarding
Onboarding interaktif juga menggunakan
openclaw.install untuk permukaan pemasangan sesuai kebutuhan. Jika plugin Anda mengekspos pilihan autentikasi provider atau metadata penyiapan/katalog channel sebelum runtime dimuat, onboarding dapat menampilkan pilihan tersebut, meminta pemasangan ClawHub, npm, atau lokal, memasang atau mengaktifkan plugin, lalu melanjutkan alur yang dipilih. Pilihan onboarding ClawHub menggunakan clawhubSpec dan diprioritaskan jika ada; pilihan npm memerlukan metadata katalog tepercaya dengan npmSpec registry; versi persis dan expectedIntegrity adalah pin npm opsional. Jika expectedIntegrity ada, alur pemasangan/pembaruan menegakkannya untuk npm. Simpan metadata “apa yang ditampilkan” di openclaw.plugin.json dan metadata “cara memasangnya” di package.json.Penegakan minHostVersion
Penegakan minHostVersion
Jika
minHostVersion disetel, pemasangan dan pemuatan registry manifes non-bawaan sama-sama menegakkannya. Host yang lebih lama melewati plugin eksternal; string versi yang tidak valid ditolak. Plugin sumber bawaan diasumsikan memiliki versi yang sama dengan checkout host.Pemasangan npm yang dipin
Pemasangan npm yang dipin
Untuk pemasangan npm yang dipin, simpan versi persis di
npmSpec dan tambahkan integritas artefak yang diharapkan:Cakupan allowInvalidConfigRecovery
Cakupan allowInvalidConfigRecovery
allowInvalidConfigRecovery bukan pintasan umum untuk konfigurasi rusak. Ini hanya untuk pemulihan plugin bawaan yang sempit, sehingga pemasangan ulang/penyiapan dapat 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 yang tidak terkait, pemasangan tetap gagal tertutup dan memberi tahu operator untuk menjalankan openclaw doctor --fix.Pemuatan penuh yang ditunda
Plugin channel dapat memilih pemuatan tertunda dengan:setupEntry selama fase startup pra-listen, bahkan untuk channel yang sudah dikonfigurasi. Entri penuh dimuat setelah gateway mulai listen.
Jika entri penyiapan/penuh Anda mendaftarkan metode RPC gateway, pertahankan pada prefiks khusus plugin. Namespace admin inti yang dicadangkan (config.*, exec.approvals.*, wizard.*, update.*) tetap dimiliki inti dan selalu diselesaikan ke operator.admin.
Manifes plugin
Setiap plugin native harus menyertakanopenclaw.plugin.json di root paket. OpenClaw menggunakan ini untuk memvalidasi konfigurasi tanpa mengeksekusi kode plugin.
kind dan channels:
Penerbitan ClawHub
Untuk paket plugin, gunakan perintah ClawHub khusus paket:Alias penerbitan lama yang hanya untuk skill digunakan untuk skills. Paket Plugin harus selalu menggunakan
clawhub package publish.Entri setup
Filesetup-entry.ts adalah alternatif ringan untuk index.ts yang dimuat OpenClaw saat hanya membutuhkan permukaan setup (onboarding, perbaikan konfigurasi, inspeksi channel yang dinonaktifkan).
defineBundledChannelSetupEntry(...) dari openclaw/plugin-sdk/channel-entry-contract alih-alih defineSetupPluginEntry(...). Kontrak bawaan itu juga mendukung ekspor runtime opsional sehingga wiring runtime saat setup dapat tetap ringan dan eksplisit.
Saat OpenClaw menggunakan setupEntry alih-alih entri penuh
Saat OpenClaw menggunakan setupEntry alih-alih entri penuh
- Channel dinonaktifkan tetapi membutuhkan permukaan setup/onboarding.
- Channel diaktifkan tetapi belum dikonfigurasi.
- Pemuatan tertunda diaktifkan (
deferConfiguredChannelFullLoadUntilAfterListen).
Yang harus didaftarkan setupEntry
Yang harus didaftarkan setupEntry
- Objek plugin channel (melalui
defineSetupPluginEntry). - Route HTTP apa pun yang diperlukan sebelum gateway listen.
- Metode gateway apa pun yang diperlukan selama startup.
config.* atau update.*.Yang TIDAK boleh disertakan setupEntry
Yang TIDAK boleh disertakan setupEntry
- Registrasi CLI.
- Layanan latar belakang.
- Impor runtime berat (kriptografi, SDK).
- Metode Gateway yang hanya diperlukan setelah startup.
Impor helper setup sempit
Untuk jalur panas yang hanya untuk setup, pilih seam helper setup yang sempit daripada payungplugin-sdk/setup yang lebih luas saat Anda hanya membutuhkan sebagian permukaan setup:
| Jalur impor | Gunakan untuk | Ekspor utama |
|---|---|---|
plugin-sdk/setup-runtime | helper runtime saat setup yang tetap tersedia di setupEntry / startup channel tertunda | createSetupTranslator, createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy |
plugin-sdk/setup-adapter-runtime | alias kompatibilitas yang tidak digunakan lagi; gunakan plugin-sdk/setup-runtime | createEnvPatchedAccountSetupAdapter |
plugin-sdk/setup-tools | helper setup/instalasi CLI/arsip/dokumentasi | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
plugin-sdk/setup yang lebih luas saat Anda menginginkan toolbox setup bersama yang lengkap, termasuk helper patch konfigurasi seperti moveSingleAccountChannelSectionToDefaultAccount(...).
Gunakan createSetupTranslator(...) untuk salinan wizard setup tetap. Ini mengikuti locale wizard
CLI (OPENCLAW_LOCALE, lalu variabel locale sistem) dan melakukan fallback
ke bahasa Inggris. Simpan teks setup khusus plugin dalam kode milik plugin dan gunakan
kunci katalog bersama hanya untuk label setup umum, teks status, dan salinan setup
plugin bawaan resmi.
Adapter patch setup tetap aman untuk jalur panas saat diimpor. Lookup permukaan kontrak promosi akun tunggal bawaannya bersifat lazy, jadi mengimpor plugin-sdk/setup-runtime tidak langsung memuat discovery permukaan kontrak bawaan sebelum adapter benar-benar digunakan.
Promosi akun tunggal milik channel
Saat channel ditingkatkan dari konfigurasi tingkat atas akun tunggal kechannels.<id>.accounts.*, perilaku bersama default adalah memindahkan nilai yang dipromosikan dengan cakupan akun ke accounts.default.
Channel bawaan dapat mempersempit atau menimpa promosi tersebut melalui permukaan kontrak setupnya:
singleAccountKeysToMove: kunci tingkat atas tambahan yang harus dipindahkan ke akun yang dipromosikannamedAccountPromotionKeys: saat akun bernama sudah ada, hanya kunci-kunci ini yang dipindahkan ke akun yang dipromosikan; kunci kebijakan/pengiriman bersama tetap berada di root channelresolveSingleAccountPromotionTarget(...): pilih akun yang sudah ada yang menerima nilai yang dipromosikan
Matrix adalah contoh bawaan saat ini. Jika tepat satu akun Matrix bernama sudah ada, atau jika
defaultAccount menunjuk ke kunci non-kanonis yang sudah ada seperti Ops, promosi mempertahankan akun tersebut alih-alih membuat entri accounts.default baru.Skema konfigurasi
Konfigurasi plugin divalidasi terhadap JSON Schema di manifes Anda. Pengguna mengonfigurasi plugin melalui:api.pluginConfig selama registrasi.
Untuk konfigurasi khusus channel, gunakan bagian konfigurasi channel sebagai gantinya:
Membuat skema konfigurasi channel
GunakanbuildChannelConfigSchema untuk mengonversi skema Zod menjadi wrapper ChannelConfigSchema yang digunakan oleh artefak konfigurasi milik plugin:
openclaw.plugin.json#channelConfigs sehingga skema konfigurasi, setup, dan permukaan UI dapat menginspeksi channels.<id> tanpa memuat kode runtime.
Wizard setup
Plugin channel dapat menyediakan wizard setup interaktif untukopenclaw onboard. Wizard adalah objek ChannelSetupWizard pada ChannelPlugin:
ChannelSetupWizard mendukung credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize, dan lainnya. Lihat paket plugin bawaan (misalnya plugin Discord src/channel.setup.ts) untuk contoh lengkap.
Prompt allowFrom bersama
Prompt allowFrom bersama
Untuk prompt allowlist DM yang hanya membutuhkan alur standar
note -> prompt -> parse -> merge -> patch, pilih helper setup bersama dari openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...), dan createNestedChannelParsedAllowFromPrompt(...).Status setup channel standar
Status setup channel standar
Untuk blok status setup channel yang hanya berbeda pada 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 setup channel opsional
Permukaan setup channel opsional
Untuk permukaan setup opsional yang hanya boleh muncul dalam konteks tertentu, gunakan
createOptionalChannelSetupSurface dari openclaw/plugin-sdk/channel-setup:plugin-sdk/channel-setup juga mengekspos builder tingkat lebih rendah createOptionalChannelSetupAdapter(...) dan createOptionalChannelSetupWizard(...) saat Anda hanya membutuhkan salah satu bagian dari permukaan instalasi opsional tersebut.Adapter/wizard opsional yang dihasilkan gagal tertutup pada penulisan konfigurasi nyata. Mereka menggunakan kembali satu pesan perlu-instal di seluruh validateInput, applyAccountConfig, dan finalize, serta menambahkan tautan dokumentasi saat docsPath diatur.Helper setup berbasis biner
Helper setup berbasis biner
Untuk UI setup berbasis biner, pilih helper delegasi bersama alih-alih menyalin glue biner/status yang sama ke setiap channel:
createDetectedBinaryStatus(...)untuk blok status yang hanya berbeda pada label, petunjuk, skor, dan deteksi binercreateCliPathTextInput(...)untuk input teks berbasis jalurcreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...), dancreateDelegatedResolveConfigured(...)ketikasetupEntryperlu meneruskan ke wizard lengkap yang lebih berat secara malascreateDelegatedTextInputShouldPrompt(...)ketikasetupEntryhanya perlu mendelegasikan keputusantextInputs[*].shouldPrompt
Menerbitkan dan menginstal
Plugin eksternal: terbitkan ke ClawHub, lalu instal:- npm
- Hanya ClawHub
- Spesifikasi paket npm
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. Jaga agar pohon dependensi plugin tetap murni JS/TS dan hindari paket yang memerlukan build postinstall.Startup Gateway tidak menginstal dependensi plugin. Alur instalasi npm/git/ClawHub memiliki konvergensi dependensi; plugin lokal harus sudah memiliki dependensinya terinstal.
Terkait
- Membangun plugin — panduan memulai langkah demi langkah
- Manifes Plugin — referensi skema manifes lengkap
- Titik masuk SDK —
definePluginEntrydandefineChannelPluginEntry