OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Plugins

Plugin

Plugin memperluas OpenClaw dengan saluran, penyedia model, harness agen, alat, Skills, percakapan, transkripsi waktu nyata, suara, pemahaman media, pembuatan, pengambilan web, pencarian web, dan kemampuan runtime lainnya.

Gunakan halaman ini untuk menginstal Plugin, memulai ulang Gateway, memverifikasi bahwa runtime telah memuatnya, dan menangani kegagalan penyiapan umum. Untuk contoh yang hanya berisi perintah, lihat Kelola Plugin. Untuk inventaris yang dihasilkan dari Plugin bawaan, eksternal resmi, dan khusus sumber, lihat Inventaris Plugin.

Persyaratan

  • checkout atau instalasi OpenClaw dengan CLI openclaw yang tersedia
  • akses jaringan ke sumber yang dipilih (ClawHub, npm, atau host git)
  • kredensial khusus Plugin, kunci konfigurasi, atau alat OS yang disebutkan oleh dokumentasi penyiapan Plugin tersebut
  • izin bagi Gateway yang melayani saluran Anda untuk memuat ulang atau memulai ulang

Mulai cepat

  • Temukan Plugin

    Cari paket Plugin publik di ClawHub:

    bash
    openclaw plugins search "calendar"

    ClawHub adalah sarana penemuan utama untuk Plugin komunitas. Selama transisi peluncuran, spesifikasi paket biasa tanpa prefiks tetap diinstal dari npm kecuali cocok dengan id Plugin resmi. Spesifikasi mentah @openclaw/* yang cocok dengan Plugin bawaan akan diarahkan ke salinan bawaan tersebut. Gunakan prefiks sumber eksplisit ketika Anda membutuhkan sumber tertentu.

  • Instal Plugin

    bash
    # Dari ClawHub.openclaw plugins install clawhub:<package> # Dari npm.openclaw plugins install npm:<package> # Dari git.openclaw plugins install git:github.com/<owner>/<repo>@<ref> # Dari checkout pengembangan lokal.openclaw plugins install ./my-pluginopenclaw plugins install --link ./my-plugin

    Perlakukan instalasi Plugin seperti menjalankan kode. Utamakan versi yang dipatok untuk instalasi produksi yang dapat direproduksi.

  • Konfigurasikan dan aktifkan

    Konfigurasikan pengaturan khusus Plugin di bawah plugins.entries.<id>.config. Aktifkan Plugin jika belum aktif:

    bash
    openclaw plugins enable <plugin-id>

    Jika plugins.allow ditetapkan, id Plugin yang diinstal harus ada dalam daftar tersebut sebelum Plugin dapat dimuat. openclaw plugins install menambahkan id yang diinstal ke daftar plugins.allow yang sudah ada dan menghapus id yang sama dari plugins.deny agar instalasi eksplisit dapat dimuat setelah dimulai ulang.

  • Biarkan Gateway memuat ulang

    Menginstal, memperbarui, atau menghapus instalasi kode Plugin memerlukan dimulainya ulang Gateway. Gateway terkelola dengan pemuatan ulang konfigurasi yang diaktifkan akan mendeteksi perubahan catatan instalasi Plugin dan memulai ulang secara otomatis. Jika tidak, mulai ulang sendiri:

    bash
    openclaw gateway restart

    Pengaktifan/penonaktifan memperbarui konfigurasi dan registri dingin. Pemeriksaan runtime tetap menjadi bukti paling jelas atas permukaan runtime yang aktif.

  • Verifikasi pendaftaran runtime

    bash
    openclaw plugins inspect <plugin-id> --runtime --json

    Gunakan --runtime untuk membuktikan alat, hook, layanan, metode Gateway, atau perintah CLI milik Plugin yang terdaftar. inspect biasa hanya memeriksa manifes dan registri dingin.

    • Konfigurasi

    Pilih sumber instalasi

    Sumber Gunakan ketika Contoh
    ClawHub Anda menginginkan penemuan asli OpenClaw, pemindaian, metadata versi, dan petunjuk instalasi openclaw plugins install clawhub:<package>
    npm Anda memerlukan alur kerja registri npm atau dist-tag secara langsung openclaw plugins install npm:<package>
    git Anda memerlukan cabang, tag, atau commit dari suatu repositori openclaw plugins install git:github.com/<owner>/<repo>@<ref>
    jalur lokal Anda sedang mengembangkan atau menguji Plugin pada mesin yang sama openclaw plugins install --link ./my-plugin
    marketplace Anda sedang menginstal Plugin marketplace yang kompatibel dengan Claude openclaw plugins install <plugin> --marketplace <source>

    Spesifikasi paket tanpa prefiks memiliki perilaku kompatibilitas khusus: nama tanpa prefiks yang cocok dengan id Plugin bawaan menggunakan sumber bawaan tersebut; nama tanpa prefiks yang cocok dengan id Plugin eksternal resmi menggunakan katalog paket resmi; spesifikasi tanpa prefiks lainnya diinstal melalui npm selama transisi peluncuran. Spesifikasi mentah @openclaw/* yang cocok dengan Plugin bawaan juga diarahkan ke salinan bawaan sebelum fallback ke npm. Gunakan npm:@openclaw/<plugin>@<version> untuk secara sengaja menginstal paket npm eksternal alih-alih salinan bawaan. Gunakan clawhub:, npm:, git:, atau npm-pack: untuk pemilihan sumber deterministik. Lihat openclaw plugins untuk kontrak perintah lengkap.

    Untuk instalasi npm, spesifikasi yang tidak dipatok dan @latest memilih paket stabil terbaru yang menyatakan kompatibilitas dengan build OpenClaw ini. Jika rilis terbaru npm saat ini mendeklarasikan openclaw.compat.pluginApi atau openclaw.install.minHostVersion yang lebih baru daripada yang didukung build ini, OpenClaw memindai versi stabil yang lebih lama dan menginstal versi terbaru yang sesuai. Versi persis dan tag saluran eksplisit seperti @beta tetap dipatok ke paket yang dipilih dan gagal jika tidak kompatibel.

    Kebijakan instalasi operator

    Konfigurasikan security.installPolicy untuk menjalankan perintah kebijakan lokal tepercaya sebelum instalasi atau pembaruan Plugin dilanjutkan. Kebijakan menerima metadata beserta jalur sumber yang telah disiapkan dan dapat mengizinkan atau memblokir instalasi. Kebijakan ini mencakup jalur instalasi/ pembaruan melalui CLI maupun Gateway. Hook before_install Plugin dijalankan setelahnya, dan hanya dalam proses OpenClaw tempat hook Plugin dimuat, jadi gunakan security.installPolicy untuk keputusan instalasi milik operator. Flag --dangerously-force-unsafe-install yang tidak lagi disarankan diterima untuk kompatibilitas tetapi tidak melakukan apa pun: flag tersebut tidak melewati kebijakan instalasi atau daftar larangan dependensi Plugin bawaan OpenClaw.

    Lihat Konfigurasi Skills untuk skema eksekusi bersama security.installPolicy yang digunakan oleh Skills dan Plugin.

    Konfigurasikan kebijakan Plugin

    Bentuk konfigurasi Plugin yang umum adalah:

    json5
    {  plugins: {    enabled: true,    allow: ["voice-call"],    deny: ["untrusted-plugin"],    load: { paths: ["~/Projects/oss/voice-call-plugin"] },    slots: { memory: "memory-core" },    entries: {      "voice-call": { enabled: true, config: { provider: "twilio" } },    },  },}

    Aturan kebijakan utama:

    • plugins.enabled: false menonaktifkan semua Plugin dan melewati pekerjaan penemuan/pemuatan. Referensi Plugin usang tetap tidak aktif selama ini berlaku; aktifkan kembali Plugin sebelum menjalankan pembersihan doctor jika Anda ingin id usang dihapus.
    • plugins.deny lebih diutamakan daripada daftar izin dan pengaktifan per Plugin.
    • plugins.allow adalah daftar izin eksklusif. Alat milik Plugin di luar daftar izin tetap tidak tersedia meskipun tools.allow menyertakan "*".
    • plugins.entries.<id>.enabled: false menonaktifkan satu Plugin sambil mempertahankan konfigurasinya.
    • plugins.load.paths menambahkan file atau direktori Plugin lokal secara eksplisit. Jalur lokal yang dikelola oleh plugins install harus berupa direktori atau arsip Plugin; gunakan plugins.load.paths untuk file Plugin mandiri.
    • Plugin yang berasal dari ruang kerja dinonaktifkan secara default; aktifkan atau masukkan secara eksplisit ke daftar izin sebelum menggunakan kode ruang kerja lokal.
    • Plugin bawaan mengikuti metadata bawaan aktif-secara-default/ nonaktif-secara-default kecuali konfigurasi menimpanya secara eksplisit.
    • plugins.slots.<slot> (memory atau contextEngine) memilih satu Plugin untuk kategori eksklusif. Pemilihan slot dihitung sebagai aktivasi eksplisit dan memaksa Plugin yang dipilih aktif untuk slot tersebut, meskipun biasanya bersifat pilihan. plugins.deny dan plugins.entries.<id>.enabled: false tetap memblokirnya.
    • Plugin bawaan yang bersifat pilihan dapat aktif secara otomatis ketika konfigurasi menyebut salah satu permukaan miliknya, seperti referensi penyedia/model, konfigurasi saluran, backend CLI, atau runtime harness agen.
    • Perutean Codex keluarga OpenAI menjaga batas penyedia dan Plugin runtime tetap terpisah: referensi model Codex lama merupakan konfigurasi lama yang diperbaiki doctor, sedangkan Plugin codex bawaan memiliki runtime app-server Codex untuk referensi agen openai/* kanonis, agentRuntime.id: "codex" eksplisit, dan referensi codex/* lama.

    Saat plugins.allow tidak ditetapkan dan Plugin nonbawaan ditemukan secara otomatis dari ruang kerja atau root Plugin global, log startup menampilkan plugins.allow is empty; discovered non-bundled plugins may auto-load: ... beserta id Plugin yang ditemukan dan, untuk daftar pendek, cuplikan plugins.allow minimal. Jalankan openclaw plugins list --enabled --verbose atau openclaw plugins inspect <id> pada id Plugin yang tercantum sebelum menyalin Plugin tepercaya ke openclaw.json. Pemastian kepercayaan yang sama berlaku ketika diagnostik menyatakan Plugin dimuat without install/load-path provenance: periksa id Plugin tersebut, lalu patok di plugins.allow atau instal ulang dari sumber tepercaya agar OpenClaw mencatat asal instalasi.

    Jalankan openclaw doctor atau openclaw doctor --fix ketika validasi konfigurasi melaporkan id Plugin usang, ketidakcocokan daftar izin/alat, atau jalur Plugin bawaan lama.

    Memahami format Plugin

    OpenClaw mengenali dua format Plugin:

    Format Cara pemuatan Gunakan ketika
    Plugin asli OpenClaw openclaw.plugin.json ditambah modul runtime yang dimuat dalam proses Anda menginstal atau membangun kemampuan runtime khusus OpenClaw
    Bundel kompatibel Tata letak Plugin Codex, Claude, atau Cursor yang dipetakan ke inventaris Plugin OpenClaw Anda menggunakan kembali Skills, perintah, hook, atau metadata bundel yang kompatibel

    Kedua format muncul di openclaw plugins list, openclaw plugins inspect, openclaw plugins enable, dan openclaw plugins disable. Lihat Bundel Plugin untuk batas kompatibilitas bundel dan Membangun Plugin untuk pembuatan Plugin asli.

    Hook Plugin

    Plugin dapat mendaftarkan hook saat runtime melalui dua API berbeda:

    • Hook bertipe api.on(...) untuk peristiwa siklus hidup runtime. Ini adalah permukaan yang diutamakan untuk middleware, kebijakan, penulisan ulang pesan, pembentukan prompt, dan kontrol alat.
    • api.registerHook(...) untuk sistem hook internal yang dijelaskan di Hook. Ini terutama untuk efek samping perintah/siklus hidup tingkat kasar dan kompatibilitas dengan otomatisasi bergaya HOOK yang sudah ada.

    Aturan singkat: jika handler memerlukan prioritas, semantik penggabungan, atau perilaku pemblokiran/pembatalan, gunakan hook bertipe. Jika hanya bereaksi terhadap command:new, command:reset, message:sent, atau peristiwa tingkat kasar serupa, api.registerHook sudah memadai.

    Hook internal yang dikelola Plugin muncul di openclaw hooks list dengan plugin:<id>. Anda tidak dapat mengaktifkan atau menonaktifkannya melalui openclaw hooks; aktifkan atau nonaktifkan Plugin sebagai gantinya.

    Verifikasi Gateway aktif

    openclaw plugins list dan openclaw plugins inspect biasa membaca konfigurasi dingin, manifes, dan status registri. Perintah tersebut tidak membuktikan bahwa Gateway yang sudah berjalan telah mengimpor kode Plugin yang sama.

    Ketika Plugin tampak terinstal tetapi lalu lintas percakapan aktif tidak menggunakannya:

    bash
    openclaw gateway status --deep --require-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw gateway restart

    Gateway terkelola dimulai ulang secara otomatis setelah perubahan pemasangan, pembaruan, dan penghapusan Plugin yang mengubah sumber Plugin. Pada pemasangan VPS atau kontainer, pastikan setiap mulai ulang manual menargetkan proses turunan openclaw gateway run sebenarnya yang melayani saluran Anda, bukan hanya pembungkus atau supervisor.

    Pemecahan masalah

    Gejala Pemeriksaan Perbaikan
    Plugin muncul di plugins list, tetapi hook runtime tidak berjalan Gunakan openclaw plugins inspect <id> --runtime --json dan konfirmasikan Gateway aktif dengan gateway status --deep --require-rpc Mulai ulang Gateway aktif setelah perubahan pemasangan, pembaruan, konfigurasi, atau sumber
    Diagnostik kepemilikan saluran atau alat duplikat muncul Jalankan openclaw plugins list --enabled --verbose, periksa setiap Plugin yang dicurigai dengan --runtime --json, dan bandingkan kepemilikan saluran/alat Nonaktifkan salah satu pemilik, hapus pemasangan usang, atau gunakan preferOver dalam manifes untuk penggantian yang disengaja
    Konfigurasi menyatakan suatu Plugin tidak ditemukan Periksa inventaris Plugin untuk mengetahui apakah Plugin tersebut dibundel, eksternal resmi, atau hanya berupa sumber Pasang paket eksternal, aktifkan Plugin yang dibundel, atau hapus konfigurasi usang
    Konfigurasi tidak valid selama pemasangan Baca pesan validasi dan jalankan openclaw doctor --fix jika pesan tersebut menunjukkan status Plugin yang usang Doctor dapat mengarantina konfigurasi Plugin yang tidak valid dengan menonaktifkan entri dan menghapus muatan yang tidak valid
    Jalur Plugin diblokir karena kepemilikan atau izin mencurigakan Periksa diagnostik sebelum galat konfigurasi Perbaiki kepemilikan/izin sistem berkas, lalu jalankan openclaw plugins registry --refresh
    OPENCLAW_NIX_MODE=1 memblokir perintah siklus hidup Pastikan pemasangan dikelola oleh Nix Ubah pemilihan Plugin dalam sumber Nix alih-alih menggunakan perintah pengubah Plugin
    Impor dependensi gagal saat runtime Periksa apakah Plugin dipasang melalui npm/git/ClawHub atau dimuat dari jalur lokal Jalankan openclaw plugins update <id>, pasang ulang sumber, atau pasang sendiri dependensi Plugin lokal

    Jika konfigurasi Plugin usang masih menyebutkan Plugin saluran yang tidak lagi dapat ditemukan, validasi konfigurasi menurunkan kunci saluran tersebut menjadi peringatan, bukan kegagalan fatal, sehingga Gateway masih dapat dimulai dan melayani semua saluran lainnya. Jalankan openclaw doctor --fix untuk menghapus entri Plugin dan saluran yang usang. Kunci saluran yang tidak dikenal tanpa bukti Plugin usang tetap menggagalkan validasi agar kesalahan ketik tetap terlihat.

    Untuk penggantian saluran yang disengaja, Plugin yang diutamakan harus mendeklarasikan channelConfigs.<channel-id>.preferOver dengan id Plugin lama atau yang berprioritas lebih rendah. Jika kedua Plugin diaktifkan secara eksplisit, OpenClaw mempertahankan permintaan tersebut dan melaporkan diagnostik saluran/alat duplikat alih-alih memilih satu pemilik secara diam-diam.

    Jika paket yang terpasang melaporkan bahwa paket tersebut requires compiled runtime output for TypeScript entry ..., paket tersebut diterbitkan tanpa berkas JavaScript yang diperlukan OpenClaw saat runtime. Perbarui atau pasang ulang setelah penerbit menyediakan JavaScript yang telah dikompilasi, atau nonaktifkan/hapus Plugin hingga saat itu.

    Kepemilikan jalur Plugin yang diblokir

    Jika diagnostik menyatakan blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) dan validasi kemudian menampilkan plugin present but blocked, OpenClaw menemukan berkas Plugin yang dimiliki oleh pengguna Unix yang berbeda dari pengguna proses yang memuatnya. Pertahankan konfigurasi Plugin; perbaiki kepemilikan sistem berkas atau jalankan OpenClaw sebagai pengguna yang sama dengan pemilik direktori status.

    Untuk pemasangan Docker, citra resmi berjalan sebagai node (uid 1000), sehingga direktori konfigurasi dan ruang kerja OpenClaw pada hos yang dipasang menggunakan bind mount biasanya harus dimiliki oleh uid 1000:

    bash
    sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

    Jika Anda sengaja menjalankan OpenClaw sebagai root, perbaiki kepemilikan root Plugin terkelola menjadi milik root:

    bash
    sudo chown -R root:root /path/to/openclaw-config/npm

    Setelah memperbaiki kepemilikan, jalankan kembali openclaw doctor --fix atau openclaw plugins registry --refresh agar registri Plugin yang dipersistenkan sesuai dengan berkas yang telah diperbaiki.

    Penyiapan alat Plugin yang lambat

    Jika giliran agen tampak terhenti saat menyiapkan alat, aktifkan pencatatan jejak dan periksa baris waktu factory alat Plugin:

    bash
    openclaw config set logging.level traceopenclaw logs --follow

    Cari:

    text
    [trace:plugin-tools] factory timings ...

    Ringkasan mencantumkan total waktu factory dan factory alat Plugin yang paling lambat, termasuk id Plugin, nama alat yang dideklarasikan, bentuk hasil, serta apakah alat tersebut opsional. Baris yang lambat dinaikkan menjadi peringatan jika satu factory membutuhkan waktu setidaknya 1 detik atau total persiapan factory alat Plugin membutuhkan waktu setidaknya 5 detik.

    OpenClaw menyimpan hasil factory alat Plugin yang berhasil ke dalam cache untuk resolusi berulang dengan konteks permintaan efektif yang sama. Kunci cache mencakup konfigurasi runtime efektif, ruang kerja dan id agen, kebijakan sandbox, pengaturan peramban, konteks pengiriman, identitas peminta, dan status kepemilikan, sehingga factory yang bergantung pada bidang tepercaya tersebut dijalankan kembali saat konteks berubah. Jika waktunya tetap tinggi, Plugin mungkin melakukan pekerjaan berat sebelum mengembalikan definisi alatnya.

    Jika satu Plugin mendominasi waktu tersebut, periksa pendaftaran runtime-nya:

    bash
    openclaw plugins inspect <plugin-id> --runtime --json

    Kemudian perbarui, pasang ulang, atau nonaktifkan Plugin tersebut. Penulis Plugin sebaiknya memindahkan pemuatan dependensi yang berat ke jalur eksekusi alat, bukan melakukannya di dalam factory alat.

    Untuk root dependensi, validasi metadata paket, catatan registri, perilaku pemuatan ulang saat memulai, dan pembersihan lama, lihat Resolusi dependensi Plugin.

    Terkait

    Was this useful?
    On this page

    On this page