--- read_when: - Menggunakan CLI ClawHub - Men-debug instalasi, pembaruan, atau publikasi summary: 'Referensi CLI: perintah, flag, konfigurasi, dan perilaku lockfile.' x-i18n: generated_at: "2026-07-03T17:41:14Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 23065775d74e7b52ed250051b8724b780c28dfdfc0adf9b8f115f7133fbdd77b source_path: clawhub/cli.md workflow: 16 --- # CLI Paket CLI: `clawhub`, bin: `clawhub`. Instal secara global dengan npm atau pnpm: ```bash npm i -g clawhub # or pnpm add -g clawhub ``` Lalu verifikasi: ```bash clawhub --help clawhub login clawhub whoami ``` ## Flag global - `--workdir `: direktori kerja (default: cwd; fallback ke workspace Clawdbot jika dikonfigurasi) - `--dir `: direktori instalasi di bawah workdir (default: `skills`) - `--site `: URL dasar untuk login browser (default: `https://clawhub.ai`) - `--registry `: URL dasar API (default: ditemukan otomatis, jika tidak `https://clawhub.ai`) - `--no-input`: nonaktifkan prompt Padanan env: - `CLAWHUB_SITE` (legacy `CLAWDHUB_SITE`) - `CLAWHUB_REGISTRY` (legacy `CLAWDHUB_REGISTRY`) - `CLAWHUB_WORKDIR` (legacy `CLAWDHUB_WORKDIR`) ### Proxy HTTP CLI menghormati variabel lingkungan proxy HTTP standar untuk sistem di balik proxy perusahaan atau jaringan terbatas: - `HTTPS_PROXY` / `https_proxy` - `HTTP_PROXY` / `http_proxy` - `NO_PROXY` / `no_proxy` Ketika salah satu variabel ini disetel, CLI merutekan permintaan keluar melalui proxy yang ditentukan. `HTTPS_PROXY` digunakan untuk permintaan HTTPS, `HTTP_PROXY` untuk HTTP biasa. `NO_PROXY` / `no_proxy` dihormati untuk melewati proxy bagi host atau domain tertentu. Ini diperlukan pada sistem tempat koneksi keluar langsung diblokir (misalnya container Docker, VPS Hetzner dengan internet hanya-proxy, firewall perusahaan). Contoh: ```bash export HTTPS_PROXY=http://proxy.example.com:3128 export NO_PROXY=localhost,127.0.0.1 clawhub search "my query" ``` Ketika tidak ada variabel proxy yang disetel, perilaku tidak berubah (koneksi langsung). ## File konfigurasi Menyimpan token API Anda + URL registry yang di-cache. - macOS: `~/Library/Application Support/clawhub/config.json` - Linux/XDG: `$XDG_CONFIG_HOME/clawhub/config.json` atau `~/.config/clawhub/config.json` - Windows: `%APPDATA%\\clawhub\\config.json` - Fallback legacy: jika `clawhub/config.json` belum ada tetapi `clawdhub/config.json` ada, CLI memakai ulang path legacy - override: `CLAWHUB_CONFIG_PATH` (legacy `CLAWDHUB_CONFIG_PATH`) ## Perintah ### `login` / `auth login` - Default: membuka browser ke `/cli/auth` dan menyelesaikan lewat callback loopback. - Headless: `clawhub login --token clh_...` - Interaktif remote/headless: `clawhub login --device` mencetak kode dan menunggu saat Anda mengotorisasinya di `/cli/device`. ### `whoami` - Memverifikasi token tersimpan lewat `/api/v1/whoami`. ### `token` - Mencetak token API tersimpan ke stdout. - Berguna untuk menyalurkan token login lokal ke perintah setup secret CI. ### `star ` / `unstar ` - Menambahkan/menghapus skill dari sorotan Anda. - Memanggil `POST /api/v1/stars/` dan `DELETE /api/v1/stars/`. - `--yes` melewati konfirmasi. ### `search ` - Memanggil `/api/v1/search?q=...`. - Output menyertakan slug skill, handle pemilik, nama tampilan, dan skor relevansi. - Pencarian memprioritaskan kecocokan token slug/nama yang persis sebelum popularitas unduhan. Token slug mandiri seperti `map` lebih kuat mencocokkan `personal-map` daripada substring di dalam `amap`. - Popularitas adalah prior peringkat kecil, bukan jaminan posisi teratas. - Jika sebuah skill seharusnya muncul tetapi tidak, jalankan `clawhub inspect @owner/slug` saat sudah login untuk memeriksa diagnostik moderasi yang terlihat oleh pemilik sebelum mengganti nama metadata. ### `explore` - Mencantumkan skill terbaru lewat `/api/v1/skills?limit=...&sort=createdAt` (diurutkan berdasarkan `createdAt` desc). - Flag: - `--limit ` (1-200, default: 25) - `--sort newest|updated|rating|downloads|trending` (default: newest). Alias pengurutan instalasi legacy masih berfungsi untuk kompatibilitas. - `--json` (output yang dapat dibaca mesin) - Output: ` v ` (ringkasan dipotong hingga 50 karakter). ### `inspect @owner/slug` - Mengambil metadata skill dan file versi tanpa menginstal. - `--version `: inspeksi versi tertentu (default: latest). - `--tag `: inspeksi versi bertag (misalnya `latest`). - `--versions`: cantumkan riwayat versi (halaman pertama). - `--limit `: versi maksimum untuk dicantumkan (1-200). - `--files`: cantumkan file untuk versi yang dipilih. - `--file `: ambil konten file mentah (hanya file teks; batas 200KB). - `--json`: output yang dapat dibaca mesin. ### `install @owner/slug` - Menyelesaikan versi terbaru untuk pemilik dan skill bernama. - Mengunduh zip lewat `/api/v1/download`. - Mengekstrak ke `//`. - Menolak menimpa skill yang dipin; jalankan `clawhub unpin ` terlebih dahulu. - Menulis: - `/.clawhub/lock.json` (legacy `.clawdhub`) - `/.clawhub/origin.json` (legacy `.clawdhub`) ### `uninstall ` - Menghapus `//` dan menghapus entri lockfile. - Mengirim telemetri best-effort saat login agar jumlah instalasi saat ini dapat dinonaktifkan. - Interaktif: meminta konfirmasi. - Non-interaktif (`--no-input`): memerlukan `--yes`. ### `list` - Membaca `/.clawhub/lock.json` (legacy `.clawdhub`). - Menampilkan `pinned` di sebelah skill yang dibekukan dengan `clawhub pin`, termasuk alasan opsional. ### `pin ` - Menandai skill terinstal sebagai dipin di lockfile. - `--reason ` mencatat mengapa skill dibekukan. - Skill yang dipin dilewati oleh `update --all` dan ditolak oleh `update ` langsung. - Skill yang dipin juga menolak `install --force` agar byte lokal tidak terganti secara tidak sengaja. ### `unpin ` - Menghapus pin lockfile dari skill terinstal sehingga pembaruan mendatang dapat mengubahnya. ### `update [@owner/slug]` / `update --all` - Menghitung sidik jari dari file lokal. - Jika sidik jari cocok dengan versi yang dikenal: tanpa prompt. - Jika sidik jari tidak cocok: - menolak secara default - menimpa dengan `--force` (atau prompt, jika interaktif) - Skill yang dipin tidak pernah diperbarui oleh `--force`. - `update ` gagal cepat untuk skill yang dipin dan memberi tahu Anda untuk menjalankan `clawhub unpin ` terlebih dahulu. - `update --all` melewati slug yang dipin dan mencetak ringkasan apa saja yang tetap dibekukan. ### `skill publish ` - Membandingkan sidik jari bundle lokal dengan ClawHub dan keluar sukses ketika konten sudah dipublikasikan. - Skill baru default ke `1.0.0`; skill yang berubah default ke versi patch berikutnya. - `--version ` secara eksplisit memilih versi dan memublikasikan bahkan ketika konten cocok dengan versi yang ada. - `--dry-run` menyelesaikan publikasi tanpa mengunggah; `--json` mencetak hasil yang dapat dibaca mesin. - `--owner ` memublikasikan di bawah handle penerbit org/pengguna ketika aktor memiliki akses penerbit. - `--migrate-owner` memindahkan skill yang ada ke `--owner` saat memublikasikan versi baru. Memerlukan akses admin/pemilik pada kedua penerbit. - Perilaku pemilik dan peninjauan dijelaskan di `docs/publishing.md`. - Memublikasikan skill berarti skill dirilis di bawah `MIT-0` di ClawHub. - Skill yang dipublikasikan bebas digunakan, dimodifikasi, dan didistribusikan ulang tanpa atribusi. - ClawHub tidak mendukung skill berbayar atau harga per skill. - Alias legacy: `publish `. ```bash clawhub skill publish ./my-skill --dry-run clawhub skill publish ./my-skill clawhub skill publish ./my-skill --version 2.0.0 ``` #### GitHub Actions Workflow reusable [`skill-publish.yml`](https://github.com/openclaw/clawhub/blob/main/.github/workflows/skill-publish.yml) milik ClawHub memanggil `skill publish` untuk satu `skill_path`, atau untuk setiap folder skill langsung di bawah `root` (default: `skills`). Workflow ini melewati skill yang tidak berubah dan menggunakan perilaku versi patch otomatis yang sama. Setel `dry_run: true` untuk pratinjau tanpa token. Publikasi nyata memerlukan secret `clawhub_token`. ### `sync` - Memindai workdir saat ini, direktori skills yang dikonfigurasi, dan folder `--root ` apa pun untuk folder skill lokal yang berisi `SKILL.md` atau `skill.md`. - Membandingkan setiap sidik jari skill lokal dengan ClawHub dan hanya memublikasikan skill baru atau yang berubah. - Skill baru dipublikasikan sebagai `1.0.0`; skill yang berubah secara default memublikasikan versi patch berikutnya. Gunakan `--bump minor|major` untuk batch pembaruan yang harus naik dengan langkah semver lebih besar. - `--dry-run` menampilkan rencana publikasi tanpa mengunggah; `--json` mencetak rencana yang dapat dibaca mesin. - `--all` memublikasikan setiap skill baru atau yang berubah tanpa prompt. Tanpa `--all`, terminal interaktif memungkinkan Anda memilih skill untuk dipublikasikan. - `--owner ` memublikasikan di bawah handle penerbit org/pengguna ketika aktor memiliki akses penerbit. - `sync` hanya publikasi satu arah. Perintah ini tidak menginstal, memperbarui, mengunduh, atau melaporkan telemetri instalasi/unduhan. ```bash clawhub sync --all --dry-run clawhub sync --all clawhub sync --root ./skills --owner openclaw --bump minor ``` ### `scan --slug ` - Memerlukan `clawhub login`. - Menjalankan ClawHub ClawScan melalui `POST /api/v1/skills/-/scan`, lalu melakukan polling hingga pemindaian terminal. - Pemindaian bersifat asinkron dan mungkin perlu waktu untuk selesai. Saat dalam antrean, spinner terminal menampilkan posisi pemindaian terprioritas saat ini dan berapa banyak pemindaian yang ada di depan. - Pemindaian yang dipublikasikan memerlukan kepemilikan atau akses manajemen penerbit. Moderator/admin dapat menggunakan backend yang sama melalui `clawhub-admin`. - `--update` hanya valid dengan `--slug`; flag ini menulis hasil pemindaian terpublikasi yang sukses kembali ke versi yang dipilih. - `--output ` mengunduh arsip laporan lengkap dengan `manifest.json`, `clawscan.json`, `skillspector.json`, `static-analysis.json`, `virustotal.json`, dan `README.md`. - `--json` mencetak respons polling lengkap untuk otomatisasi. - Pemindaian path lokal tidak lagi didukung. Unggah versi baru, lalu gunakan `scan download` untuk mengambil hasil pemindaian tersimpan untuk versi yang dikirim tersebut. ```bash clawhub scan --slug gifgrep clawhub scan --slug gifgrep --version 1.2.3 clawhub scan --slug gifgrep --update --output report.zip ``` ### `scan download ` - Memerlukan `clawhub login`. - Mengunduh ZIP laporan pemindaian tersimpan untuk versi skill atau plugin yang dikirim, termasuk versi yang diblokir atau disembunyikan oleh pemeriksaan keamanan ClawHub. - Unduhan skill menggunakan slug skill dan default ke `--kind skill`. - Unduhan Plugin menggunakan nama paket dan memerlukan `--kind plugin`. - `--version` wajib agar penulis memeriksa versi kiriman persis yang diblokir ClawHub. - `--output ` memilih path tujuan. ```bash clawhub scan download gifgrep --version 1.2.3 clawhub scan download @scope/demo --version 2.0.0 --kind plugin --output report.zip ``` #### GitHub Actions ClawHub menyertakan workflow reusable resmi di [`/.github/workflows/skill-publish.yml`](https://github.com/openclaw/clawhub/blob/76b4f36bb0f7409ed7cb9c6fd6f1ccf81396ee88/.github/workflows/skill-publish.yml) untuk repo skill dan repo katalog. Setup katalog umum: ```yaml name: Skill Publish on: pull_request: workflow_dispatch: jobs: dry-run: if: github.event_name == 'pull_request' uses: openclaw/clawhub/.github/workflows/skill-publish.yml@v1 with: owner: nvidia dry_run: true publish: if: github.event_name == 'workflow_dispatch' uses: openclaw/clawhub/.github/workflows/skill-publish.yml@v1 with: owner: nvidia dry_run: false secrets: clawhub_token: ${{ secrets.CLAWHUB_TOKEN }} ``` Catatan: - `root` default ke `skills` untuk repo katalog. - Teruskan `skill_path: skills/review-helper` untuk memproses satu folder skill. - `owner` dipetakan ke flag CLI `--owner`; hilangkan untuk memublikasikan sebagai pengguna terautentikasi. - Publikasi skill V1 menggunakan `clawhub_token`; publikasi tepercaya GitHub OIDC saat ini hanya untuk paket. ### `delete ` - Tanpa `--version`, hapus sementara sebuah skill (pemilik, moderator, atau admin). - Memanggil `DELETE /api/v1/skills/{slug}`. - Penghapusan sementara yang dimulai pemilik akan mencadangkan slug selama 30 hari; perintah mencetak waktu kedaluwarsanya. - `--version ` menghapus permanen satu versi non-terbaru yang dimiliki melalui rute fail-closed khusus versi. Versi yang dihapus tidak dapat dipulihkan atau dipublikasikan ulang. Publikasikan pengganti sebelum menghapus versi terbaru saat ini. Staf platform tidak melewati kepemilikan untuk alur khusus versi ini. - `--reason ` mencatat catatan moderasi pada penghapusan sementara skill secara keseluruhan dan log audit. - `--note ` adalah alias untuk `--reason`. - `--yes` melewati konfirmasi. ### `undelete ` - Pulihkan skill tersembunyi (pemilik, moderator, atau admin). - Tidak ada pembatalan penghapusan versi; versi yang dihapus permanen tidak dapat dipulihkan. - Memanggil `POST /api/v1/skills/{slug}/undelete`. - `--reason ` mencatat catatan moderasi pada skill dan log audit. - `--note ` adalah alias untuk `--reason`. - `--yes` melewati konfirmasi. ### `hide ` - Sembunyikan skill (pemilik, moderator, atau admin). - Alias untuk `delete`. ### `unhide ` - Tampilkan kembali skill (pemilik, moderator, atau admin). - Alias untuk `undelete`. ### `skill rename ` - Ganti nama skill yang dimiliki dan pertahankan slug sebelumnya sebagai alias pengalihan. - Memanggil `POST /api/v1/skills/{slug}/rename`. - `--yes` melewati konfirmasi. ### `skill merge ` - Gabungkan satu skill yang dimiliki ke skill lain yang dimiliki. - Slug sumber berhenti ditampilkan secara publik dan menjadi alias pengalihan ke target. - Memanggil `POST /api/v1/skills/{sourceSlug}/merge`. - `--yes` melewati konfirmasi. ### `transfer` - Alur kerja transfer kepemilikan. - Transfer ke handle pengguna membuat permintaan tertunda yang diterima oleh penerima. - Transfer ke handle org/publisher langsung berlaku hanya ketika aktor memiliki akses admin ke pemilik saat ini dan publisher tujuan. - Subperintah: - `transfer request [--message "..."] [--yes]` - `transfer list [--outgoing]` - `transfer accept [--yes]` - `transfer reject [--yes]` - `transfer cancel [--yes]` - Endpoint: - `POST /api/v1/skills/{slug}/transfer` - `POST /api/v1/skills/{slug}/transfer/accept` - `POST /api/v1/skills/{slug}/transfer/reject` - `POST /api/v1/skills/{slug}/transfer/cancel` - `GET /api/v1/transfers/incoming` - `GET /api/v1/transfers/outgoing` ### `package explore [query...]` - Menjelajahi atau mencari katalog paket terpadu melalui `GET /api/v1/packages` dan `GET /api/v1/packages/search`. - Gunakan ini untuk plugin dan entri keluarga paket lainnya; `search` tingkat atas tetap menjadi permukaan pencarian skill. - Flag: - `--family skill|code-plugin|bundle-plugin` - `--official` - `--executes-code` - `--target `, `--os `, `--arch `, `--libc ` - `--requires-browser`, `--requires-desktop`, `--requires-native-deps` - `--requires-external-service`, `--external-service ` - `--binary `, `--os-permission ` - `--artifact-kind legacy-zip|npm-pack` - `--npm-mirror` - `--limit ` (1-100, default: 25) - `--json` Contoh: ```bash clawhub package explore --family code-plugin clawhub package explore --family code-plugin --os darwin --requires-desktop clawhub package explore --family code-plugin --artifact-kind npm-pack clawhub package explore --npm-mirror clawhub package explore episodic-claw --family code-plugin ``` ### `package inspect ` - Mengambil metadata paket tanpa menginstal. - Gunakan ini untuk metadata plugin, kompatibilitas, verifikasi, sumber, dan pemeriksaan versi/file. - `--version `: periksa versi tertentu (default: latest). - `--tag `: periksa versi bertag (misalnya `latest`). - `--versions`: daftar riwayat versi (halaman pertama). - `--limit `: versi maksimum yang dicantumkan (1-100). - `--files`: daftar file untuk versi yang dipilih. - `--file `: ambil konten file mentah (hanya file teks; batas 200KB). - `--json`: keluaran yang dapat dibaca mesin. ### `package download ` - Menyelesaikan versi paket melalui `GET /api/v1/packages/{name}/versions/{version}/artifact`. - Mengunduh artefak dari `downloadUrl` milik resolver. - Memverifikasi SHA-256 ClawHub untuk semua artefak. - Untuk artefak ClawPack npm-pack, juga memverifikasi integritas npm `sha512`, shasum npm, dan nama/versi `package.json` tarball. - Versi ZIP legacy diunduh melalui rute ZIP legacy. - Flag: - `--version `: unduh versi tertentu. - `--tag `: unduh versi bertag (default: `latest`). - `-o, --output `: file atau direktori keluaran. - `--force`: timpa file keluaran yang sudah ada. - `--json`: keluaran yang dapat dibaca mesin. Contoh: ```bash clawhub package download @openclaw/example-plugin --tag latest clawhub package download @openclaw/example-plugin --version 1.2.3 -o artifacts/ ``` ### `package verify ` - Menghitung SHA-256 ClawHub, integritas npm `sha512`, dan shasum npm untuk artefak lokal. - Dengan `--package`, menyelesaikan metadata yang diharapkan dari ClawHub dan membandingkan file lokal dengan metadata artefak yang dipublikasikan. - Dengan flag digest langsung, memverifikasi tanpa pencarian jaringan. - Flag: - `--package `: nama paket untuk menyelesaikan metadata artefak yang diharapkan. - `--version ` atau `--tag `: versi paket yang diharapkan. - `--sha256 `: SHA-256 ClawHub yang diharapkan. - `--npm-integrity `: integritas npm yang diharapkan. - `--npm-shasum `: shasum npm yang diharapkan. - `--json`: keluaran yang dapat dibaca mesin. Contoh: ```bash clawhub package verify ./example-plugin-1.2.3.tgz --package @openclaw/example-plugin --version 1.2.3 clawhub package verify ./example-plugin-1.2.3.tgz --sha256 ``` ### `package validate ` - Menjalankan Plugin Inspector bawaan CLI ClawHub terhadap folder paket plugin lokal. - Default ke validasi offline/statis, tanpa menemukan atau mengimpor checkout OpenClaw lokal. - Kesalahan kompatibilitas berat keluar dengan nilai non-nol. Temuan yang hanya berupa peringatan dicetak tetapi keluar dengan nilai nol. - Flag: - `--out `: tulis laporan Plugin Inspector ke direktori ini. - `--openclaw `: periksa terhadap checkout OpenClaw lokal yang eksplisit. - `--runtime`: aktifkan penangkapan runtime; mengimpor kode plugin. - `--allow-execute`: izinkan penangkapan runtime di workspace terisolasi. - `--no-mock-sdk`: nonaktifkan SDK OpenClaw tiruan selama penangkapan runtime. - `--json`: keluaran yang dapat dibaca mesin. Contoh: ```bash clawhub package validate ./example-plugin ``` Jika validasi melaporkan temuan paket, manifes, impor SDK, atau artefak, lihat [Perbaikan validasi plugin](/clawhub/plugin-validation-fixes), lalu jalankan ulang perintah. ### `package delete ` - Tanpa `--version`, menghapus sementara paket dan semua rilis. - `--version ` menghapus permanen satu rilis non-terbaru yang dimiliki melalui rute fail-closed khusus versi. Versi yang dihapus tidak dapat dipulihkan atau dipublikasikan ulang. Publikasikan pengganti sebelum menghapus versi terbaru saat ini. Alur khusus versi ini memerlukan pemilik paket atau admin publisher org; staf platform tidak melewati kepemilikan paket. - Penghapusan sementara seluruh paket memerlukan pemilik paket, owner/admin publisher org, moderator platform, atau admin platform. - Flag: - `--version `: hapus permanen satu versi non-terbaru. - `--yes`: lewati konfirmasi. - `--json`: keluaran yang dapat dibaca mesin. Contoh: ```bash clawhub package delete @openclaw/example-plugin --yes clawhub package delete @openclaw/example-plugin --version 1.2.3 --yes ``` ### `package undelete ` - Memulihkan paket dan rilis yang dihapus sementara. - Tidak ada pembatalan penghapusan versi; versi yang dihapus permanen tidak dapat dipulihkan. - Memerlukan pemilik paket, owner/admin publisher org, moderator platform, atau admin platform. - Memanggil `POST /api/v1/packages/{name}/undelete`. - Flag: - `--yes`: lewati konfirmasi. - `--json`: keluaran yang dapat dibaca mesin. Contoh: ```bash clawhub package undelete @openclaw/example-plugin --yes ``` ### `package transfer ` - Mentransfer paket ke publisher lain. - Memerlukan akses admin ke pemilik paket saat ini dan publisher tujuan, kecuali dilakukan oleh admin platform. - Nama paket berscope harus ditransfer ke pemilik scope yang cocok. - Memanggil `POST /api/v1/packages/{name}/transfer`. - Flag: - `--to `: handle publisher tujuan. - `--reason `: alasan audit opsional. - `--json`: keluaran yang dapat dibaca mesin. Contoh: ```bash clawhub package transfer @openclaw/example-plugin --to openclaw ``` ### `package report` - Perintah terautentikasi untuk melaporkan paket kepada moderator. - Memanggil `POST /api/v1/packages/{name}/report`. - Laporan berada pada tingkat paket, secara opsional terikat ke versi, dan menjadi terlihat oleh moderator untuk ditinjau. - Laporan tidak otomatis menyembunyikan paket atau memblokir unduhan dengan sendirinya. - Flag: - `--version `: versi paket opsional untuk dilampirkan ke laporan. - `--reason `: alasan laporan wajib. - `--json`: keluaran yang dapat dibaca mesin. Contoh: ```bash clawhub package report @openclaw/example-plugin --version 1.2.3 --reason "suspicious native payload" ``` ### `package moderation-status` - Perintah pemilik untuk memeriksa visibilitas moderasi paket. - Memanggil `GET /api/v1/packages/{name}/moderation`. - Menampilkan status pemindaian paket saat ini, jumlah laporan terbuka, status moderasi manual rilis terbaru, status blokir unduhan, dan alasan moderasi. - Flag: - `--json`: keluaran yang dapat dibaca mesin. Contoh: ```bash clawhub package moderation-status @openclaw/example-plugin ``` ### `package readiness ` - Memeriksa apakah paket siap untuk konsumsi OpenClaw mendatang. - Memanggil `GET /api/v1/packages/{name}/readiness`. - Melaporkan pemblokir untuk status resmi, ketersediaan ClawPack, digest artefak, asal-usul sumber, kompatibilitas OpenClaw, target host, metadata lingkungan, dan status pemindaian. - Flag: - `--json`: keluaran yang dapat dibaca mesin. Contoh: ```bash clawhub package readiness @openclaw/example-plugin ``` ### `package migration-status ` - Menampilkan status migrasi berorientasi operator untuk paket yang dapat menggantikan plugin OpenClaw bawaan. - Memanggil endpoint kesiapan terhitung yang sama dengan `package readiness`, tetapi mencetak status berfokus migrasi, versi terbaru, status paket resmi, pemeriksaan, dan pemblokir. - Flag: - `--json`: keluaran yang dapat dibaca mesin. Contoh: ```bash clawhub package migration-status @openclaw/example-plugin ``` ### `publisher create ` - Membuat publisher org yang dimiliki oleh pengguna terautentikasi. - Handle dinormalisasi ke huruf kecil dan dapat diberikan dengan atau tanpa `@`. - Publisher org yang baru dibuat tidak dipercaya/resmi secara default. - Gagal jika handle sudah digunakan oleh publisher, pengguna, atau rute cadangan yang sudah ada. ```bash clawhub publisher create opik --display-name "Opik" ``` ### `package publish ` - Menerbitkan Plugin kode atau Plugin bundel melalui `POST /api/v1/packages`. - `` menerima: - Path folder lokal: `./my-plugin` - Tarball npm-pack ClawPack lokal: `./my-plugin-1.2.3.tgz` - Repo GitHub: `owner/repo` atau `owner/repo@ref` - URL GitHub: `https://github.com/owner/repo` - Metadata dideteksi otomatis dari `package.json`, `openclaw.plugin.json`, dan penanda bundel OpenClaw nyata seperti `.codex-plugin/plugin.json`, `.claude-plugin/plugin.json`, dan `.cursor-plugin/plugin.json`. - Sumber `.tgz` diperlakukan sebagai ClawPack. CLI mengunggah byte npm-pack yang persis dan menggunakan konten `package/` yang diekstrak hanya untuk validasi dan pengisian awal metadata. - Folder Plugin kode dikemas menjadi tarball npm ClawPack sebelum diunggah agar instalasi OpenClaw dapat memverifikasi artefak yang persis. Folder Plugin bundel tetap menggunakan jalur penerbitan file yang diekstrak. - Untuk sumber GitHub, atribusi sumber diisi otomatis dari repo, commit yang di-resolve, ref, dan subpath. - Untuk folder lokal, atribusi sumber dideteksi otomatis dari git lokal saat remote origin mengarah ke GitHub. - Plugin kode eksternal harus mendeklarasikan `openclaw.compat.pluginApi` dan `openclaw.build.openclawVersion` secara eksplisit. `package.json.version` tingkat atas tidak digunakan sebagai fallback untuk validasi penerbitan. - `--dry-run` menampilkan pratinjau payload penerbitan yang di-resolve tanpa mengunggah. - `--json` menghasilkan output yang dapat dibaca mesin untuk CI. - `--owner ` menerbitkan di bawah handle penerbit pengguna atau org saat aktor memiliki akses penerbit. - Nama paket berscope harus cocok dengan owner yang dipilih. Lihat `docs/publishing.md`. - Flag yang ada (`--family`, `--name`, `--version`, `--source-repo`, `--source-commit`, `--source-ref`, `--source-path`) tetap berfungsi sebagai override. - Repo GitHub privat memerlukan `GITHUB_TOKEN`. ```bash clawhub package publish ./plugin.tgz --owner openclaw ``` #### Alur lokal yang direkomendasikan Gunakan `--dry-run` terlebih dahulu agar Anda dapat mengonfirmasi metadata paket yang di-resolve dan atribusi sumber sebelum membuat rilis aktual: ```bash npm pack clawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin --dry-run clawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin ``` #### Alur folder lokal Untuk Plugin kode, penerbitan folder membangun dan mengunggah artefak ClawPack dari folder paket: ```bash clawhub package publish ./my-plugin --family code-plugin --dry-run clawhub package publish ./my-plugin --family code-plugin ``` #### `package.json` minimal untuk `--family code-plugin` Plugin kode eksternal memerlukan sedikit metadata OpenClaw di `package.json`. Manifest minimal ini cukup untuk penerbitan yang berhasil: ```json { "name": "@myorg/openclaw-my-plugin", "version": "1.0.0", "type": "module", "openclaw": { "extensions": ["./index.ts"], "compat": { "pluginApi": ">=2026.3.24-beta.2" }, "build": { "openclawVersion": "2026.3.24-beta.2" } } } ``` Kolom wajib: - `openclaw.compat.pluginApi` - `openclaw.build.openclawVersion` Catatan: - `package.json.version` adalah versi rilis paket Anda, tetapi tidak digunakan sebagai fallback untuk validasi kompatibilitas/build OpenClaw. - `openclaw.hostTargets` dan `openclaw.environment` adalah metadata opsional. ClawHub dapat menampilkannya saat ada, tetapi keduanya tidak wajib untuk penerbitan. - `openclaw.compat.minGatewayVersion` dan `openclaw.build.pluginSdkVersion` adalah tambahan opsional jika Anda ingin menerbitkan metadata kompatibilitas yang lebih detail. - Jika Anda menggunakan rilis CLI `clawhub` yang lebih lama, tingkatkan sebelum menerbitkan agar pemeriksaan preflight lokal berjalan sebelum pengunggahan. - Jika validasi melaporkan kode remediasi, lihat [Perbaikan validasi Plugin](/clawhub/plugin-validation-fixes). #### GitHub Actions ClawHub juga menyertakan workflow resmi yang dapat digunakan ulang di [`/.github/workflows/package-publish.yml`](https://github.com/openclaw/clawhub/blob/76b4f36bb0f7409ed7cb9c6fd6f1ccf81396ee88/.github/workflows/package-publish.yml) untuk repo Plugin. Pengaturan pemanggil umum: ```yaml name: Package Publish on: pull_request: workflow_dispatch: push: tags: - "v*" jobs: dry-run: if: github.event_name == 'pull_request' uses: openclaw/clawhub/.github/workflows/package-publish.yml@v0.12.0 with: dry_run: true publish: if: github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/') permissions: contents: read id-token: write uses: openclaw/clawhub/.github/workflows/package-publish.yml@v0.12.0 with: dry_run: false secrets: clawhub_token: ${{ secrets.CLAWHUB_TOKEN }} ``` Catatan: - Workflow yang dapat digunakan ulang menjadikan `source` default ke repo pemanggil. - Untuk monorepo, berikan `source_path` agar workflow menerbitkan folder paket Plugin, misalnya `source_path: extensions/codex`. - Pin workflow yang dapat digunakan ulang ke tag stabil atau SHA commit lengkap. Jangan menjalankan penerbitan rilis dari `@main`. - `pull_request` sebaiknya menggunakan `dry_run: true` agar CI tetap tidak mencemari. - Penerbitan nyata sebaiknya dibatasi ke event tepercaya seperti `workflow_dispatch` atau push tag. - Penerbitan tepercaya tanpa secret hanya berfungsi pada `workflow_dispatch`; push tag tetap memerlukan `clawhub_token`. - Biarkan `clawhub_token` tersedia untuk penerbitan pertama, paket tidak tepercaya, atau penerbitan break-glass. - Workflow mengunggah hasil JSON sebagai artefak dan mengeksposnya sebagai output workflow. ### `package trusted-publisher get ` - Menampilkan konfigurasi penerbit tepercaya GitHub Actions untuk sebuah paket. - Gunakan ini setelah mengatur konfigurasi untuk mengonfirmasi repositori, nama file workflow, dan pin environment opsional. - Flag: - `--json`: output yang dapat dibaca mesin. Contoh: ```bash clawhub package trusted-publisher get @openclaw/example-plugin ``` ### `package trusted-publisher set ` - Melampirkan atau mengganti konfigurasi penerbit tepercaya GitHub Actions untuk paket yang sudah ada. - Paket harus dibuat terlebih dahulu melalui `clawhub package publish` manual normal atau yang diautentikasi token. - Setelah konfigurasi diatur, penerbitan GitHub Actions yang didukung di masa mendatang dapat menggunakan penerbitan OIDC/tepercaya tanpa token ClawHub berumur panjang. - `--repository ` harus berupa `owner/repo`. - `--workflow-filename ` harus cocok dengan nama file workflow di `.github/workflows/`. - `--environment ` bersifat opsional. Saat dikonfigurasi, environment GitHub Actions dalam klaim OIDC harus cocok persis. - ClawHub memverifikasi repositori GitHub yang dikonfigurasi saat perintah ini berjalan. Repositori publik dapat diverifikasi melalui metadata GitHub publik. Repositori privat memerlukan ClawHub memiliki akses GitHub ke repositori tersebut, misalnya melalui instalasi GitHub App ClawHub di masa mendatang atau integrasi GitHub resmi lainnya. - Flag: - `--repository `: repositori GitHub, misalnya `openclaw/example-plugin`. - `--workflow-filename `: nama file workflow, misalnya `package-publish.yml`. - `--environment `: environment GitHub Actions pencocokan persis opsional. - `--json`: output yang dapat dibaca mesin. Contoh: ```bash clawhub package trusted-publisher set @openclaw/example-plugin \ --repository openclaw/example-plugin \ --workflow-filename package-publish.yml \ --environment release ``` ### `package trusted-publisher delete ` - Menghapus konfigurasi penerbit tepercaya dari sebuah paket. - Gunakan ini sebagai rollback jika workflow, repositori, atau pin environment perlu dinonaktifkan atau dibuat ulang. - Penerbitan nyata di masa mendatang harus menggunakan penerbitan terautentikasi normal hingga konfigurasi diatur lagi. - Flag: - `--json`: output yang dapat dibaca mesin. Contoh: ```bash clawhub package trusted-publisher delete @openclaw/example-plugin ``` ### Telemetri instalasi - Dikirim setelah `clawhub install ` saat masuk, kecuali `CLAWHUB_DISABLE_TELEMETRY=1` diatur. - Pelaporan bersifat upaya terbaik. Perintah instalasi tidak gagal jika telemetri tidak tersedia. - Detail: `docs/telemetry.md`.