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

Building plugins

Membangun plugin

Plugin memperluas OpenClaw tanpa mengubah inti. Plugin dapat menambahkan saluran perpesanan, 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, lalu pengguna dapat memasangnya dengan:

bash
openclaw plugins install clawhub:<package-name>

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

Persyaratan

  • Node 22.19+, Node 23.11+, atau Node 24+, serta npm atau pnpm.
  • Modul ESM TypeScript.
  • Untuk pekerjaan plugin bawaan dalam repositori, klon repositori dan jalankan pnpm install. Pengembangan plugin dari checkout sumber hanya mendukung pnpm karena OpenClaw menemukan plugin bawaan dari paket ruang kerja extensions/*.

Pilih bentuk plugin

Plugin saluran

Hubungkan OpenClaw ke platform perpesanan.
Plugin penyedia

Tambahkan penyedia model, media, pencarian, pengambilan, suara, atau waktu nyata.
Plugin backend CLI

Jalankan CLI AI lokal melalui fallback model OpenClaw.
Plugin alat

Daftarkan alat agen.

Mulai cepat

Buat plugin alat minimal dengan mendaftarkan satu alat agen wajib. Ini adalah bentuk plugin berguna yang paling ringkas dan mencakup paket, manifes, titik masuk, serta bukti lokal.

  • Buat metadata paket

    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 harus mengarahkan entri runtime ke berkas JavaScript hasil build. Lihat Titik masuk SDK untuk kontrak titik masuk lengkap.

    Setiap plugin memerlukan manifes, bahkan tanpa konfigurasi. Alat runtime harus tercantum dalam contracts.tools agar OpenClaw dapat menemukan kepemilikan tanpa memuat setiap runtime plugin secara dini. Tetapkan activation.onStartup secara sengaja; contoh ini dimuat saat Gateway dimulai.

    Permukaan plugin yang dipercaya host juga dibatasi oleh manifes dan memerlukan deklarasi eksplisit untuk plugin terpasang: api.registerAgentToolResultMiddleware(...) memerlukan setiap runtime target dicantumkan dalam contracts.agentToolResultMiddleware, dan api.registerTrustedToolPolicy(...) memerlukan setiap ID kebijakan dalam contracts.trustedToolPolicies. Deklarasi ini menjaga pemeriksaan saat pemasangan tetap selaras dengan pendaftaran runtime.

    Untuk setiap bidang manifes, lihat Manifes plugin.

  • Daftarkan alat

    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-saluran. Sebagai gantinya, plugin saluran menggunakan defineChannelPluginEntry dari openclaw/plugin-sdk/core.

  • Uji runtime

    Untuk plugin terpasang atau eksternal, periksa runtime yang dimuat:

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

    Jika plugin mendaftarkan perintah CLI, jalankan juga perintah tersebut dan konfirmasikan keluarannya, misalnya openclaw demo-plugin ping.

    Untuk plugin bawaan dalam repositori ini, OpenClaw menemukan paket plugin dari checkout sumber melalui ruang kerja extensions/*. Jalankan pengujian tertarget yang paling relevan:

    bash
    pnpm test extensions/my-plugin/pnpm check

  • Uji pemasangan paket

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

    Kemudian kemas 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 yang dikelola OpenClaw sehingga dapat menemukan kesalahan dependensi runtime yang mungkin tersembunyi dalam pengujian checkout sumber. Ini membuktikan bentuk paket dan dependensi, bukan kepercayaan resmi yang ditautkan katalog. Impor runtime harus berada dalam dependencies atau optionalDependencies; dependensi yang hanya tersisa dalam devDependencies tidak akan dipasang untuk proyek runtime terkelola.

    Jangan gunakan pemasangan arsip/jalur mentah sebagai bukti akhir untuk perilaku plugin resmi atau berprivilese. Sumber mentah berguna untuk pengawakutuan 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 akar pemasangan dan kepemilikan dependensi.

  • Publikasikan

    Validasi paket sebelum memublikasikannya:

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

    Cuplikan paket ClawHub kanonis berada dalam docs/snippets/plugin-publish/.

  • Pasang

    Pasang paket yang telah dipublikasikan melalui ClawHub:

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

    • Mendaftarkan alat

    Alat dapat bersifat wajib atau opsional. Alat wajib selalu tersedia saat plugin diaktifkan. Alat opsional memerlukan persetujuan eksplisit pengguna sebelum OpenClaw memuat runtime plugin pemiliknya.

    Factory alat menerima konteks runtime tepercaya, termasuk deliveryContext, nativeChannelId untuk percakapan platform aktif jika tersedia, serta requesterSenderId.

    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 manifes plugin:

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

    Pengguna ikut serta dengan tools.allow:

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

    Alat opsional mengendalikan apakah suatu alat diekspos ke model. Gunakan permintaan izin plugin ketika alat atau hook harus meminta persetujuan setelah model memilihnya dan sebelum tindakan dijalankan.

    Gunakan alat opsional untuk efek samping, biner yang tidak lazim, atau kapabilitas yang tidak boleh diekspos secara default. Nama alat tidak boleh bertentangan dengan nama alat inti; konflik dilewati dan dilaporkan dalam diagnostik plugin. Pendaftaran yang cacat dilewati dan dilaporkan dengan cara yang sama: name tidak ada atau kosong, execute bukan fungsi, atau deskriptor alat tanpa objek parameters.

    Factory alat menerima objek konteks yang disediakan runtime. Gunakan ctx.activeModel saat alat perlu mencatat, menampilkan, atau menyesuaikan diri dengan model aktif untuk giliran saat ini; objek tersebut dapat mencakup provider, modelId, dan modelRef. Perlakukan objek itu sebagai metadata runtime informasional, bukan batas keamanan terhadap operator lokal, kode plugin terpasang, atau runtime OpenClaw yang dimodifikasi. Alat lokal sensitif tetap harus memerlukan persetujuan eksplisit plugin atau operator dan gagal secara tertutup ketika metadata model aktif tidak ada atau tidak sesuai.

    Manifes mendeklarasikan kepemilikan dan penemuan; eksekusi tetap memanggil implementasi alat terdaftar yang aktif. Jaga toolMetadata.<tool>.optional: true tetap selaras dengan api.registerTool(..., { optional: true }) agar OpenClaw dapat menghindari pemuatan runtime plugin tersebut hingga alat secara eksplisit dimasukkan ke daftar izin.

    Konvensi impor

    Impor dari subjalur SDK yang spesifik:

    typescript

    Jangan mengimpor dari barrel akar yang sudah tidak digunakan:

    typescript

    Di dalam paket plugin Anda, gunakan berkas barrel lokal seperti api.ts dan runtime-api.ts untuk impor internal. Jangan mengimpor plugin Anda sendiri melalui jalur SDK. Pembantu khusus penyedia harus tetap berada dalam paket penyedia kecuali batas antarmukanya benar-benar generik.

    Metode RPC Gateway khusus merupakan titik masuk lanjutan. Pertahankan metode tersebut pada awalan khusus plugin; namespace admin inti seperti config.*, exec.approvals.*, operator.admin.*, wizard.*, dan update.* tetap dicadangkan dan diresolusikan ke operator.admin. Jembatan openclaw/plugin-sdk/gateway-method-runtime dicadangkan untuk rute HTTP plugin yang mendeklarasikan contracts.gatewayMethodDispatch: ["authenticated-request"].

    Untuk peta impor lengkap, lihat Ikhtisar SDK Plugin.

    Daftar periksa sebelum pengajuan

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

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Manifes openclaw.plugin.json tersedia dan valid OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Titik masuk menggunakan defineChannelPluginEntry atau definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

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

    Was this useful?
    On this page

    On this page