Perbaikan validasi plugin

ClawHub memvalidasi paket plugin sebelum dipublikasikan dan juga dapat menampilkan temuan dari pemindaian paket otomatis. Halaman ini membahas temuan yang ditujukan kepada penulis, yaitu temuan yang dapat diperbaiki oleh penulis plugin dalam metadata paket, manifes, impor SDK, atau artefak yang dipublikasikan.

Halaman ini tidak membahas temuan cakupan internal Plugin Inspector. Jika laporan lengkap berisi kode pemeliharaan pemindai tanpa panduan perbaikan untuk penulis, kode tersebut ditujukan kepada pengelola OpenClaw, bukan penulis plugin.

Setelah menerapkan perbaikan apa pun, jalankan kembali:

clawhub package validate <path-to-plugin>

Temuan untuk penulis

Metadata paket

package-json-missing

Akar paket tidak menyertakan package.json, sehingga ClawHub tidak dapat mengidentifikasi paket npm, versi, titik masuk, atau metadata OpenClaw.

• Tambahkan package.json dengan name, version, dan type.
• Tambahkan blok openclaw saat paket menyertakan plugin OpenClaw.
• Gunakan Membuat plugin untuk contoh paket minimal dan Manifes plugin untuk mengetahui pemisahan antara paket dan manifes.
• Jalankan kembali clawhub package validate <path-to-plugin>.

package-openclaw-metadata-missing

Paket memiliki package.json, tetapi tidak mendeklarasikan metadata paket OpenClaw.

• Tambahkan package.json#openclaw.
• Sertakan metadata titik masuk seperti openclaw.extensions atau openclaw.runtimeExtensions.
• Tambahkan metadata kompatibilitas dan instalasi saat paket akan dipublikasikan atau diinstal melalui ClawHub.
• Lihat bidang package.json yang memengaruhi penemuan.
• Jalankan kembali clawhub package validate <path-to-plugin>.

package-openclaw-entry-missing

Metadata paket tersedia, tetapi tidak mendeklarasikan titik masuk runtime OpenClaw.

• Tambahkan openclaw.extensions untuk titik masuk plugin native.
• Tambahkan openclaw.runtimeExtensions saat paket yang dipublikasikan harus memuat JavaScript yang telah dibangun.
• Pastikan semua jalur titik masuk tetap berada di dalam direktori paket.
• Lihat Titik masuk plugin dan bidang package.json yang memengaruhi penemuan.
• Jalankan kembali clawhub package validate <path-to-plugin>.

package-entrypoint-missing

Paket mendeklarasikan titik masuk OpenClaw, tetapi file yang dirujuk tidak ada dalam paket yang sedang divalidasi.

• Periksa setiap jalur dalam openclaw.extensions, openclaw.runtimeExtensions, openclaw.setupEntry, dan openclaw.runtimeSetupEntry.
• Bangun paket jika titik masuk dihasilkan ke dalam dist.
• Perbarui metadata jika titik masuk telah dipindahkan.
• Lihat Titik masuk plugin.
• Jalankan kembali clawhub package validate <path-to-plugin>.

package-install-metadata-incomplete

ClawHub tidak dapat menentukan cara paket harus diinstal atau diperbarui.

• Isi openclaw.install dengan sumber instalasi yang didukung, seperti clawhubSpec, npmSpec, atau localPath.
• Atur openclaw.install.defaultChoice saat tersedia lebih dari satu sumber instalasi.
• Gunakan openclaw.install.minHostVersion untuk versi host OpenClaw minimum.
• Lihat bidang package.json yang memengaruhi penemuan.
• Jalankan kembali clawhub package validate <path-to-plugin>.

package-plugin-api-compat-missing

Paket tidak mendeklarasikan rentang API plugin OpenClaw yang didukungnya.

• Tambahkan openclaw.compat.pluginApi ke package.json.
• Gunakan versi API plugin OpenClaw atau batas bawah semver yang digunakan untuk membangun dan menguji paket.
• Pisahkan ini dari versi paket. Versi paket menjelaskan rilis plugin; openclaw.compat.pluginApi menjelaskan kontrak API host.
• Lihat bidang package.json yang memengaruhi penemuan.
• Jalankan kembali clawhub package validate <path-to-plugin>.

package-min-host-version-drift

Versi host minimum paket tidak cocok dengan metadata versi OpenClaw yang digunakan untuk membangun paket.

• Periksa openclaw.install.minHostVersion.
• Periksa semua metadata build OpenClaw dalam paket, seperti versi OpenClaw yang digunakan selama rilis.
• Selaraskan versi host minimum dengan rentang versi host yang benar-benar didukung oleh paket.
• Lihat bidang package.json yang memengaruhi penemuan.
• Jalankan kembali clawhub package validate <path-to-plugin>.

package-manifest-version-drift

Versi paket dan versi manifes plugin tidak sama.

• Utamakan package.json#version sebagai versi rilis paket.
• Jika openclaw.plugin.json juga memiliki version, perbarui agar sesuai atau hapus metadata versi manifes yang usang jika metadata paket bersifat otoritatif.
• Publikasikan versi paket baru setelah mengubah metadata yang telah dipublikasikan.
• Lihat Manifes plugin.
• Jalankan kembali clawhub package validate <path-to-plugin>.

package-openclaw-unsupported-metadata

Blok package.json#openclaw berisi bidang yang bukan merupakan metadata paket OpenClaw yang didukung.

• Hapus bidang yang tidak didukung seperti openclaw.bundle.
• Simpan metadata plugin native dalam openclaw.plugin.json.
• Simpan titik masuk paket serta metadata kompatibilitas, instalasi, penyiapan, dan katalog dalam bidang package.json#openclaw yang didukung.
• Lihat bidang package.json yang memengaruhi penemuan.
• Jalankan kembali clawhub package validate <path-to-plugin>.

Artefak yang dipublikasikan

package-npm-pack-unavailable

Paket tidak dapat dikemas menjadi artefak yang akan diperiksa atau dipublikasikan oleh ClawHub.

• Jalankan npm pack --dry-run dari akar paket.
• Perbaiki metadata paket yang tidak valid, skrip siklus hidup yang rusak, atau entri file yang menyebabkan pengemasan gagal.
• Hapus private: true jika paket ini ditujukan untuk publikasi umum.
• Jalankan kembali clawhub package validate <path-to-plugin>.

package-npm-pack-entrypoint-missing

Paket dapat dikemas, tetapi artefak yang dikemas tidak menyertakan file titik masuk yang dideklarasikan dalam package.json#openclaw.

• Jalankan npm pack --dry-run dan periksa file yang akan disertakan.
• Bangun titik masuk yang dihasilkan sebelum pengemasan.
• Perbarui files, .npmignore, atau keluaran build agar titik masuk yang dideklarasikan disertakan.
• Lihat Titik masuk plugin.
• Jalankan kembali clawhub package validate <path-to-plugin>.

package-npm-pack-metadata-missing

Artefak yang dikemas tidak memiliki metadata OpenClaw yang tersedia dalam paket sumber Anda.

• Jalankan npm pack --dry-run dan periksa file metadata yang disertakan.
• Pastikan package.json menyertakan blok openclaw dalam artefak yang dikemas.
• Pastikan openclaw.plugin.json disertakan jika paket tersebut merupakan plugin OpenClaw native.
• Perbarui files atau .npmignore agar metadata paket tidak dikecualikan.
• Lihat Membangun plugin.
• Jalankan kembali clawhub package validate <path-to-plugin>.

Metadata manifes

manifest-name-missing

Manifes plugin native tidak menyertakan nama tampilan.

• Tambahkan bidang name yang tidak kosong ke openclaw.plugin.json.
• Pastikan name mudah dibaca manusia dan pertahankan id sebagai id mesin yang stabil.
• Lihat Manifes plugin.
• Jalankan kembali clawhub package validate <path-to-plugin>.

manifest-unknown-fields

Manifes plugin memiliki bidang tingkat teratas yang tidak didukung OpenClaw.

• Bandingkan setiap bidang tingkat teratas dengan referensi bidang manifes.
• Hapus bidang khusus dari openclaw.plugin.json.
• Pindahkan metadata paket atau instalasi ke bidang package.json#openclaw yang didukung, bukan ke manifes.
• Jalankan kembali clawhub package validate <path-to-plugin>.

manifest-unknown-contracts

Manifes mendeklarasikan kunci yang tidak didukung di dalam contracts.

• Bandingkan setiap kunci di bawah contracts dengan referensi kontrak.
• Hapus kunci kontrak yang tidak didukung.
• Pindahkan perilaku runtime ke kode pendaftaran plugin, dan batasi contracts hanya untuk metadata kepemilikan kapabilitas statis.
• Jalankan kembali clawhub package validate <path-to-plugin>.

Migrasi SDK dan kompatibilitas

legacy-root-sdk-import

Plugin mengimpor dari barrel SDK root yang tidak lagi direkomendasikan: openclaw/plugin-sdk.

• Ganti impor barrel root dengan impor subjalur publik yang spesifik.
• Gunakan openclaw/plugin-sdk/plugin-entry untuk definePluginEntry.
• Gunakan openclaw/plugin-sdk/channel-core untuk helper titik masuk saluran.
• Gunakan Konvensi impor dan Subjalur SDK Plugin untuk menemukan impor yang paling spesifik.
• Jalankan kembali clawhub package validate <path-to-plugin>.

reserved-sdk-import

Plugin mengimpor jalur SDK yang dicadangkan untuk plugin bawaan atau kompatibilitas internal.

• Ganti impor SDK internal OpenClaw yang dicadangkan dengan subjalur openclaw/plugin-sdk/* publik yang terdokumentasi.
• Jika perilaku tersebut tidak memiliki SDK publik, pertahankan helper di dalam paket Anda atau minta API OpenClaw publik.
• Gunakan Subjalur SDK Plugin dan Migrasi SDK untuk memilih impor yang didukung.
• Jalankan kembali clawhub package validate <path-to-plugin>.

sdk-load-session-store

Plugin masih menggunakan helper seluruh penyimpanan sesi yang tidak lagi direkomendasikan, loadSessionStore.

• Gunakan getSessionEntry(...) atau listSessionEntries(...) saat membaca status sesi.
• Gunakan patchSessionEntry(...) atau upsertSessionEntry(...) saat menulis status sesi.
• Hindari memuat, memutasi, dan menyimpan seluruh objek penyimpanan sesi.
• Pertahankan loadSessionStore(...) hanya selama rentang kompatibilitas yang Anda deklarasikan masih mendukung versi OpenClaw lama yang memerlukannya.
• Lihat API Runtime dan Subjalur SDK Plugin.
• Jalankan kembali clawhub package validate <path-to-plugin>.

sdk-session-store-write

Plugin masih menggunakan helper penulisan seluruh penyimpanan sesi yang tidak lagi direkomendasikan, seperti saveSessionStore atau updateSessionStore.

• Gunakan patchSessionEntry(...) saat memperbarui bidang pada entri sesi yang sudah ada.
• Gunakan upsertSessionEntry(...) saat mengganti atau membuat entri sesi.
• Hindari memuat, memutasi, dan menyimpan seluruh objek penyimpanan sesi.
• Pertahankan helper penulisan seluruh penyimpanan hanya selama rentang kompatibilitas yang Anda deklarasikan masih mendukung versi OpenClaw lama yang memerlukannya.
• Lihat API Runtime dan Subjalur SDK Plugin.
• Jalankan kembali clawhub package validate <path-to-plugin>.

sdk-session-file-helper

Plugin masih menggunakan helper jalur file sesi yang tidak lagi direkomendasikan, seperti resolveSessionFilePath atau resolveAndPersistSessionFile.

• Gunakan getSessionEntry(...) untuk membaca metadata sesi berdasarkan identitas agen dan sesi.
• Gunakan patchSessionEntry(...) atau upsertSessionEntry(...) untuk menyimpan metadata sesi.
• Gunakan identitas transkrip atau helper target saat kode sedang menyiapkan operasi transkrip.
• Jangan menyimpan atau bergantung pada jalur file transkrip lama.
• Lihat API Runtime dan Subjalur SDK Plugin.
• Jalankan kembali clawhub package validate <path-to-plugin>.

sdk-session-transcript-file-target

Plugin masih menggunakan helper target file transkrip yang tidak lagi direkomendasikan, resolveSessionTranscriptLegacyFileTarget.

• Gunakan resolveSessionTranscriptIdentity(...) saat kode hanya memerlukan identitas sesi publik.
• Gunakan resolveSessionTranscriptTarget(...) saat kode memerlukan target operasi transkrip terstruktur.
• Hindari membaca atau menyusun target file transkrip lama secara langsung.
• Pertahankan helper lama hanya selama rentang kompatibilitas yang Anda deklarasikan masih mendukung versi OpenClaw lama yang memerlukannya.
• Lihat API Runtime dan Subjalur SDK Plugin.
• Jalankan kembali clawhub package validate <path-to-plugin>.

sdk-session-transcript-low-level

Plugin masih menggunakan helper transkrip tingkat rendah yang tidak lagi direkomendasikan, seperti appendSessionTranscriptMessage atau emitSessionTranscriptUpdate.

• Gunakan appendSessionTranscriptMessageByIdentity(...) untuk penambahan transkrip.
• Gunakan publishSessionTranscriptUpdateByIdentity(...) untuk notifikasi pembaruan transkrip.
• Utamakan permukaan runtime transkrip terstruktur agar OpenClaw dapat menerapkan batas transaksi dan penanganan identitas yang tepat.
• Pertahankan helper transkrip tingkat rendah hanya selama rentang kompatibilitas yang Anda deklarasikan masih mendukung versi OpenClaw lama yang memerlukannya.
• Lihat API Runtime dan Subjalur SDK Plugin.
• Jalankan kembali clawhub package validate <path-to-plugin>.

legacy-before-agent-start

Plugin masih menggunakan hook before_agent_start lama.

• Pindahkan pekerjaan penggantian model atau penyedia ke before_model_resolve.
• Pindahkan pekerjaan mutasi prompt atau konteks ke before_prompt_build.
• Pertahankan before_agent_start hanya selama rentang kompatibilitas yang Anda deklarasikan masih mendukung versi OpenClaw lama yang memerlukannya.
• Lihat Hook dan Kompatibilitas plugin.
• Jalankan kembali clawhub package validate <path-to-plugin>.

provider-auth-env-vars

Manifes masih menggunakan metadata autentikasi penyedia providerAuthEnvVars lama.

• Salin metadata variabel lingkungan penyedia ke setup.providers[].envVars.
• Pertahankan providerAuthEnvVars hanya sebagai metadata kompatibilitas selama rentang OpenClaw yang Anda dukung masih memerlukannya.
• Lihat referensi penyiapan dan Migrasi SDK.
• Jalankan kembali clawhub package validate <path-to-plugin>.

channel-env-vars

Manifes menggunakan metadata variabel lingkungan saluran lama atau versi sebelumnya tanpa metadata penyiapan atau konfigurasi terkini yang diharapkan ClawHub.

• Pertahankan metadata variabel lingkungan saluran secara deklaratif agar OpenClaw dapat memeriksa status penyiapan tanpa memuat runtime saluran.
• Salin penyiapan saluran berbasis lingkungan ke metadata penyiapan, konfigurasi saluran, atau saluran paket terkini yang digunakan oleh bentuk plugin Anda.
• Pertahankan channelEnvVars hanya sebagai metadata kompatibilitas selama versi OpenClaw lama yang didukung masih memerlukannya.
• Lihat Manifes plugin dan Plugin saluran.
• Jalankan kembali clawhub package validate <path-to-plugin>.

Manifes keamanan

security-manifest-schema-unavailable

Paket menyediakan openclaw.security.json dengan referensi skema yang tidak dikenali ClawHub sebagai tersedia.

• Hapus URL skema jika hanya bersifat anjuran.
• Gunakan skema berversi yang terdokumentasi hanya setelah OpenClaw menerbitkannya.
• Jalankan kembali clawhub package validate <path-to-plugin>.

unrecognized-security-manifest

Paket menyediakan file manifes keamanan yang tidak didukung.

• Hapus openclaw.security.json hingga OpenClaw mendokumentasikan skema manifes keamanan berversi dan perilaku ClawHub.
• Pertahankan dokumentasi perilaku yang sensitif terhadap keamanan dalam dokumentasi paket publik atau README Anda hingga kontrak manifes tersedia.
• Jalankan kembali clawhub package validate <path-to-plugin>.

Terkait

• CLI ClawHub
• Publikasi ClawHub
• Membangun plugin
• Manifes plugin
• Titik masuk plugin
• Kompatibilitas plugin