Referensi untuk pengemasan Plugin (metadataDocumentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
package.json), manifes (openclaw.plugin.json), entri penyiapan, dan skema konfigurasi.
Metadata paket
package.json Anda memerlukan kolom openclaw yang memberi tahu sistem Plugin apa yang disediakan Plugin Anda:
- Channel plugin
- Provider plugin / ClawHub baseline
Jika Anda memublikasikan Plugin secara eksternal di ClawHub, kolom
compat dan build tersebut wajib ada. Cuplikan publikasi kanonis berada di docs/snippets/plugin-publish/.Kolom openclaw
Berkas titik masuk (relatif terhadap root paket).
Entri ringan khusus penyiapan (opsional).
Metadata katalog saluran untuk penyiapan, pemilih, quickstart, dan permukaan status.
ID penyedia yang didaftarkan oleh Plugin ini.
Petunjuk instalasi:
npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery.Flag perilaku startup.
openclaw.channel
openclaw.channel adalah metadata paket ringan untuk penemuan saluran dan permukaan penyiapan sebelum runtime dimuat.
| Kolom | Tipe | Artinya |
|---|---|---|
id | string | ID saluran kanonis. |
label | string | Label saluran utama. |
selectionLabel | string | Label pemilih/penyiapan saat harus berbeda dari label. |
detailLabel | string | Label detail sekunder untuk katalog saluran dan permukaan status yang lebih kaya. |
docsPath | string | Jalur dokumentasi untuk tautan penyiapan dan pemilihan. |
docsLabel | string | Label pengganti yang digunakan untuk tautan dokumentasi saat harus berbeda dari ID saluran. |
blurb | string | Deskripsi singkat untuk onboarding/katalog. |
order | number | Urutan pengurutan dalam katalog saluran. |
aliases | string[] | Alias pencarian tambahan untuk pemilihan saluran. |
preferOver | string[] | ID Plugin/saluran prioritas lebih rendah yang harus dikalahkan saluran ini. |
systemImage | string | Nama ikon/system-image opsional untuk katalog UI saluran. |
selectionDocsPrefix | string | Teks awalan sebelum tautan dokumentasi di permukaan pemilihan. |
selectionDocsOmitLabel | boolean | Tampilkan jalur dokumentasi secara langsung alih-alih tautan dokumentasi berlabel dalam salinan pemilihan. |
selectionExtras | string[] | String pendek tambahan yang ditambahkan dalam salinan pemilihan. |
markdownCapable | boolean | Menandai saluran sebagai mendukung markdown untuk keputusan pemformatan keluar. |
exposure | object | Kontrol visibilitas saluran untuk penyiapan, daftar terkonfigurasi, dan permukaan dokumentasi. |
quickstartAllowFrom | boolean | Ikutkan saluran ini ke dalam alur penyiapan quickstart allowFrom standar. |
forceAccountBinding | boolean | Wajibkan pengikatan akun eksplisit bahkan saat hanya ada satu akun. |
preferSessionLookupForAnnounceTarget | boolean | Utamakan pencarian sesi saat menyelesaikan target pengumuman untuk saluran ini. |
exposure mendukung:
configured: sertakan saluran dalam permukaan daftar bergaya terkonfigurasi/statussetup: sertakan saluran dalam pemilih penyiapan/konfigurasi interaktifdocs: tandai saluran sebagai menghadap publik dalam permukaan dokumentasi/navigasi
showConfigured dan showInSetup tetap didukung sebagai alias lama. Utamakan exposure.openclaw.install
openclaw.install adalah metadata paket, bukan metadata manifes.
| Kolom | Tipe | Artinya |
|---|---|---|
clawhubSpec | string | Spesifikasi ClawHub kanonis untuk alur instal/perbarui dan instal saat diperlukan onboarding. |
npmSpec | string | Spesifikasi npm kanonis untuk alur fallback instal/perbarui. |
localPath | string | Jalur pengembangan lokal atau instalasi bawaan. |
defaultChoice | "clawhub" | "npm" | "local" | Sumber instalasi pilihan saat tersedia beberapa sumber. |
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 instalasi terpancang. |
allowInvalidConfigRecovery | boolean | Memungkinkan alur instal ulang Plugin bawaan memulihkan kegagalan konfigurasi usang tertentu. |
Onboarding behavior
Onboarding behavior
Onboarding interaktif juga menggunakan
openclaw.install untuk permukaan instal saat diperlukan. Jika Plugin Anda mengekspos pilihan auth penyedia atau metadata penyiapan/katalog saluran sebelum runtime dimuat, onboarding dapat menampilkan pilihan itu, meminta instalasi ClawHub, npm, atau lokal, menginstal atau mengaktifkan Plugin, lalu melanjutkan alur yang dipilih. Pilihan onboarding ClawHub menggunakan clawhubSpec dan diutamakan saat tersedia; pilihan npm memerlukan metadata katalog tepercaya dengan npmSpec registry; versi persis dan expectedIntegrity adalah pin npm opsional. Jika expectedIntegrity ada, alur instal/perbarui memberlakukannya untuk npm. Simpan metadata “apa yang ditampilkan” di openclaw.plugin.json dan metadata “cara menginstalnya” di package.json.minHostVersion enforcement
minHostVersion enforcement
Jika
minHostVersion disetel, pemuatan instalasi dan registry manifes non-bawaan sama-sama memberlakukannya. Host yang lebih lama melewati Plugin eksternal; string versi tidak valid ditolak. Plugin sumber bawaan diasumsikan diversi bersama dengan checkout host.Pinned npm installs
Pinned npm installs
Untuk instalasi npm terpancang, simpan versi persis di
npmSpec dan tambahkan integritas artefak yang diharapkan:allowInvalidConfigRecovery scope
allowInvalidConfigRecovery scope
allowInvalidConfigRecovery bukan bypass umum untuk konfigurasi rusak. Ini hanya untuk pemulihan Plugin bawaan yang sempit, sehingga instal 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, instalasi tetap gagal tertutup dan memberi tahu operator untuk menjalankan openclaw doctor --fix.Pemuatan penuh yang ditangguhkan
Plugin saluran dapat memilih pemuatan tertunda dengan:setupEntry selama fase startup sebelum listen, bahkan untuk saluran yang sudah dikonfigurasi. Entri penuh dimuat setelah Gateway mulai listening.
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:
Publikasi ClawHub
Untuk paket Plugin, gunakan perintah ClawHub khusus paket:Alias publish lama yang hanya untuk skill ditujukan untuk skills. Paket Plugin harus selalu menggunakan
clawhub package publish.Entri penyiapan
Filesetup-entry.ts adalah alternatif ringan untuk index.ts yang dimuat OpenClaw saat hanya memerlukan permukaan penyiapan (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 penyiapan dapat tetap ringan dan eksplisit.
Saat OpenClaw menggunakan setupEntry alih-alih entri penuh
Saat OpenClaw menggunakan setupEntry alih-alih entri penuh
- Channel dinonaktifkan tetapi memerlukan permukaan penyiapan/onboarding.
- Channel diaktifkan tetapi belum dikonfigurasi.
- Pemuatan tertunda diaktifkan (
deferConfiguredChannelFullLoadUntilAfterListen).
Yang harus didaftarkan setupEntry
Yang harus didaftarkan setupEntry
- Objek Plugin channel (melalui
defineSetupPluginEntry). - Rute 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 (crypto, SDK).
- Metode Gateway yang hanya diperlukan setelah startup.
Impor helper penyiapan yang sempit
Untuk jalur panas khusus penyiapan, pilih seam helper penyiapan yang sempit daripada umbrellaplugin-sdk/setup yang lebih luas saat Anda hanya memerlukan sebagian permukaan penyiapan:
| Jalur impor | Gunakan untuk | Ekspor utama |
|---|---|---|
plugin-sdk/setup-runtime | helper runtime saat penyiapan yang tetap tersedia di setupEntry / startup channel tertunda | createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy |
plugin-sdk/setup-adapter-runtime | alias kompatibilitas yang usang; gunakan plugin-sdk/setup-runtime | createEnvPatchedAccountSetupAdapter |
plugin-sdk/setup-tools | helper CLI/arsip/dokumen untuk penyiapan/instalasi | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
plugin-sdk/setup yang lebih luas saat Anda menginginkan seluruh toolbox penyiapan bersama, termasuk helper patch konfigurasi seperti moveSingleAccountChannelSectionToDefaultAccount(...).
Adapter patch penyiapan tetap aman untuk jalur panas saat diimpor. Lookup permukaan kontrak promosi akun tunggal bawaannya bersifat lazy, sehingga mengimpor plugin-sdk/setup-runtime tidak langsung memuat discovery permukaan kontrak bawaan sebelum adapter benar-benar digunakan.
Promosi akun tunggal milik channel
Saat sebuah channel ditingkatkan dari konfigurasi tingkat atas akun tunggal kechannels.<id>.accounts.*, perilaku bersama default adalah memindahkan nilai berskala akun yang dipromosikan ke accounts.default.
Channel bawaan dapat mempersempit atau menimpa promosi tersebut melalui permukaan kontrak penyiapannya:
singleAccountKeysToMove: kunci tingkat atas tambahan yang harus dipindahkan ke akun yang dipromosikannamedAccountPromotionKeys: saat akun bernama sudah ada, hanya 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 manifest 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 pembungkus ChannelConfigSchema yang digunakan oleh artefak konfigurasi milik Plugin:
openclaw.plugin.json#channelConfigs sehingga skema konfigurasi, penyiapan, dan permukaan UI dapat menginspeksi channels.<id> tanpa memuat kode runtime.
Wizard penyiapan
Plugin channel dapat menyediakan wizard penyiapan 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 daftar izin 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 channel standar
Status penyiapan channel standar
Untuk blok status penyiapan channel yang hanya berbeda pada label, skor, dan baris tambahan opsional, pilih
createStandardChannelSetupStatus(...) dari openclaw/plugin-sdk/setup alih-alih membuat objek status yang sama secara manual di setiap Plugin.Permukaan penyiapan channel opsional
Permukaan penyiapan channel 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 lebih rendah createOptionalChannelSetupAdapter(...) dan createOptionalChannelSetupWizard(...) saat Anda hanya memerlukan salah satu bagian dari permukaan instal-opsional tersebut.Adapter/wizard opsional yang dihasilkan gagal secara tertutup pada penulisan konfigurasi nyata. Mereka menggunakan kembali satu pesan instalasi-diperlukan di validateInput, applyAccountConfig, dan finalize, serta menambahkan tautan dokumen saat docsPath diatur.Helper penyiapan berbasis biner
Helper penyiapan berbasis biner
Untuk UI penyiapan 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(...)saatsetupEntryperlu meneruskan ke wizard penuh yang lebih berat secara lazycreateDelegatedTextInputShouldPrompt(...)saatsetupEntryhanya 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 di bawah ~/.openclaw/npm dengan skrip lifecycle dinonaktifkan. Pertahankan pohon dependensi Plugin sebagai JS/TS murni dan hindari paket yang memerlukan build postinstall.Startup Gateway tidak menginstal dependensi Plugin. Alur instalasi npm/git/ClawHub bertanggung jawab atas 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