English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Building plugins

Membangun plugin

Plugin memperluas OpenClaw tanpa mengubah core. Sebuah plugin dapat menambahkan channel pesan, penyedia model, backend CLI lokal, alat agen, hook, penyedia media, atau kapabilitas lain yang dimiliki plugin.

Anda tidak perlu menambahkan plugin eksternal ke repositori OpenClaw. Publikasikan paket ke ClawHub dan pengguna memasangnya dengan:

bash
openclaw plugins install clawhub:<package-name>

Spesifikasi paket polos tetap dipasang dari npm selama transisi peluncuran. Gunakan prefiks clawhub: saat Anda menginginkan resolusi ClawHub.

Persyaratan

  • Gunakan Node 22.19+, Node 23.11+, atau Node 24+ dan manajer paket seperti npm atau pnpm.
  • Pahami modul TypeScript ESM.
  • Untuk pekerjaan plugin bawaan di dalam repo, clone repositori dan jalankan pnpm install. Pengembangan plugin dari checkout sumber hanya mendukung pnpm karena OpenClaw memuat plugin bawaan dari paket workspace extensions/*.

Pilih bentuk plugin

Channel plugin

Hubungkan OpenClaw ke platform perpesanan.
Provider plugin

Tambahkan penyedia model, media, pencarian, pengambilan, ucapan, atau realtime.
CLI backend plugin

Jalankan CLI AI lokal melalui fallback model OpenClaw.
Tool plugin

Daftarkan alat agen.

Mulai cepat

Bangun plugin alat minimal dengan mendaftarkan satu alat agen wajib. Ini adalah bentuk plugin berguna yang paling singkat dan menunjukkan paket, manifest, entry point, dan bukti lokal.

  • Create package metadata

    package.json
    {"name": "@myorg/openclaw-my-plugin","version": "1.0.0","type": "module","dependencies": {"typebox": "1.1.39"},"peerDependencies": {"openclaw": ">=2026.3.24-beta.2"},"openclaw": {"extensions": ["./index.ts"],"compat": {"pluginApi": ">=2026.3.24-beta.2","minGatewayVersion": "2026.3.24-beta.2"},"build": {"openclawVersion": "2026.3.24-beta.2","pluginSdkVersion": "2026.3.24-beta.2"}}}
    openclaw.plugin.json
    {"id": "my-plugin","name": "My Plugin","description": "Adds a custom tool to OpenClaw","contracts": {"tools": ["my_tool"]},"activation": {"onStartup": true},"configSchema": {"type": "object","additionalProperties": false}}

    Plugin eksternal yang dipublikasikan sebaiknya mengarahkan entri runtime ke file JavaScript hasil build. Lihat entry point SDK untuk kontrak entry point lengkap.

    Setiap plugin membutuhkan manifest, bahkan ketika tidak memiliki config. Alat runtime harus muncul di contracts.tools agar OpenClaw dapat menemukan kepemilikan tanpa memuat setiap runtime plugin secara bersemangat. Atur activation.onStartup secara sengaja. Contoh ini dimulai saat startup Gateway.

    Surface plugin tepercaya host juga dibatasi manifest dan memerlukan pengaktifan eksplisit untuk plugin yang dipasang. Jika plugin yang dipasang mendaftarkan api.registerAgentToolResultMiddleware(...), deklarasikan setiap target runtime di contracts.agentToolResultMiddleware. Jika mendaftarkan api.registerTrustedToolPolicy(...), deklarasikan setiap id kebijakan di contracts.trustedToolPolicies. Deklarasi ini menjaga inspeksi saat pemasangan dan pendaftaran runtime tetap selaras.

    Untuk setiap field manifest, lihat Manifest plugin.

  • Register the tool

    index.ts
    import { Type } from "typebox";import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Adds a custom tool to OpenClaw",  register(api) {    api.registerTool({      name: "my_tool",      description: "Echo one input value",      parameters: Type.Object({ input: Type.String() }),      async execute(_id, params) {        return {          content: [{ type: "text", text: `Got: ${params.input}` }],        };      },    });  },});

    Gunakan definePluginEntry untuk plugin non-channel. Plugin channel menggunakan defineChannelPluginEntry.

  • Test the runtime

    Untuk plugin yang dipasang atau plugin eksternal, inspeksi runtime yang dimuat:

    bash
    openclaw plugins inspect my-plugin --runtime --json

    Jika plugin mendaftarkan perintah CLI, jalankan juga perintah tersebut. Misalnya, perintah demo sebaiknya memiliki bukti eksekusi seperti openclaw demo-plugin ping.

    Untuk plugin bawaan dalam repositori ini, OpenClaw menemukan paket plugin checkout sumber dari workspace extensions/*. Jalankan pengujian tertarget terdekat:

    bash
    pnpm test -- extensions/my-plugin/pnpm check

  • Test the package install

    Sebelum memublikasikan plugin yang siap dipaketkan, uji bentuk pemasangan yang sama dengan yang akan diterima pengguna. Pertama tambahkan langkah build, arahkan entri runtime seperti openclaw.extensions ke JavaScript hasil build seperti ./dist/index.js, dan pastikan npm pack menyertakan output dist/ tersebut. Entri sumber TypeScript hanya untuk checkout sumber dan jalur pengembangan lokal.

    Lalu paketkan plugin dan pasang tarball dengan npm-pack::

    bash
    npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

    npm-pack: menggunakan proyek npm per-plugin terkelola milik OpenClaw, sehingga menangkap kesalahan dependensi runtime yang dapat tersembunyi oleh pengujian checkout sumber. Ini membuktikan bentuk paket dan dependensi, bukan kepercayaan resmi yang tertaut katalog. Impor runtime harus berada di dependencies atau optionalDependencies; dependensi yang hanya tersisa di devDependencies tidak akan dipasang untuk proyek runtime terkelola.

    Jangan gunakan pemasangan arsip/path mentah sebagai bukti akhir untuk perilaku plugin resmi atau dengan hak istimewa. Sumber mentah berguna untuk debugging lokal, tetapi tidak membuktikan jalur dependensi yang sama seperti pemasangan npm atau ClawHub. Jika plugin Anda bergantung pada status plugin resmi tepercaya, tambahkan bukti kedua melalui pemasangan resmi berbasis katalog atau jalur paket yang dipublikasikan yang mencatat kepercayaan resmi. Lihat Resolusi dependensi plugin untuk detail root pemasangan dan kepemilikan dependensi.

  • Publish

    Validasi paket sebelum memublikasikan:

    bash
    clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

    Cuplikan ClawHub kanonis berada di docs/snippets/plugin-publish/.

  • Install

    Pasang paket yang dipublikasikan melalui ClawHub:

    bash
    openclaw plugins install clawhub:your-org/your-plugin

    • Mendaftarkan alat

    Alat dapat bersifat wajib atau opsional. Alat wajib selalu tersedia ketika plugin diaktifkan. Alat opsional memerlukan opt-in pengguna.

    typescript
    register(api) {  api.registerTool(    {      name: "workflow_tool",      description: "Run a workflow",      parameters: Type.Object({ pipeline: Type.String() }),      async execute(_id, params) {        return { content: [{ type: "text", text: params.pipeline }] };      },    },    { optional: true },  );}

    Setiap alat yang didaftarkan dengan api.registerTool(...) juga harus dideklarasikan dalam manifest plugin:

    json
    {  "contracts": {    "tools": ["workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

    Pengguna opt in dengan tools.allow:

    json5
    {  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for all tools from one plugin}

    Alat opsional mengontrol apakah alat diekspos ke model. Gunakan permintaan izin plugin ketika alat atau hook harus meminta persetujuan setelah model memilihnya dan sebelum aksi berjalan.

    Gunakan alat opsional untuk efek samping, binary yang tidak biasa, atau kapabilitas yang sebaiknya tidak diekspos secara default. Nama alat tidak boleh bentrok dengan alat core; konflik dilewati dan dilaporkan dalam diagnostik plugin. Pendaftaran yang salah bentuk, termasuk deskriptor alat tanpa parameters, dilewati dan dilaporkan dengan cara yang sama. Alat terdaftar adalah fungsi bertipe yang dapat dipanggil model setelah pemeriksaan kebijakan dan allowlist lolos.

    Factory alat menerima objek konteks yang disediakan runtime. Gunakan ctx.activeModel ketika alat perlu mencatat log, menampilkan, atau beradaptasi dengan model aktif untuk turn saat ini. Objek dapat menyertakan provider, modelId, dan modelRef. Perlakukan sebagai metadata runtime informasional, bukan sebagai batas keamanan terhadap operator lokal, kode plugin yang dipasang, atau runtime OpenClaw yang dimodifikasi. Alat lokal sensitif tetap harus memerlukan opt-in plugin atau operator yang eksplisit dan gagal tertutup ketika metadata model aktif hilang atau tidak sesuai.

    Manifest mendeklarasikan kepemilikan dan discovery; eksekusi tetap memanggil implementasi alat terdaftar yang aktif. Jaga toolMetadata.<tool>.optional: true tetap selaras dengan api.registerTool(..., { optional: true }) agar OpenClaw dapat menghindari memuat runtime plugin tersebut sampai alat secara eksplisit masuk allowlist.

    Konvensi impor

    Impor dari subpath SDK yang terfokus:

    typescript

    Jangan impor dari barrel root yang sudah deprecated:

    typescript

    Di dalam paket plugin Anda, gunakan file barrel lokal seperti api.ts dan runtime-api.ts untuk impor internal. Jangan impor plugin Anda sendiri melalui path SDK. Helper khusus penyedia sebaiknya tetap berada di paket penyedia kecuali seam tersebut benar-benar generik.

    Metode RPC Gateway kustom adalah entry point lanjutan. Pertahankan pada prefiks khusus plugin; namespace admin core seperti config.*, exec.approvals.*, operator.admin.*, wizard.*, dan update.* tetap dicadangkan dan di-resolve ke operator.admin. Bridge openclaw/plugin-sdk/gateway-method-runtime dicadangkan untuk route HTTP plugin yang mendeklarasikan contracts.gatewayMethodDispatch: ["authenticated-request"].

    Untuk peta impor lengkap, lihat Gambaran umum SDK plugin.

    Checklist pra-pengajuan

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json memiliki metadata openclaw yang benar OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Manifest openclaw.plugin.json ada dan valid OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Entry point menggunakan defineChannelPluginEntry atau definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Semua impor menggunakan path plugin-sdk/<subpath> yang terfokus OPENCLAW_DOCS_MARKER:calloutClose:

    Was this useful?
    On this page

    On this page