Titik masuk Plugin

Setiap plugin mengekspor objek entri default. SDK menyediakan tiga helper untuk membuatnya. Untuk plugin yang terpasang, package.json harus mengarahkan pemuatan runtime ke JavaScript yang sudah dibangun saat tersedia:

{
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"],
    "setupEntry": "./src/setup-entry.ts",
    "runtimeSetupEntry": "./dist/setup-entry.js"
  }
}

extensions dan setupEntry tetap valid sebagai entri sumber untuk pengembangan workspace dan git checkout. runtimeExtensions dan runtimeSetupEntry lebih disarankan saat OpenClaw memuat paket yang terpasang dan memungkinkan paket npm menghindari kompilasi TypeScript saat runtime. Entri runtime eksplisit wajib: runtimeSetupEntry memerlukan setupEntry, dan artefak runtimeExtensions atau runtimeSetupEntry yang hilang akan menggagalkan pemasangan/penemuan alih-alih diam-diam kembali ke sumber. Jika paket yang terpasang hanya mendeklarasikan entri sumber TypeScript, OpenClaw akan menggunakan peer dist/*.js hasil build yang sesuai saat ada, lalu kembali ke sumber TypeScript. Semua jalur entri harus tetap berada di dalam direktori paket plugin. Entri runtime dan peer JavaScript hasil build yang disimpulkan tidak membuat jalur sumber extensions atau setupEntry yang keluar direktori menjadi valid.

Mencari panduan langkah demi langkah? Lihat Plugin Channel atau Plugin Provider untuk panduan bertahap.

`definePluginEntry`

Impor: openclaw/plugin-sdk/plugin-entry Untuk plugin provider, plugin tool, plugin hook, dan apa pun yang bukan channel pesan.

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
  },
});

Field	Type	Required	Default
`id`	`string`	Ya	-
`name`	`string`	Ya	-
`description`	`string`	Ya	-
`kind`	`string`	Tidak	-
`configSchema`	`OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema`	Tidak	Skema objek kosong
`register`	`(api: OpenClawPluginApi) => void`	Ya	-

id harus cocok dengan manifes openclaw.plugin.json Anda.
kind digunakan untuk slot eksklusif: "memory" atau "context-engine".
configSchema dapat berupa fungsi untuk evaluasi lazy.
OpenClaw menyelesaikan dan mememoisasi skema tersebut pada akses pertama, sehingga pembangun skema yang mahal hanya berjalan sekali.

`defineChannelPluginEntry`

Impor: openclaw/plugin-sdk/channel-core Membungkus definePluginEntry dengan wiring khusus channel. Secara otomatis memanggil api.registerChannel({ plugin }), mengekspos seam metadata CLI bantuan root opsional, dan membatasi registerFull berdasarkan mode pendaftaran.

import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerCliMetadata(api) {
    api.registerCli(/* ... */);
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});

Field	Type	Required	Default
`id`	`string`	Ya	-
`name`	`string`	Ya	-
`description`	`string`	Ya	-
`plugin`	`ChannelPlugin`	Ya	-
`configSchema`	`OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema`	Tidak	Skema objek kosong
`setRuntime`	`(runtime: PluginRuntime) => void`	Tidak	-
`registerCliMetadata`	`(api: OpenClawPluginApi) => void`	Tidak	-
`registerFull`	`(api: OpenClawPluginApi) => void`	Tidak	-

setRuntime dipanggil selama pendaftaran sehingga Anda dapat menyimpan referensi runtime (biasanya melalui createPluginRuntimeStore). Ini dilewati selama pengambilan metadata CLI.
registerCliMetadata berjalan selama api.registrationMode === "cli-metadata", api.registrationMode === "discovery", dan api.registrationMode === "full". Gunakan ini sebagai tempat kanonis untuk deskriptor CLI milik channel sehingga bantuan root tetap tidak mengaktifkan, snapshot penemuan menyertakan metadata perintah statis, dan pendaftaran perintah CLI normal tetap kompatibel dengan pemuatan plugin penuh.
Pendaftaran penemuan tidak mengaktifkan, bukan bebas impor. OpenClaw dapat mengevaluasi entri plugin tepercaya dan modul plugin channel untuk membangun snapshot, jadi jaga agar impor tingkat atas bebas efek samping dan tempatkan socket, klien, worker, dan layanan di balik jalur khusus "full".
registerFull hanya berjalan saat api.registrationMode === "full". Ini dilewati selama pemuatan khusus setup.
Seperti definePluginEntry, configSchema dapat berupa factory lazy dan OpenClaw mememoisasi skema yang diselesaikan pada akses pertama.
Untuk perintah CLI root milik plugin, pilih api.registerCli(..., { descriptors: [...] }) saat Anda ingin perintah tetap dimuat secara lazy tanpa menghilang dari pohon parse CLI root. Untuk perintah fitur node berpasangan, pilih api.registerNodeCliFeature(...) agar perintah ditempatkan di bawah openclaw nodes. Untuk perintah plugin bersarang lainnya, tambahkan parentPath dan daftarkan perintah pada objek program yang diteruskan ke registrar; OpenClaw menyelesaikannya ke perintah induk sebelum memanggil plugin. Untuk plugin channel, pilih mendaftarkan deskriptor tersebut dari registerCliMetadata(...) dan jaga agar registerFull(...) fokus pada pekerjaan khusus runtime.
Jika registerFull(...) juga mendaftarkan metode RPC gateway, pertahankan pada prefiks khusus plugin. Namespace admin inti yang dicadangkan (config.*, exec.approvals.*, wizard.*, update.*) selalu dipaksa menjadi operator.admin.

`defineSetupPluginEntry`

Impor: openclaw/plugin-sdk/channel-core Untuk file setup-entry.ts yang ringan. Mengembalikan hanya { plugin } tanpa wiring runtime atau CLI.

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);

OpenClaw memuat ini alih-alih entri penuh saat channel dinonaktifkan, belum dikonfigurasi, atau saat pemuatan tertunda diaktifkan. Lihat Setup dan Konfigurasi untuk kapan ini penting. Dalam praktiknya, pasangkan defineSetupPluginEntry(...) dengan keluarga helper setup yang sempit:

openclaw/plugin-sdk/setup-runtime untuk helper setup yang aman runtime seperti adapter patch setup yang aman impor, output lookup-note, promptResolvedAllowFrom, splitSetupEntries, dan proxy setup yang didelegasikan
openclaw/plugin-sdk/channel-setup untuk surface setup pemasangan opsional
openclaw/plugin-sdk/setup-tools untuk helper setup/install CLI/archive/docs

Simpan SDK berat, pendaftaran CLI, dan layanan runtime berumur panjang di entri penuh. Channel workspace bawaan yang memisahkan surface setup dan runtime dapat menggunakan defineBundledChannelSetupEntry(...) dari openclaw/plugin-sdk/channel-entry-contract sebagai gantinya. Kontrak tersebut memungkinkan entri setup mempertahankan ekspor plugin/secret yang aman untuk setup sekaligus tetap mengekspos setter runtime:

import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";

export default defineBundledChannelSetupEntry({
  importMetaUrl: import.meta.url,
  plugin: {
    specifier: "./channel-plugin-api.js",
    exportName: "myChannelPlugin",
  },
  runtime: {
    specifier: "./runtime-api.js",
    exportName: "setMyChannelRuntime",
  },
});

Gunakan kontrak bawaan tersebut hanya saat alur setup benar-benar memerlukan setter runtime yang ringan sebelum entri channel penuh dimuat.

Mode pendaftaran

api.registrationMode memberi tahu plugin Anda bagaimana ia dimuat:

Mode	Kapan	Apa yang didaftarkan
`"full"`	Startup gateway normal	Semuanya
`"discovery"`	Penemuan kapabilitas baca-saja	Pendaftaran channel plus deskriptor CLI statis; kode entri dapat dimuat, tetapi lewati socket, worker, klien, dan layanan
`"setup-only"`	Channel dinonaktifkan/belum dikonfigurasi	Hanya pendaftaran channel
`"setup-runtime"`	Alur setup dengan runtime tersedia	Pendaftaran channel plus hanya runtime ringan yang diperlukan sebelum entri penuh dimuat
`"cli-metadata"`	Bantuan root / pengambilan metadata CLI	Hanya deskriptor CLI

defineChannelPluginEntry menangani pemisahan ini secara otomatis. Jika Anda menggunakan definePluginEntry langsung untuk channel, periksa sendiri modenya:

register(api) {
  if (
    api.registrationMode === "cli-metadata" ||
    api.registrationMode === "discovery" ||
    api.registrationMode === "full"
  ) {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // Heavy runtime-only registrations
  api.registerService(/* ... */);
}

Mode penemuan membangun snapshot registry yang tidak mengaktifkan. Mode ini tetap dapat mengevaluasi entri plugin dan objek plugin channel agar OpenClaw dapat mendaftarkan kapabilitas channel dan deskriptor CLI statis. Perlakukan evaluasi modul dalam penemuan sebagai tepercaya tetapi ringan: tidak ada klien jaringan, subprocess, listener, koneksi database, worker latar belakang, pembacaan kredensial, atau efek samping runtime hidup lainnya di tingkat atas. Perlakukan "setup-runtime" sebagai jendela ketika surface startup khusus setup harus ada tanpa masuk kembali ke runtime channel bawaan penuh. Kecocokan yang baik adalah pendaftaran channel, route HTTP yang aman untuk setup, metode gateway yang aman untuk setup, dan helper setup yang didelegasikan. Layanan latar belakang berat, registrar CLI, dan bootstrap SDK provider/klien tetap berada di "full". Khusus untuk registrar CLI:

gunakan descriptors saat registrar memiliki satu atau beberapa perintah root dan Anda ingin OpenClaw memuat lambat modul CLI asli pada pemanggilan pertama
pastikan descriptor tersebut mencakup setiap root perintah tingkat atas yang diekspos oleh registrar
batasi nama perintah descriptor pada huruf, angka, tanda hubung, dan garis bawah, dimulai dengan huruf atau angka; OpenClaw menolak nama descriptor di luar bentuk tersebut dan menghapus urutan kontrol terminal dari deskripsi sebelum merender bantuan
gunakan commands saja hanya untuk jalur kompatibilitas eager

Bentuk Plugin

OpenClaw mengklasifikasikan plugin yang dimuat berdasarkan perilaku pendaftarannya:

Bentuk	Deskripsi
plain-capability	Satu jenis kapabilitas (mis. hanya provider)
hybrid-capability	Beberapa jenis kapabilitas (mis. provider + speech)
hook-only	Hanya hook, tanpa kapabilitas
non-capability	Alat/perintah/layanan tetapi tanpa kapabilitas

Gunakan openclaw plugins inspect <id> untuk melihat bentuk sebuah plugin.

Terkait

Ikhtisar SDK - API pendaftaran dan referensi subpath
Pembantu Runtime - api.runtime dan createPluginRuntimeStore
Penyiapan dan Konfigurasi - manifest, entri penyiapan, pemuatan tertunda
Plugin Channel - membangun objek ChannelPlugin
Plugin Provider - pendaftaran provider dan hook

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Release and CI

Titik masuk Plugin

`definePluginEntry`

`defineChannelPluginEntry`

`defineSetupPluginEntry`

Mode pendaftaran

Bentuk Plugin

Terkait

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Release and CI

Documentation Index

​definePluginEntry

​defineChannelPluginEntry

​defineSetupPluginEntry

​Mode pendaftaran

​Bentuk Plugin

​Terkait

`definePluginEntry`

`defineChannelPluginEntry`

`defineSetupPluginEntry`

Mode pendaftaran

Bentuk Plugin

Terkait