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. Sebuah plugin dapat menambahkan kanal 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 menginstalnya dengan:

bash
openclaw plugins install clawhub:<package-name>

Spesifikasi paket tanpa awalan masih diinstal dari npm selama peralihan peluncuran. Gunakan awalan clawhub: ketika Anda menginginkan resolusi ClawHub.

Persyaratan

  • Node 22.22.3+, Node 24.15+, atau Node 25.9+, dan npm atau pnpm.
  • Modul ESM TypeScript.
  • Untuk pekerjaan plugin bawaan dalam repositori, klon repositori dan jalankan pnpm install. Pengembangan plugin dari checkout sumber hanya menggunakan pnpm karena OpenClaw menemukan plugin bawaan dari paket workspace extensions/*.

Pilih bentuk plugin

Plugin kanal

Hubungkan OpenClaw ke platform pesan.
Plugin penyedia

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

Jalankan CLI AI lokal melalui fallback model OpenClaw.
Plugin alat

Daftarkan alat agen.

Mulai cepat

Bangun plugin alat minimal dengan mendaftarkan satu alat agen wajib. Ini adalah bentuk plugin berguna yang paling ringkas dan mencakup paket, manifes, titik masuk, serta pembuktian 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, meskipun tanpa konfigurasi. Alat runtime harus muncul di 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 yang diinstal: 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 instalasi 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() }),      outputSchema: Type.Object(        { input: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        const details = { input: params.input };        return {          content: [{ type: "text", text: `Got: ${params.input}` }],          details,        };      },    });  },});

    Gunakan definePluginEntry untuk plugin non-kanal. Plugin kanal menggunakan defineChannelPluginEntry dari openclaw/plugin-sdk/core sebagai gantinya.

  • Uji runtime

    Untuk plugin eksternal atau yang telah diinstal, 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 checkout sumber dari workspace extensions/*. Jalankan pengujian tertarget yang paling sesuai:

    bash
    pnpm test extensions/my-plugin/pnpm check

  • Uji instalasi paket

    Sebelum memublikasikan plugin yang siap dipaketkan, uji bentuk instalasi 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 keluaran dist/ tersebut. Entri sumber TypeScript hanya untuk checkout sumber dan jalur pengembangan lokal.

    Kemudian kemas plugin dan instal 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 mendeteksi kesalahan dependensi runtime yang dapat tersembunyi dalam pengujian checkout sumber. Ini membuktikan bentuk paket dan dependensi, bukan kepercayaan resmi yang tertaut katalog. Impor runtime harus berada dalam dependencies atau optionalDependencies; dependensi yang hanya dibiarkan dalam devDependencies tidak akan diinstal untuk proyek runtime terkelola.

    Jangan gunakan instalasi arsip/jalur mentah sebagai pembuktian akhir untuk perilaku plugin resmi atau berhak istimewa. Sumber mentah berguna untuk debugging lokal, tetapi tidak membuktikan jalur dependensi yang sama seperti instalasi npm atau ClawHub. Jika plugin Anda bergantung pada status plugin resmi tepercaya, tambahkan pembuktian kedua melalui instalasi resmi berbasis katalog atau jalur paket yang dipublikasikan yang mencatat kepercayaan resmi. Lihat Resolusi dependensi plugin untuk detail akar instalasi 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 di docs/snippets/plugin-publish/.

  • Instal

    Instal 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 ketika 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, dan requesterSenderId.

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

    outputSchema bersifat opsional. Ini menjelaskan nilai details terstruktur yang digunakan oleh Mode Kode dan Pencarian Alat. Panggilan katalog menolak skema yang tidak valid sebelum eksekusi dan memvalidasi nilai akhir setelah hook alat. Hilangkan untuk alat tanpa hasil JSON yang stabil. Lihat Plugin alat untuk kontrak lengkap.

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

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

    Pengguna memilih ikut serta dengan tools.allow:

    json5
    {  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for every tool 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 tindakan dijalankan.

    Gunakan alat opsional untuk efek samping, biner yang tidak umum, 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 salah format dilewati dan dilaporkan dengan cara yang sama: name nonkosong yang hilang, execute yang bukan fungsi, atau deskriptor alat tanpa objek parameters.

    Factory alat menerima objek konteks yang disediakan runtime. Gunakan ctx.activeModel ketika alat perlu mencatat log, menampilkan, atau menyesuaikan diri dengan model aktif untuk giliran saat ini; objek ini dapat menyertakan provider, modelId, dan modelRef. Perlakukan sebagai metadata runtime informasional, bukan batas keamanan terhadap operator lokal, kode plugin yang diinstal, atau runtime OpenClaw yang dimodifikasi. Alat lokal sensitif tetap harus memerlukan persetujuan eksplisit plugin atau operator dan gagal secara tertutup ketika metadata model aktif hilang 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 yang diizinkan.

    Konvensi impor

    Impor dari subjalur SDK yang terfokus:

    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 seam tersebut benar-benar generik.

    Metode RPC Gateway khusus adalah titik masuk tingkat lanjut. Pertahankan metode tersebut pada awalan khusus plugin; namespace admin inti seperti config.*, exec.approvals.*, operator.admin.*, wizard.*, dan update.* tetap dicadangkan dan diresolusikan menjadi operator.admin. Bridge 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 prapengajuan

    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 terfokus OPENCLAW_DOCS_MARKER:calloutClose:

    Was this useful?
    On this page

    On this page